2 This file declares EFI PCI Hot Plug Init Protocol.
3 This protocol provides the necessary functionality to initialize the Hot Plug Controllers (HPCs) and
4 the buses that they control. This protocol also provides information regarding resource padding.
6 Copyright (c) 2007 - 2009, Intel Corporation
7 All rights reserved. This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 @par Revision Reference:
16 This protocol is defined in Framework of EFI Hot Plug Pci Initialization Protocol Spec
21 #ifndef _EFI_PCI_HOT_PLUG_INIT_H_
22 #define _EFI_PCI_HOT_PLUG_INIT_H_
26 /// Global ID for the PCI Hot Plug Protocol
28 #define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \
30 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \
33 typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL
;
36 /// Current state of an HPC
38 typedef UINT16 EFI_HPC_STATE
;
41 /// The HPC initialization function was called and the HPC completed
42 /// initialization, but it was not enabled for some reason. The HPC may be
43 /// disabled in hardware, or it may be disabled due to user preferences,
44 /// hardware failure, or other reasons. No resource padding is required.
46 #define EFI_HPC_STATE_INITIALIZED 0x01
49 /// The HPC initialization function was called, the HPC completed
50 /// initialization, and it was enabled. Resource padding is required.
52 #define EFI_HPC_STATE_ENABLED 0x02
55 /// Location definition for PCI Hot Plug Controller
59 /// The device path to the Root HPC
61 EFI_DEVICE_PATH_PROTOCOL
*HpcDevicePath
;
63 /// The device path to the Hot Plug Bus (HPB) that is controlled by
66 EFI_DEVICE_PATH_PROTOCOL
*HpbDevicePath
;
71 /// Describes how resource padding should be applied
75 EfiPaddingPciRootBridge
76 } EFI_HPC_PADDING_ATTRIBUTES
;
79 Returns a list of root Hot Plug Controllers (HPCs) that require initialization
80 during the boot process.
82 This procedure returns a list of root HPCs. The PCI bus driver must initialize these controllers
83 during the boot process. The PCI bus driver may or may not be able to detect these HPCs. If the
84 platform includes a PCI-to-CardBus bridge, it can be included in this list if it requires initialization.
85 The HpcList must be self consistent. An HPC cannot control any of its parent buses. Only one HPC
86 can control a PCI bus. Because this list includes only root HPCs, no HPC in the list can be a child of
87 another HPC. This policy must be enforced by the EFI_PCI_HOT_PLUG_INIT_PROTOCOL.
88 The PCI bus driver may not check for such invalid conditions.
89 The callee allocates the buffer HpcList
91 @param This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
92 @param HpcCount The number of root HPCs that were returned.
93 @param HpcList The list of root HPCs. HpcCount defines the number of
94 elements in this list.
96 @retval EFI_SUCCESS HpcList was returned.
97 @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient resources.
98 @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL.
103 (EFIAPI
*EFI_GET_ROOT_HPC_LIST
)(
104 IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL
*This
,
106 OUT EFI_HPC_LOCATION
**HpcList
110 Initializes one root Hot Plug Controller (HPC). This process may causes
111 initialization of its subordinate buses.
113 This function initializes the specified HPC. At the end of initialization, the hot-plug slots or sockets
114 (controlled by this HPC) are powered and are connected to the bus. All the necessary registers in the
115 HPC are set up. For a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set up
116 are defined in the PCI Standard Hot Plug Controller and Subsystem Specification.
118 @param This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
119 @param HpcDevicePath The device path to the HPC that is being initialized.
120 @param HpcPciAddress The address of the HPC function on the PCI bus.
121 @param Event The event that should be signaled when the HPC initialization
123 @param HpcState The state of the HPC hardware. The state is EFI_HPC_STATE_INITIALIZED
124 or EFI_HPC_STATE_ENABLED.
126 @retval EFI_SUCCESS If Event is NULL, the specific HPC was successfully
127 initialized. If Event is not NULL, Event will be signaled at a later time
128 when initialization is complete.
129 @retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL
130 does not support the specified HPC.
131 @retval EFI_OUT_OF_RESOURCES Initialization failed due to insufficient
133 @retval EFI_INVALID_PARAMETER HpcState is NULL.
138 (EFIAPI
*EFI_INITIALIZE_ROOT_HPC
)(
139 IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL
*This
,
140 IN EFI_DEVICE_PATH_PROTOCOL
*HpcDevicePath
,
141 IN UINT64 HpcPciAddress
,
142 IN EFI_EVENT Event
, OPTIONAL
143 OUT EFI_HPC_STATE
*HpcState
147 Returns the resource padding that is required by the PCI bus that is controlled
148 by the specified Hot Plug Controller (HPC).
150 This function returns the resource padding that is required by the PCI bus that is controlled by the
151 specified HPC. This member function is called for all the root HPCs and nonroot HPCs that are
152 detected by the PCI bus enumerator. This function will be called before PCI resource allocation is
153 completed. This function must be called after all the root HPCs, with the possible exception of a
154 PCI-to-CardBus bridge, have completed initialization.
156 @param This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance.
157 @param HpcDevicePath The device path to the HPC.
158 @param HpcPciAddress The address of the HPC function on the PCI bus.
159 @param HpcState The state of the HPC hardware.
160 @param Padding The amount of resource padding that is required by the
161 PCI bus under the control of the specified HPC.
162 @param Attributes Describes how padding is accounted for. The padding
163 is returned in the form of ACPI 2.0 resource descriptors.
165 @retval EFI_SUCCESS The resource padding was successfully returned.
166 @retval EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL
167 does not support the specified HPC.
168 @retval EFI_NOT_READY This function was called before HPC initialization is complete.
169 @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL.
170 @retval EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding
171 cannot be allocated due to insufficient resources.
176 (EFIAPI
*EFI_GET_HOT_PLUG_PADDING
)(
177 IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL
*This
,
178 IN EFI_DEVICE_PATH_PROTOCOL
*HpcDevicePath
,
179 IN UINT64 HpcPciAddress
,
180 OUT EFI_HPC_STATE
*HpcState
,
182 OUT EFI_HPC_PADDING_ATTRIBUTES
*Attributes
187 // Prototypes for the PCI Hot Plug Init Protocol
191 /// This protocol provides the necessary functionality to initialize the
192 /// Hot Plug Controllers (HPCs) and the buses that they control. This protocol
193 /// also provides information regarding resource padding.
195 struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL
{
197 /// Returns a list of root HPCs and the buses that they control.
199 EFI_GET_ROOT_HPC_LIST GetRootHpcList
;
202 /// Initializes the specified root HPC.
204 EFI_INITIALIZE_ROOT_HPC InitializeRootHpc
;
207 /// Returns the resource padding that is required by the HPC.
209 EFI_GET_HOT_PLUG_PADDING GetResourcePadding
;
212 extern EFI_GUID gEfiPciHotPlugInitProtocolGuid
;