/** @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. All rights reserved.<BR>\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
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
+ 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
\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
///\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
///\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
/// 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
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
/// Returns a list of root HPCs and the buses that they control.\r
///\r
EFI_GET_ROOT_HPC_LIST GetRootHpcList;\r
- \r
+\r
///\r
/// Initializes the specified root HPC.\r
///\r
EFI_INITIALIZE_ROOT_HPC InitializeRootHpc;\r
- \r
+\r
///\r
/// Returns the resource padding that is required by the HPC.\r
///\r
projects / mirror_edk2.git / blobdiff