IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciEnumerator.h

   1 /** @file
   2   Header file declares all logic function for PCI bus enumeration.
   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 **/
  14
  15
  16 #ifndef _EFI_PCI_ENUMERATOR_H_
  17 #define _EFI_PCI_ENUMERATOR_H_
  18
  19 #include "PciResourceSupport.h"
  20
  21 /**
  22   This routine is used to enumerate entire pci bus system
  23   in a given platform
  24
  25   @param Controller  Parent controller handle.
  26
  27   @return Status of enumerating.
  28 **/
  29 EFI_STATUS
  30 PciEnumerator (
  31   IN EFI_HANDLE                    Controller
  32   );
  33
  34 /**
  35   Enumerate PCI root bridge
  36
  37   @param PciResAlloc   Pointer to protocol instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
  38   @param RootBridgeDev Instance of root bridge device.
  39
  40   @retval EFI_SUCCESS  Success to enumerate root bridge.
  41   @retval Others       Fail to enumerate root bridge.
  42
  43 **/
  44 EFI_STATUS
  45 PciRootBridgeEnumerator (
  46   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *PciResAlloc,
  47   IN PCI_IO_DEVICE                                     *RootBridgeDev
  48   );
  49
  50 /**
  51   This routine is used to process option rom on a certain root bridge
  52
  53   @param Bridge     Given parent's root bridge.
  54   @param RomBase    Base address of ROM driver loaded from.
  55   @param MaxLength  Max rom size.
  56
  57   @retval EFI_SUCCESS Success to process option rom image.
  58 **/
  59 EFI_STATUS
  60 ProcessOptionRom (
  61   IN PCI_IO_DEVICE *Bridge,
  62   IN UINT64        RomBase,
  63   IN UINT64        MaxLength
  64   );
  65
  66 /**
  67   This routine is used to assign bus number to the given PCI bus system
  68
  69   @param Bridge           Parent root bridge instance.
  70   @param StartBusNumber   Number of beginning.
  71   @param SubBusNumber     the number of sub bus.
  72
  73   @retval EFI_SUCCESS  Success to assign bus number.
  74 **/
  75 EFI_STATUS
  76 PciAssignBusNumber (
  77   IN PCI_IO_DEVICE                      *Bridge,
  78   IN UINT8                              StartBusNumber,
  79   OUT UINT8                             *SubBusNumber
  80   );
  81
  82 /**
  83   This routine is used to determine the root bridge attribute by interfacing
  84   the host bridge resource allocation protocol.
  85
  86   @param PciResAlloc    Protocol instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.
  87   @param RootBridgeDev  Root bridge instance.
  88
  89   @retval EFI_SUCCESS  Success to get root bridge's attribute.
  90   @retval Others       Fail to get attribute.
  91 **/
  92 EFI_STATUS
  93 DetermineRootBridgeAttributes (
  94   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc,
  95   IN PCI_IO_DEVICE                                    *RootBridgeDev
  96   );
  97
  98 /**
  99   Get Max Option Rom size on this bridge
 100
 101   @param Bridge  Bridge device instance.
 102   @return Max size of option rom.
 103 **/
 104 UINT64
 105 GetMaxOptionRomSize (
 106   IN PCI_IO_DEVICE   *Bridge
 107   );
 108
 109 /**
 110   Process attributes of devices on this host bridge
 111
 112   @param PciResAlloc Protocol instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
 113
 114   @retval EFI_NOT_FOUND Can not find the specific root bridge device.
 115   @retval EFI_SUCCESS   Success Process attribute.
 116   @retval Others        Can not determine the root bridge device's attribute.
 117 **/
 118 EFI_STATUS
 119 PciHostBridgeDeviceAttribute (
 120   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc
 121   );
 122
 123 /**
 124   Get resource allocation status from the ACPI pointer
 125
 126   @param AcpiConfig       Point to Acpi configuration table.
 127   @param IoResStatus      Return the status of I/O resource.
 128   @param Mem32ResStatus   Return the status of 32-bit Memory resource.
 129   @param PMem32ResStatus  Return the status of 32-bit PMemory resource.
 130   @param Mem64ResStatus   Return the status of 64-bit Memory resource.
 131   @param PMem64ResStatus  Return the status of 64-bit PMemory resource.
 132
 133   @retval EFI_SUCCESS Success to get resource allocation status from ACPI configuration table.
 134 **/
 135 EFI_STATUS
 136 GetResourceAllocationStatus (
 137   VOID        *AcpiConfig,
 138   OUT UINT64  *IoResStatus,
 139   OUT UINT64  *Mem32ResStatus,
 140   OUT UINT64  *PMem32ResStatus,
 141   OUT UINT64  *Mem64ResStatus,
 142   OUT UINT64  *PMem64ResStatus
 143   );
 144
 145 /**
 146   Remove a PCI device from device pool and mark its bar
 147
 148   @param PciDevice Instance of Pci device.
 149
 150   @retval EFI_SUCCESS Success Operation.
 151   @retval EFI_ABORTED Pci device is a root bridge.
 152 **/
 153 EFI_STATUS
 154 RejectPciDevice (
 155   IN PCI_IO_DEVICE       *PciDevice
 156   );
 157
 158 /**
 159   Determine whethter a PCI device can be rejected
 160
 161   @param PciResNode Pointer to Pci resource node instance.
 162
 163   @return whethter a PCI device can be rejected.
 164 **/
 165 BOOLEAN
 166 IsRejectiveDevice (
 167   IN  PCI_RESOURCE_NODE   *PciResNode
 168   );
 169
 170 /**
 171   Compare two resource node and get the larger resource consumer
 172
 173   @param PciResNode1  resource node 1 want to be compared.
 174   @param PciResNode2  resource node 2 want to be compared.
 175
 176   @return Larger resource consumer.
 177 **/
 178 PCI_RESOURCE_NODE *
 179 GetLargerConsumerDevice (
 180   IN  PCI_RESOURCE_NODE   *PciResNode1,
 181   IN  PCI_RESOURCE_NODE   *PciResNode2
 182   );
 183
 184 /**
 185   Get the max resource consumer in the host resource pool
 186
 187   @param ResPool  Pointer to resource pool node.
 188
 189   @return the max resource consumer in the host resource pool.
 190 **/
 191 PCI_RESOURCE_NODE *
 192 GetMaxResourceConsumerDevice (
 193   IN  PCI_RESOURCE_NODE   *ResPool
 194   );
 195
 196 /**
 197   Adjust host bridge allocation so as to reduce resource requirement
 198
 199   @param IoPool           Pointer to instance of I/O resource Node.
 200   @param Mem32Pool        Pointer to instance of 32-bit memory resource Node.
 201   @param PMem32Pool       Pointer to instance of 32-bit Pmemory resource node.
 202   @param Mem64Pool        Pointer to instance of 64-bit memory resource node.
 203   @param PMem64Pool       Pointer to instance of 64-bit Pmemory resource node.
 204   @param IoResStatus      Status of I/O resource Node.
 205   @param Mem32ResStatus   Status of 32-bit memory resource Node.
 206   @param PMem32ResStatus  Status of 32-bit Pmemory resource node.
 207   @param Mem64ResStatus   Status of 64-bit memory resource node.
 208   @param PMem64ResStatus  Status of 64-bit Pmemory resource node.
 209 **/
 210 EFI_STATUS
 211 PciHostBridgeAdjustAllocation (
 212   IN  PCI_RESOURCE_NODE   *IoPool,
 213   IN  PCI_RESOURCE_NODE   *Mem32Pool,
 214   IN  PCI_RESOURCE_NODE   *PMem32Pool,
 215   IN  PCI_RESOURCE_NODE   *Mem64Pool,
 216   IN  PCI_RESOURCE_NODE   *PMem64Pool,
 217   IN  UINT64              IoResStatus,
 218   IN  UINT64              Mem32ResStatus,
 219   IN  UINT64              PMem32ResStatus,
 220   IN  UINT64              Mem64ResStatus,
 221   IN  UINT64              PMem64ResStatus
 222   );
 223
 224 /**
 225   Summary requests for all resource type, and contruct ACPI resource
 226   requestor instance.
 227
 228   @param Bridge           detecting bridge.
 229   @param IoNode           Pointer to instance of I/O resource Node.
 230   @param Mem32Node        Pointer to instance of 32-bit memory resource Node.
 231   @param PMem32Node       Pointer to instance of 32-bit Pmemory resource node.
 232   @param Mem64Node        Pointer to instance of 64-bit memory resource node.
 233   @param PMem64Node       Pointer to instance of 64-bit Pmemory resource node.
 234   @param pConfig          outof buffer holding new constructed APCI resource requestor.
 235 **/
 236 EFI_STATUS
 237 ConstructAcpiResourceRequestor (
 238   IN PCI_IO_DEVICE      *Bridge,
 239   IN PCI_RESOURCE_NODE  *IoNode,
 240   IN PCI_RESOURCE_NODE  *Mem32Node,
 241   IN PCI_RESOURCE_NODE  *PMem32Node,
 242   IN PCI_RESOURCE_NODE  *Mem64Node,
 243   IN PCI_RESOURCE_NODE  *PMem64Node,
 244   OUT VOID              **pConfig
 245   );
 246
 247 /**
 248   Get resource base from a acpi configuration descriptor.
 249
 250   @param pConfig      an acpi configuration descriptor.
 251   @param IoBase       output of I/O resource base address.
 252   @param Mem32Base    output of 32-bit memory base address.
 253   @param PMem32Base   output of 32-bit pmemory base address.
 254   @param Mem64Base    output of 64-bit memory base address.
 255   @param PMem64Base   output of 64-bit pmemory base address.
 256
 257   @return EFI_SUCCESS  Success operation.
 258 **/
 259 EFI_STATUS
 260 GetResourceBase (
 261   IN VOID     *pConfig,
 262   OUT UINT64  *IoBase,
 263   OUT UINT64  *Mem32Base,
 264   OUT UINT64  *PMem32Base,
 265   OUT UINT64  *Mem64Base,
 266   OUT UINT64  *PMem64Base
 267   );
 268
 269 /**
 270   Enumerate pci bridge, allocate resource and determine attribute
 271   for devices on this bridge
 272
 273   @param BridgeDev Pointer to instance of bridge device.
 274
 275   @retval EFI_SUCCESS Success operation.
 276   @retval Others      Fail to enumerate.
 277 **/
 278 EFI_STATUS
 279 PciBridgeEnumerator (
 280   IN PCI_IO_DEVICE                                     *BridgeDev
 281   );
 282
 283 /**
 284   Allocate all kinds of resource for bridge
 285
 286   @param Bridge      Pointer to bridge instance.
 287
 288   @retval EFI_SUCCESS Success operation.
 289   @retval Others      Fail to allocate resource for bridge.
 290 **/
 291 EFI_STATUS
 292 PciBridgeResourceAllocator (
 293   IN PCI_IO_DEVICE  *Bridge
 294   );
 295
 296 /**
 297   Get resource base address for a pci bridge device
 298
 299   @param Bridge  Given Pci driver instance.
 300   @param IoBase  output for base address of I/O type resource.
 301   @param Mem32Base  output for base address of 32-bit memory type resource.
 302   @param PMem32Base  output for base address of 32-bit Pmemory type resource.
 303   @param Mem64Base  output for base address of 64-bit memory type resource.
 304   @param PMem64Base  output for base address of 64-bit Pmemory type resource.
 305
 306   @retval EFI_SUCCESS Succes to get resource base address.
 307 **/
 308 EFI_STATUS
 309 GetResourceBaseFromBridge (
 310   IN  PCI_IO_DEVICE *Bridge,
 311   OUT UINT64        *IoBase,
 312   OUT UINT64        *Mem32Base,
 313   OUT UINT64        *PMem32Base,
 314   OUT UINT64        *Mem64Base,
 315   OUT UINT64        *PMem64Base
 316   );
 317
 318 /**
 319   Process Option Rom on this host bridge
 320
 321   @param PciResAlloc Pointer to instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.
 322
 323   @retval EFI_NOT_FOUND Can not find the root bridge instance.
 324   @retval EFI_SUCCESS   Success process.
 325 **/
 326 EFI_STATUS
 327 PciHostBridgeP2CProcess (
 328   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc
 329   );
 330
 331 /**
 332    These are the notifications from the PCI bus driver that it is about to enter a certain
 333    phase of the PCI enumeration process.
 334
 335    This member function can be used to notify the host bridge driver to perform specific actions,
 336    including any chipset-specific initialization, so that the chipset is ready to enter the next phase.
 337    Eight notification points are defined at this time. See belows:
 338    EfiPciHostBridgeBeginEnumeration     - Resets the host bridge PCI apertures and internal data
 339                                           structures. The PCI enumerator should issue this notification
 340                                           before starting a fresh enumeration process. Enumeration cannot
 341                                           be restarted after sending any other notification such as
 342                                           EfiPciHostBridgeBeginBusAllocation.
 343    EfiPciHostBridgeBeginBusAllocation   - The bus allocation phase is about to begin. No specific action is
 344                                           required here. This notification can be used to perform any
 345                                           chipset-specific programming.
 346    EfiPciHostBridgeEndBusAllocation     - The bus allocation and bus programming phase is complete. No
 347                                           specific action is required here. This notification can be used to
 348                                           perform any chipset-specific programming.
 349    EfiPciHostBridgeBeginResourceAllocation -  The resource allocation phase is about to begin. No specific
 350                                               action is required here. This notification can be used to perform
 351                                               any chipset-specific programming.
 352    EfiPciHostBridgeAllocateResources    - Allocates resources per previously submitted requests for all the PCI
 353                                           root bridges. These resource settings are returned on the next call to
 354                                           GetProposedResources(). Before calling NotifyPhase() with a Phase of
 355                                           EfiPciHostBridgeAllocateResource, the PCI bus enumerator is responsible for gathering I/O and memory requests for
 356                                           all the PCI root bridges and submitting these requests using
 357                                           SubmitResources(). This function pads the resource amount
 358                                           to suit the root bridge hardware, takes care of dependencies between
 359                                           the PCI root bridges, and calls the Global Coherency Domain (GCD)
 360                                           with the allocation request. In the case of padding, the allocated range
 361                                           could be bigger than what was requested.
 362    EfiPciHostBridgeSetResources         - Programs the host bridge hardware to decode previously allocated
 363                                           resources (proposed resources) for all the PCI root bridges. After the
 364                                           hardware is programmed, reassigning resources will not be supported.
 365                                           The bus settings are not affected.
 366    EfiPciHostBridgeFreeResources        - Deallocates resources that were previously allocated for all the PCI
 367                                           root bridges and resets the I/O and memory apertures to their initial
 368                                           state. The bus settings are not affected. If the request to allocate
 369                                           resources fails, the PCI enumerator can use this notification to
 370                                           deallocate previous resources, adjust the requests, and retry
 371                                           allocation.
 372    EfiPciHostBridgeEndResourceAllocation- The resource allocation phase is completed. No specific action is
 373                                           required here. This notification can be used to perform any chipsetspecific
 374                                           programming.
 375
 376    @param[in] PciResAlloc         The instance pointer of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
 377    @param[in] Phase               The phase during enumeration
 378
 379    @retval EFI_NOT_READY          This phase cannot be entered at this time. For example, this error
 380                                   is valid for a Phase of EfiPciHostBridgeAllocateResources if
 381                                   SubmitResources() has not been called for one or more
 382                                   PCI root bridges before this call
 383    @retval EFI_DEVICE_ERROR       Programming failed due to a hardware error. This error is valid
 384                                   for a Phase of EfiPciHostBridgeSetResources.
 385    @retval EFI_INVALID_PARAMETER  Invalid phase parameter
 386    @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.
 387                                   This error is valid for a Phase of EfiPciHostBridgeAllocateResources if the
 388                                   previously submitted resource requests cannot be fulfilled or
 389                                   were only partially fulfilled.
 390    @retval EFI_SUCCESS            The notification was accepted without any errors.
 391
 392 **/
 393 EFI_STATUS
 394 NotifyPhase (
 395   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc,
 396   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE       Phase
 397   );
 398
 399 /**
 400    Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various
 401    stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual
 402    PCI controllers before enumeration.
 403
 404    This function is called during the PCI enumeration process. No specific action is expected from this
 405    member function. It allows the host bridge driver to preinitialize individual PCI controllers before
 406    enumeration.
 407
 408    @param Bridge            Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
 409    @param Bus               The bus number of the pci device.
 410    @param Device            The device number of the pci device.
 411    @param Func              The function number of the pci device.
 412    @param Phase             The phase of the PCI device enumeration.
 413
 414    @retval EFI_SUCCESS              The requested parameters were returned.
 415    @retval EFI_INVALID_PARAMETER    RootBridgeHandle is not a valid root bridge handle.
 416    @retval EFI_INVALID_PARAMETER    Phase is not a valid phase that is defined in
 417                                     EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE.
 418    @retval EFI_DEVICE_ERROR         Programming failed due to a hardware error. The PCI enumerator should
 419                                     not enumerate this device, including its child devices if it is a PCI-to-PCI
 420                                     bridge.
 421
 422 **/
 423 EFI_STATUS
 424 PreprocessController (
 425   IN PCI_IO_DEVICE                                  *Bridge,
 426   IN UINT8                                          Bus,
 427   IN UINT8                                          Device,
 428   IN UINT8                                          Func,
 429   IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE   Phase
 430   );
 431
 432 /**
 433   Hot plug request notify.
 434
 435   @param This                 - A pointer to the hot plug request protocol.
 436   @param Operation            - The operation.
 437   @param Controller           - A pointer to the controller.
 438   @param RemainingDevicePath  - A pointer to the device path.
 439   @param NumberOfChildren     - A the number of child handle in the ChildHandleBuffer.
 440   @param ChildHandleBuffer    - A pointer to the array contain the child handle.
 441
 442   @retval EFI_NOT_FOUND Can not find bridge according to controller handle.
 443   @retval EFI_SUCCESS   Success operating.
 444 **/
 445 EFI_STATUS
 446 EFIAPI
 447 PciHotPlugRequestNotify (
 448   IN EFI_PCI_HOTPLUG_REQUEST_PROTOCOL * This,
 449   IN EFI_PCI_HOTPLUG_OPERATION        Operation,
 450   IN EFI_HANDLE                       Controller,
 451   IN EFI_DEVICE_PATH_PROTOCOL         * RemainingDevicePath OPTIONAL,
 452   IN OUT UINT8                        *NumberOfChildren,
 453   IN OUT EFI_HANDLE                   * ChildHandleBuffer
 454   );
 455
 456 /**
 457   Search hostbridge according to given handle
 458
 459   @param RootBridgeHandle     - Host bridge handle.
 460
 461   @return TRUE  Found.
 462   @return FALSE Not found.
 463 **/
 464 BOOLEAN
 465 SearchHostBridgeHandle (
 466   IN EFI_HANDLE RootBridgeHandle
 467   );
 468
 469 /**
 470   Add host bridge handle to global variable for enumating.
 471
 472   @param HostBridgeHandle host bridge handle.
 473 **/
 474 EFI_STATUS
 475 AddHostBridgeEnumerator (
 476   IN EFI_HANDLE HostBridgeHandle
 477   );
 478
 479 #endif