EdkCompatibilityPkg/Foundation/Framework/Protocol/PciHostBridgeResourceAllocation/PciHostBridgeResourceAllocation.h

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