add detailed description for functions.

[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / PciHotPlugInit.h

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
 /// 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
 \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
 } EFI_HPC_LOCATION;\r
 \r
 \r

+///\r
+/// Describes how resource padding should be applied\r
+///\r

 typedef enum{\r
   EfiPaddingPciBus,\r
   EfiPaddingPciRootBridge\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
   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
   @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
   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
 \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
 \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
   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
   @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
 **/\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
   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
   ///\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
 };\r
 \r
 extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;\r