/** @file\r
- This file declares EFI PCI Hot Plug Init Protocol\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
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
-\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
-\r
- Module Name: PciHotPlugInit.h\r
+ This file declares EFI PCI Hot Plug Init Protocol.\r
+\r
+ This protocol provides the necessary functionality to initialize the Hot Plug\r
+ Controllers (HPCs) and the buses that they control. This protocol also provides\r
+ information regarding resource padding.\r
+\r
+ @par Note:\r
+ This protocol is required only on platforms that support one or more PCI Hot\r
+ Plug* slots or CardBus sockets.\r
+\r
+ The EFI_PCI_HOT_PLUG_INIT_PROTOCOL provides a mechanism for the PCI bus enumerator\r
+ to properly initialize the HPCs and CardBus sockets that require initialization.\r
+ The HPC initialization takes place before the PCI enumeration process is complete.\r
+ There cannot be more than one instance of this protocol in a system. This protocol\r
+ is installed on its own separate handle.\r
+\r
+ Because the system may include multiple HPCs, one instance of this protocol\r
+ should represent all of them. The protocol functions use the device path of\r
+ the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it\r
+ will call EFI_PCI_HOT_PLUG_INIT_PROTOCOL.InitializeRootHpc(). If InitializeRootHpc()\r
+ is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC\r
+ and continue the enumeration process. If the HPC is not initialized, the devices\r
+ that it controls may not be initialized, and no resource padding will be provided.\r
+\r
+ From the standpoint of the PCI bus enumerator, HPCs are divided into the following\r
+ two classes:\r
+\r
+ - Root HPC:\r
+ These HPCs must be initialized by calling InitializeRootHpc() during the\r
+ enumeration process. These HPCs will also require resource padding. The\r
+ platform code must have a priori knowledge of these devices and must know\r
+ how to initialize them. There may not be any way to access their PCI\r
+ configuration space before the PCI enumerator programs all the upstream\r
+ bridges and thus enables the path to these devices. The PCI bus enumerator\r
+ is responsible for determining the PCI bus address of the HPC before it\r
+ calls InitializeRootHpc().\r
+ - Nonroot HPC:\r
+ These HPCs will not need explicit initialization during enumeration process.\r
+ These HPCs will require resource padding. The platform code does not have\r
+ to have a priori knowledge of these devices.\r
+\r
+ Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD License\r
+ which accompanies this distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php\r
+\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
@par Revision Reference:\r
- This protocol is defined in Framework of EFI Hot Plug Pci Initialization Protocol Spec\r
- Version 0.9\r
+ This Protocol is defined in UEFI Platform Initialization Specification 1.2\r
+ Volume 5: Standards\r
\r
**/\r
\r
-#ifndef _EFI_PCI_HOT_PLUG_INIT_H\r
-#define _EFI_PCI_HOT_PLUG_INIT_H\r
+#ifndef _EFI_PCI_HOT_PLUG_INIT_H_\r
+#define _EFI_PCI_HOT_PLUG_INIT_H_\r
\r
-//\r
-// Global ID for the PCI Hot Plug Protocol\r
-//\r
+///\r
+/// Global ID for the EFI_PCI_HOT_PLUG_INIT_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
+ 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \\r
+ }\r
\r
- \r
+///\r
+/// Forward declaration for EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
+///\r
typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL;\r
\r
-#define EFI_HPC_STATE_INITIALIZED 0x01\r
-#define EFI_HPC_STATE_ENABLED 0x02\r
-\r
+///\r
+/// Describes the current state of an HPC\r
+///\r
typedef UINT16 EFI_HPC_STATE;\r
\r
+///\r
+/// The HPC initialization function was called and the HPC completed\r
+/// initialization, but it was not enabled for some reason. The HPC may be\r
+/// disabled in hardware, or it may be disabled due to user preferences,\r
+/// hardware failure, or other reasons. No resource padding is required.\r
+///\r
+#define EFI_HPC_STATE_INITIALIZED 0x01\r
\r
+///\r
+/// The HPC initialization function was called, the HPC completed\r
+/// initialization, and it was enabled. Resource padding is required.\r
+///\r
+#define EFI_HPC_STATE_ENABLED 0x02\r
+\r
+///\r
+/// Location definition for PCI Hot Plug Controller\r
+///\r
typedef struct{\r
+ ///\r
+ ///\r
+ /// The device path to the root HPC. An HPC cannot control its parent buses.\r
+ /// The PCI bus driver requires this information so that it can pass the\r
+ /// correct HpcPciAddress to the InitializeRootHpc() and GetResourcePadding()\r
+ /// functions.\r
+ ///\r
EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath;\r
+ ///\r
+ /// The device path to the Hot Plug Bus (HPB) that is controlled by the root\r
+ /// HPC. The PCI bus driver uses this information to check if a particular PCI\r
+ /// bus has hot-plug slots. The device path of a PCI bus is the same as the\r
+ /// device path of its parent. For Standard(PCI) Hot Plug Controllers (SHPCs)\r
+ /// and PCI Express*, HpbDevicePath is the same as HpcDevicePath.\r
+ ///\r
EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath;\r
} EFI_HPC_LOCATION;\r
\r
-\r
-typedef enum{\r
+///\r
+/// Describes how resource padding should be applied\r
+///\r
+typedef enum {\r
+ ///\r
+ /// Apply the padding at a PCI bus level. In other words, the resources\r
+ /// that are allocated to the bus containing hot-plug slots are padded by\r
+ /// the specified amount. If the hot-plug bus is behind a PCI-to-PCI\r
+ /// bridge, the PCI-to-PCI bridge apertures will indicate the padding\r
+ ///\r
EfiPaddingPciBus,\r
+ ///\r
+ /// Apply the padding at a PCI root bridge level. If a PCI root bridge\r
+ /// includes more than one hot-plug bus, the resource padding requests\r
+ /// for these buses are added together and the resources that are\r
+ /// allocated to the root bridge are padded by the specified amount. This\r
+ /// strategy may reduce the total amount of padding, but requires\r
+ /// reprogramming of PCI-to-PCI bridges in a hot-add event. If the hotplug\r
+ /// bus is behind a PCI-to-PCI bridge, the PCI-to-PCI bridge\r
+ /// apertures do not indicate the padding for that bus.\r
+ ///\r
EfiPaddingPciRootBridge\r
} EFI_HPC_PADDING_ATTRIBUTES;\r
\r
/**\r
- Returns a list of root Hot Plug Controllers (HPCs) that require initialization \r
+ Returns a list of root Hot Plug Controllers (HPCs) that require initialization\r
during the boot process.\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
- elements in this list.\r
-\r
- @retval EFI_SUCCESS HpcList was returned.\r
- @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient resources.\r
- @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.\r
+ This procedure returns a list of root HPCs. The PCI bus driver must initialize\r
+ these controllers during the boot process. The PCI bus driver may or may not be\r
+ able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it\r
+ can be included in this list if it requires initialization. The HpcList must be\r
+ self consistent. An HPC cannot control any of its parent buses. Only one HPC can\r
+ control a PCI bus. Because this list includes only root HPCs, no HPC in the list\r
+ can be a child of another HPC. This policy must be enforced by the\r
+ EFI_PCI_HOT_PLUG_INIT_PROTOCOL. The PCI bus driver may not check for such\r
+ invalid conditions. The callee allocates the buffer HpcList\r
+\r
+ @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
+ @param[out] HpcCount The number of root HPCs that were returned.\r
+ @param[out] HpcList The list of root HPCs. HpcCount defines the number of\r
+ elements in this list.\r
+\r
+ @retval EFI_SUCCESS HpcList was returned.\r
+ @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient\r
+ resources.\r
+ @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_GET_ROOT_HPC_LIST) (\r
- IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
+(EFIAPI *EFI_GET_ROOT_HPC_LIST)(\r
+ IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
OUT UINTN *HpcCount,\r
OUT EFI_HPC_LOCATION **HpcList\r
-);\r
+ );\r
\r
/**\r
- Initializes one root Hot Plug Controller (HPC). This process may causes \r
- initialization of its subordinate buses. \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
-\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
- when initialization is complete.\r
- @retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
- does not support the specified HPC.\r
- @retval EFI_OUT_OF_RESOURCES Initialization failed due to insufficient\r
- resources.\r
- @retval EFI_INVALID_PARAMETER HpcState is NULL.\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,\r
+ the hot-plug slots or sockets (controlled by this HPC) are powered and are\r
+ connected to the bus. All the necessary registers in the HPC are set up. For\r
+ a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set\r
+ up are defined in the PCI Standard Hot Plug Controller and Subsystem\r
+ Specification.\r
+\r
+ @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
+ @param[in] HpcDevicePath The device path to the HPC that is being initialized.\r
+ @param[in] HpcPciAddress The address of the HPC function on the PCI bus.\r
+ @param[in] Event The event that should be signaled when the HPC\r
+ initialization is complete. Set to NULL if the\r
+ caller wants to wait until the entire initialization\r
+ process is complete.\r
+ @param[out] HpcState The state of the HPC hardware. The state is\r
+ EFI_HPC_STATE_INITIALIZED 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\r
+ signaled at a later time when initialization is complete.\r
+ @retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
+ does not support the specified HPC.\r
+ @retval EFI_OUT_OF_RESOURCES Initialization failed due to insufficient\r
+ resources.\r
+ @retval EFI_INVALID_PARAMETER HpcState is NULL.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_INITIALIZE_ROOT_HPC) (\r
- IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
- IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath,\r
- IN UINT64 HpcPciAddress,\r
- IN EFI_EVENT Event, OPTIONAL\r
- OUT EFI_HPC_STATE *HpcState\r
-);\r
+(EFIAPI *EFI_INITIALIZE_ROOT_HPC)(\r
+ IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath,\r
+ IN UINT64 HpcPciAddress,\r
+ IN EFI_EVENT Event, OPTIONAL\r
+ OUT EFI_HPC_STATE *HpcState\r
+ );\r
\r
/**\r
- Returns the resource padding that is required by the PCI bus that is controlled \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
- @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 HpcState The state of the HPC hardware.\r
- @param Padding The amount of resource padding that is required by the\r
- PCI bus under the control of the specified HPC.\r
- @param Attributes Describes how padding is accounted for. The padding\r
- is returned in the form of ACPI 2.0 resource descriptors.\r
-\r
- @retval EFI_SUCCESS The resource padding was successfully returned.\r
- @retval EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
- does not support the specified HPC.\r
- @retval EFI_NOT_READY This function was called before HPC initialization is complete.\r
- @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.\r
- @retval EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding\r
- cannot be allocated due to insufficient resources.\r
+ This function returns the resource padding that is required by the PCI bus that\r
+ is controlled by the specified HPC. This member function is called for all the\r
+ root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This\r
+ function will be called before PCI resource allocation is completed. This function\r
+ 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[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.\r
+ @param[in] HpcDevicePath The device path to the HPC.\r
+ @param[in] HpcPciAddress The address of the HPC function on the PCI bus.\r
+ @param[in] HpcState The state of the HPC hardware.\r
+ @param[out] Padding The amount of resource padding that is required by the\r
+ PCI bus under the control of the specified HPC.\r
+ @param[out] Attributes Describes how padding is accounted for. The padding\r
+ is returned in the form of ACPI 2.0 resource descriptors.\r
+\r
+ @retval EFI_SUCCESS The resource padding was successfully returned.\r
+ @retval EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
+ does not support the specified HPC.\r
+ @retval EFI_NOT_READY This function was called before HPC initialization\r
+ is complete.\r
+ @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.\r
+ @retval EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding\r
+ cannot be allocated due to insufficient resources.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_GET_PCI_HOT_PLUG_PADDING) (\r
- IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This,\r
- IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath,\r
- IN UINT64 HpcPciAddress,\r
- OUT EFI_HPC_STATE *HpcState,\r
- OUT VOID **Padding,\r
- OUT EFI_HPC_PADDING_ATTRIBUTES *Attributes\r
-); \r
-\r
-\r
-//\r
-// Prototypes for the PCI Hot Plug Init Protocol\r
-//\r
-\r
-/**\r
- @par Protocol Description:\r
- This protocol provides the necessary functionality to initialize the \r
- Hot Plug Controllers (HPCs) and the buses that they control. This protocol \r
- also provides information regarding resource padding. \r
-\r
- @param GetRootHpcList\r
- Returns a list of root HPCs and the buses that they control.\r
-\r
- @param InitializeRootHpc\r
- Initializes the specified root HPC.\r
-\r
- @param GetResourcePadding\r
- Returns the resource padding that is required by the HPC.\r
-\r
-**/\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
+ OUT EFI_HPC_STATE *HpcState,\r
+ OUT VOID **Padding,\r
+ OUT EFI_HPC_PADDING_ATTRIBUTES *Attributes\r
+ );\r
+\r
+///\r
+/// This protocol provides the necessary functionality to initialize the\r
+/// Hot Plug Controllers (HPCs) and the buses that they control. This protocol\r
+/// also provides information regarding resource padding.\r
+///\r
struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL {\r
- EFI_GET_ROOT_HPC_LIST GetRootHpcList;\r
- EFI_INITIALIZE_ROOT_HPC InitializeRootHpc;\r
- EFI_GET_PCI_HOT_PLUG_PADDING GetResourcePadding;\r
+ ///\r
+ /// Returns a list of root HPCs and the buses that they control.\r
+ ///\r
+ EFI_GET_ROOT_HPC_LIST GetRootHpcList;\r
+\r
+ ///\r
+ /// Initializes the specified root HPC.\r
+ ///\r
+ EFI_INITIALIZE_ROOT_HPC InitializeRootHpc;\r
+\r
+ ///\r
+ /// Returns the resource padding that is required by the HPC.\r
+ ///\r
+ EFI_GET_HOT_PLUG_PADDING GetResourcePadding;\r
};\r
\r
extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;\r
projects / mirror_edk2.git / blobdiff