1 /** @file 2 This file declares PCI Host Bridge Resource Allocation Protocol which 3 provides the basic interfaces to abstract a PCI host bridge resource allocation. 4 This protocol is mandatory if the system includes PCI devices. 5 6 Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> 7 SPDX-License-Identifier: BSD-2-Clause-Patent 8 9 @par Revision Reference: 10 This Protocol is defined in UEFI Platform Initialization Specification 1.2 11 Volume 5: Standards. 12 13 **/ 14 15 #ifndef _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_ 16 #define _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_ 17 18 // 19 // This file must be included because EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 20 // uses EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS 21 // 22 #include <Protocol/PciRootBridgeIo.h> 23 24 /// 25 /// Global ID for the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL. 26 /// 27 #define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID \ 28 { \ 29 0xCF8034BE, 0x6768, 0x4d8b, {0xB7,0x39,0x7C,0xCE,0x68,0x3A,0x9F,0xBE } \ 30 } 31 32 /// 33 /// Forward declaration for EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL. 34 /// 35 typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL; 36 37 /// If this bit is set, then the PCI Root Bridge does not 38 /// support separate windows for Non-prefetchable and Prefetchable 39 /// memory. A PCI bus driver needs to include requests for Prefetchable 40 /// memory in the Non-prefetchable memory pool. 41 /// 42 #define EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM 1 43 44 /// 45 /// If this bit is set, then the PCI Root Bridge supports 46 /// 64 bit memory windows. If this bit is not set, 47 /// the PCI bus driver needs to include requests for 64 bit 48 /// memory address in the corresponding 32 bit memory pool. 49 /// 50 #define EFI_PCI_HOST_BRIDGE_MEM64_DECODE 2 51 52 /// 53 /// A UINT64 value that contains the status of a PCI resource requested 54 /// in the Configuration parameter returned by GetProposedResources() 55 /// The legal values are EFI_RESOURCE_SATISFIED and EFI_RESOURCE_NOT_SATISFIED 56 /// 57 typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS; 58 59 /// 60 /// The request of this resource type could be fulfilled. Used in the 61 /// Configuration parameter returned by GetProposedResources() to identify 62 /// a PCI resources request that can be satisfied. 63 /// 64 #define EFI_RESOURCE_SATISFIED 0x0000000000000000ULL 65 66 /// 67 /// The request of this resource type could not be fulfilled for its 68 /// absence in the host bridge resource pool. Used in the Configuration parameter 69 /// returned by GetProposedResources() to identify a PCI resources request that 70 /// can not be satisfied. 71 /// 72 #define EFI_RESOURCE_NOT_SATISFIED 0xFFFFFFFFFFFFFFFFULL 73 74 /// 75 /// This enum is used to specify the phase of the PCI enumaeration process. 76 /// 77 typedef enum { 78 /// 79 /// Reset the host bridge PCI apertures and internal data structures. 80 /// PCI enumerator should issue this notification before starting fresh 81 /// enumeration process. Enumeration cannot be restarted after sending 82 /// any other notification such as EfiPciHostBridgeBeginBusAllocation. 83 /// 84 EfiPciHostBridgeBeginEnumeration, 85 86 /// 87 /// The bus allocation phase is about to begin. No specific action 88 /// is required here. This notification can be used to perform any 89 /// chipset specific programming. 90 /// 91 EfiPciHostBridgeBeginBusAllocation, 92 93 /// 94 /// The bus allocation and bus programming phase is complete. No specific 95 /// action is required here. This notification can be used to perform any 96 /// chipset specific programming. 97 /// 98 EfiPciHostBridgeEndBusAllocation, 99 100 /// 101 /// The resource allocation phase is about to begin.No specific action is 102 /// required here. This notification can be used to perform any chipset specific programming. 103 /// 104 EfiPciHostBridgeBeginResourceAllocation, 105 106 /// 107 /// Allocate resources per previously submitted requests for all the PCI Root 108 /// Bridges. These resource settings are returned on the next call to 109 /// GetProposedResources(). 110 /// 111 EfiPciHostBridgeAllocateResources, 112 113 /// 114 /// Program the Host Bridge hardware to decode previously allocated resources 115 /// (proposed resources) for all the PCI Root Bridges. 116 /// 117 EfiPciHostBridgeSetResources, 118 119 /// 120 /// De-allocate previously allocated resources previously for all the PCI 121 /// Root Bridges and reset the I/O and memory apertures to initial state. 122 /// 123 EfiPciHostBridgeFreeResources, 124 125 /// 126 /// The resource allocation phase is completed. No specific action is required 127 /// here. This notification can be used to perform any chipset specific programming. 128 /// 129 EfiPciHostBridgeEndResourceAllocation, 130 131 /// 132 /// The Host Bridge Enumeration is completed. No specific action is required here. 133 /// This notification can be used to perform any chipset specific programming. 134 /// 135 EfiPciHostBridgeEndEnumeration, 136 EfiMaxPciHostBridgeEnumerationPhase 137 } EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE; 138 139 /// 140 /// Definitions of 2 notification points. 141 /// 142 typedef enum { 143 /// 144 /// This notification is only applicable to PCI-PCI bridges and 145 /// indicates that the PCI enumerator is about to begin enumerating 146 /// the bus behind the PCI-PCI Bridge. This notification is sent after 147 /// the primary bus number, the secondary bus number and the subordinate 148 /// bus number registers in the PCI-PCI Bridge are programmed to valid 149 /// (not necessary final) values 150 /// 151 EfiPciBeforeChildBusEnumeration, 152 153 /// 154 /// This notification is sent before the PCI enumerator probes BAR registers 155 /// for every valid PCI function. 156 /// 157 EfiPciBeforeResourceCollection 158 } EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE; 159 160 /** 161 These are the notifications from the PCI bus driver that it is about to enter a certain phase of the PCI 162 enumeration process. 163 164 @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 165 instance. 166 @param[in] Phase The phase during enumeration. 167 168 @retval EFI_SUCCESS The notification was accepted without any errors. 169 @retval EFI_INVALID_PARAMETER The Phase is invalid. 170 @retval EFI_NOT_READY This phase cannot be entered at this time. For example, this error 171 is valid for a Phase of EfiPciHostBridgeAllocateResources if 172 SubmitResources() has not been called for one or more 173 PCI root bridges before this call. 174 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. This error is valid for 175 a Phase of EfiPciHostBridgeSetResources. 176 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 177 This error is valid for a Phase of EfiPciHostBridgeAllocateResources 178 if the previously submitted resource requests cannot be fulfilled or were only 179 partially fulfilled 180 181 **/ 182 typedef 183 EFI_STATUS 184 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE)( 185 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, 186 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase 187 ); 188 189 /** 190 Returns the device handle of the next PCI root bridge that is associated with this host bridge. 191 192 @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 193 instance. 194 @param[in,out] RootBridgeHandle Returns the device handle of the next PCI root bridge. On input, it holds the 195 RootBridgeHandle that was returned by the most recent call to 196 GetNextRootBridge(). If RootBridgeHandle is NULL on input, the handle 197 for the first PCI root bridge is returned. 198 199 @retval EFI_SUCCESS The requested attribute information was returned. 200 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was returned 201 on a previous call to GetNextRootBridge(). 202 @retval EFI_NOT_FOUND There are no more PCI root bridge device handles. 203 204 **/ 205 typedef 206 EFI_STATUS 207 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE)( 208 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, 209 IN OUT EFI_HANDLE *RootBridgeHandle 210 ); 211 212 /** 213 Returns the allocation attributes of a PCI root bridge. 214 215 @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 216 instance. 217 @param[in] RootBridgeHandle The device handle of the PCI root bridge in which the caller is interested. 218 @param[out] Attribute The pointer to attributes of the PCI root bridge. 219 220 @retval EFI_SUCCESS The requested attribute information was returned. 221 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. 222 @retval EFI_INVALID_PARAMETER Attributes is NULL. 223 224 **/ 225 typedef 226 EFI_STATUS 227 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES)( 228 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, 229 IN EFI_HANDLE RootBridgeHandle, 230 OUT UINT64 *Attributes 231 ); 232 233 /** 234 Sets up the specified PCI root bridge for the bus enumeration process. 235 236 @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 237 instance. 238 @param[in] RootBridgeHandle The PCI root bridge to be set up. 239 @param[out] Configuration The pointer to the pointer to the PCI bus resource descriptor. 240 241 @retval EFI_SUCCESS The PCI root bridge was set up and the bus range was returned in 242 Configuration. 243 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. 244 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. 245 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 246 247 **/ 248 typedef 249 EFI_STATUS 250 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION)( 251 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, 252 IN EFI_HANDLE RootBridgeHandle, 253 OUT VOID **Configuration 254 ); 255 256 /** 257 Programs the PCI root bridge hardware so that it decodes the specified PCI bus range. 258 259 @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 260 instance. 261 @param[in] RootBridgeHandle The PCI root bridge whose bus range is to be programmed. 262 @param[in] Configuration The pointer to the PCI bus resource descriptor. 263 264 @retval EFI_SUCCESS The bus range for the PCI root bridge was programmed. 265 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. 266 @retval EFI_INVALID_PARAMETER Configuration is NULL 267 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) 268 resource descriptor. 269 @retval EFI_INVALID_PARAMETER Configuration does not include a valid ACPI 2.0 bus resource 270 descriptor. 271 @retval EFI_INVALID_PARAMETER Configuration includes valid ACPI (2.0 & 3.0) resource 272 descriptors other than bus descriptors. 273 @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource 274 descriptors. 275 @retval EFI_INVALID_PARAMETER "Address Range Minimum" is invalid for this root bridge. 276 @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this root bridge. 277 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. 278 279 **/ 280 typedef 281 EFI_STATUS 282 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS)( 283 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, 284 IN EFI_HANDLE RootBridgeHandle, 285 IN VOID *Configuration 286 ); 287 288 /** 289 Submits the I/O and memory resource requirements for the specified PCI root bridge. 290 291 @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 292 instance. 293 @param[in] RootBridgeHandle The PCI root bridge whose I/O and memory resource requirements are being 294 submitted. 295 @param[in] Configuration The pointer to the PCI I/O and PCI memory resource descriptor. 296 297 @retval EFI_SUCCESS The I/O and memory resource requests for a PCI root bridge were 298 accepted. 299 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. 300 @retval EFI_INVALID_PARAMETER Configuration is NULL. 301 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) 302 resource descriptor. 303 @retval EFI_INVALID_PARAMETER Configuration includes requests for one or more resource 304 types that are not supported by this PCI root bridge. This error will 305 happen if the caller did not combine resources according to 306 Attributes that were returned by GetAllocAttributes(). 307 @retval EFI_INVALID_PARAMETER "Address Range Maximum" is invalid. 308 @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this PCI root bridge. 309 @retval EFI_INVALID_PARAMETER "Address Space Granularity" is invalid for this PCI root bridge. 310 311 **/ 312 typedef 313 EFI_STATUS 314 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES)( 315 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, 316 IN EFI_HANDLE RootBridgeHandle, 317 IN VOID *Configuration 318 ); 319 320 /** 321 Returns the proposed resource settings for the specified PCI root bridge. 322 323 @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL 324 instance. 325 @param[in] RootBridgeHandle The PCI root bridge handle. 326 @param[out] Configuration The pointer to the pointer to the PCI I/O and memory resource descriptor. 327 328 @retval EFI_SUCCESS The requested parameters were returned. 329 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. 330 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. 331 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 332 333 **/ 334 typedef 335 EFI_STATUS 336 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES)( 337 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, 338 IN EFI_HANDLE RootBridgeHandle, 339 OUT VOID **Configuration 340 ); 341 342 /** 343 Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various 344 stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual 345 PCI controllers before enumeration. 346 347 @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. 348 @param[in] RootBridgeHandle The associated PCI root bridge handle. 349 @param[in] PciAddress The address of the PCI device on the PCI bus. 350 @param[in] Phase The phase of the PCI device enumeration. 351 352 @retval EFI_SUCCESS The requested parameters were returned. 353 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. 354 @retval EFI_INVALID_PARAMETER Phase is not a valid phase that is defined in 355 EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE. 356 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. The PCI enumerator 357 should not enumerate this device, including its child devices if it is 358 a PCI-to-PCI bridge. 359 360 **/ 361 typedef 362 EFI_STATUS 363 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER)( 364 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, 365 IN EFI_HANDLE RootBridgeHandle, 366 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress, 367 IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase 368 ); 369 370 /// 371 /// Provides the basic interfaces to abstract a PCI host bridge resource allocation. 372 /// 373 struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL { 374 /// 375 /// The notification from the PCI bus enumerator that it is about to enter 376 /// a certain phase during the enumeration process. 377 /// 378 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE NotifyPhase; 379 380 /// 381 /// Retrieves the device handle for the next PCI root bridge that is produced by the 382 /// host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached. 383 /// 384 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE GetNextRootBridge; 385 386 /// 387 /// Retrieves the allocation-related attributes of a PCI root bridge. 388 /// 389 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES GetAllocAttributes; 390 391 /// 392 /// Sets up a PCI root bridge for bus enumeration. 393 /// 394 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION StartBusEnumeration; 395 396 /// 397 /// Sets up the PCI root bridge so that it decodes a specific range of bus numbers. 398 /// 399 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS SetBusNumbers; 400 401 /// 402 /// Submits the resource requirements for the specified PCI root bridge. 403 /// 404 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES SubmitResources; 405 406 /// 407 /// Returns the proposed resource assignment for the specified PCI root bridges. 408 /// 409 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources; 410 411 /// 412 /// Provides hooks from the PCI bus driver to every PCI controller 413 /// (device/function) at various stages of the PCI enumeration process that 414 /// allow the host bridge driver to preinitialize individual PCI controllers 415 /// before enumeration. 416 /// 417 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER PreprocessController; 418 }; 419 420 extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid; 421 422 #endif 423