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] This                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 This              Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
 409    @param RootBridgeHandle  The associated PCI root bridge handle. Type EFI_HANDLE is defined in
 410                             InstallProtocolInterface() in the UEFI 2.0 Specification.
 411    @param PciAddress        The address of the PCI device on the PCI bus. This address can be passed to the
 412                             EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL member functions to access the PCI
 413                             configuration space of the device. See Table 12-1 in the UEFI 2.0 Specification for
 414                             the definition of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS.
 415    @param Phase             The phase of the PCI device enumeration.
 416
 417    @retval EFI_SUCCESS              The requested parameters were returned.
 418    @retval EFI_INVALID_PARAMETER    RootBridgeHandle is not a valid root bridge handle.
 419    @retval EFI_INVALID_PARAMETER    Phase is not a valid phase that is defined in
 420                                     EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE.
 421    @retval EFI_DEVICE_ERROR         Programming failed due to a hardware error. The PCI enumerator should
 422                                     not enumerate this device, including its child devices if it is a PCI-to-PCI
 423                                     bridge.
 424
 425 **/
 426 EFI_STATUS
 427 PreprocessController (
 428   IN PCI_IO_DEVICE                                  *Bridge,
 429   IN UINT8                                          Bus,
 430   IN UINT8                                          Device,
 431   IN UINT8                                          Func,
 432   IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE   Phase
 433   );
 434
 435 /**
 436   Hot plug request notify.
 437
 438   @param This                 - A pointer to the hot plug request protocol.
 439   @param Operation            - The operation.
 440   @param Controller           - A pointer to the controller.
 441   @param RemainningDevicePath - A pointer to the device path.
 442   @param NumberOfChildren     - A the number of child handle in the ChildHandleBuffer.
 443   @param ChildHandleBuffer    - A pointer to the array contain the child handle.
 444
 445   @retval EFI_NOT_FOUND Can not find bridge according to controller handle
 446   @retval EFI_SUCCESS   Success operating
 447 **/
 448 EFI_STATUS
 449 EFIAPI
 450 PciHotPlugRequestNotify (
 451   IN EFI_PCI_HOTPLUG_REQUEST_PROTOCOL * This,
 452   IN EFI_PCI_HOTPLUG_OPERATION        Operation,
 453   IN EFI_HANDLE                       Controller,
 454   IN EFI_DEVICE_PATH_PROTOCOL         * RemainingDevicePath OPTIONAL,
 455   IN OUT UINT8                        *NumberOfChildren,
 456   IN OUT EFI_HANDLE                   * ChildHandleBuffer
 457   );
 458
 459 /**
 460   Search hostbridge according to given handle
 461
 462   @return whether 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