Refine the file/function comments to follow doxygen format

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@10359 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 812 insertions, 153 deletions

diff --git a/PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c b/PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c
index 36f83f62e0..9230434185 100644
--- a/PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c
+++ b/PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c
@@ -1,14 +1,14 @@
 /** @file

   PCI Root Bridge Io Protocol implementation

 

-  Copyright (c) 2008 - 2009, Intel Corporation<BR> All rights

-  reserved. This program and the accompanying materials are

-  licensed and made available under the terms and conditions of the BSD License

-  which accompanies this distribution.  The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php

-  

-  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

-  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

+Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved. <BR> 

+This program and the accompanying materials are

+licensed and made available under the terms and conditions of the BSD License

+which accompanies this distribution.  The full text of the license may be found at

+http://opensource.org/licenses/bsd-license.php

+

+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

 **/ 

 

@@ -33,6 +33,35 @@ RESOURCE_CONFIGURATION Configuration = {
 // Protocol Member Function Prototypes

 //

 

+/**

+   Polls an address in memory mapped I/O space until an exit condition is met, or 

+   a timeout occurs. 

+

+   This function provides a standard way to poll a PCI memory location. A PCI memory read

+   operation is performed at the PCI memory address specified by Address for the width specified

+   by Width. The result of this PCI memory read operation is stored in Result. This PCI memory

+   read operation is repeated until either a timeout of Delay 100 ns units has expired, or (Result &

+   Mask) is equal to Value.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operations.

+   @param[in]   Address   The base address of the memory operations. The caller is

+                          responsible for aligning Address if required.

+   @param[in]   Mask      Mask used for the polling criteria. Bytes above Width in Mask

+                          are ignored. The bits in the bytes below Width which are zero in

+                          Mask are ignored when polling the memory address.

+   @param[in]   Value     The comparison value used for the polling exit criteria.

+   @param[in]   Delay     The number of 100 ns units to poll. Note that timer available may

+                          be of poorer granularity.

+   @param[out]  Result    Pointer to the last value read from the memory location.

+   

+   @retval EFI_SUCCESS            The last data returned from the access matched the poll exit criteria.

+   @retval EFI_INVALID_PARAMETER  Width is invalid.

+   @retval EFI_INVALID_PARAMETER  Result is NULL.

+   @retval EFI_TIMEOUT            Delay expired before a match occurred.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoPollMem ( 

@@ -45,6 +74,35 @@ RootBridgeIoPollMem (
   OUT UINT64                                 *Result

   );

   

+/**

+   Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is

+   satisfied or after a defined duration.

+

+   This function provides a standard way to poll a PCI I/O location. A PCI I/O read operation is

+   performed at the PCI I/O address specified by Address for the width specified by Width.

+   The result of this PCI I/O read operation is stored in Result. This PCI I/O read operation is

+   repeated until either a timeout of Delay 100 ns units has expired, or (Result & Mask) is equal

+   to Value.

+

+   @param[in] This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in] Width     Signifies the width of the I/O operations.

+   @param[in] Address   The base address of the I/O operations. The caller is responsible

+                        for aligning Address if required.

+   @param[in] Mask      Mask used for the polling criteria. Bytes above Width in Mask

+                        are ignored. The bits in the bytes below Width which are zero in

+                        Mask are ignored when polling the I/O address.

+   @param[in] Value     The comparison value used for the polling exit criteria.

+   @param[in] Delay     The number of 100 ns units to poll. Note that timer available may

+                        be of poorer granularity.

+   @param[out] Result   Pointer to the last value read from the memory location.

+   

+   @retval EFI_SUCCESS            The last data returned from the access matched the poll exit criteria.

+   @retval EFI_INVALID_PARAMETER  Width is invalid.

+   @retval EFI_INVALID_PARAMETER  Result is NULL.

+   @retval EFI_TIMEOUT            Delay expired before a match occurred.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoPollIo ( 

@@ -57,6 +115,29 @@ RootBridgeIoPollIo (
   OUT UINT64                                 *Result

   );

   

+/**

+   Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.

+

+   The Mem.Read(), and Mem.Write() functions enable a driver to access PCI controller

+   registers in the PCI root bridge memory space.

+   The memory operations are carried out exactly as requested. The caller is responsible for satisfying

+   any alignment and memory width restrictions that a PCI Root Bridge on a platform might require.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operation.

+   @param[in]   Address   The base address of the memory operation. The caller is

+                          responsible for aligning the Address if required.

+   @param[in]   Count     The number of memory operations to perform. Bytes moved is

+                          Width size * Count, starting at Address.

+   @param[out]  Buffer    For read operations, the destination buffer to store the results. For

+                          write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoMemRead (

@@ -67,6 +148,28 @@ RootBridgeIoMemRead (
   IN OUT VOID                                   *Buffer

   );

 

+/**

+   Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.

+

+   The Mem.Read(), and Mem.Write() functions enable a driver to access PCI controller

+   registers in the PCI root bridge memory space.

+   The memory operations are carried out exactly as requested. The caller is responsible for satisfying

+   any alignment and memory width restrictions that a PCI Root Bridge on a platform might require.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operation.

+   @param[in]   Address   The base address of the memory operation. The caller is

+                          responsible for aligning the Address if required.

+   @param[in]   Count     The number of memory operations to perform. Bytes moved is

+                          Width size * Count, starting at Address.

+   @param[out]  Buffer    For read operations, the destination buffer to store the results. For

+                          write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoMemWrite (

@@ -77,6 +180,24 @@ RootBridgeIoMemWrite (
   IN OUT VOID                                   *Buffer

   );

 

+/**

+   Enables a PCI driver to access PCI controller registers in the PCI root bridge I/O space.

+

+   @param[in]   This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width       Signifies the width of the memory operations.

+   @param[in]   Address     The base address of the I/O operation. The caller is responsible for

+                            aligning the Address if required.

+   @param[in]   Count       The number of I/O operations to perform. Bytes moved is Width

+                            size * Count, starting at Address.

+   @param[out]  Buffer      For read operations, the destination buffer to store the results. For

+                            write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS              The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER    Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER    Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoIoRead (

@@ -87,6 +208,24 @@ RootBridgeIoIoRead (
   IN OUT VOID                                   *UserBuffer

   );

 

+/**

+   Enables a PCI driver to access PCI controller registers in the PCI root bridge I/O space.

+

+   @param[in]   This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width       Signifies the width of the memory operations.

+   @param[in]   Address     The base address of the I/O operation. The caller is responsible for

+                            aligning the Address if required.

+   @param[in]   Count       The number of I/O operations to perform. Bytes moved is Width

+                            size * Count, starting at Address.

+   @param[out]  Buffer      For read operations, the destination buffer to store the results. For

+                            write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS              The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER    Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER    Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoIoWrite (

@@ -97,6 +236,30 @@ RootBridgeIoIoWrite (
   IN OUT VOID                                   *UserBuffer

   );

 

+/**

+   Enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI

+   root bridge memory space.

+

+   The CopyMem() function enables a PCI driver to copy one region of PCI root bridge memory

+   space to another region of PCI root bridge memory space. This is especially useful for video scroll

+   operation on a memory mapped video buffer.

+   The memory operations are carried out exactly as requested. The caller is responsible for satisfying

+   any alignment and memory width restrictions that a PCI root bridge on a platform might require.

+

+   @param[in] This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.

+   @param[in] Width       Signifies the width of the memory operations.

+   @param[in] DestAddress The destination address of the memory operation. The caller is

+                          responsible for aligning the DestAddress if required.

+   @param[in] SrcAddress  The source address of the memory operation. The caller is

+                          responsible for aligning the SrcAddress if required.

+   @param[in] Count       The number of memory operations to perform. Bytes moved is

+                          Width size * Count, starting at DestAddress and SrcAddress.

+   

+   @retval  EFI_SUCCESS             The data was copied from one memory region to another memory region.

+   @retval  EFI_INVALID_PARAMETER   Width is invalid for this PCI root bridge.

+   @retval  EFI_OUT_OF_RESOURCES    The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoCopyMem (

@@ -107,6 +270,29 @@ RootBridgeIoCopyMem (
   IN     UINTN                                  Count

   );

 

+/**

+   Enables a PCI driver to access PCI controller registers in a PCI root bridge's configuration space.

+

+   The Pci.Read() and Pci.Write() functions enable a driver to access PCI configuration

+   registers for a PCI controller.

+   The PCI Configuration operations are carried out exactly as requested. The caller is responsible for

+   any alignment and PCI configuration width issues that a PCI Root Bridge on a platform might

+   require.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operations.

+   @param[in]   Address   The address within the PCI configuration space for the PCI controller.

+   @param[in]   Count     The number of PCI configuration operations to perform. Bytes

+                          moved is Width size * Count, starting at Address.

+   @param[out]  Buffer    For read operations, the destination buffer to store the results. For

+                          write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoPciRead (

@@ -117,6 +303,29 @@ RootBridgeIoPciRead (
   IN OUT VOID                                   *Buffer

   );

 

+/**

+   Enables a PCI driver to access PCI controller registers in a PCI root bridge's configuration space.

+

+   The Pci.Read() and Pci.Write() functions enable a driver to access PCI configuration

+   registers for a PCI controller.

+   The PCI Configuration operations are carried out exactly as requested. The caller is responsible for

+   any alignment and PCI configuration width issues that a PCI Root Bridge on a platform might

+   require.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operations.

+   @param[in]   Address   The address within the PCI configuration space for the PCI controller.

+   @param[in]   Count     The number of PCI configuration operations to perform. Bytes

+                          moved is Width size * Count, starting at Address.

+   @param[out]  Buffer    For read operations, the destination buffer to store the results. For

+                          write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoPciWrite (

@@ -127,6 +336,32 @@ RootBridgeIoPciWrite (
   IN OUT VOID                                   *Buffer

   );

 

+/**

+   Provides the PCI controller-specific addresses required to access system memory from a

+   DMA bus master.

+

+   The Map() function provides the PCI controller specific addresses needed to access system

+   memory. This function is used to map system memory for PCI bus master DMA accesses.

+

+   @param[in]       This            A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]       Operation       Indicates if the bus master is going to read or write to system memory.

+   @param[in]       HostAddress     The system memory address to map to the PCI controller.

+   @param[in][out]  NumberOfBytes   On input the number of bytes to map. On output the number of bytes that were mapped.

+   @param[out]      DeviceAddress   The resulting map address for the bus master PCI controller to use

+                                    to access the system memory's HostAddress.

+   @param[out]      Mapping         The value to pass to Unmap() when the bus master DMA operation is complete.

+   

+   @retval EFI_SUCCESS            The range was mapped for the returned NumberOfBytes.

+   @retval EFI_INVALID_PARAMETER  Operation is invalid.

+   @retval EFI_INVALID_PARAMETER  HostAddress is NULL.

+   @retval EFI_INVALID_PARAMETER  NumberOfBytes is NULL.

+   @retval EFI_INVALID_PARAMETER  DeviceAddress is NULL.

+   @retval EFI_INVALID_PARAMETER  Mapping is NULL.

+   @retval EFI_UNSUPPORTED        The HostAddress cannot be mapped as a common buffer.

+   @retval EFI_DEVICE_ERROR       The system hardware could not map the requested address.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoMap (

@@ -138,6 +373,22 @@ RootBridgeIoMap (
   OUT    VOID                                       **Mapping

   );

 

+/**

+   Completes the Map() operation and releases any corresponding resources.

+

+   The Unmap() function completes the Map() operation and releases any corresponding resources.

+   If the operation was an EfiPciOperationBusMasterWrite or

+   EfiPciOperationBusMasterWrite64, the data is committed to the target system memory.

+   Any resources used for the mapping are freed.  

+

+   @param[in] This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in] Mapping   The mapping value returned from Map().

+   

+   @retval EFI_SUCCESS            The range was unmapped.

+   @retval EFI_INVALID_PARAMETER  Mapping is not a value that was returned by Map().

+   @retval EFI_DEVICE_ERROR       The data was not committed to the target system memory.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoUnmap (

@@ -145,6 +396,27 @@ RootBridgeIoUnmap (
   IN  VOID                             *Mapping

   );

 

+/**

+   Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or

+   EfiPciOperationBusMasterCommonBuffer64 mapping.

+  

+   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param Type        This parameter is not used and must be ignored.

+   @param MemoryType  The type of memory to allocate, EfiBootServicesData or EfiRuntimeServicesData.

+   @param Pages       The number of pages to allocate.

+   @param HostAddress A pointer to store the base system memory address of the allocated range.

+   @param Attributes  The requested bit mask of attributes for the allocated range. Only

+                      the attributes EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE, EFI_PCI_ATTRIBUTE_MEMORY_CACHED, 

+                      and EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE may be used with this function.

+   

+   @retval EFI_SUCCESS            The requested memory pages were allocated.

+   @retval EFI_INVALID_PARAMETER  MemoryType is invalid.

+   @retval EFI_INVALID_PARAMETER  HostAddress is NULL.

+   @retval EFI_UNSUPPORTED        Attributes is unsupported. The only legal attribute bits are

+                                  MEMORY_WRITE_COMBINE, MEMORY_CACHED, and DUAL_ADDRESS_CYCLE.

+   @retval EFI_OUT_OF_RESOURCES   The memory pages could not be allocated.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoAllocateBuffer (

@@ -156,6 +428,20 @@ RootBridgeIoAllocateBuffer (
   IN  UINT64                           Attributes

   );

 

+/**

+   Frees memory that was allocated with AllocateBuffer().

+

+   The FreeBuffer() function frees memory that was allocated with AllocateBuffer().

+

+   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param Pages       The number of pages to free.

+   @param HostAddress The base system memory address of the allocated range.

+   

+   @retval EFI_SUCCESS            The requested memory pages were freed.

+   @retval EFI_INVALID_PARAMETER  The memory range specified by HostAddress and Pages

+                                  was not allocated with AllocateBuffer().

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoFreeBuffer (

@@ -164,12 +450,51 @@ RootBridgeIoFreeBuffer (
   OUT VOID                             *HostAddress

   );

 

+/**

+   Flushes all PCI posted write transactions from a PCI host bridge to system memory.

+

+   The Flush() function flushes any PCI posted write transactions from a PCI host bridge to system

+   memory. Posted write transactions are generated by PCI bus masters when they perform write

+   transactions to target addresses in system memory.

+   This function does not flush posted write transactions from any PCI bridges. A PCI controller

+   specific action must be taken to guarantee that the posted write transactions have been flushed from

+   the PCI controller and from all the PCI bridges into the PCI host bridge. This is typically done with

+   a PCI read transaction from the PCI controller prior to calling Flush().

+

+   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   

+   @retval EFI_SUCCESS        The PCI posted write transactions were flushed from the PCI host

+                              bridge to system memory.

+   @retval EFI_DEVICE_ERROR   The PCI posted write transactions were not flushed from the PCI

+                              host bridge due to a hardware error.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoFlush (

   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *This

   );

 

+/**

+   Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the

+   attributes that a PCI root bridge is currently using.  

+

+   The GetAttributes() function returns the mask of attributes that this PCI root bridge supports

+   and the mask of attributes that the PCI root bridge is currently using.

+

+   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param Supported   A pointer to the mask of attributes that this PCI root bridge

+                      supports setting with SetAttributes().

+   @param Attributes  A pointer to the mask of attributes that this PCI root bridge is

+                      currently using.

+   

+   @retval  EFI_SUCCESS           If Supports is not NULL, then the attributes that the PCI root

+                                  bridge supports is returned in Supports. If Attributes is

+                                  not NULL, then the attributes that the PCI root bridge is currently

+                                  using is returned in Attributes.

+   @retval  EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoGetAttributes (

@@ -178,6 +503,36 @@ RootBridgeIoGetAttributes (
   OUT UINT64                           *Attributes

   );

 

+/**

+   Sets attributes for a resource range on a PCI root bridge.

+

+   The SetAttributes() function sets the attributes specified in Attributes for the PCI root

+   bridge on the resource range specified by ResourceBase and ResourceLength. Since the

+   granularity of setting these attributes may vary from resource type to resource type, and from

+   platform to platform, the actual resource range and the one passed in by the caller may differ. As a

+   result, this function may set the attributes specified by Attributes on a larger resource range

+   than the caller requested. The actual range is returned in ResourceBase and

+   ResourceLength. The caller is responsible for verifying that the actual range for which the

+   attributes were set is acceptable.

+

+   @param[in]       This            A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]       Attributes      The mask of attributes to set. If the attribute bit

+                                    MEMORY_WRITE_COMBINE, MEMORY_CACHED, or

+                                    MEMORY_DISABLE is set, then the resource range is specified by

+                                    ResourceBase and ResourceLength. If

+                                    MEMORY_WRITE_COMBINE, MEMORY_CACHED, and

+                                    MEMORY_DISABLE are not set, then ResourceBase and

+                                    ResourceLength are ignored, and may be NULL.

+   @param[in][out]  ResourceBase    A pointer to the base address of the resource range to be modified

+                                    by the attributes specified by Attributes.

+   @param[in][out]  ResourceLength  A pointer to the length of the resource range to be modified by the

+                                    attributes specified by Attributes.

+   

+   @retval  EFI_SUCCESS     The current configuration of this PCI root bridge was returned in Resources.

+   @retval  EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be retrieved.

+   @retval  EFI_INVALID_PARAMETER Invalid pointer of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoSetAttributes (

@@ -187,6 +542,29 @@ RootBridgeIoSetAttributes (
   IN OUT UINT64                           *ResourceLength 

   ); 

 

+/**

+   Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI 2.0

+   resource descriptors.

+

+   There are only two resource descriptor types from the ACPI Specification that may be used to

+   describe the current resources allocated to a PCI root bridge. These are the QWORD Address

+   Space Descriptor (ACPI 2.0 Section 6.4.3.5.1), and the End Tag (ACPI 2.0 Section 6.4.2.8). The

+   QWORD Address Space Descriptor can describe memory, I/O, and bus number ranges for dynamic

+   or fixed resources. The configuration of a PCI root bridge is described with one or more QWORD

+   Address Space Descriptors followed by an End Tag.

+

+   @param[in]   This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[out]  Resources   A pointer to the ACPI 2.0 resource descriptors that describe the

+                            current configuration of this PCI root bridge. The storage for the

+                            ACPI 2.0 resource descriptors is allocated by this function. The

+                            caller must treat the return buffer as read-only data, and the buffer

+                            must not be freed by the caller.

+   

+   @retval  EFI_SUCCESS     The current configuration of this PCI root bridge was returned in Resources.

+   @retval  EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be retrieved.

+   @retval  EFI_INVALID_PARAMETER Invalid pointer of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoConfiguration (

@@ -197,6 +575,24 @@ RootBridgeIoConfiguration (
 //

 // Sub Function Prototypes

 //

+/**

+   Internal help function for read and write PCI configuration space.

+

+   @param[in]   This          A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Write         Switch value for Read or Write.

+   @param[in]   Width         Signifies the width of the memory operations.

+   @param[in]   UserAddress   The address within the PCI configuration space for the PCI controller.

+   @param[in]   Count         The number of PCI configuration operations to perform. Bytes

+                              moved is Width size * Count, starting at Address.

+   @param[out]  UserBuffer    For read operations, the destination buffer to store the results. For

+                              write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 RootBridgeIoPciRW (

   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL        *This,

@@ -213,6 +609,18 @@ RootBridgeIoPciRW (
 EFI_METRONOME_ARCH_PROTOCOL *mMetronome;

 EFI_CPU_IO2_PROTOCOL *mCpuIo;

 

+/**

+

+  Construct the Pci Root Bridge Io protocol

+

+  @param Protocol         Point to protocol instance

+  @param HostBridgeHandle Handle of host bridge

+  @param Attri            Attribute of host bridge

+  @param ResAppeture      ResourceAppeture for host bridge

+

+  @retval EFI_SUCCESS Success to initialize the Pci Root Bridge.

+

+**/

 EFI_STATUS

 RootBridgeConstructor (

   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL    *Protocol,

@@ -220,21 +628,6 @@ RootBridgeConstructor (
   IN UINT64                             Attri,

   IN PCI_ROOT_BRIDGE_RESOURCE_APPETURE  *ResAppeture

   )

-/*++

-

-Routine Description:

-

-    Construct the Pci Root Bridge Io protocol

-

-Arguments:

-

-    Protocol - protocol to initialize

-    

-Returns:

-

-    None

-

---*/

 {

   EFI_STATUS                        Status;

   PCI_ROOT_BRIDGE_INSTANCE          *PrivateData;

@@ -322,6 +715,35 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+   Polls an address in memory mapped I/O space until an exit condition is met, or 

+   a timeout occurs. 

+

+   This function provides a standard way to poll a PCI memory location. A PCI memory read

+   operation is performed at the PCI memory address specified by Address for the width specified

+   by Width. The result of this PCI memory read operation is stored in Result. This PCI memory

+   read operation is repeated until either a timeout of Delay 100 ns units has expired, or (Result &

+   Mask) is equal to Value.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operations.

+   @param[in]   Address   The base address of the memory operations. The caller is

+                          responsible for aligning Address if required.

+   @param[in]   Mask      Mask used for the polling criteria. Bytes above Width in Mask

+                          are ignored. The bits in the bytes below Width which are zero in

+                          Mask are ignored when polling the memory address.

+   @param[in]   Value     The comparison value used for the polling exit criteria.

+   @param[in]   Delay     The number of 100 ns units to poll. Note that timer available may

+                          be of poorer granularity.

+   @param[out]  Result    Pointer to the last value read from the memory location.

+   

+   @retval EFI_SUCCESS            The last data returned from the access matched the poll exit criteria.

+   @retval EFI_INVALID_PARAMETER  Width is invalid.

+   @retval EFI_INVALID_PARAMETER  Result is NULL.

+   @retval EFI_TIMEOUT            Delay expired before a match occurred.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoPollMem ( 

@@ -333,16 +755,6 @@ RootBridgeIoPollMem (
   IN  UINT64                                 Delay,

   OUT UINT64                                 *Result

   )

-/*++

-

-Routine Description:

-  Memory Poll

-  

-Arguments:

-    

-Returns:

-

---*/  

 {

   EFI_STATUS  Status;

   UINT64      NumberOfTicks;

@@ -406,6 +818,35 @@ Returns:
   return EFI_TIMEOUT;

 }

   

+/**

+   Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is

+   satisfied or after a defined duration.

+

+   This function provides a standard way to poll a PCI I/O location. A PCI I/O read operation is

+   performed at the PCI I/O address specified by Address for the width specified by Width.

+   The result of this PCI I/O read operation is stored in Result. This PCI I/O read operation is

+   repeated until either a timeout of Delay 100 ns units has expired, or (Result & Mask) is equal

+   to Value.

+

+   @param[in] This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in] Width     Signifies the width of the I/O operations.

+   @param[in] Address   The base address of the I/O operations. The caller is responsible

+                        for aligning Address if required.

+   @param[in] Mask      Mask used for the polling criteria. Bytes above Width in Mask

+                        are ignored. The bits in the bytes below Width which are zero in

+                        Mask are ignored when polling the I/O address.

+   @param[in] Value     The comparison value used for the polling exit criteria.

+   @param[in] Delay     The number of 100 ns units to poll. Note that timer available may

+                        be of poorer granularity.

+   @param[out] Result   Pointer to the last value read from the memory location.

+   

+   @retval EFI_SUCCESS            The last data returned from the access matched the poll exit criteria.

+   @retval EFI_INVALID_PARAMETER  Width is invalid.

+   @retval EFI_INVALID_PARAMETER  Result is NULL.

+   @retval EFI_TIMEOUT            Delay expired before a match occurred.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoPollIo ( 

@@ -417,16 +858,6 @@ RootBridgeIoPollIo (
   IN  UINT64                                 Delay,

   OUT UINT64                                 *Result

   )

-/*++

-

-Routine Description:

-  Io Poll

-  

-Arguments:

-    

-Returns:

-

---*/  

 {

   EFI_STATUS  Status;

   UINT64      NumberOfTicks;

@@ -488,6 +919,29 @@ Returns:
   return EFI_TIMEOUT;

 }

 

+/**

+   Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.

+

+   The Mem.Read(), and Mem.Write() functions enable a driver to access PCI controller

+   registers in the PCI root bridge memory space.

+   The memory operations are carried out exactly as requested. The caller is responsible for satisfying

+   any alignment and memory width restrictions that a PCI Root Bridge on a platform might require.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operation.

+   @param[in]   Address   The base address of the memory operation. The caller is

+                          responsible for aligning the Address if required.

+   @param[in]   Count     The number of memory operations to perform. Bytes moved is

+                          Width size * Count, starting at Address.

+   @param[out]  Buffer    For read operations, the destination buffer to store the results. For

+                          write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoMemRead (

@@ -497,16 +951,6 @@ RootBridgeIoMemRead (
   IN     UINTN                                  Count,

   IN OUT VOID                                   *Buffer

   )

-/*++

-

-Routine Description:

-  Memory read

-  

-Arguments:

-    

-Returns:

-

---*/  

 {

   PCI_ROOT_BRIDGE_INSTANCE                 *PrivateData;

   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH    OldWidth;

@@ -546,6 +990,28 @@ Returns:
                        Address, OldCount, Buffer);

 }

 

+/**

+   Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.

+

+   The Mem.Read(), and Mem.Write() functions enable a driver to access PCI controller

+   registers in the PCI root bridge memory space.

+   The memory operations are carried out exactly as requested. The caller is responsible for satisfying

+   any alignment and memory width restrictions that a PCI Root Bridge on a platform might require.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operation.

+   @param[in]   Address   The base address of the memory operation. The caller is

+                          responsible for aligning the Address if required.

+   @param[in]   Count     The number of memory operations to perform. Bytes moved is

+                          Width size * Count, starting at Address.

+   @param[out]  Buffer    For read operations, the destination buffer to store the results. For

+                          write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoMemWrite (

@@ -555,16 +1021,6 @@ RootBridgeIoMemWrite (
   IN     UINTN                                  Count,

   IN OUT VOID                                   *Buffer

   )

-/*++

-

-Routine Description:

-  Memory write

-  

-Arguments:

-    

-Returns:

-

---*/  

 {

   PCI_ROOT_BRIDGE_INSTANCE                    *PrivateData;

   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH       OldWidth;

@@ -603,6 +1059,24 @@ Returns:
                        Address, OldCount, Buffer);

 }

 

+/**

+   Enables a PCI driver to access PCI controller registers in the PCI root bridge I/O space.

+

+   @param[in]   This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width       Signifies the width of the memory operations.

+   @param[in]   Address     The base address of the I/O operation. The caller is responsible for

+                            aligning the Address if required.

+   @param[in]   Count       The number of I/O operations to perform. Bytes moved is Width

+                            size * Count, starting at Address.

+   @param[out]  Buffer      For read operations, the destination buffer to store the results. For

+                            write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS              The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER    Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER    Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoIoRead (

@@ -612,16 +1086,6 @@ RootBridgeIoIoRead (
   IN     UINTN                                  Count,

   IN OUT VOID                                   *Buffer

   )

-/*++

-

-Routine Description:

-  Io read

-  

-Arguments:

-    

-Returns:

-

---*/  

 {

   

   

@@ -671,6 +1135,24 @@ Returns:
 

 }

 

+/**

+   Enables a PCI driver to access PCI controller registers in the PCI root bridge I/O space.

+

+   @param[in]   This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width       Signifies the width of the memory operations.

+   @param[in]   Address     The base address of the I/O operation. The caller is responsible for

+                            aligning the Address if required.

+   @param[in]   Count       The number of I/O operations to perform. Bytes moved is Width

+                            size * Count, starting at Address.

+   @param[out]  Buffer      For read operations, the destination buffer to store the results. For

+                            write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS              The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER    Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER    Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoIoWrite (

@@ -680,16 +1162,6 @@ RootBridgeIoIoWrite (
   IN       UINTN                                   Count,

   IN OUT   VOID                                    *Buffer

   )

-/*++

-

-Routine Description:

-  Io write

-  

-Arguments:

-    

-Returns:

-

---*/  

 {

   UINTN                                         AlignMask;

   PCI_ROOT_BRIDGE_INSTANCE                      *PrivateData;

@@ -737,6 +1209,30 @@ Returns:
 

 }

 

+/**

+   Enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI

+   root bridge memory space.

+

+   The CopyMem() function enables a PCI driver to copy one region of PCI root bridge memory

+   space to another region of PCI root bridge memory space. This is especially useful for video scroll

+   operation on a memory mapped video buffer.

+   The memory operations are carried out exactly as requested. The caller is responsible for satisfying

+   any alignment and memory width restrictions that a PCI root bridge on a platform might require.

+

+   @param[in] This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.

+   @param[in] Width       Signifies the width of the memory operations.

+   @param[in] DestAddress The destination address of the memory operation. The caller is

+                          responsible for aligning the DestAddress if required.

+   @param[in] SrcAddress  The source address of the memory operation. The caller is

+                          responsible for aligning the SrcAddress if required.

+   @param[in] Count       The number of memory operations to perform. Bytes moved is

+                          Width size * Count, starting at DestAddress and SrcAddress.

+   

+   @retval  EFI_SUCCESS             The data was copied from one memory region to another memory region.

+   @retval  EFI_INVALID_PARAMETER   Width is invalid for this PCI root bridge.

+   @retval  EFI_OUT_OF_RESOURCES    The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoCopyMem (

@@ -746,16 +1242,6 @@ RootBridgeIoCopyMem (
   IN UINT64                                       SrcAddress,

   IN UINTN                                        Count

   )

-/*++

-

-Routine Description:

-  Memory copy

-  

-Arguments:

-    

-Returns:

-

---*/

 {

   EFI_STATUS  Status;

   BOOLEAN     Direction;

@@ -812,6 +1298,29 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+   Enables a PCI driver to access PCI controller registers in a PCI root bridge's configuration space.

+

+   The Pci.Read() and Pci.Write() functions enable a driver to access PCI configuration

+   registers for a PCI controller.

+   The PCI Configuration operations are carried out exactly as requested. The caller is responsible for

+   any alignment and PCI configuration width issues that a PCI Root Bridge on a platform might

+   require.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operations.

+   @param[in]   Address   The address within the PCI configuration space for the PCI controller.

+   @param[in]   Count     The number of PCI configuration operations to perform. Bytes

+                          moved is Width size * Count, starting at Address.

+   @param[out]  Buffer    For read operations, the destination buffer to store the results. For

+                          write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoPciRead (

@@ -821,16 +1330,6 @@ RootBridgeIoPciRead (
   IN       UINTN                                  Count,

   IN OUT   VOID                                   *Buffer

   )

-/*++

-

-Routine Description:

-  Pci read

-  

-Arguments:

-    

-Returns:

-

---*/  

 {

   

   if (Buffer == NULL) {

@@ -846,6 +1345,29 @@ Returns:
   return RootBridgeIoPciRW (This, FALSE, Width, Address, Count, Buffer);

 }

 

+/**

+   Enables a PCI driver to access PCI controller registers in a PCI root bridge's configuration space.

+

+   The Pci.Read() and Pci.Write() functions enable a driver to access PCI configuration

+   registers for a PCI controller.

+   The PCI Configuration operations are carried out exactly as requested. The caller is responsible for

+   any alignment and PCI configuration width issues that a PCI Root Bridge on a platform might

+   require.

+

+   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Width     Signifies the width of the memory operations.

+   @param[in]   Address   The address within the PCI configuration space for the PCI controller.

+   @param[in]   Count     The number of PCI configuration operations to perform. Bytes

+                          moved is Width size * Count, starting at Address.

+   @param[out]  Buffer    For read operations, the destination buffer to store the results. For

+                          write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoPciWrite (

@@ -855,16 +1377,6 @@ RootBridgeIoPciWrite (
   IN       UINTN                                  Count,

   IN OUT   VOID                                   *Buffer

   )

-/*++

-

-Routine Description:

-  Pci write

-  

-Arguments:

-    

-Returns:

-

---*/  

 {

   

   if (Buffer == NULL) {

@@ -880,6 +1392,32 @@ Returns:
   return RootBridgeIoPciRW (This, TRUE, Width, Address, Count, Buffer);

 }

 

+/**

+   Provides the PCI controller-specific addresses required to access system memory from a

+   DMA bus master.

+

+   The Map() function provides the PCI controller specific addresses needed to access system

+   memory. This function is used to map system memory for PCI bus master DMA accesses.

+

+   @param[in]       This            A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]       Operation       Indicates if the bus master is going to read or write to system memory.

+   @param[in]       HostAddress     The system memory address to map to the PCI controller.

+   @param[in][out]  NumberOfBytes   On input the number of bytes to map. On output the number of bytes that were mapped.

+   @param[out]      DeviceAddress   The resulting map address for the bus master PCI controller to use

+                                    to access the system memory's HostAddress.

+   @param[out]      Mapping         The value to pass to Unmap() when the bus master DMA operation is complete.

+   

+   @retval EFI_SUCCESS            The range was mapped for the returned NumberOfBytes.

+   @retval EFI_INVALID_PARAMETER  Operation is invalid.

+   @retval EFI_INVALID_PARAMETER  HostAddress is NULL.

+   @retval EFI_INVALID_PARAMETER  NumberOfBytes is NULL.

+   @retval EFI_INVALID_PARAMETER  DeviceAddress is NULL.

+   @retval EFI_INVALID_PARAMETER  Mapping is NULL.

+   @retval EFI_UNSUPPORTED        The HostAddress cannot be mapped as a common buffer.

+   @retval EFI_DEVICE_ERROR       The system hardware could not map the requested address.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoMap (

@@ -890,7 +1428,6 @@ RootBridgeIoMap (
   OUT    EFI_PHYSICAL_ADDRESS                       *DeviceAddress,

   OUT    VOID                                       **Mapping

   )

-

 {

   EFI_STATUS            Status;

   EFI_PHYSICAL_ADDRESS  PhysicalAddress;

@@ -999,13 +1536,28 @@ RootBridgeIoMap (
   return EFI_SUCCESS;

 }

 

+/**

+   Completes the Map() operation and releases any corresponding resources.

+

+   The Unmap() function completes the Map() operation and releases any corresponding resources.

+   If the operation was an EfiPciOperationBusMasterWrite or

+   EfiPciOperationBusMasterWrite64, the data is committed to the target system memory.

+   Any resources used for the mapping are freed.  

+

+   @param[in] This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in] Mapping   The mapping value returned from Map().

+   

+   @retval EFI_SUCCESS            The range was unmapped.

+   @retval EFI_INVALID_PARAMETER  Mapping is not a value that was returned by Map().

+   @retval EFI_DEVICE_ERROR       The data was not committed to the target system memory.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoUnmap (

   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *This,

   IN VOID                             *Mapping

   )

-

 {

   MAP_INFO    *MapInfo;

 

@@ -1041,6 +1593,27 @@ RootBridgeIoUnmap (
   return EFI_SUCCESS;

 }

 

+/**

+   Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or

+   EfiPciOperationBusMasterCommonBuffer64 mapping.

+  

+   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param Type        This parameter is not used and must be ignored.

+   @param MemoryType  The type of memory to allocate, EfiBootServicesData or EfiRuntimeServicesData.

+   @param Pages       The number of pages to allocate.

+   @param HostAddress A pointer to store the base system memory address of the allocated range.

+   @param Attributes  The requested bit mask of attributes for the allocated range. Only

+                      the attributes EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE, EFI_PCI_ATTRIBUTE_MEMORY_CACHED, 

+                      and EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE may be used with this function.

+   

+   @retval EFI_SUCCESS            The requested memory pages were allocated.

+   @retval EFI_INVALID_PARAMETER  MemoryType is invalid.

+   @retval EFI_INVALID_PARAMETER  HostAddress is NULL.

+   @retval EFI_UNSUPPORTED        Attributes is unsupported. The only legal attribute bits are

+                                  MEMORY_WRITE_COMBINE, MEMORY_CACHED, and DUAL_ADDRESS_CYCLE.

+   @retval EFI_OUT_OF_RESOURCES   The memory pages could not be allocated.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoAllocateBuffer (

@@ -1051,7 +1624,6 @@ RootBridgeIoAllocateBuffer (
   OUT VOID                             **HostAddress,

   IN  UINT64                           Attributes

   )

-

 {

   EFI_STATUS            Status;

   EFI_PHYSICAL_ADDRESS  PhysicalAddress;

@@ -1092,6 +1664,20 @@ RootBridgeIoAllocateBuffer (
   return EFI_SUCCESS;

 }

 

+/**

+   Frees memory that was allocated with AllocateBuffer().

+

+   The FreeBuffer() function frees memory that was allocated with AllocateBuffer().

+

+   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param Pages       The number of pages to free.

+   @param HostAddress The base system memory address of the allocated range.

+   

+   @retval EFI_SUCCESS            The requested memory pages were freed.

+   @retval EFI_INVALID_PARAMETER  The memory range specified by HostAddress and Pages

+                                  was not allocated with AllocateBuffer().

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoFreeBuffer (

@@ -1099,25 +1685,34 @@ RootBridgeIoFreeBuffer (
   IN  UINTN                            Pages,

   OUT VOID                             *HostAddress

   )

-

 {

   return gBS->FreePages ((EFI_PHYSICAL_ADDRESS) (UINTN) HostAddress, Pages);

 }

 

+/**

+   Flushes all PCI posted write transactions from a PCI host bridge to system memory.

+

+   The Flush() function flushes any PCI posted write transactions from a PCI host bridge to system

+   memory. Posted write transactions are generated by PCI bus masters when they perform write

+   transactions to target addresses in system memory.

+   This function does not flush posted write transactions from any PCI bridges. A PCI controller

+   specific action must be taken to guarantee that the posted write transactions have been flushed from

+   the PCI controller and from all the PCI bridges into the PCI host bridge. This is typically done with

+   a PCI read transaction from the PCI controller prior to calling Flush().

+

+   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   

+   @retval EFI_SUCCESS        The PCI posted write transactions were flushed from the PCI host

+                              bridge to system memory.

+   @retval EFI_DEVICE_ERROR   The PCI posted write transactions were not flushed from the PCI

+                              host bridge due to a hardware error.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoFlush (

   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This

   )

-/*++

-

-Routine Description:

-

-Arguments:

-    

-Returns:

-

---*/

 {

   //

   // not supported yet

@@ -1125,6 +1720,26 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+   Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the

+   attributes that a PCI root bridge is currently using.  

+

+   The GetAttributes() function returns the mask of attributes that this PCI root bridge supports

+   and the mask of attributes that the PCI root bridge is currently using.

+

+   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param Supported   A pointer to the mask of attributes that this PCI root bridge

+                      supports setting with SetAttributes().

+   @param Attributes  A pointer to the mask of attributes that this PCI root bridge is

+                      currently using.

+   

+   @retval  EFI_SUCCESS           If Supports is not NULL, then the attributes that the PCI root

+                                  bridge supports is returned in Supports. If Attributes is

+                                  not NULL, then the attributes that the PCI root bridge is currently

+                                  using is returned in Attributes.

+   @retval  EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoGetAttributes (

@@ -1132,15 +1747,6 @@ RootBridgeIoGetAttributes (
   OUT UINT64                           *Supported,

   OUT UINT64                           *Attributes

   )

-/*++

-

-Routine Description:

-

-Arguments:

-    

-Returns:

-

---*/

 {

   PCI_ROOT_BRIDGE_INSTANCE *PrivateData;

 

@@ -1164,6 +1770,36 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+   Sets attributes for a resource range on a PCI root bridge.

+

+   The SetAttributes() function sets the attributes specified in Attributes for the PCI root

+   bridge on the resource range specified by ResourceBase and ResourceLength. Since the

+   granularity of setting these attributes may vary from resource type to resource type, and from

+   platform to platform, the actual resource range and the one passed in by the caller may differ. As a

+   result, this function may set the attributes specified by Attributes on a larger resource range

+   than the caller requested. The actual range is returned in ResourceBase and

+   ResourceLength. The caller is responsible for verifying that the actual range for which the

+   attributes were set is acceptable.

+

+   @param[in]       This            A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]       Attributes      The mask of attributes to set. If the attribute bit

+                                    MEMORY_WRITE_COMBINE, MEMORY_CACHED, or

+                                    MEMORY_DISABLE is set, then the resource range is specified by

+                                    ResourceBase and ResourceLength. If

+                                    MEMORY_WRITE_COMBINE, MEMORY_CACHED, and

+                                    MEMORY_DISABLE are not set, then ResourceBase and

+                                    ResourceLength are ignored, and may be NULL.

+   @param[in][out]  ResourceBase    A pointer to the base address of the resource range to be modified

+                                    by the attributes specified by Attributes.

+   @param[in][out]  ResourceLength  A pointer to the length of the resource range to be modified by the

+                                    attributes specified by Attributes.

+   

+   @retval  EFI_SUCCESS     The current configuration of this PCI root bridge was returned in Resources.

+   @retval  EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be retrieved.

+   @retval  EFI_INVALID_PARAMETER Invalid pointer of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoSetAttributes (

@@ -1172,15 +1808,6 @@ RootBridgeIoSetAttributes (
   IN OUT UINT64                           *ResourceBase,

   IN OUT UINT64                           *ResourceLength 

   )

-/*++

-

-Routine Description:

-

-Arguments:

-    

-Returns:

-

---*/

 {

   PCI_ROOT_BRIDGE_INSTANCE            *PrivateData;

   

@@ -1205,21 +1832,35 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+   Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI 2.0

+   resource descriptors.

+

+   There are only two resource descriptor types from the ACPI Specification that may be used to

+   describe the current resources allocated to a PCI root bridge. These are the QWORD Address

+   Space Descriptor (ACPI 2.0 Section 6.4.3.5.1), and the End Tag (ACPI 2.0 Section 6.4.2.8). The

+   QWORD Address Space Descriptor can describe memory, I/O, and bus number ranges for dynamic

+   or fixed resources. The configuration of a PCI root bridge is described with one or more QWORD

+   Address Space Descriptors followed by an End Tag.

+

+   @param[in]   This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[out]  Resources   A pointer to the ACPI 2.0 resource descriptors that describe the

+                            current configuration of this PCI root bridge. The storage for the

+                            ACPI 2.0 resource descriptors is allocated by this function. The

+                            caller must treat the return buffer as read-only data, and the buffer

+                            must not be freed by the caller.

+   

+   @retval  EFI_SUCCESS     The current configuration of this PCI root bridge was returned in Resources.

+   @retval  EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be retrieved.

+   @retval  EFI_INVALID_PARAMETER Invalid pointer of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL

+

+**/

 EFI_STATUS

 EFIAPI

 RootBridgeIoConfiguration (

   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL     *This,

   OUT VOID                                **Resources

   )

-/*++

-

-Routine Description:

-

-Arguments:

-    

-Returns:

-

---*/

 {

   PCI_ROOT_BRIDGE_INSTANCE              *PrivateData;

   UINTN                                 Index;

@@ -1241,6 +1882,24 @@ Returns:
 //

 // Internal function

 //

+/**

+   Internal help function for read and write PCI configuration space.

+

+   @param[in]   This          A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+   @param[in]   Write         Switch value for Read or Write.

+   @param[in]   Width         Signifies the width of the memory operations.

+   @param[in]   UserAddress   The address within the PCI configuration space for the PCI controller.

+   @param[in]   Count         The number of PCI configuration operations to perform. Bytes

+                              moved is Width size * Count, starting at Address.

+   @param[out]  UserBuffer    For read operations, the destination buffer to store the results. For

+                              write operations, the source buffer to write data from.

+   

+   @retval EFI_SUCCESS            The data was read from or written to the PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.

+   @retval EFI_INVALID_PARAMETER  Buffer is NULL.

+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.

+

+**/

 EFI_STATUS

 RootBridgeIoPciRW (

   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL        *This,