/** @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
+\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
+\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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
@par Revision Reference:\r
- This Protocol is defined in UEFI Platform Initialization Specification 1.2 \r
+ This Protocol is defined in UEFI Platform Initialization Specification 1.2\r
Volume 5: Standards\r
\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
+/// 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
+#define EFI_HPC_STATE_INITIALIZED 0x01\r
\r
///\r
-/// The HPC initialization function was called, the HPC completed \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
+#define EFI_HPC_STATE_ENABLED 0x02\r
\r
///\r
/// Location definition for PCI Hot Plug Controller\r
///\r
-typedef struct{\r
+typedef struct {\r
+ ///\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
+ /// 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
+ 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
+ /// 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_DEVICE_PATH_PROTOCOL *HpbDevicePath;\r
} EFI_HPC_LOCATION;\r
\r
///\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
+ /// apertures do not indicate the padding for that bus.\r
///\r
EfiPaddingPciRootBridge\r
} EFI_HPC_PADDING_ATTRIBUTES;\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
+ 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
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
+ @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
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
+ 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
+ @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
+ @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
+ 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
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
+ IN EFI_EVENT Event OPTIONAL,\r
OUT EFI_HPC_STATE *HpcState\r
);\r
\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
+ 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
///\r
/// Returns a list of root HPCs and the buses that they control.\r
///\r
- EFI_GET_ROOT_HPC_LIST GetRootHpcList;\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
+ 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
+ EFI_GET_HOT_PLUG_PADDING GetResourcePadding;\r
};\r
\r
-extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;\r
+extern EFI_GUID gEfiPciHotPlugInitProtocolGuid;\r
\r
#endif\r
projects / mirror_edk2.git / blobdiff