IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h

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