Add function doxygen header for PciBus module.

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

diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.c b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.c
index ee95864f1b0b038963b537b24688cd6b9a7b8025..22bef0df3df5e619dc24ffca25257a17de08a82e 100644 (file)
--- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.c
+++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.c
@@ -1,5 +1,6 @@
 /**@file\r
-\r
+  This module provide support function for hot plug device.\r
+  \r
 Copyright (c) 2006, Intel Corporation                                                         \r
 All rights reserved. This program and the accompanying materials                          \r
 are licensed and made available under the terms and conditions of the BSD License         \r
@@ -20,25 +21,18 @@ EFI_HPC_LOCATION                *gPciRootHpcPool;
 UINTN                           gPciRootHpcCount;\r
 ROOT_HPC_DATA                   *gPciRootHpcData;\r
 \r
+/**\r
+  Init HPC private data.\r
+  \r
+  @param  Event     event object\r
+  @param  Context   HPC private data.\r
+**/\r
 VOID\r
 EFIAPI\r
 PciHPCInitialized (\r
   IN EFI_EVENT    Event,\r
   IN VOID         *Context\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    Event - add argument and description to function comment\r
-// TODO:    Context - add argument and description to function comment\r
 {\r
   ROOT_HPC_DATA *HpcData;\r
 \r
@@ -47,24 +41,20 @@ Returns:
 \r
 }\r
 \r
+/**\r
+  Compare two device path\r
+  \r
+  @param DevicePath1    the first device path want to be compared\r
+  @param DevicePath2    the first device path want to be compared\r
+  \r
+  @retval TRUE    equal\r
+  @retval FALSE   different\r
+**/\r
 BOOLEAN\r
 EfiCompareDevicePath (\r
   IN EFI_DEVICE_PATH_PROTOCOL *DevicePath1,\r
   IN EFI_DEVICE_PATH_PROTOCOL *DevicePath2\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    DevicePath1 - add argument and description to function comment\r
-// TODO:    DevicePath2 - add argument and description to function comment\r
 {\r
   UINTN Size1;\r
   UINTN Size2;\r
@@ -83,24 +73,14 @@ Returns:
   return TRUE;\r
 }\r
 \r
+/**\r
+  Init hot plug support and root hot plug private data.\r
+  \r
+**/\r
 EFI_STATUS\r
 InitializeHotPlugSupport (\r
   VOID\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    EFI_UNSUPPORTED - 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
 {\r
   EFI_STATUS        Status;\r
   EFI_HPC_LOCATION  *HpcList;\r
@@ -148,26 +128,20 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
+/**\r
+  Test whether device path is for root pci hot plug bus\r
+  \r
+  @param HpbdevicePath  tested device path\r
+  @param HpIndex        Return the index of root hot plug in global array.\r
+  \r
+  @retval TRUE  device path is for root pci hot plug\r
+  @retval FALSE device path is not for root pci hot plug\r
+**/\r
 BOOLEAN\r
 IsRootPciHotPlugBus (\r
   IN EFI_DEVICE_PATH_PROTOCOL         *HpbDevicePath,\r
   OUT UINTN                           *HpIndex\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-  HpcDevicePath       - A pointer to the EFI_DEVICE_PATH_PROTOCOL.\r
-  HpIndex             - A pointer to the Index.\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    HpbDevicePath - add argument and description to function comment\r
 {\r
   UINTN Index;\r
 \r
@@ -186,25 +160,20 @@ Returns:
   return FALSE;\r
 }\r
 \r
+/**\r
+  Test whether device path is for root pci hot plug controller\r
+  \r
+  @param HpbdevicePath  tested device path\r
+  @param HpIndex        Return the index of root hot plug in global array.\r
+  \r
+  @retval TRUE  device path is for root pci hot plug controller\r
+  @retval FALSE device path is not for root pci hot plug controller\r
+**/\r
 BOOLEAN\r
 IsRootPciHotPlugController (\r
   IN EFI_DEVICE_PATH_PROTOCOL         *HpcDevicePath,\r
   OUT UINTN                           *HpIndex\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-  HpcDevicePath       - A pointer to the EFI_DEVICE_PATH_PROTOCOL.\r
-  HpIndex             - A pointer to the Index.\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
 {\r
   UINTN Index;\r
 \r
@@ -223,24 +192,19 @@ Returns:
   return FALSE;\r
 }\r
 \r
+/**\r
+  Wrapper for creating event object for HPC \r
+  \r
+  @param  HpIndex   index of hot plug device in global array\r
+  @param  Event     event object\r
+  \r
+  @return status of create event invoken\r
+**/\r
 EFI_STATUS\r
 CreateEventForHpc (\r
   IN UINTN       HpIndex,\r
   OUT EFI_EVENT  *Event\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    HpIndex - add argument and description to function comment\r
-// TODO:    Event - add argument and description to function comment\r
 {\r
   EFI_STATUS  Status;\r
 \r
@@ -259,22 +223,15 @@ Returns:
   return Status;\r
 }\r
 \r
+/**\r
+  Wait for all root HPC initialized.\r
+  \r
+  @param TimeoutInMicroSeconds  microseconds to wait for all root hpc's initialization\r
+**/\r
 EFI_STATUS\r
 AllRootHPCInitialized (\r
   IN  UINTN           TimeoutInMicroSeconds\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-  TimeoutInMicroSeconds - microseconds to wait for all root hpc's initialization\r
-\r
-Returns:\r
-  EFI_SUCCESS - All root hpc's initialization is finished before the timeout\r
-  EFI_TIMEOUT - Time out\r
-\r
-**/\r
 {\r
   UINT32  Delay;\r
   UINTN   Index;\r
@@ -305,25 +262,18 @@ Returns:
   return EFI_TIMEOUT;\r
 }\r
 \r
+/**\r
+  Check HPC capability register block\r
+  \r
+  @param PciIoDevice PCI device instance\r
+  \r
+  @retval EFI_SUCCESS   PCI device is HPC\r
+  @retval EFI_NOT_FOUND PCI device is not HPC\r
+**/\r
 EFI_STATUS\r
 IsSHPC (\r
   PCI_IO_DEVICE                       *PciIoDevice\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    PciIoDevice - add argument and description 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
-// TODO:    EFI_NOT_FOUND - add return value to function comment\r
 {\r
 \r
   EFI_STATUS  Status;\r
@@ -352,6 +302,14 @@ Returns:
   return EFI_NOT_FOUND;\r
 }\r
 \r
+/**\r
+  Get resource padding for hot plug bus\r
+  \r
+  @param PciIoDevice PCI device instance\r
+  \r
+  @retval EFI_SUCCESS   success get padding and set it into PCI device instance\r
+  @retval EFI_NOT_FOUND PCI device is not a hot plug bus.\r
+**/\r
 EFI_STATUS\r
 GetResourcePaddingForHpb (\r
   IN PCI_IO_DEVICE *PciIoDevice\r
@@ -405,25 +363,18 @@ Returns:
   return EFI_NOT_FOUND;\r
 }\r
 \r
+/**\r
+  Test whether PCI device is hot plug bus.\r
+  \r
+  @param PciIoDevice  PCI device instance\r
+  \r
+  @retval EFI_SUCCESS   PCI device is hot plug bus\r
+  @retval EFI_NOT_FOUND PCI device is not hot plug bus\r
+**/\r
 EFI_STATUS\r
 IsPciHotPlugBus (\r
   PCI_IO_DEVICE                       *PciIoDevice\r
   )\r
-/**\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
-**/\r
-// TODO:    PciIoDevice - add argument and description to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
-// TODO:    EFI_NOT_FOUND - add return value to function comment\r
 {\r
   BOOLEAN     Result;\r
   EFI_STATUS  Status;\r
@@ -449,3 +400,4 @@ Returns:
 \r
   return EFI_NOT_FOUND;\r
 }\r
+\r