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