Add function doxygen header for PciBus module.

[mirror_edk2.git] / IntelFrameworkModulePkg / Bus / Pci / PciBusDxe / PciLib.c

diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.c b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.c
index 658992b1acec5df9c72845eb03f832cce7cbac36..587f1767d733982cbfe16db41abd7071cecbd907 100644 (file)
--- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.c
+++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.c
@@ -21,23 +21,14 @@ GLOBAL_REMOVE_IF_UNREFERENCED EFI_PCI_HOTPLUG_REQUEST_PROTOCOL gPciHotPlugReques
   PciHotPlugRequestNotify\r
 };\r
 \r
-\r
+/**\r
+  Install protocol gEfiPciHotPlugRequestProtocolGuid\r
+  @param Status    return status of protocol installation.\r
+**/\r
 VOID\r
 InstallHotPlugRequestProtocol (\r
   IN EFI_STATUS *Status\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-  Status   - A pointer to the status.\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
 {\r
   EFI_HANDLE  Handle;\r
 \r
@@ -54,23 +45,17 @@ Returns:
                   );\r
 }\r
 \r
+/**\r
+  Install protocol gEfiPciHotplugDeviceGuid into hotplug device\r
+  instance\r
+  \r
+  @param PciIoDevice  hotplug device instance\r
+  \r
+**/\r
 VOID\r
 InstallPciHotplugGuid (\r
   IN  PCI_IO_DEVICE                  *PciIoDevice\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-  PciIoDevice    -  A pointer to the PCI_IO_DEVICE.\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
 {\r
   EFI_STATUS  Status;\r
 \r
@@ -90,23 +75,17 @@ Returns:
   }\r
 }\r
 \r
+/**\r
+  UnInstall protocol gEfiPciHotplugDeviceGuid into hotplug device\r
+  instance\r
+  \r
+  @param PciIoDevice  hotplug device instance\r
+  \r
+**/\r
 VOID\r
 UninstallPciHotplugGuid (\r
   IN  PCI_IO_DEVICE                  *PciIoDevice\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-  PciIoDevice    - A pointer to the PCI_IO_DEVICE.\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
 {\r
   EFI_STATUS  Status;\r
 \r
@@ -136,24 +115,15 @@ Returns:
   }\r
 }\r
 \r
+/**\r
+  Retrieve the BAR information via PciIo interface\r
+  \r
+  @param PciIoDevice Pci device instance\r
+**/\r
 VOID\r
 GetBackPcCardBar (\r
   IN  PCI_IO_DEVICE                  *PciIoDevice\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-\r
-Arguments:\r
-\r
-  PciIoDevice      - A pointer to the PCI_IO_DEVICE.\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
 {\r
   UINT32  Address;\r
 \r
@@ -222,27 +192,20 @@ Returns:
   }\r
 }\r
 \r
+/**\r
+  Remove rejected pci device from specific root bridge\r
+  handle.\r
+  \r
+  @param RootBridgeHandle  specific parent root bridge handle\r
+  @param Bridge            Bridge device instance\r
+  \r
+  @retval EFI_SUCCESS  Success operation.\r
+**/\r
 EFI_STATUS\r
 RemoveRejectedPciDevices (\r
   EFI_HANDLE        RootBridgeHandle,\r
   IN PCI_IO_DEVICE  *Bridge\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-\r
-Arguments:\r
-\r
-  RootBridgeHandle   - An efi handle.\r
-  Bridge             - An pointer to the PCI_IO_DEVICE.\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   PCI_IO_DEVICE   *Temp;\r
   LIST_ENTRY      *CurrentLink;\r
@@ -295,6 +258,12 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
+/**\r
+  Wrapper function for allocating resource for pci host bridge.\r
+  \r
+  @param PciResAlloc Point to protocol instance EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL\r
+  \r
+**/\r
 EFI_STATUS\r
 PciHostBridgeResourceAllocator (\r
   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc\r
@@ -311,27 +280,17 @@ PciHostBridgeResourceAllocator (
   }\r
 }\r
 \r
+/**\r
+  Submits the I/O and memory resource requirements for the specified PCI Root Bridge\r
+\r
+  @param PciResAlloc  Point to protocol instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL\r
 \r
+  @retval EFI_SUCCESS           Success\r
+**/\r
 EFI_STATUS\r
 PciHostBridgeResourceAllocator_WithoutHotPlugDeviceSupport (\r
   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    PciResAlloc - add argument and description to function comment\r
-// TODO:    EFI_NOT_FOUND - add return value to function comment\r
-// TODO:    EFI_OUT_OF_RESOURCES - add return value to function comment\r
-// TODO:    EFI_NOT_FOUND - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   PCI_IO_DEVICE                   *RootBridgeDev;\r
   EFI_HANDLE                      RootBridgeHandle;\r
@@ -684,30 +643,18 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
+/**\r
+  Submits the I/O and memory resource requirements for the specified PCI Root Bridge\r
+\r
+  @param PciResAlloc  Point to protocol instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL\r
+\r
+  @retval EFI_SUCCESS           Success\r
+**/\r
 \r
 EFI_STATUS\r
 PciHostBridgeResourceAllocator_WithHotPlugDeviceSupport (\r
   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-  Host brige resource allocator.\r
-\r
-Arguments:\r
-\r
-  PciResAlloc  - A pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.\r
-\r
-Returns:\r
-\r
-  EFI Status.\r
-\r
-**/\r
-// TODO:    EFI_NOT_FOUND - add return value to function comment\r
-// TODO:    EFI_NOT_FOUND - add return value to function comment\r
-// TODO:    EFI_NOT_FOUND - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   PCI_IO_DEVICE                         *RootBridgeDev;\r
   EFI_HANDLE                            RootBridgeHandle;\r
@@ -1190,7 +1137,18 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
-\r
+/**\r
+  Wapper function of scanning pci bus and assign bus number to the given PCI bus system\r
+  Feature flag PcdPciBusHotplugDeviceSupport determine whether need support hotplug  \r
+  \r
+  @param  Bridge          Bridge device instance\r
+  @param  StartBusNumber  start point\r
+  @param  SubBusNumber    Point to sub bus number\r
+  @param  PaddedBusRange  Customized bus number\r
+  \r
+  @retval EFI_SUCCESS     Success\r
+  @retval EFI_DEVICE_ERROR Fail to scan bus\r
+**/\r
 EFI_STATUS\r
 PciScanBus (\r
   IN PCI_IO_DEVICE                      *Bridge,\r
@@ -1216,7 +1174,18 @@ PciScanBus (
   }\r
 }\r
 \r
-\r
+/**\r
+  Wapper function of scanning pci bus and assign bus number to the given PCI bus system\r
+  Feature flag PcdPciBusHotplugDeviceSupport determine whether need support hotplug  \r
+  \r
+  @param  Bridge          Bridge device instance\r
+  @param  StartBusNumber  start point\r
+  @param  SubBusNumber    Point to sub bus number\r
+  @param  PaddedBusRange  Customized bus number\r
+  \r
+  @retval EFI_SUCCESS     Success\r
+  @retval EFI_DEVICE_ERROR Fail to scan bus\r
+**/\r
 EFI_STATUS\r
 PciScanBus_WithoutHotPlugDeviceSupport (\r
   IN PCI_IO_DEVICE                      *Bridge,\r
@@ -1224,25 +1193,6 @@ PciScanBus_WithoutHotPlugDeviceSupport (
   OUT UINT8                             *SubBusNumber,\r
   OUT UINT8                             *PaddedBusRange\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-  This routine is used to assign bus number to the given PCI bus system\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    Bridge - add argument and description to function comment\r
-// TODO:    StartBusNumber - add argument and description to function comment\r
-// TODO:    SubBusNumber - add argument and description to function comment\r
-// TODO:    PaddedBusRange - add argument and description to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   EFI_STATUS                      Status;\r
   PCI_TYPE00                      Pci;\r
@@ -1402,6 +1352,18 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
+/**\r
+  Wapper function of scanning pci bus and assign bus number to the given PCI bus system\r
+  Feature flag PcdPciBusHotplugDeviceSupport determine whether need support hotplug  \r
+  \r
+  @param  Bridge          Bridge device instance\r
+  @param  StartBusNumber  start point\r
+  @param  SubBusNumber    Point to sub bus number\r
+  @param  PaddedBusRange  Customized bus number\r
+  \r
+  @retval EFI_SUCCESS     Success\r
+  @retval EFI_DEVICE_ERROR Fail to scan bus\r
+**/\r
 EFI_STATUS\r
 PciScanBus_WithHotPlugDeviceSupport (\r
   IN PCI_IO_DEVICE                      *Bridge,\r
@@ -1409,26 +1371,6 @@ PciScanBus_WithHotPlugDeviceSupport (
   OUT UINT8                             *SubBusNumber,\r
   OUT UINT8                             *PaddedBusRange\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-  This routine is used to assign bus number to the given PCI bus system\r
-\r
-Arguments:\r
-\r
-  Bridge         - A pointer to the PCI_IO_DEVICE structure.\r
-  StartBusNumber - The start bus number.\r
-  SubBusNumber   - A pointer to the sub bus number.\r
-  PaddedBusRange - A pointer to the padded bus range.\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   EFI_STATUS                        Status;\r
   PCI_TYPE00                        Pci;\r
@@ -1700,25 +1642,17 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
+/**\r
+  Process Option Rom on this host bridge\r
+  \r
+  @param Bridge  Pci bridge device instance\r
+  \r
+  @retval EFI_SUCCESS Success\r
+**/\r
 EFI_STATUS\r
 PciRootBridgeP2CProcess (\r
   IN PCI_IO_DEVICE *Bridge\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-    Process Option Rom on this host bridge\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    Bridge - add argument and description to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   LIST_ENTRY      *CurrentLink;\r
   PCI_IO_DEVICE   *Temp;\r
@@ -1823,30 +1757,20 @@ PciHostBridgeP2CProcess (
   return EFI_SUCCESS;\r
 }\r
 \r
-EFI_STATUS\r
-PciHostBridgeEnumerator (\r
-  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *PciResAlloc\r
-  )\r
 /**\r
-\r
-Routine Description:\r
-\r
   This function is used to enumerate the entire host bridge\r
   in a given platform\r
 \r
-Arguments:\r
-\r
-  PciResAlloc   - A pointer to the resource allocate protocol.\r
+  @param PciResAlloc   A pointer to the resource allocate protocol.\r
 \r
-Returns:\r
-\r
-  None\r
+  @retval EFI_OUT_OF_RESOURCES no enough resource\r
+  @retval EFI_SUCCESS Success\r
 \r
 **/\r
-// TODO:    EFI_OUT_OF_RESOURCES - add return value to function comment\r
-// TODO:    EFI_OUT_OF_RESOURCES - add return value to function comment\r
-// TODO:    EFI_OUT_OF_RESOURCES - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
+EFI_STATUS\r
+PciHostBridgeEnumerator (\r
+  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *PciResAlloc\r
+  )\r
 {\r
   EFI_HANDLE                        RootBridgeHandle;\r
   PCI_IO_DEVICE                     *RootBridgeDev;\r
@@ -2933,3 +2857,4 @@ PciIoWrite (
                    );\r
   }\r
 }\r
+\r