diff options
Diffstat (limited to 'MdePkg/Include/Protocol/PciHotPlugInit.h')
| -rw-r--r-- | MdePkg/Include/Protocol/PciHotPlugInit.h | 142 |
1 files changed, 68 insertions, 74 deletions
diff --git a/MdePkg/Include/Protocol/PciHotPlugInit.h b/MdePkg/Include/Protocol/PciHotPlugInit.h index 65701773825db..9cf91479ad84d 100644 --- a/MdePkg/Include/Protocol/PciHotPlugInit.h +++ b/MdePkg/Include/Protocol/PciHotPlugInit.h @@ -1,56 +1,50 @@ /** @file This file declares EFI PCI Hot Plug Init Protocol. - - This protocol provides the necessary functionality to initialize the Hot Plug - Controllers (HPCs) and the buses that they control. This protocol also provides + + This protocol provides the necessary functionality to initialize the Hot Plug + Controllers (HPCs) and the buses that they control. This protocol also provides information regarding resource padding. - - @par Note: + + @par Note: This protocol is required only on platforms that support one or more PCI Hot - Plug* slots or CardBus sockets. + Plug* slots or CardBus sockets. The EFI_PCI_HOT_PLUG_INIT_PROTOCOL provides a mechanism for the PCI bus enumerator - to properly initialize the HPCs and CardBus sockets that require initialization. - The HPC initialization takes place before the PCI enumeration process is complete. - There cannot be more than one instance of this protocol in a system. This protocol - is installed on its own separate handle. - - Because the system may include multiple HPCs, one instance of this protocol - should represent all of them. The protocol functions use the device path of - the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it + to properly initialize the HPCs and CardBus sockets that require initialization. + The HPC initialization takes place before the PCI enumeration process is complete. + There cannot be more than one instance of this protocol in a system. This protocol + is installed on its own separate handle. + + Because the system may include multiple HPCs, one instance of this protocol + should represent all of them. The protocol functions use the device path of + the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it will call EFI_PCI_HOT_PLUG_INIT_PROTOCOL.InitializeRootHpc(). If InitializeRootHpc() - is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC - and continue the enumeration process. If the HPC is not initialized, the devices + is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC + and continue the enumeration process. If the HPC is not initialized, the devices that it controls may not be initialized, and no resource padding will be provided. - From the standpoint of the PCI bus enumerator, HPCs are divided into the following + From the standpoint of the PCI bus enumerator, HPCs are divided into the following two classes: - Root HPC: - These HPCs must be initialized by calling InitializeRootHpc() during the - enumeration process. These HPCs will also require resource padding. The - platform code must have a priori knowledge of these devices and must know - how to initialize them. There may not be any way to access their PCI + These HPCs must be initialized by calling InitializeRootHpc() during the + enumeration process. These HPCs will also require resource padding. The + platform code must have a priori knowledge of these devices and must know + how to initialize them. There may not be any way to access their PCI configuration space before the PCI enumerator programs all the upstream - bridges and thus enables the path to these devices. The PCI bus enumerator - is responsible for determining the PCI bus address of the HPC before it + bridges and thus enables the path to these devices. The PCI bus enumerator + is responsible for determining the PCI bus address of the HPC before it calls InitializeRootHpc(). - Nonroot HPC: - These HPCs will not need explicit initialization during enumeration process. - These HPCs will require resource padding. The platform code does not have + These HPCs will not need explicit initialization during enumeration process. + These HPCs will require resource padding. The platform code does not have to have a priori knowledge of these devices. - Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards **/ @@ -77,15 +71,15 @@ typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL; typedef UINT16 EFI_HPC_STATE; /// -/// The HPC initialization function was called and the HPC completed -/// initialization, but it was not enabled for some reason. The HPC may be -/// disabled in hardware, or it may be disabled due to user preferences, +/// The HPC initialization function was called and the HPC completed +/// initialization, but it was not enabled for some reason. The HPC may be +/// disabled in hardware, or it may be disabled due to user preferences, /// hardware failure, or other reasons. No resource padding is required. /// #define EFI_HPC_STATE_INITIALIZED 0x01 /// -/// The HPC initialization function was called, the HPC completed +/// The HPC initialization function was called, the HPC completed /// initialization, and it was enabled. Resource padding is required. /// #define EFI_HPC_STATE_ENABLED 0x02 @@ -95,18 +89,18 @@ typedef UINT16 EFI_HPC_STATE; /// typedef struct{ /// - /// + /// /// The device path to the root HPC. An HPC cannot control its parent buses. - /// The PCI bus driver requires this information so that it can pass the - /// correct HpcPciAddress to the InitializeRootHpc() and GetResourcePadding() - /// functions. + /// The PCI bus driver requires this information so that it can pass the + /// correct HpcPciAddress to the InitializeRootHpc() and GetResourcePadding() + /// functions. /// EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath; /// - /// The device path to the Hot Plug Bus (HPB) that is controlled by the root - /// HPC. The PCI bus driver uses this information to check if a particular PCI - /// bus has hot-plug slots. The device path of a PCI bus is the same as the - /// device path of its parent. For Standard(PCI) Hot Plug Controllers (SHPCs) + /// The device path to the Hot Plug Bus (HPB) that is controlled by the root + /// HPC. The PCI bus driver uses this information to check if a particular PCI + /// bus has hot-plug slots. The device path of a PCI bus is the same as the + /// device path of its parent. For Standard(PCI) Hot Plug Controllers (SHPCs) /// and PCI Express*, HpbDevicePath is the same as HpcDevicePath. /// EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath; @@ -131,7 +125,7 @@ typedef enum { /// strategy may reduce the total amount of padding, but requires /// reprogramming of PCI-to-PCI bridges in a hot-add event. If the hotplug /// bus is behind a PCI-to-PCI bridge, the PCI-to-PCI bridge - /// apertures do not indicate the padding for that bus. + /// apertures do not indicate the padding for that bus. /// EfiPaddingPciRootBridge } EFI_HPC_PADDING_ATTRIBUTES; @@ -140,14 +134,14 @@ typedef enum { Returns a list of root Hot Plug Controllers (HPCs) that require initialization during the boot process. - This procedure returns a list of root HPCs. The PCI bus driver must initialize - these controllers during the boot process. The PCI bus driver may or may not be - able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it - can be included in this list if it requires initialization. The HpcList must be - self consistent. An HPC cannot control any of its parent buses. Only one HPC can - control a PCI bus. Because this list includes only root HPCs, no HPC in the list - can be a child of another HPC. This policy must be enforced by the - EFI_PCI_HOT_PLUG_INIT_PROTOCOL. The PCI bus driver may not check for such + This procedure returns a list of root HPCs. The PCI bus driver must initialize + these controllers during the boot process. The PCI bus driver may or may not be + able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it + can be included in this list if it requires initialization. The HpcList must be + self consistent. An HPC cannot control any of its parent buses. Only one HPC can + control a PCI bus. Because this list includes only root HPCs, no HPC in the list + can be a child of another HPC. This policy must be enforced by the + EFI_PCI_HOT_PLUG_INIT_PROTOCOL. The PCI bus driver may not check for such invalid conditions. The callee allocates the buffer HpcList @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. @@ -156,7 +150,7 @@ typedef enum { elements in this list. @retval EFI_SUCCESS HpcList was returned. - @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient + @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient resources. @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL. @@ -172,26 +166,26 @@ EFI_STATUS /** Initializes one root Hot Plug Controller (HPC). This process may causes initialization of its subordinate buses. - - This function initializes the specified HPC. At the end of initialization, - the hot-plug slots or sockets (controlled by this HPC) are powered and are - connected to the bus. All the necessary registers in the HPC are set up. For - a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set - up are defined in the PCI Standard Hot Plug Controller and Subsystem - Specification. + + This function initializes the specified HPC. At the end of initialization, + the hot-plug slots or sockets (controlled by this HPC) are powered and are + connected to the bus. All the necessary registers in the HPC are set up. For + a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set + up are defined in the PCI Standard Hot Plug Controller and Subsystem + Specification. @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. @param[in] HpcDevicePath The device path to the HPC that is being initialized. @param[in] HpcPciAddress The address of the HPC function on the PCI bus. - @param[in] Event The event that should be signaled when the HPC - initialization is complete. Set to NULL if the - caller wants to wait until the entire initialization + @param[in] Event The event that should be signaled when the HPC + initialization is complete. Set to NULL if the + caller wants to wait until the entire initialization process is complete. - @param[out] HpcState The state of the HPC hardware. The state is + @param[out] HpcState The state of the HPC hardware. The state is EFI_HPC_STATE_INITIALIZED or EFI_HPC_STATE_ENABLED. @retval EFI_SUCCESS If Event is NULL, the specific HPC was successfully - initialized. If Event is not NULL, Event will be + initialized. If Event is not NULL, Event will be signaled at a later time when initialization is complete. @retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL does not support the specified HPC. @@ -215,10 +209,10 @@ EFI_STATUS by the specified Hot Plug Controller (HPC). This function returns the resource padding that is required by the PCI bus that - is controlled by the specified HPC. This member function is called for all the - root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This - function will be called before PCI resource allocation is completed. This function - must be called after all the root HPCs, with the possible exception of a + is controlled by the specified HPC. This member function is called for all the + root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This + function will be called before PCI resource allocation is completed. This function + must be called after all the root HPCs, with the possible exception of a PCI-to-CardBus bridge, have completed initialization. @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. @@ -261,12 +255,12 @@ struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL { /// Returns a list of root HPCs and the buses that they control. /// EFI_GET_ROOT_HPC_LIST GetRootHpcList; - + /// /// Initializes the specified root HPC. /// EFI_INITIALIZE_ROOT_HPC InitializeRootHpc; - + /// /// Returns the resource padding that is required by the HPC. /// |