MdeModulePkg/Bus/Pci/PciBusDxe/PciEnumeratorSupport.h

   1 /** @file
   2   PCI enumeration support functions declaration for PCI Bus module.
   3
   4 Copyright (c) 2006 - 2021, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _EFI_PCI_ENUMERATOR_SUPPORT_H_
  10 #define _EFI_PCI_ENUMERATOR_SUPPORT_H_
  11
  12 /**
  13   This routine is used to check whether the pci device is present.
  14
  15   @param PciRootBridgeIo   Pointer to instance of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
  16   @param Pci               Output buffer for PCI device configuration space.
  17   @param Bus               PCI bus NO.
  18   @param Device            PCI device NO.
  19   @param Func              PCI Func NO.
  20
  21   @retval EFI_NOT_FOUND    PCI device not present.
  22   @retval EFI_SUCCESS      PCI device is found.
  23
  24 **/
  25 EFI_STATUS
  26 PciDevicePresent (
  27   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *PciRootBridgeIo,
  28   OUT PCI_TYPE00                       *Pci,
  29   IN  UINT8                            Bus,
  30   IN  UINT8                            Device,
  31   IN  UINT8                            Func
  32   );
  33
  34 /**
  35   Collect all the resource information under this root bridge.
  36
  37   A database that records all the information about pci device subject to this
  38   root bridge will then be created.
  39
  40   @param Bridge         Parent bridge instance.
  41   @param StartBusNumber Bus number of beginning.
  42
  43   @retval EFI_SUCCESS   PCI device is found.
  44   @retval other         Some error occurred when reading PCI bridge information.
  45
  46 **/
  47 EFI_STATUS
  48 PciPciDeviceInfoCollector (
  49   IN PCI_IO_DEVICE  *Bridge,
  50   IN UINT8          StartBusNumber
  51   );
  52
  53 /**
  54   Search required device and create PCI device instance.
  55
  56   @param Bridge     Parent bridge instance.
  57   @param Pci        Input PCI device information block.
  58   @param Bus        PCI bus NO.
  59   @param Device     PCI device NO.
  60   @param Func       PCI func  NO.
  61   @param PciDevice  Output of searched PCI device instance.
  62
  63   @retval EFI_SUCCESS           Successfully created PCI device instance.
  64   @retval EFI_OUT_OF_RESOURCES  Cannot get PCI device information.
  65
  66 **/
  67 EFI_STATUS
  68 PciSearchDevice (
  69   IN  PCI_IO_DEVICE  *Bridge,
  70   IN  PCI_TYPE00     *Pci,
  71   IN  UINT8          Bus,
  72   IN  UINT8          Device,
  73   IN  UINT8          Func,
  74   OUT PCI_IO_DEVICE  **PciDevice
  75   );
  76
  77 /**
  78   Create PCI device instance for PCI device.
  79
  80   @param Bridge   Parent bridge instance.
  81   @param Pci      Input PCI device information block.
  82   @param Bus      PCI device Bus NO.
  83   @param Device   PCI device Device NO.
  84   @param Func     PCI device's func NO.
  85
  86   @return  Created PCI device instance.
  87
  88 **/
  89 PCI_IO_DEVICE *
  90 GatherDeviceInfo (
  91   IN PCI_IO_DEVICE  *Bridge,
  92   IN PCI_TYPE00     *Pci,
  93   IN UINT8          Bus,
  94   IN UINT8          Device,
  95   IN UINT8          Func
  96   );
  97
  98 /**
  99   Create PCI device instance for PCI-PCI bridge.
 100
 101   @param Bridge   Parent bridge instance.
 102   @param Pci      Input PCI device information block.
 103   @param Bus      PCI device Bus NO.
 104   @param Device   PCI device Device NO.
 105   @param Func     PCI device's func NO.
 106
 107   @return  Created PCI device instance.
 108
 109 **/
 110 PCI_IO_DEVICE *
 111 GatherPpbInfo (
 112   IN PCI_IO_DEVICE  *Bridge,
 113   IN PCI_TYPE00     *Pci,
 114   IN UINT8          Bus,
 115   IN UINT8          Device,
 116   IN UINT8          Func
 117   );
 118
 119 /**
 120   Create PCI device instance for PCI Card bridge device.
 121
 122   @param Bridge   Parent bridge instance.
 123   @param Pci      Input PCI device information block.
 124   @param Bus      PCI device Bus NO.
 125   @param Device   PCI device Device NO.
 126   @param Func     PCI device's func NO.
 127
 128   @return  Created PCI device instance.
 129
 130 **/
 131 PCI_IO_DEVICE *
 132 GatherP2CInfo (
 133   IN PCI_IO_DEVICE  *Bridge,
 134   IN PCI_TYPE00     *Pci,
 135   IN UINT8          Bus,
 136   IN UINT8          Device,
 137   IN UINT8          Func
 138   );
 139
 140 /**
 141   Create device path for pci device.
 142
 143   @param ParentDevicePath  Parent bridge's path.
 144   @param PciIoDevice       Pci device instance.
 145
 146   @return Device path protocol instance for specific pci device.
 147
 148 **/
 149 EFI_DEVICE_PATH_PROTOCOL *
 150 CreatePciDevicePath (
 151   IN  EFI_DEVICE_PATH_PROTOCOL  *ParentDevicePath,
 152   IN  PCI_IO_DEVICE             *PciIoDevice
 153   );
 154
 155 /**
 156   Check whether the PCI IOV VF bar is existed or not.
 157
 158   @param PciIoDevice       A pointer to the PCI_IO_DEVICE.
 159   @param Offset            The offset.
 160   @param BarLengthValue    The bar length value returned.
 161   @param OriginalBarValue  The original bar value returned.
 162
 163   @retval EFI_NOT_FOUND    The bar doesn't exist.
 164   @retval EFI_SUCCESS      The bar exist.
 165
 166 **/
 167 EFI_STATUS
 168 VfBarExisted (
 169   IN PCI_IO_DEVICE  *PciIoDevice,
 170   IN UINTN          Offset,
 171   OUT UINT32        *BarLengthValue,
 172   OUT UINT32        *OriginalBarValue
 173   );
 174
 175 /**
 176   Check whether the bar is existed or not.
 177
 178   @param PciIoDevice       A pointer to the PCI_IO_DEVICE.
 179   @param Offset            The offset.
 180   @param BarLengthValue    The bar length value returned.
 181   @param OriginalBarValue  The original bar value returned.
 182
 183   @retval EFI_NOT_FOUND    The bar doesn't exist.
 184   @retval EFI_SUCCESS      The bar exist.
 185
 186 **/
 187 EFI_STATUS
 188 BarExisted (
 189   IN  PCI_IO_DEVICE  *PciIoDevice,
 190   IN  UINTN          Offset,
 191   OUT UINT32         *BarLengthValue,
 192   OUT UINT32         *OriginalBarValue
 193   );
 194
 195 /**
 196   Test whether the device can support given attributes.
 197
 198   @param PciIoDevice      Pci device instance.
 199   @param Command          Input command register value, and
 200                           returned supported register value.
 201   @param BridgeControl    Input bridge control value for PPB or P2C, and
 202                           returned supported bridge control value.
 203   @param OldCommand       Returned and stored old command register offset.
 204   @param OldBridgeControl Returned and stored old Bridge control value for PPB or P2C.
 205
 206 **/
 207 VOID
 208 PciTestSupportedAttribute (
 209   IN     PCI_IO_DEVICE  *PciIoDevice,
 210   IN OUT UINT16         *Command,
 211   IN OUT UINT16         *BridgeControl,
 212   OUT UINT16            *OldCommand,
 213   OUT UINT16            *OldBridgeControl
 214   );
 215
 216 /**
 217   Set the supported or current attributes of a PCI device.
 218
 219   @param PciIoDevice    Structure pointer for PCI device.
 220   @param Command        Command register value.
 221   @param BridgeControl  Bridge control value for PPB or P2C.
 222   @param Option         Make a choice of EFI_SET_SUPPORTS or EFI_SET_ATTRIBUTES.
 223
 224 **/
 225 VOID
 226 PciSetDeviceAttribute (
 227   IN PCI_IO_DEVICE  *PciIoDevice,
 228   IN UINT16         Command,
 229   IN UINT16         BridgeControl,
 230   IN UINTN          Option
 231   );
 232
 233 /**
 234   Determine if the device can support Fast Back to Back attribute.
 235
 236   @param PciIoDevice  Pci device instance.
 237   @param StatusIndex  Status register value.
 238
 239   @retval EFI_SUCCESS       This device support Fast Back to Back attribute.
 240   @retval EFI_UNSUPPORTED   This device doesn't support Fast Back to Back attribute.
 241
 242 **/
 243 EFI_STATUS
 244 GetFastBackToBackSupport (
 245   IN PCI_IO_DEVICE  *PciIoDevice,
 246   IN UINT8          StatusIndex
 247   );
 248
 249 /**
 250   Determine the related attributes of all devices under a Root Bridge.
 251
 252   @param PciIoDevice   PCI device instance.
 253
 254 **/
 255 EFI_STATUS
 256 DetermineDeviceAttribute (
 257   IN PCI_IO_DEVICE  *PciIoDevice
 258   );
 259
 260 /**
 261   This routine is used to update the bar information for those incompatible PCI device.
 262
 263   @param PciIoDevice      Input Pci device instance. Output Pci device instance with updated
 264                           Bar information.
 265   @param IgnoreOptionRom  Output If the option rom of incompatible device need to be ignored.
 266
 267   @retval EFI_SUCCESS     Successfully updated bar information.
 268   @retval EFI_UNSUPPORTED Given PCI device doesn't belong to incompatible PCI device list.
 269
 270 **/
 271 EFI_STATUS
 272 UpdatePciInfo (
 273   IN OUT PCI_IO_DEVICE  *PciIoDevice,
 274   OUT BOOLEAN           *IgnoreOptionRom
 275   );
 276
 277 /**
 278   This routine will update the alignment with the new alignment.
 279
 280   @param Alignment    Input Old alignment. Output updated alignment.
 281   @param NewAlignment New alignment.
 282
 283 **/
 284 VOID
 285 SetNewAlign (
 286   IN OUT UINT64  *Alignment,
 287   IN     UINT64  NewAlignment
 288   );
 289
 290 /**
 291   Parse PCI bar information and fill them into PCI device instance.
 292
 293   @param PciIoDevice  Pci device instance.
 294   @param Offset       Bar offset.
 295   @param BarIndex     Bar index.
 296
 297   @return Next bar offset.
 298
 299 **/
 300 UINTN
 301 PciParseBar (
 302   IN PCI_IO_DEVICE  *PciIoDevice,
 303   IN UINTN          Offset,
 304   IN UINTN          BarIndex
 305   );
 306
 307 /**
 308   Parse PCI IOV VF bar information and fill them into PCI device instance.
 309
 310   @param PciIoDevice  Pci device instance.
 311   @param Offset       Bar offset.
 312   @param BarIndex     Bar index.
 313
 314   @return Next bar offset.
 315
 316 **/
 317 UINTN
 318 PciIovParseVfBar (
 319   IN PCI_IO_DEVICE  *PciIoDevice,
 320   IN UINTN          Offset,
 321   IN UINTN          BarIndex
 322   );
 323
 324 /**
 325   This routine is used to initialize the bar of a PCI device.
 326
 327   @param PciIoDevice Pci device instance.
 328
 329   @note It can be called typically when a device is going to be rejected.
 330
 331 **/
 332 VOID
 333 InitializePciDevice (
 334   IN PCI_IO_DEVICE  *PciIoDevice
 335   );
 336
 337 /**
 338   This routine is used to initialize the bar of a PCI-PCI Bridge device.
 339
 340   @param  PciIoDevice PCI-PCI bridge device instance.
 341
 342 **/
 343 VOID
 344 InitializePpb (
 345   IN PCI_IO_DEVICE  *PciIoDevice
 346   );
 347
 348 /**
 349   This routine is used to initialize the bar of a PCI Card Bridge device.
 350
 351   @param PciIoDevice  PCI Card bridge device.
 352
 353 **/
 354 VOID
 355 InitializeP2C (
 356   IN PCI_IO_DEVICE  *PciIoDevice
 357   );
 358
 359 /**
 360   Create and initialize general PCI I/O device instance for
 361   PCI device/bridge device/hotplug bridge device.
 362
 363   @param Bridge            Parent bridge instance.
 364   @param Pci               Input Pci information block.
 365   @param Bus               Device Bus NO.
 366   @param Device            Device device NO.
 367   @param Func              Device func NO.
 368
 369   @return Instance of PCI device. NULL means no instance created.
 370
 371 **/
 372 PCI_IO_DEVICE *
 373 CreatePciIoDevice (
 374   IN PCI_IO_DEVICE  *Bridge,
 375   IN PCI_TYPE00     *Pci,
 376   IN UINT8          Bus,
 377   IN UINT8          Device,
 378   IN UINT8          Func
 379   );
 380
 381 /**
 382   This routine is used to enumerate entire pci bus system
 383   in a given platform.
 384
 385   It is only called on the second start on the same Root Bridge.
 386
 387   @param  Controller     Parent bridge handler.
 388
 389   @retval EFI_SUCCESS    PCI enumeration finished successfully.
 390   @retval other          Some error occurred when enumerating the pci bus system.
 391
 392 **/
 393 EFI_STATUS
 394 PciEnumeratorLight (
 395   IN EFI_HANDLE  Controller
 396   );
 397
 398 /**
 399   Get bus range from PCI resource descriptor list.
 400
 401   @param Descriptors  A pointer to the address space descriptor.
 402   @param MinBus       The min bus returned.
 403   @param MaxBus       The max bus returned.
 404   @param BusRange     The bus range returned.
 405
 406   @retval EFI_SUCCESS    Successfully got bus range.
 407   @retval EFI_NOT_FOUND  Can not find the specific bus.
 408
 409 **/
 410 EFI_STATUS
 411 PciGetBusRange (
 412   IN     EFI_ACPI_ADDRESS_SPACE_DESCRIPTOR  **Descriptors,
 413   OUT    UINT16                             *MinBus,
 414   OUT    UINT16                             *MaxBus,
 415   OUT    UINT16                             *BusRange
 416   );
 417
 418 /**
 419   This routine can be used to start the root bridge.
 420
 421   @param RootBridgeDev     Pci device instance.
 422
 423   @retval EFI_SUCCESS      This device started.
 424   @retval other            Failed to get PCI Root Bridge I/O protocol.
 425
 426 **/
 427 EFI_STATUS
 428 StartManagingRootBridge (
 429   IN PCI_IO_DEVICE  *RootBridgeDev
 430   );
 431
 432 /**
 433   This routine can be used to check whether a PCI device should be rejected when light enumeration.
 434
 435   @param PciIoDevice  Pci device instance.
 436
 437   @retval TRUE      This device should be rejected.
 438   @retval FALSE     This device shouldn't be rejected.
 439
 440 **/
 441 BOOLEAN
 442 IsPciDeviceRejected (
 443   IN PCI_IO_DEVICE  *PciIoDevice
 444   );
 445
 446 /**
 447   Reset all bus number from specific bridge.
 448
 449   @param Bridge           Parent specific bridge.
 450   @param StartBusNumber   Start bus number.
 451
 452 **/
 453 VOID
 454 ResetAllPpbBusNumber (
 455   IN PCI_IO_DEVICE  *Bridge,
 456   IN UINT8          StartBusNumber
 457   );
 458
 459 /**
 460   Dump the PPB padding resource information.
 461
 462   @param PciIoDevice     PCI IO instance.
 463   @param ResourceType    The desired resource type to dump.
 464                          PciBarTypeUnknown means to dump all types of resources.
 465 **/
 466 VOID
 467 DumpPpbPaddingResource (
 468   IN PCI_IO_DEVICE  *PciIoDevice,
 469   IN PCI_BAR_TYPE   ResourceType
 470   );
 471
 472 /**
 473   Dump the PCI BAR information.
 474
 475   @param PciIoDevice     PCI IO instance.
 476 **/
 477 VOID
 478 DumpPciBars (
 479   IN PCI_IO_DEVICE  *PciIoDevice
 480   );
 481
 482 #endif