MdeModulePkg/PciHostBridge: Refine function header comments.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Ruiyu Ni <ruiyu.ni@intel.com>
Cc: Shumin Qiu <shumin.qiu@intel.com>
Reviewed-by: Qiu Shumin <shumin.qiu@intel.com>

4 files changed, 103 insertions, 81 deletions

diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c
index 08285d8..edf042c 100644
--- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c
+++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c
@@ -258,6 +258,19 @@ ResourceConflict (
   FreePool (Resources);

 }

 

+/**

+  Allocate Length of MMIO or IO resource with alignment BitsOfAlignment

+  from GCD range [BaseAddress, Limit).

+

+  @param Mmio            TRUE for MMIO and FALSE for IO.

+  @param Length          Length of the resource to allocate.

+  @param BitsOfAlignment Alignment of the resource to allocate.

+  @param BaseAddress     The starting address the allocation is from.

+  @param Limit           The ending address the allocation is to.

+

+  @retval  The base address of the allocated resource or MAX_UINT64 if allocation

+           fails.

+**/

 UINT64

 AllocateResource (

   BOOLEAN Mmio,

@@ -306,6 +319,7 @@ AllocateResource (
   }

   return MAX_UINT64;

 }

+

 /**

 

   Enter a certain phase of the PCI enumeration process.

diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h
index 288823c..9a8ca21 100644
--- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h
+++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h
@@ -65,12 +65,12 @@ InitializePciHostBridge (
 

   Enter a certain phase of the PCI enumeration process.

 

-  @param This   -  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.

-  @param Phase  -  The phase during enumeration.

+  @param This   The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.

+  @param Phase  The phase during enumeration.

 

-  @retval EFI_SUCCESS            -  Succeed.

-  @retval EFI_INVALID_PARAMETER  -  Wrong phase parameter passed in.

-  @retval EFI_NOT_READY          -  Resources have not been submitted yet.

+  @retval EFI_SUCCESS            Succeed.

+  @retval EFI_INVALID_PARAMETER  Wrong phase parameter passed in.

+  @retval EFI_NOT_READY          Resources have not been submitted yet.

 

 **/

 EFI_STATUS

@@ -85,15 +85,15 @@ NotifyPhase (
   Return the device handle of the next PCI root bridge that is associated with

   this Host Bridge.

 

-  @param This              - The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance.

-  RootBridgeHandle  -  Returns the device handle of the next PCI Root Bridge.

-                       On input, it holds the RootBridgeHandle returned by the most

-                       recent call to GetNextRootBridge().The handle for the first

-                       PCI Root Bridge is returned if RootBridgeHandle is NULL on input.

+  @param This              The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance.

+  @param RootBridgeHandle  Returns the device handle of the next PCI Root Bridge.

+                           On input, it holds the RootBridgeHandle returned by the most

+                           recent call to GetNextRootBridge().The handle for the first

+                           PCI Root Bridge is returned if RootBridgeHandle is NULL on input.

 

-  @retval EFI_SUCCESS            -  Succeed.

-  @retval EFI_NOT_FOUND          -  Next PCI root bridge not found.

-  @retval EFI_INVALID_PARAMETER  -  Wrong parameter passed in.

+  @retval EFI_SUCCESS            Succeed.

+  @retval EFI_NOT_FOUND          Next PCI root bridge not found.

+  @retval EFI_INVALID_PARAMETER  Wrong parameter passed in.

 

 **/

 EFI_STATUS

diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h
index 2915981..b1e83f1 100644
--- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h
+++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h
@@ -86,15 +86,13 @@ typedef struct {
 #define ROOT_BRIDGE_FROM_LINK(a) CR (a, PCI_ROOT_BRIDGE_INSTANCE, Link, PCI_ROOT_BRIDGE_SIGNATURE)

 

 /**

+  Construct the Pci Root Bridge instance.

 

-  Construct the Pci Root Bridge Io protocol.

-

-  @param Protocol          -  Protocol to initialize.

-  @param HostBridgeHandle  -  Handle to the HostBridge.

-

-  @retval EFI_SUCCESS  -  Success.

-  @retval Others       -  Fail.

+  @param Bridge            The root bridge instance.

+  @param HostBridgeHandle  Handle to the HostBridge.

 

+  @return The pointer to PCI_ROOT_BRIDGE_INSTANCE just created

+          or NULL if creation fails.

 **/

 PCI_ROOT_BRIDGE_INSTANCE *

 CreateRootBridge (

@@ -359,30 +357,25 @@ RootBridgeIoPciWrite (
 ;

 

 /**

-

   Provides the PCI controller-specific address needed to access

   system memory for DMA.

 

-  @param This           -  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

-  @param Operation      -  Indicate if the bus master is going to read or write

-                           to system memory.

-  @param HostAddress    -  The system memory address to map on the PCI controller.

-  @param NumberOfBytes  -  On input the number of bytes to map.

-                           On output the number of bytes that were mapped.

-  @param DeviceAddress  -  The resulting map address for the bus master PCI

-                           controller to use to access the system memory's HostAddress.

-  @param Mapping        -  The value to pass to Unmap() when the bus master DMA

-                           operation is complete.

-

-  @retval EFI_SUCCESS            -  Success.

-  @retval EFI_INVALID_PARAMETER  -  Invalid parameters found.

-  @retval EFI_UNSUPPORTED        -  The HostAddress cannot be mapped as a common

-                            @retval buffer.

-  @retval EFI_DEVICE_ERROR       -  The System hardware could not map the requested

-                            @retval address.

-  @retval EFI_OUT_OF_RESOURCES   -  The request could not be completed due to

-                            @retval lack of resources.

-

+  @param This           A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

+  @param Operation      Indicate if the bus master is going to read or write

+                        to system memory.

+  @param HostAddress    The system memory address to map on the PCI controller.

+  @param NumberOfBytes  On input the number of bytes to map.

+                        On output the number of bytes that were mapped.

+  @param DeviceAddress  The resulting map address for the bus master PCI

+                        controller to use to access the system memory's HostAddress.

+  @param Mapping        The value to pass to Unmap() when the bus master DMA

+                        operation is complete.

+

+  @retval EFI_SUCCESS            Success.

+  @retval EFI_INVALID_PARAMETER  Invalid parameters found.

+  @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 lack of resources.

 **/

 EFI_STATUS

 EFIAPI

@@ -397,18 +390,21 @@ RootBridgeIoMap (
 ;

 

 /**

-

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

 

-  @param This     -  Pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.

-  Mapping  -  The value returned from Map() operation.

+  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.

 

-  @retval EFI_SUCCESS            -  The range was unmapped successfully.

-  @retval EFI_INVALID_PARAMETER  -  Mapping is not a value that was returned

-                            @retval by Map operation.

-  @retval EFI_DEVICE_ERROR       -  The data was not committed to the target

-                            @retval system memory.

+  @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

@@ -419,22 +415,30 @@ RootBridgeIoUnmap (
 ;

 

 /**

-

-  Allocates pages that are suitable for a common buffer mapping.

-

-  @param This         -  Pointer to EFI_ROOT_BRIDGE_IO_PROTOCOL instance.

-  @param Type         -  Not used and can be ignored.

-  @param MemoryType   -  Type of memory to allocate.

-  @param Pages        -  Number of pages to allocate.

-  @param HostAddress  -  Pointer to store the base system memory address

-                         of the allocated range.

-  @param Attributes   -  Requested bit mask of attributes of the allocated

-                         range.

-

-  @retval EFI_SUCCESS            -  The requested memory range were allocated.

-  @retval EFI_INVALID_PARAMETER  -  Invalid parameter found.

-  @retval EFI_UNSUPPORTED        -  Attributes is unsupported.

-

+  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

@@ -491,19 +495,26 @@ RootBridgeIoFlush (
 ;

 

 /**

-

-  Get the attributes that a PCI root bridge supports and

-  the attributes the PCI root bridge is currently using.

-

-  @param This        -  Pointer to EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL

-                        instance.

-  @param Supports    -  A pointer to the mask of attributes that

-                        this PCI root bridge supports.

-  @param Attributes  -  A pointer to the mask of attributes that

-                        this PCI root bridge is currently using.

-  @retval EFI_SUCCESS            -  Success.

-  @retval EFI_INVALID_PARAMETER  -  Invalid parameter found.

-

+  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

diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c
index 6a9294d..332860e 100644
--- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c
+++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c
@@ -399,7 +399,6 @@ RootBridgeIoCheckParameter (
   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a

                                  lack of resources.

 **/

-

 EFI_STATUS

 EFIAPI

 RootBridgeIoPollMem (

@@ -987,7 +986,6 @@ RootBridgeIoPciWrite (
 }

 

 /**

-

   Provides the PCI controller-specific address needed to access

   system memory for DMA.

 

@@ -1007,7 +1005,6 @@ RootBridgeIoPciWrite (
   @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 lack of resources.

-

 **/

 EFI_STATUS

 EFIAPI