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