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>

diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c
index 08285d84d501239b0bc6136bb2f937b3986369a7..edf042cc254790a931f8e0130c4b5a6fea92f9ac 100644 (file)
--- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c
+++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c
@@ -258,6 +258,19 @@ ResourceConflict (
   FreePool (Resources);\r
 }\r
 \r
+/**\r
+  Allocate Length of MMIO or IO resource with alignment BitsOfAlignment\r
+  from GCD range [BaseAddress, Limit).\r
+\r
+  @param Mmio            TRUE for MMIO and FALSE for IO.\r
+  @param Length          Length of the resource to allocate.\r
+  @param BitsOfAlignment Alignment of the resource to allocate.\r
+  @param BaseAddress     The starting address the allocation is from.\r
+  @param Limit           The ending address the allocation is to.\r
+\r
+  @retval  The base address of the allocated resource or MAX_UINT64 if allocation\r
+           fails.\r
+**/\r
 UINT64\r
 AllocateResource (\r
   BOOLEAN Mmio,\r
@@ -306,6 +319,7 @@ AllocateResource (
   }\r
   return MAX_UINT64;\r
 }\r
+\r
 /**\r
 \r
   Enter a certain phase of the PCI enumeration process.\r

diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h
index 288823c7784aaa64bd3caecb5c850cbf40157fcf..9a8ca21f4819e33e5911174aa0c6a75d6b60359a 100644 (file)
--- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h
+++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h
@@ -65,12 +65,12 @@ InitializePciHostBridge (
 \r
   Enter a certain phase of the PCI enumeration process.\r
 \r
-  @param This   -  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.\r
-  @param Phase  -  The phase during enumeration.\r
+  @param This   The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.\r
+  @param Phase  The phase during enumeration.\r
 \r
-  @retval EFI_SUCCESS            -  Succeed.\r
-  @retval EFI_INVALID_PARAMETER  -  Wrong phase parameter passed in.\r
-  @retval EFI_NOT_READY          -  Resources have not been submitted yet.\r
+  @retval EFI_SUCCESS            Succeed.\r
+  @retval EFI_INVALID_PARAMETER  Wrong phase parameter passed in.\r
+  @retval EFI_NOT_READY          Resources have not been submitted yet.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -85,15 +85,15 @@ NotifyPhase (
   Return the device handle of the next PCI root bridge that is associated with\r
   this Host Bridge.\r
 \r
-  @param This              - The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance.\r
-  RootBridgeHandle  -  Returns the device handle of the next PCI Root Bridge.\r
-                       On input, it holds the RootBridgeHandle returned by the most\r
-                       recent call to GetNextRootBridge().The handle for the first\r
-                       PCI Root Bridge is returned if RootBridgeHandle is NULL on input.\r
+  @param This              The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance.\r
+  @param RootBridgeHandle  Returns the device handle of the next PCI Root Bridge.\r
+                           On input, it holds the RootBridgeHandle returned by the most\r
+                           recent call to GetNextRootBridge().The handle for the first\r
+                           PCI Root Bridge is returned if RootBridgeHandle is NULL on input.\r
 \r
-  @retval EFI_SUCCESS            -  Succeed.\r
-  @retval EFI_NOT_FOUND          -  Next PCI root bridge not found.\r
-  @retval EFI_INVALID_PARAMETER  -  Wrong parameter passed in.\r
+  @retval EFI_SUCCESS            Succeed.\r
+  @retval EFI_NOT_FOUND          Next PCI root bridge not found.\r
+  @retval EFI_INVALID_PARAMETER  Wrong parameter passed in.\r
 \r
 **/\r
 EFI_STATUS\r

diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h
index 2915981ea5536f9773052114bf84fac3039690c3..b1e83f1c9089f4f703101eb14b6738aea4543a77 100644 (file)
--- 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)\r
 \r
 /**\r
+  Construct the Pci Root Bridge instance.\r
 \r
-  Construct the Pci Root Bridge Io protocol.\r
-\r
-  @param Protocol          -  Protocol to initialize.\r
-  @param HostBridgeHandle  -  Handle to the HostBridge.\r
-\r
-  @retval EFI_SUCCESS  -  Success.\r
-  @retval Others       -  Fail.\r
+  @param Bridge            The root bridge instance.\r
+  @param HostBridgeHandle  Handle to the HostBridge.\r
 \r
+  @return The pointer to PCI_ROOT_BRIDGE_INSTANCE just created\r
+          or NULL if creation fails.\r
 **/\r
 PCI_ROOT_BRIDGE_INSTANCE *\r
 CreateRootBridge (\r
@@ -359,30 +357,25 @@ RootBridgeIoPciWrite (
 ;\r
 \r
 /**\r
-\r
   Provides the PCI controller-specific address needed to access\r
   system memory for DMA.\r
 \r
-  @param This           -  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.\r
-  @param Operation      -  Indicate if the bus master is going to read or write\r
-                           to system memory.\r
-  @param HostAddress    -  The system memory address to map on the PCI controller.\r
-  @param NumberOfBytes  -  On input the number of bytes to map.\r
-                           On output the number of bytes that were mapped.\r
-  @param DeviceAddress  -  The resulting map address for the bus master PCI\r
-                           controller to use to access the system memory's HostAddress.\r
-  @param Mapping        -  The value to pass to Unmap() when the bus master DMA\r
-                           operation is complete.\r
-\r
-  @retval EFI_SUCCESS            -  Success.\r
-  @retval EFI_INVALID_PARAMETER  -  Invalid parameters found.\r
-  @retval EFI_UNSUPPORTED        -  The HostAddress cannot be mapped as a common\r
-                            @retval buffer.\r
-  @retval EFI_DEVICE_ERROR       -  The System hardware could not map the requested\r
-                            @retval address.\r
-  @retval EFI_OUT_OF_RESOURCES   -  The request could not be completed due to\r
-                            @retval lack of resources.\r
-\r
+  @param This           A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.\r
+  @param Operation      Indicate if the bus master is going to read or write\r
+                        to system memory.\r
+  @param HostAddress    The system memory address to map on the PCI controller.\r
+  @param NumberOfBytes  On input the number of bytes to map.\r
+                        On output the number of bytes that were mapped.\r
+  @param DeviceAddress  The resulting map address for the bus master PCI\r
+                        controller to use to access the system memory's HostAddress.\r
+  @param Mapping        The value to pass to Unmap() when the bus master DMA\r
+                        operation is complete.\r
+\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_INVALID_PARAMETER  Invalid parameters found.\r
+  @retval EFI_UNSUPPORTED        The HostAddress cannot be mapped as a common buffer.\r
+  @retval EFI_DEVICE_ERROR       The System hardware could not map the requested address.\r
+  @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to lack of resources.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -397,18 +390,21 @@ RootBridgeIoMap (
 ;\r
 \r
 /**\r
-\r
   Completes the Map() operation and releases any corresponding resources.\r
 \r
-  @param This     -  Pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.\r
-  Mapping  -  The value returned from Map() operation.\r
+  The Unmap() function completes the Map() operation and releases any\r
+  corresponding resources.\r
+  If the operation was an EfiPciOperationBusMasterWrite or\r
+  EfiPciOperationBusMasterWrite64, the data is committed to the target system\r
+  memory.\r
+  Any resources used for the mapping are freed.\r
 \r
-  @retval EFI_SUCCESS            -  The range was unmapped successfully.\r
-  @retval EFI_INVALID_PARAMETER  -  Mapping is not a value that was returned\r
-                            @retval by Map operation.\r
-  @retval EFI_DEVICE_ERROR       -  The data was not committed to the target\r
-                            @retval system memory.\r
+  @param[in] This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.\r
+  @param[in] Mapping   The mapping value returned from Map().\r
 \r
+  @retval EFI_SUCCESS            The range was unmapped.\r
+  @retval EFI_INVALID_PARAMETER  Mapping is not a value that was returned by Map().\r
+  @retval EFI_DEVICE_ERROR       The data was not committed to the target system memory.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -419,22 +415,30 @@ RootBridgeIoUnmap (
 ;\r
 \r
 /**\r
-\r
-  Allocates pages that are suitable for a common buffer mapping.\r
-\r
-  @param This         -  Pointer to EFI_ROOT_BRIDGE_IO_PROTOCOL instance.\r
-  @param Type         -  Not used and can be ignored.\r
-  @param MemoryType   -  Type of memory to allocate.\r
-  @param Pages        -  Number of pages to allocate.\r
-  @param HostAddress  -  Pointer to store the base system memory address\r
-                         of the allocated range.\r
-  @param Attributes   -  Requested bit mask of attributes of the allocated\r
-                         range.\r
-\r
-  @retval EFI_SUCCESS            -  The requested memory range were allocated.\r
-  @retval EFI_INVALID_PARAMETER  -  Invalid parameter found.\r
-  @retval EFI_UNSUPPORTED        -  Attributes is unsupported.\r
-\r
+  Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer\r
+  or EfiPciOperationBusMasterCommonBuffer64 mapping.\r
+\r
+  @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.\r
+  @param Type        This parameter is not used and must be ignored.\r
+  @param MemoryType  The type of memory to allocate, EfiBootServicesData or\r
+                     EfiRuntimeServicesData.\r
+  @param Pages       The number of pages to allocate.\r
+  @param HostAddress A pointer to store the base system memory address of the\r
+                     allocated range.\r
+  @param Attributes  The requested bit mask of attributes for the allocated\r
+                     range. Only the attributes\r
+                     EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE,\r
+                     EFI_PCI_ATTRIBUTE_MEMORY_CACHED, and\r
+                     EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE may be used with this\r
+                     function.\r
+\r
+  @retval EFI_SUCCESS            The requested memory pages were allocated.\r
+  @retval EFI_INVALID_PARAMETER  MemoryType is invalid.\r
+  @retval EFI_INVALID_PARAMETER  HostAddress is NULL.\r
+  @retval EFI_UNSUPPORTED        Attributes is unsupported. The only legal\r
+                                 attribute bits are MEMORY_WRITE_COMBINE,\r
+                                 MEMORY_CACHED, and DUAL_ADDRESS_CYCLE.\r
+  @retval EFI_OUT_OF_RESOURCES   The memory pages could not be allocated.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -491,19 +495,26 @@ RootBridgeIoFlush (
 ;\r
 \r
 /**\r
-\r
-  Get the attributes that a PCI root bridge supports and\r
-  the attributes the PCI root bridge is currently using.\r
-\r
-  @param This        -  Pointer to EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL\r
-                        instance.\r
-  @param Supports    -  A pointer to the mask of attributes that\r
-                        this PCI root bridge supports.\r
-  @param Attributes  -  A pointer to the mask of attributes that\r
-                        this PCI root bridge is currently using.\r
-  @retval EFI_SUCCESS            -  Success.\r
-  @retval EFI_INVALID_PARAMETER  -  Invalid parameter found.\r
-\r
+  Gets the attributes that a PCI root bridge supports setting with\r
+  SetAttributes(), and the attributes that a PCI root bridge is currently\r
+  using.\r
+\r
+  The GetAttributes() function returns the mask of attributes that this PCI\r
+  root bridge supports and the mask of attributes that the PCI root bridge is\r
+  currently using.\r
+\r
+  @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.\r
+  @param Supported   A pointer to the mask of attributes that this PCI root\r
+                     bridge supports setting with SetAttributes().\r
+  @param Attributes  A pointer to the mask of attributes that this PCI root\r
+                     bridge is currently using.\r
+\r
+  @retval  EFI_SUCCESS           If Supports is not NULL, then the attributes\r
+                                 that the PCI root bridge supports is returned\r
+                                 in Supports. If Attributes is not NULL, then\r
+                                 the attributes that the PCI root bridge is\r
+                                 currently using is returned in Attributes.\r
+  @retval  EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r

diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c
index 6a9294d3495b8c54f5acbfa3c11d3b1189ab7cac..332860eb3819a8fbd1f83975cce8efc74c7c0ee1 100644 (file)
--- 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\r
                                  lack of resources.\r
 **/\r
-\r
 EFI_STATUS\r
 EFIAPI\r
 RootBridgeIoPollMem (\r
@@ -987,7 +986,6 @@ RootBridgeIoPciWrite (
 }\r
 \r
 /**\r
-\r
   Provides the PCI controller-specific address needed to access\r
   system memory for DMA.\r
 \r
@@ -1007,7 +1005,6 @@ RootBridgeIoPciWrite (
   @retval EFI_UNSUPPORTED        The HostAddress cannot be mapped as a common buffer.\r
   @retval EFI_DEVICE_ERROR       The System hardware could not map the requested address.\r
   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to lack of resources.\r
-\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r