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 Config           Output 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              **Config
 245   );
 246
 247 /**
 248   Get resource base from an acpi configuration descriptor.
 249
 250   @param Config       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    Get resource base address successfully.
 258
 259 **/
 260 EFI_STATUS
 261 GetResourceBase (
 262   IN VOID     *Config,
 263   OUT UINT64  *IoBase,
 264   OUT UINT64  *Mem32Base,
 265   OUT UINT64  *PMem32Base,
 266   OUT UINT64  *Mem64Base,
 267   OUT UINT64  *PMem64Base
 268   );
 269
 270 /**
 271   Enumerate pci bridge, allocate resource and determine attribute
 272   for devices on this bridge
 273
 274   @param BridgeDev Pointer to instance of bridge device.
 275
 276   @retval EFI_SUCCESS Success operation.
 277   @retval Others      Fail to enumerate.
 278 **/
 279 EFI_STATUS
 280 PciBridgeEnumerator (
 281   IN PCI_IO_DEVICE                                     *BridgeDev
 282   );
 283
 284 /**
 285   Allocate all kinds of resource for bridge
 286
 287   @param Bridge      Pointer to bridge instance.
 288
 289   @retval EFI_SUCCESS Success operation.
 290   @retval Others      Fail to allocate resource for bridge.
 291 **/
 292 EFI_STATUS
 293 PciBridgeResourceAllocator (
 294   IN PCI_IO_DEVICE  *Bridge
 295   );
 296
 297 /**
 298   Get resource base address for a pci bridge device
 299
 300   @param Bridge  Given Pci driver instance.
 301   @param IoBase  output for base address of I/O type resource.
 302   @param Mem32Base  output for base address of 32-bit memory type resource.
 303   @param PMem32Base  output for base address of 32-bit Pmemory type resource.
 304   @param Mem64Base  output for base address of 64-bit memory type resource.
 305   @param PMem64Base  output for base address of 64-bit Pmemory type resource.
 306
 307   @retval EFI_SUCCESS Succes to get resource base address.
 308 **/
 309 EFI_STATUS
 310 GetResourceBaseFromBridge (
 311   IN  PCI_IO_DEVICE *Bridge,
 312   OUT UINT64        *IoBase,
 313   OUT UINT64        *Mem32Base,
 314   OUT UINT64        *PMem32Base,
 315   OUT UINT64        *Mem64Base,
 316   OUT UINT64        *PMem64Base
 317   );
 318
 319 /**
 320   Process Option Rom on this host bridge
 321
 322   @param PciResAlloc Pointer to instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.
 323
 324   @retval EFI_NOT_FOUND Can not find the root bridge instance.
 325   @retval EFI_SUCCESS   Success process.
 326 **/
 327 EFI_STATUS
 328 PciHostBridgeP2CProcess (
 329   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc
 330   );
 331
 332 /**
 333    These are the notifications from the PCI bus driver that it is about to enter a certain
 334    phase of the PCI enumeration process.
 335
 336    This member function can be used to notify the host bridge driver to perform specific actions,
 337    including any chipset-specific initialization, so that the chipset is ready to enter the next phase.
 338    Eight notification points are defined at this time. See belows:
 339    EfiPciHostBridgeBeginEnumeration     - Resets the host bridge PCI apertures and internal data
 340                                           structures. The PCI enumerator should issue this notification
 341                                           before starting a fresh enumeration process. Enumeration cannot
 342                                           be restarted after sending any other notification such as
 343                                           EfiPciHostBridgeBeginBusAllocation.
 344    EfiPciHostBridgeBeginBusAllocation   - The bus allocation phase is about to begin. No specific action is
 345                                           required here. This notification can be used to perform any
 346                                           chipset-specific programming.
 347    EfiPciHostBridgeEndBusAllocation     - The bus allocation and bus programming phase is complete. No
 348                                           specific action is required here. This notification can be used to
 349                                           perform any chipset-specific programming.
 350    EfiPciHostBridgeBeginResourceAllocation -  The resource allocation phase is about to begin. No specific
 351                                               action is required here. This notification can be used to perform
 352                                               any chipset-specific programming.
 353    EfiPciHostBridgeAllocateResources    - Allocates resources per previously submitted requests for all the PCI
 354                                           root bridges. These resource settings are returned on the next call to
 355                                           GetProposedResources(). Before calling NotifyPhase() with a Phase of
 356                                           EfiPciHostBridgeAllocateResource, the PCI bus enumerator is responsible for gathering I/O and memory requests for
 357                                           all the PCI root bridges and submitting these requests using
 358                                           SubmitResources(). This function pads the resource amount
 359                                           to suit the root bridge hardware, takes care of dependencies between
 360                                           the PCI root bridges, and calls the Global Coherency Domain (GCD)
 361                                           with the allocation request. In the case of padding, the allocated range
 362                                           could be bigger than what was requested.
 363    EfiPciHostBridgeSetResources         - Programs the host bridge hardware to decode previously allocated
 364                                           resources (proposed resources) for all the PCI root bridges. After the
 365                                           hardware is programmed, reassigning resources will not be supported.
 366                                           The bus settings are not affected.
 367    EfiPciHostBridgeFreeResources        - Deallocates resources that were previously allocated for all the PCI
 368                                           root bridges and resets the I/O and memory apertures to their initial
 369                                           state. The bus settings are not affected. If the request to allocate
 370                                           resources fails, the PCI enumerator can use this notification to
 371                                           deallocate previous resources, adjust the requests, and retry
 372                                           allocation.
 373    EfiPciHostBridgeEndResourceAllocation- The resource allocation phase is completed. No specific action is
 374                                           required here. This notification can be used to perform any chipsetspecific
 375                                           programming.
 376
 377    @param[in] PciResAlloc         The instance pointer of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
 378    @param[in] Phase               The phase during enumeration
 379
 380    @retval EFI_NOT_READY          This phase cannot be entered at this time. For example, this error
 381                                   is valid for a Phase of EfiPciHostBridgeAllocateResources if
 382                                   SubmitResources() has not been called for one or more
 383                                   PCI root bridges before this call
 384    @retval EFI_DEVICE_ERROR       Programming failed due to a hardware error. This error is valid
 385                                   for a Phase of EfiPciHostBridgeSetResources.
 386    @retval EFI_INVALID_PARAMETER  Invalid phase parameter
 387    @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.
 388                                   This error is valid for a Phase of EfiPciHostBridgeAllocateResources if the
 389                                   previously submitted resource requests cannot be fulfilled or
 390                                   were only partially fulfilled.
 391    @retval EFI_SUCCESS            The notification was accepted without any errors.
 392
 393 **/
 394 EFI_STATUS
 395 NotifyPhase (
 396   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc,
 397   EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE       Phase
 398   );
 399
 400 /**
 401    Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various
 402    stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual
 403    PCI controllers before enumeration.
 404
 405    This function is called during the PCI enumeration process. No specific action is expected from this
 406    member function. It allows the host bridge driver to preinitialize individual PCI controllers before
 407    enumeration.
 408
 409    @param Bridge            Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
 410    @param Bus               The bus number of the pci device.
 411    @param Device            The device number of the pci device.
 412    @param Func              The function number of the pci device.
 413    @param Phase             The phase of the PCI device enumeration.
 414
 415    @retval EFI_SUCCESS              The requested parameters were returned.
 416    @retval EFI_INVALID_PARAMETER    RootBridgeHandle is not a valid root bridge handle.
 417    @retval EFI_INVALID_PARAMETER    Phase is not a valid phase that is defined in
 418                                     EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE.
 419    @retval EFI_DEVICE_ERROR         Programming failed due to a hardware error. The PCI enumerator should
 420                                     not enumerate this device, including its child devices if it is a PCI-to-PCI
 421                                     bridge.
 422
 423 **/
 424 EFI_STATUS
 425 PreprocessController (
 426   IN PCI_IO_DEVICE                                  *Bridge,
 427   IN UINT8                                          Bus,
 428   IN UINT8                                          Device,
 429   IN UINT8                                          Func,
 430   IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE   Phase
 431   );
 432
 433 /**
 434   Hot plug request notify.
 435
 436   @param This                 - A pointer to the hot plug request protocol.
 437   @param Operation            - The operation.
 438   @param Controller           - A pointer to the controller.
 439   @param RemainingDevicePath  - A pointer to the device path.
 440   @param NumberOfChildren     - A the number of child handle in the ChildHandleBuffer.
 441   @param ChildHandleBuffer    - A pointer to the array contain the child handle.
 442
 443   @retval EFI_NOT_FOUND Can not find bridge according to controller handle.
 444   @retval EFI_SUCCESS   Success operating.
 445 **/
 446 EFI_STATUS
 447 EFIAPI
 448 PciHotPlugRequestNotify (
 449   IN EFI_PCI_HOTPLUG_REQUEST_PROTOCOL * This,
 450   IN EFI_PCI_HOTPLUG_OPERATION        Operation,
 451   IN EFI_HANDLE                       Controller,
 452   IN EFI_DEVICE_PATH_PROTOCOL         * RemainingDevicePath OPTIONAL,
 453   IN OUT UINT8                        *NumberOfChildren,
 454   IN OUT EFI_HANDLE                   * ChildHandleBuffer
 455   );
 456
 457 /**
 458   Search hostbridge according to given handle
 459
 460   @param RootBridgeHandle     - Host bridge handle.
 461
 462   @return TRUE  Found.
 463   @return FALSE Not found.
 464 **/
 465 BOOLEAN
 466 SearchHostBridgeHandle (
 467   IN EFI_HANDLE RootBridgeHandle
 468   );
 469
 470 /**
 471   Add host bridge handle to global variable for enumating.
 472
 473   @param HostBridgeHandle host bridge handle.
 474 **/
 475 EFI_STATUS
 476 AddHostBridgeEnumerator (
 477   IN EFI_HANDLE HostBridgeHandle
 478   );
 479
 480 #endif