1 /** @file 2 This file declares EFI PCI Hot Plug Init Protocol. 3 4 This protocol provides the necessary functionality to initialize the Hot Plug 5 Controllers (HPCs) and the buses that they control. This protocol also provides 6 information regarding resource padding. 7 8 @par Note: 9 This protocol is required only on platforms that support one or more PCI Hot 10 Plug* slots or CardBus sockets. 11 12 The EFI_PCI_HOT_PLUG_INIT_PROTOCOL provides a mechanism for the PCI bus enumerator 13 to properly initialize the HPCs and CardBus sockets that require initialization. 14 The HPC initialization takes place before the PCI enumeration process is complete. 15 There cannot be more than one instance of this protocol in a system. This protocol 16 is installed on its own separate handle. 17 18 Because the system may include multiple HPCs, one instance of this protocol 19 should represent all of them. The protocol functions use the device path of 20 the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it 21 will call EFI_PCI_HOT_PLUG_INIT_PROTOCOL.InitializeRootHpc(). If InitializeRootHpc() 22 is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC 23 and continue the enumeration process. If the HPC is not initialized, the devices 24 that it controls may not be initialized, and no resource padding will be provided. 25 26 From the standpoint of the PCI bus enumerator, HPCs are divided into the following 27 two classes: 28 29 - Root HPC: 30 These HPCs must be initialized by calling InitializeRootHpc() during the 31 enumeration process. These HPCs will also require resource padding. The 32 platform code must have a priori knowledge of these devices and must know 33 how to initialize them. There may not be any way to access their PCI 34 configuration space before the PCI enumerator programs all the upstream 35 bridges and thus enables the path to these devices. The PCI bus enumerator 36 is responsible for determining the PCI bus address of the HPC before it 37 calls InitializeRootHpc(). 38 - Nonroot HPC: 39 These HPCs will not need explicit initialization during enumeration process. 40 These HPCs will require resource padding. The platform code does not have 41 to have a priori knowledge of these devices. 42 43 Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR> 44 This program and the accompanying materials 45 are licensed and made available under the terms and conditions of the BSD License 46 which accompanies this distribution. The full text of the license may be found at 47 http://opensource.org/licenses/bsd-license.php 48 49 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 50 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 51 52 @par Revision Reference: 53 This Protocol is defined in UEFI Platform Initialization Specification 1.2 54 Volume 5: Standards 55 56 **/ 57 58 #ifndef _EFI_PCI_HOT_PLUG_INIT_H_ 59 #define _EFI_PCI_HOT_PLUG_INIT_H_ 60 61 /// 62 /// Global ID for the EFI_PCI_HOT_PLUG_INIT_PROTOCOL 63 /// 64 #define EFI_PCI_HOT_PLUG_INIT_PROTOCOL_GUID \ 65 { \ 66 0xaa0e8bc1, 0xdabc, 0x46b0, {0xa8, 0x44, 0x37, 0xb8, 0x16, 0x9b, 0x2b, 0xea } \ 67 } 68 69 /// 70 /// Forward declaration for EFI_PCI_HOT_PLUG_INIT_PROTOCOL 71 /// 72 typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL; 73 74 /// 75 /// Describes the current state of an HPC 76 /// 77 typedef UINT16 EFI_HPC_STATE; 78 79 /// 80 /// The HPC initialization function was called and the HPC completed 81 /// initialization, but it was not enabled for some reason. The HPC may be 82 /// disabled in hardware, or it may be disabled due to user preferences, 83 /// hardware failure, or other reasons. No resource padding is required. 84 /// 85 #define EFI_HPC_STATE_INITIALIZED 0x01 86 87 /// 88 /// The HPC initialization function was called, the HPC completed 89 /// initialization, and it was enabled. Resource padding is required. 90 /// 91 #define EFI_HPC_STATE_ENABLED 0x02 92 93 /// 94 /// Location definition for PCI Hot Plug Controller 95 /// 96 typedef struct{ 97 /// 98 /// 99 /// The device path to the root HPC. An HPC cannot control its parent buses. 100 /// The PCI bus driver requires this information so that it can pass the 101 /// correct HpcPciAddress to the InitializeRootHpc() and GetResourcePadding() 102 /// functions. 103 /// 104 EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath; 105 /// 106 /// The device path to the Hot Plug Bus (HPB) that is controlled by the root 107 /// HPC. The PCI bus driver uses this information to check if a particular PCI 108 /// bus has hot-plug slots. The device path of a PCI bus is the same as the 109 /// device path of its parent. For Standard(PCI) Hot Plug Controllers (SHPCs) 110 /// and PCI Express*, HpbDevicePath is the same as HpcDevicePath. 111 /// 112 EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath; 113 } EFI_HPC_LOCATION; 114 115 /// 116 /// Describes how resource padding should be applied 117 /// 118 typedef enum { 119 /// 120 /// Apply the padding at a PCI bus level. In other words, the resources 121 /// that are allocated to the bus containing hot-plug slots are padded by 122 /// the specified amount. If the hot-plug bus is behind a PCI-to-PCI 123 /// bridge, the PCI-to-PCI bridge apertures will indicate the padding 124 /// 125 EfiPaddingPciBus, 126 /// 127 /// Apply the padding at a PCI root bridge level. If a PCI root bridge 128 /// includes more than one hot-plug bus, the resource padding requests 129 /// for these buses are added together and the resources that are 130 /// allocated to the root bridge are padded by the specified amount. This 131 /// strategy may reduce the total amount of padding, but requires 132 /// reprogramming of PCI-to-PCI bridges in a hot-add event. If the hotplug 133 /// bus is behind a PCI-to-PCI bridge, the PCI-to-PCI bridge 134 /// apertures do not indicate the padding for that bus. 135 /// 136 EfiPaddingPciRootBridge 137 } EFI_HPC_PADDING_ATTRIBUTES; 138 139 /** 140 Returns a list of root Hot Plug Controllers (HPCs) that require initialization 141 during the boot process. 142 143 This procedure returns a list of root HPCs. The PCI bus driver must initialize 144 these controllers during the boot process. The PCI bus driver may or may not be 145 able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it 146 can be included in this list if it requires initialization. The HpcList must be 147 self consistent. An HPC cannot control any of its parent buses. Only one HPC can 148 control a PCI bus. Because this list includes only root HPCs, no HPC in the list 149 can be a child of another HPC. This policy must be enforced by the 150 EFI_PCI_HOT_PLUG_INIT_PROTOCOL. The PCI bus driver may not check for such 151 invalid conditions. The callee allocates the buffer HpcList 152 153 @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. 154 @param[out] HpcCount The number of root HPCs that were returned. 155 @param[out] HpcList The list of root HPCs. HpcCount defines the number of 156 elements in this list. 157 158 @retval EFI_SUCCESS HpcList was returned. 159 @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient 160 resources. 161 @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL. 162 163 **/ 164 typedef 165 EFI_STATUS 166 (EFIAPI *EFI_GET_ROOT_HPC_LIST)( 167 IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, 168 OUT UINTN *HpcCount, 169 OUT EFI_HPC_LOCATION **HpcList 170 ); 171 172 /** 173 Initializes one root Hot Plug Controller (HPC). This process may causes 174 initialization of its subordinate buses. 175 176 This function initializes the specified HPC. At the end of initialization, 177 the hot-plug slots or sockets (controlled by this HPC) are powered and are 178 connected to the bus. All the necessary registers in the HPC are set up. For 179 a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set 180 up are defined in the PCI Standard Hot Plug Controller and Subsystem 181 Specification. 182 183 @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. 184 @param[in] HpcDevicePath The device path to the HPC that is being initialized. 185 @param[in] HpcPciAddress The address of the HPC function on the PCI bus. 186 @param[in] Event The event that should be signaled when the HPC 187 initialization is complete. Set to NULL if the 188 caller wants to wait until the entire initialization 189 process is complete. 190 @param[out] HpcState The state of the HPC hardware. The state is 191 EFI_HPC_STATE_INITIALIZED or EFI_HPC_STATE_ENABLED. 192 193 @retval EFI_SUCCESS If Event is NULL, the specific HPC was successfully 194 initialized. If Event is not NULL, Event will be 195 signaled at a later time when initialization is complete. 196 @retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL 197 does not support the specified HPC. 198 @retval EFI_OUT_OF_RESOURCES Initialization failed due to insufficient 199 resources. 200 @retval EFI_INVALID_PARAMETER HpcState is NULL. 201 202 **/ 203 typedef 204 EFI_STATUS 205 (EFIAPI *EFI_INITIALIZE_ROOT_HPC)( 206 IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, 207 IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, 208 IN UINT64 HpcPciAddress, 209 IN EFI_EVENT Event, OPTIONAL 210 OUT EFI_HPC_STATE *HpcState 211 ); 212 213 /** 214 Returns the resource padding that is required by the PCI bus that is controlled 215 by the specified Hot Plug Controller (HPC). 216 217 This function returns the resource padding that is required by the PCI bus that 218 is controlled by the specified HPC. This member function is called for all the 219 root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This 220 function will be called before PCI resource allocation is completed. This function 221 must be called after all the root HPCs, with the possible exception of a 222 PCI-to-CardBus bridge, have completed initialization. 223 224 @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. 225 @param[in] HpcDevicePath The device path to the HPC. 226 @param[in] HpcPciAddress The address of the HPC function on the PCI bus. 227 @param[in] HpcState The state of the HPC hardware. 228 @param[out] Padding The amount of resource padding that is required by the 229 PCI bus under the control of the specified HPC. 230 @param[out] Attributes Describes how padding is accounted for. The padding 231 is returned in the form of ACPI 2.0 resource descriptors. 232 233 @retval EFI_SUCCESS The resource padding was successfully returned. 234 @retval EFI_UNSUPPORTED This instance of the EFI_PCI_HOT_PLUG_INIT_PROTOCOL 235 does not support the specified HPC. 236 @retval EFI_NOT_READY This function was called before HPC initialization 237 is complete. 238 @retval EFI_INVALID_PARAMETER HpcState or Padding or Attributes is NULL. 239 @retval EFI_OUT_OF_RESOURCES ACPI 2.0 resource descriptors for Padding 240 cannot be allocated due to insufficient resources. 241 242 **/ 243 typedef 244 EFI_STATUS 245 (EFIAPI *EFI_GET_HOT_PLUG_PADDING)( 246 IN EFI_PCI_HOT_PLUG_INIT_PROTOCOL *This, 247 IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, 248 IN UINT64 HpcPciAddress, 249 OUT EFI_HPC_STATE *HpcState, 250 OUT VOID **Padding, 251 OUT EFI_HPC_PADDING_ATTRIBUTES *Attributes 252 ); 253 254 /// 255 /// This protocol provides the necessary functionality to initialize the 256 /// Hot Plug Controllers (HPCs) and the buses that they control. This protocol 257 /// also provides information regarding resource padding. 258 /// 259 struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL { 260 /// 261 /// Returns a list of root HPCs and the buses that they control. 262 /// 263 EFI_GET_ROOT_HPC_LIST GetRootHpcList; 264 265 /// 266 /// Initializes the specified root HPC. 267 /// 268 EFI_INITIALIZE_ROOT_HPC InitializeRootHpc; 269 270 /// 271 /// Returns the resource padding that is required by the HPC. 272 /// 273 EFI_GET_HOT_PLUG_PADDING GetResourcePadding; 274 }; 275 276 extern EFI_GUID gEfiPciHotPlugInitProtocolGuid; 277 278 #endif 279
