mirror of https://github.com/acidanthera/audk.git
273 lines
12 KiB
C
273 lines
12 KiB
C
/** @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
|