add detailed description for functions.

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

diff --git a/IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h b/IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h
index 623ca7679cc9d3795ef106e745a4ff1deae43efb..a14ca9411af8c2978f6f0d25c359dba845f8ecc2 100644 (file)
--- a/IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h
+++ b/IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h
@@ -27,8 +27,9 @@
 /// Global ID for the PCI Hot Plug Protocol\r
 ///\r
 #define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \\r
-  { 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } }\r
-\r
+  { \\r
+    0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \\r
+  }\r
 \r
 typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL;\r
 \r
@@ -67,6 +68,9 @@ typedef struct{
 } EFI_HPC_LOCATION;\r
 \r
 \r
+///\r
+/// Describes how resource padding should be applied\r
+///\r
 typedef enum{\r
   EfiPaddingPciBus,\r
   EfiPaddingPciRootBridge\r
@@ -76,6 +80,15 @@ typedef enum{
   Returns a list of root Hot Plug Controllers (HPCs) that require initialization\r
   during the boot process.\r
 \r
+  This procedure returns a list of root HPCs. The PCI bus driver must initialize these controllers \r
+  during the boot process. The PCI bus driver may or may not be able to detect these HPCs. If the \r
+  platform includes a PCI-to-CardBus bridge, it can be included in this list if it requires initialization. \r
+  The HpcList must be self consistent. An HPC cannot control any of its parent buses. Only one HPC \r
+  can control a PCI bus. Because this list includes only root HPCs, no HPC in the list can be a child of \r
+  another HPC. This policy must be enforced by the EFI_PCI_HOT_PLUG_INIT_PROTOCOL. \r
+  The PCI bus driver may not check for such invalid conditions. \r
+  The callee allocates the buffer HpcList\r
+\r
   @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
   @param  HpcCount              The number of root HPCs that were returned.\r
   @param  HpcList               The list of root HPCs. HpcCount defines the number of\r
@@ -97,13 +110,19 @@ EFI_STATUS
 /**\r
   Initializes one root Hot Plug Controller (HPC). This process may causes\r
   initialization of its subordinate buses.\r
+  \r
+  This function initializes the specified HPC. At the end of initialization, the hot-plug slots or sockets \r
+  (controlled by this HPC) are powered and are connected to the bus. All the necessary registers in the \r
+  HPC are set up. For a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set up \r
+  are defined in the PCI Standard Hot Plug Controller and Subsystem Specification.\r
 \r
   @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
   @param  HpcDevicePath         The device path to the HPC that is being initialized.\r
   @param  HpcPciAddress         The address of the HPC function on the PCI bus.\r
   @param  Event                 The event that should be signaled when the HPC initialization\r
                                 is complete.\r
-  @param  HpcState              The state of the HPC hardware.\r
+  @param  HpcState              The state of the HPC hardware. The state is EFI_HPC_STATE_INITIALIZED\r
+                                or EFI_HPC_STATE_ENABLED.\r
 \r
   @retval EFI_SUCCESS           If Event is NULL, the specific HPC was successfully\r
                                 initialized. If Event is not NULL, Event will be signaled at a later time\r
@@ -129,6 +148,12 @@ EFI_STATUS
   Returns the resource padding that is required by the PCI bus that is controlled\r
   by the specified Hot Plug Controller (HPC).\r
 \r
+  This function returns the resource padding that is required by the PCI bus that is controlled by the \r
+  specified HPC. This member function is called for all the root HPCs and nonroot HPCs that are \r
+  detected by the PCI bus enumerator. This function will be called before PCI resource allocation is \r
+  completed. This function must be called after all the root HPCs, with the possible exception of a \r
+  PCI-to-CardBus bridge, have completed initialization.\r
+\r
   @param  This                  Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
   @param  HpcDevicePath         The device path to the HPC.\r
   @param  HpcPciAddress         The address of the HPC function on the PCI bus.\r
@@ -149,7 +174,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_GET_PCI_HOT_PLUG_PADDING)(\r
+(EFIAPI *EFI_GET_HOT_PLUG_PADDING)(\r
   IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL     *This,\r
   IN  EFI_DEVICE_PATH_PROTOCOL          *HpcDevicePath,\r
   IN  UINT64                            HpcPciAddress,\r
@@ -182,7 +207,7 @@ struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL {
   ///\r
   /// Returns the resource padding that is required by the HPC.\r
   ///\r
-  EFI_GET_PCI_HOT_PLUG_PADDING                           GetResourcePadding;\r
+  EFI_GET_HOT_PLUG_PADDING                               GetResourcePadding;\r
 };\r
 \r
 extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;\r