IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h

   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. This protocol is
   4   mandatory if the system includes PCI devices.
   5
   6   Copyright (c) 2007, 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
  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 Framework of EFI Pci Host Bridge Resource Allocation Protocol Spec
  17   Version 0.9
  18
  19 **/
  20
  21 #ifndef _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_
  22 #define _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_
  23
  24 #include <PiDxe.h>
  25 #include <Protocol/PciRootBridgeIo.h>
  26
  27 #define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID \
  28   { 0xCF8034BE, 0x6768, 0x4d8b, {0xB7,0x39,0x7C,0xCE,0x68,0x3A,0x9F,0xBE }}
  29
  30
  31 typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL;
  32
  33
  34 //
  35 // EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES
  36 //
  37
  38 // If this bit is set, then the PCI Root Bridge does not
  39 // support separate windows for Non-prefetchable and Prefetchable
  40 // memory. A PCI bus driver needs to include requests for Prefetchable
  41 // memory in the Non-prefetchable memory pool.
  42 //
  43 #define EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM  1
  44
  45 //
  46 // If this bit is set, then the PCI Root Bridge supports
  47 // 64 bit memory windows.  If this bit is not set,
  48 // the PCI bus driver needs to include requests for 64 bit
  49 // memory address in the corresponding 32 bit memory pool.
  50 //
  51 #define EFI_PCI_HOST_BRIDGE_MEM64_DECODE   2
  52
  53 typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS;
  54
  55 /// The request of this resource type could be fulfilled.
  56 #define EFI_RESOURCE_SATISFIED      0x0000000000000000ULL
  57
  58 /// The request of this resource type could not be fulfilled for its
  59 /// absence in the host bridge resource pool.
  60 #define EFI_RESOURCE_NOT_SATISFIED  0xFFFFFFFFFFFFFFFFULL
  61
  62 //
  63 // EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
  64 //
  65 typedef enum {
  66   EfiPciHostBridgeBeginEnumeration,
  67   EfiPciHostBridgeBeginBusAllocation,
  68   EfiPciHostBridgeEndBusAllocation,
  69   EfiPciHostBridgeBeginResourceAllocation,
  70   EfiPciHostBridgeAllocateResources,
  71   EfiPciHostBridgeSetResources,
  72   EfiPciHostBridgeFreeResources,
  73   EfiPciHostBridgeEndResourceAllocation
  74 } EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE;
  75
  76 //
  77 // EfiPciHostBridgeBeginEnumeration
  78 // Reset the host bridge PCI apertures and internal data structures.
  79 // PCI enumerator should issue this notification before starting fresh
  80 // enumeration process. Enumeration cannot be restarted after sending
  81 // any other notification such as EfiPciHostBridgeBeginBusAllocation.
  82 //
  83 // EfiPciHostBridgeBeginBusAllocation
  84 // The bus allocation phase is about to begin. No specific action
  85 // is required here. This notification can be used to perform any
  86 // chipset specific programming.
  87 //
  88 // EfiPciHostBridgeEndBusAllocation
  89 // The bus allocation and bus programming phase is complete. No specific
  90 // action is required here. This notification can be used to perform any
  91 // chipset specific programming.
  92 //
  93 // EfiPciHostBridgeBeginResourceAllocation
  94 // The resource allocation phase is about to begin.No specific action is
  95 // required here. This notification can be used to perform any chipset specific programming.
  96 //
  97 // EfiPciHostBridgeAllocateResources
  98 // Allocate resources per previously submitted requests for all the PCI Root
  99 // Bridges. These resource settings are returned on the next call to
 100 // GetProposedResources().
 101 //
 102 // EfiPciHostBridgeSetResources
 103 // Program the Host Bridge hardware to decode previously allocated resources
 104 // (proposed resources) for all the PCI Root Bridges.
 105 //
 106 // EfiPciHostBridgeFreeResources
 107 // De-allocate previously allocated resources previously for all the PCI
 108 // Root Bridges and reset the I/O and memory apertures to initial state.
 109 //
 110 // EfiPciHostBridgeEndResourceAllocation
 111 // The resource allocation phase is completed.  No specific action is required
 112 // here. This notification can be used to perform any chipset specific programming.
 113
 114
 115
 116 //
 117 // EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
 118 //
 119 typedef enum {
 120   EfiPciBeforeChildBusEnumeration,
 121   EfiPciBeforeResourceCollection
 122 } EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE;
 123
 124 //
 125 // EfiPciBeforeChildBusEnumeration
 126 // This notification is only applicable to PCI-PCI bridges and
 127 // indicates that the PCI enumerator is about to begin enumerating
 128 // the bus behind the PCI-PCI Bridge. This notification is sent after
 129 // the primary bus number, the secondary bus number and the subordinate
 130 // bus number registers in the PCI-PCI Bridge are programmed to valid
 131 // (not necessary final) values
 132 //
 133 // EfiPciBeforeResourceCollection
 134 // This notification is sent before the PCI enumerator probes BAR registers
 135 // for every valid PCI function.
 136 //
 137
 138
 139 /**
 140   Enter a certain phase of the PCI enumeration process
 141
 142   @param  This                  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance
 143   @param  Phase                 The phase during enumeration
 144
 145   @retval EFI_SUCCESS           Success
 146   @retval EFI_OUT_OF_RESOURCES  If SubmitResources ( ) could not allocate resources
 147   @retval EFI_NOT_READY         This phase cannot be entered at this time
 148   @retval EFI_DEVICE_ERROR      SetResources failed due to HW error.
 149
 150 **/
 151 typedef
 152 EFI_STATUS
 153 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE)(
 154   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL         *This,
 155   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE            Phase
 156   );
 157
 158
 159 /**
 160   Return the device handle of the next PCI root bridge that is associated with
 161   this Host Bridge
 162
 163   @param  This                  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
 164   @param  RootBridgeHandle      Returns the device handle of the next PCI Root Bridge.
 165                                 On input, it holds the RootBridgeHandle returned by the most
 166                                 recent call to GetNextRootBridge().The handle for the first
 167                                 PCI Root Bridge is returned if RootBridgeHandle is NULL on input
 168
 169   @retval EFI_SUCCESS           Success
 170   @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
 171
 172 **/
 173 typedef
 174 EFI_STATUS
 175 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE)(
 176   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL     *This,
 177   IN OUT EFI_HANDLE                                       *RootBridgeHandle
 178   );
 179
 180
 181 /**
 182   Returns the attributes of a PCI Root Bridge.
 183
 184   @param  This                  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
 185   @param  RootBridgeHandle      The device handle of the PCI Root Bridge
 186                                 that the caller is interested in
 187   @param  Attribute             The pointer to attributes of the PCI Root Bridge
 188
 189   @retval EFI_SUCCESS           Success
 190   @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
 191   @retval EFI_INVALID_PARAMETER Attributes is NULL
 192
 193 **/
 194 typedef
 195 EFI_STATUS
 196 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES)(
 197   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL           *This,
 198   IN  EFI_HANDLE                                                RootBridgeHandle,
 199   OUT UINT64                                                    *Attributes
 200   );
 201
 202
 203 /**
 204   This is the request from the PCI enumerator to set up
 205   the specified PCI Root Bridge for bus enumeration process.
 206
 207   @param  This                  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
 208   @param  RootBridgeHandle      The PCI Root Bridge to be set up
 209   @param  Configuration         Pointer to the pointer to the PCI bus resource descriptor
 210
 211   @retval EFI_SUCCESS           Success
 212   @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
 213   @retval EFI_DEVICE_ERROR      Request failed due to hardware error
 214   @retval EFI_OUT_OF_RESOURCES  Request failed due to lack of resources
 215
 216 **/
 217 typedef
 218 EFI_STATUS
 219 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION)(
 220   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL           *This,
 221   IN  EFI_HANDLE                                                RootBridgeHandle,
 222   OUT VOID                                                      **Configuration
 223   );
 224
 225
 226 /**
 227   This function programs the PCI Root Bridge hardware so that
 228   it decodes the specified PCI bus range
 229
 230   @param  This                  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
 231   @param  RootBridgeHandle      The PCI Root Bridge whose bus range is to be programmed
 232   @param  Configuration         The pointer to the PCI bus resource descriptor
 233
 234   @retval EFI_SUCCESS           Success
 235   @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
 236   @retval EFI_INVALID_PARAMETER Configuration is NULL
 237   @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
 238   @retval EFI_INVALID_PARAMETER Configuration contains one or more memory or IO ACPI resource descriptor
 239   @retval EFI_INVALID_PARAMETER Address Range Minimum or Address Range Length fields in Configuration
 240                                 are invalid for this Root Bridge.
 241   @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource descriptor
 242   @retval EFI_DEVICE_ERROR      Request failed due to hardware error
 243   @retval EFI_OUT_OF_RESOURCES  Request failed due to lack of resources
 244
 245 **/
 246 typedef
 247 EFI_STATUS
 248 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS)(
 249   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL          *This,
 250   IN EFI_HANDLE                                                RootBridgeHandle,
 251   IN VOID                                                      *Configuration
 252   );
 253
 254
 255 /**
 256   Submits the I/O and memory resource requirements for the specified PCI Root Bridge
 257
 258   @param  This                  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
 259   @param  RootBridgeHandle      The PCI Root Bridge whose I/O and memory resource requirements
 260                                 are being submitted
 261   @param  Configuration         The pointer to the PCI I/O and PCI memory resource descriptor
 262
 263   @retval EFI_SUCCESS           Success
 264   @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
 265   @retval EFI_INVALID_PARAMETER Configuration is NULL
 266   @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
 267   @retval EFI_INVALID_PARAMETER Configuration includes a resource descriptor of unsupported type
 268
 269 **/
 270 typedef
 271 EFI_STATUS
 272 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES)(
 273   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL          *This,
 274   IN EFI_HANDLE                                                RootBridgeHandle,
 275   IN VOID                                                      *Configuration
 276   );
 277
 278
 279 /**
 280   This function returns the proposed resource settings for the specified
 281   PCI Root Bridge
 282
 283   @param  This                  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
 284   @param  RootBridgeHandle      The PCI Root Bridge handle
 285   @param  Configuration         The pointer to the pointer to the PCI I/O
 286                                 and memory resource descriptor
 287
 288   @retval EFI_SUCCESS           Success
 289   @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
 290   @retval EFI_DEVICE_ERROR      Request failed due to hardware error
 291   @retval EFI_OUT_OF_RESOURCES  Request failed due to lack of resources
 292
 293 **/
 294 typedef
 295 EFI_STATUS
 296 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES)(
 297   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL           *This,
 298   IN  EFI_HANDLE                                                RootBridgeHandle,
 299   OUT VOID                                                      **Configuration
 300   );
 301
 302
 303
 304 /**
 305   This function is called for all the PCI controllers that the PCI
 306   bus driver finds. Can be used to Preprogram the controller.
 307
 308   @param  This                  The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
 309   @param  RootBridgeHandle      The PCI Root Bridge handle
 310   @param  PciBusAddress         Address of the controller on the PCI bus
 311   @param  Phase                 The Phase during resource allocation
 312
 313   @retval EFI_SUCCESS           Success
 314   @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
 315   @retval EFI_DEVICE_ERROR      Device pre-initialization failed due to hardware error.
 316
 317 **/
 318 typedef
 319 EFI_STATUS
 320 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER)(
 321   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL            *This,
 322   IN  EFI_HANDLE                                                 RootBridgeHandle,
 323   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS                PciAddress,
 324   IN  EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE               Phase
 325   );
 326
 327 /**
 328   @par Protocol Description:
 329   Provides the basic interfaces to abstract a PCI host bridge resource allocation.
 330
 331   @param NotifyPhase
 332   The notification from the PCI bus enumerator that it is about to enter
 333   a certain phase during the enumeration process.
 334
 335   @param GetNextRootBridge
 336   Retrieves the device handle for the next PCI root bridge that is produced by the
 337   host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached.
 338
 339   @param GetAllocAttributes
 340   Retrieves the allocation-related attributes of a PCI root bridge.
 341
 342   @param StartBusEnumeration
 343   Sets up a PCI root bridge for bus enumeration.
 344
 345   @param SetBusNumbers
 346   Sets up the PCI root bridge so that it decodes a specific range of bus numbers.
 347
 348   @param SubmitResources
 349   Submits the resource requirements for the specified PCI root bridge.
 350
 351   @param GetProposedResources
 352   Returns the proposed resource assignment for the specified PCI root bridges.
 353
 354   @param PreprocessController
 355   Provides hooks from the PCI bus driver to every PCI controller
 356   (device/function) at various stages of the PCI enumeration process that
 357   allow the host bridge driver to preinitialize individual PCI controllers
 358   before enumeration.
 359
 360 **/
 361 struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL {
 362   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE           NotifyPhase;
 363   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE   GetNextRootBridge;
 364   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES         GetAllocAttributes;
 365   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION  StartBusEnumeration;
 366   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS        SetBusNumbers;
 367   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES       SubmitResources;
 368   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources;
 369   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER  PreprocessController;
 370 };
 371
 372 extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid;
 373
 374 #endif