| /** @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 |
| information regarding resource padding. |
| |
| @par Note: |
| This protocol is required only on platforms that support one or more PCI Hot |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| to have a priori knowledge of these devices. |
| |
| 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 |
| Volume 5: Standards |
| |
| **/ |
| |
| #ifndef _EFI_PCI_HOT_PLUG_INIT_H_ |
| #define _EFI_PCI_HOT_PLUG_INIT_H_ |
| |
| /// |
| /// Global ID for the EFI_PCI_HOT_PLUG_INIT_PROTOCOL |
| /// |
| #define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \ |
| { \ |
| 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \ |
| } |
| |
| /// |
| /// Forward declaration for EFI_PCI_HOT_PLUG_INIT_PROTOCOL |
| /// |
| typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL; |
| |
| /// |
| /// Describes the current state of an HPC |
| /// |
| 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, |
| /// 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 |
| /// initialization, and it was enabled. Resource padding is required. |
| /// |
| #define EFI_HPC_STATE_ENABLED 0x02 |
| |
| /// |
| /// Location definition for PCI Hot Plug Controller |
| /// |
| 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. |
| /// |
| 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) |
| /// and PCI Express*, HpbDevicePath is the same as HpcDevicePath. |
| /// |
| EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath; |
| } EFI_HPC_LOCATION; |
| |
| /// |
| /// Describes how resource padding should be applied |
| /// |
| typedef enum { |
| /// |
| /// Apply the padding at a PCI bus level. In other words, the resources |
| /// that are allocated to the bus containing hot-plug slots are padded by |
| /// the specified amount. If the hot-plug bus is behind a PCI-to-PCI |
| /// bridge, the PCI-to-PCI bridge apertures will indicate the padding |
| /// |
| EfiPaddingPciBus, |
| /// |
| /// Apply the padding at a PCI root bridge level. If a PCI root bridge |
| /// includes more than one hot-plug bus, the resource padding requests |
| /// for these buses are added together and the resources that are |
| /// allocated to the root bridge are padded by the specified amount. This |
| /// 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. |
| /// |
| EfiPaddingPciRootBridge |
| } EFI_HPC_PADDING_ATTRIBUTES; |
| |
| /** |
| 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 |
| invalid conditions. The callee allocates the buffer HpcList |
| |
| @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. |
| @param[out] HpcCount The number of root HPCs that were returned. |
| @param[out] HpcList The list of root HPCs. HpcCount defines the number of |
| elements in this list. |
| |
| @retval EFI_SUCCESS HpcList was returned. |
| @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient |
| resources. |
| @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_GET_ROOT_HPC_LIST)( |
| IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, |
| OUT UINTN *HpcCount, |
| OUT EFI_HPC_LOCATION **HpcList |
| ); |
| |
| /** |
| 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. |
| |
| @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 |
| process is complete. |
| @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 |
| 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. |
| @retval EFI_OUT_OF_RESOURCES Initialization failed due to insufficient |
| resources. |
| @retval EFI_INVALID_PARAMETER HpcState is NULL. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_INITIALIZE_ROOT_HPC)( |
| IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, |
| IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, |
| IN UINT64 HpcPciAddress, |
| IN EFI_EVENT Event, OPTIONAL |
| OUT EFI_HPC_STATE *HpcState |
| ); |
| |
| /** |
| Returns the resource padding that is required by the PCI bus that is controlled |
| 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 |
| PCI-to-CardBus bridge, have completed initialization. |
| |
| @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. |
| @param[in] HpcDevicePath The device path to the HPC. |
| @param[in] HpcPciAddress The address of the HPC function on the PCI bus. |
| @param[in] HpcState The state of the HPC hardware. |
| @param[out] Padding The amount of resource padding that is required by the |
| PCI bus under the control of the specified HPC. |
| @param[out] Attributes Describes how padding is accounted for. The padding |
| is returned in the form of ACPI 2.0 resource descriptors. |
| |
| @retval EFI_SUCCESS The resource padding was successfully returned. |
| @retval EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL |
| does not support the specified HPC. |
| @retval EFI_NOT_READY This function was called before HPC initialization |
| is complete. |
| @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL. |
| @retval EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding |
| cannot be allocated due to insufficient resources. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_GET_HOT_PLUG_PADDING)( |
| IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, |
| IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, |
| IN UINT64 HpcPciAddress, |
| OUT EFI_HPC_STATE *HpcState, |
| OUT VOID **Padding, |
| OUT EFI_HPC_PADDING_ATTRIBUTES *Attributes |
| ); |
| |
| /// |
| /// 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. |
| /// |
| 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. |
| /// |
| EFI_GET_HOT_PLUG_PADDING GetResourcePadding; |
| }; |
| |
| extern EFI_GUID gEfiPciHotPlugInitProtocolGuid; |
| |
| #endif |