--- /dev/null
+/** @file\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 - 2009, 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
+ @par Revision Reference:\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
+\r
+///\r
+/// Global ID for the EFI_PCI_HOT_PLUG_INIT_PROTOCOL\r
+///\r
+#define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \\r
+ { \\r
+ 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \\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
+///\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
+/// 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
+ during the boot process.\r
+\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
+ OUT UINTN *HpcCount,\r
+ OUT EFI_HPC_LOCATION **HpcList\r
+ );\r
+\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, \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
+\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\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_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
+ ///\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
+\r
+#endif\r
projects / mirror_edk2.git / blobdiff