4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This file declares EFI PCI Hot Plug Init Protocol.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This protocol provides the necessary functionality to initialize the Hot Plug
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Controllers (HPCs) and the buses that they control. This protocol also provides
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync information regarding resource padding.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This protocol is required only on platforms that support one or more PCI Hot
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Plug* slots or CardBus sockets.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The EFI_PCI_HOT_PLUG_INIT_PROTOCOL provides a mechanism for the PCI bus enumerator
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync to properly initialize the HPCs and CardBus sockets that require initialization.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The HPC initialization takes place before the PCI enumeration process is complete.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync There cannot be more than one instance of this protocol in a system. This protocol
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is installed on its own separate handle.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Because the system may include multiple HPCs, one instance of this protocol
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync should represent all of them. The protocol functions use the device path of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync will call EFI_PCI_HOT_PLUG_INIT_PROTOCOL.InitializeRootHpc(). If InitializeRootHpc()
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync and continue the enumeration process. If the HPC is not initialized, the devices
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync that it controls may not be initialized, and no resource padding will be provided.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync From the standpoint of the PCI bus enumerator, HPCs are divided into the following
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync two classes:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync - Root HPC:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync These HPCs must be initialized by calling InitializeRootHpc() during the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync enumeration process. These HPCs will also require resource padding. The
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync platform code must have a priori knowledge of these devices and must know
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync how to initialize them. There may not be any way to access their PCI
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync configuration space before the PCI enumerator programs all the upstream
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync bridges and thus enables the path to these devices. The PCI bus enumerator
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is responsible for determining the PCI bus address of the HPC before it
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync calls InitializeRootHpc().
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync - Nonroot HPC:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync These HPCs will not need explicit initialization during enumeration process.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync These HPCs will require resource padding. The platform code does not have
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync to have a priori knowledge of these devices.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This program and the accompanying materials
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync are licensed and made available under the terms and conditions of the BSD License
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync which accompanies this distribution. The full text of the license may be found at
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @par Revision Reference:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This Protocol is defined in UEFI Platform Initialization Specification 1.2
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Volume 5: Standards
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Global ID for the EFI_PCI_HOT_PLUG_INIT_PROTOCOL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Forward declaration for EFI_PCI_HOT_PLUG_INIT_PROTOCOL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL;
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Describes the current state of an HPC
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// The HPC initialization function was called and the HPC completed
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// initialization, but it was not enabled for some reason. The HPC may be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// disabled in hardware, or it may be disabled due to user preferences,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// hardware failure, or other reasons. No resource padding is required.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// The HPC initialization function was called, the HPC completed
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// initialization, and it was enabled. Resource padding is required.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Location definition for PCI Hot Plug Controller
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct{
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// The device path to the root HPC. An HPC cannot control its parent buses.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// The PCI bus driver requires this information so that it can pass the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// correct HpcPciAddress to the InitializeRootHpc() and GetResourcePadding()
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// functions.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// The device path to the Hot Plug Bus (HPB) that is controlled by the root
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// HPC. The PCI bus driver uses this information to check if a particular PCI
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// bus has hot-plug slots. The device path of a PCI bus is the same as the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// device path of its parent. For Standard(PCI) Hot Plug Controllers (SHPCs)
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// and PCI Express*, HpbDevicePath is the same as HpcDevicePath.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Describes how resource padding should be applied
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef enum {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// Apply the padding at a PCI bus level. In other words, the resources
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// that are allocated to the bus containing hot-plug slots are padded by
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// the specified amount. If the hot-plug bus is behind a PCI-to-PCI
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// bridge, the PCI-to-PCI bridge apertures will indicate the padding
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// Apply the padding at a PCI root bridge level. If a PCI root bridge
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// includes more than one hot-plug bus, the resource padding requests
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// for these buses are added together and the resources that are
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// allocated to the root bridge are padded by the specified amount. This
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// strategy may reduce the total amount of padding, but requires
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// reprogramming of PCI-to-PCI bridges in a hot-add event. If the hotplug
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// bus is behind a PCI-to-PCI bridge, the PCI-to-PCI bridge
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// apertures do not indicate the padding for that bus.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Returns a list of root Hot Plug Controllers (HPCs) that require initialization
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync during the boot process.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This procedure returns a list of root HPCs. The PCI bus driver must initialize
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync these controllers during the boot process. The PCI bus driver may or may not be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync can be included in this list if it requires initialization. The HpcList must be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync self consistent. An HPC cannot control any of its parent buses. Only one HPC can
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync control a PCI bus. Because this list includes only root HPCs, no HPC in the list
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync can be a child of another HPC. This policy must be enforced by the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI_PCI_HOT_PLUG_INIT_PROTOCOL. The PCI bus driver may not check for such
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync invalid conditions. The callee allocates the buffer HpcList
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] HpcCount The number of root HPCs that were returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] HpcList The list of root HPCs. HpcCount defines the number of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync elements in this list.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS HpcList was returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Initializes one root Hot Plug Controller (HPC). This process may causes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync initialization of its subordinate buses.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This function initializes the specified HPC. At the end of initialization,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the hot-plug slots or sockets (controlled by this HPC) are powered and are
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync connected to the bus. All the necessary registers in the HPC are set up. For
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync up are defined in the PCI Standard Hot Plug Controller and Subsystem
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Specification.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] HpcDevicePath The device path to the HPC that is being initialized.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] HpcPciAddress The address of the HPC function on the PCI bus.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Event The event that should be signaled when the HPC
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync initialization is complete. Set to NULL if the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync caller wants to wait until the entire initialization
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync process is complete.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] HpcState The state of the HPC hardware. The state is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI_HPC_STATE_INITIALIZED or EFI_HPC_STATE_ENABLED.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS If Event is NULL, the specific HPC was successfully
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync initialized. If Event is not NULL, Event will be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync signaled at a later time when initialization is complete.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync does not support the specified HPC.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_OUT_OF_RESOURCES Initialization failed due to insufficient
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER HpcState is NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Returns the resource padding that is required by the PCI bus that is controlled
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync by the specified Hot Plug Controller (HPC).
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This function returns the resource padding that is required by the PCI bus that
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is controlled by the specified HPC. This member function is called for all the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync function will be called before PCI resource allocation is completed. This function
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync must be called after all the root HPCs, with the possible exception of a
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync PCI-to-CardBus bridge, have completed initialization.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] HpcDevicePath The device path to the HPC.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] HpcPciAddress The address of the HPC function on the PCI bus.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] HpcState The state of the HPC hardware.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Padding The amount of resource padding that is required by the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync PCI bus under the control of the specified HPC.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Attributes Describes how padding is accounted for. The padding
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is returned in the form of ACPI 2.0 resource descriptors.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The resource padding was successfully returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync does not support the specified HPC.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_NOT_READY This function was called before HPC initialization
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is complete.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync cannot be allocated due to insufficient resources.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// This protocol provides the necessary functionality to initialize the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Hot Plug Controllers (HPCs) and the buses that they control. This protocol
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// also provides information regarding resource padding.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// Returns a list of root HPCs and the buses that they control.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// Initializes the specified root HPC.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// Returns the resource padding that is required by the HPC.