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