Tools/Source/TianoTools/Include/Protocol/PciHostBridgeResourceAllocation.h

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