MdeModulePkg/Bus/Pci/PciBusDxe/PciEnumeratorSupport.h

   1 /** @file
   2   PCI enumeration support functions declaration for PCI Bus module.
   3
   4 Copyright (c) 2006 - 2019, 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
 266   @retval EFI_SUCCESS     Successfully updated bar information.
 267   @retval EFI_UNSUPPORTED Given PCI device doesn't belong to incompatible PCI device list.
 268
 269 **/
 270 EFI_STATUS
 271 UpdatePciInfo (
 272   IN OUT PCI_IO_DEVICE    *PciIoDevice
 273   );
 274
 275 /**
 276   This routine will update the alignment with the new alignment.
 277
 278   @param Alignment    Input Old alignment. Output updated alignment.
 279   @param NewAlignment New alignment.
 280
 281 **/
 282 VOID
 283 SetNewAlign (
 284   IN OUT UINT64     *Alignment,
 285   IN     UINT64     NewAlignment
 286   );
 287
 288 /**
 289   Parse PCI bar information and fill them into PCI device instance.
 290
 291   @param PciIoDevice  Pci device instance.
 292   @param Offset       Bar offset.
 293   @param BarIndex     Bar index.
 294
 295   @return Next bar offset.
 296
 297 **/
 298 UINTN
 299 PciParseBar (
 300   IN PCI_IO_DEVICE  *PciIoDevice,
 301   IN UINTN          Offset,
 302   IN UINTN          BarIndex
 303   );
 304
 305 /**
 306   Parse PCI IOV VF bar information and fill them into PCI device instance.
 307
 308   @param PciIoDevice  Pci device instance.
 309   @param Offset       Bar offset.
 310   @param BarIndex     Bar index.
 311
 312   @return Next bar offset.
 313
 314 **/
 315 UINTN
 316 PciIovParseVfBar (
 317   IN PCI_IO_DEVICE  *PciIoDevice,
 318   IN UINTN          Offset,
 319   IN UINTN          BarIndex
 320   );
 321
 322 /**
 323   This routine is used to initialize the bar of a PCI device.
 324
 325   @param PciIoDevice Pci device instance.
 326
 327   @note It can be called typically when a device is going to be rejected.
 328
 329 **/
 330 VOID
 331 InitializePciDevice (
 332   IN PCI_IO_DEVICE    *PciIoDevice
 333   );
 334
 335 /**
 336   This routine is used to initialize the bar of a PCI-PCI Bridge device.
 337
 338   @param  PciIoDevice PCI-PCI bridge device instance.
 339
 340 **/
 341 VOID
 342 InitializePpb (
 343   IN PCI_IO_DEVICE    *PciIoDevice
 344   );
 345
 346 /**
 347   This routine is used to initialize the bar of a PCI Card Bridge device.
 348
 349   @param PciIoDevice  PCI Card bridge device.
 350
 351 **/
 352 VOID
 353 InitializeP2C (
 354   IN PCI_IO_DEVICE    *PciIoDevice
 355   );
 356
 357 /**
 358   Create and initialize general PCI I/O device instance for
 359   PCI device/bridge device/hotplug bridge device.
 360
 361   @param Bridge            Parent bridge instance.
 362   @param Pci               Input Pci information block.
 363   @param Bus               Device Bus NO.
 364   @param Device            Device device NO.
 365   @param Func              Device func NO.
 366
 367   @return Instance of PCI device. NULL means no instance created.
 368
 369 **/
 370 PCI_IO_DEVICE *
 371 CreatePciIoDevice (
 372   IN PCI_IO_DEVICE                    *Bridge,
 373   IN PCI_TYPE00                       *Pci,
 374   IN UINT8                            Bus,
 375   IN UINT8                            Device,
 376   IN UINT8                            Func
 377   );
 378
 379 /**
 380   This routine is used to enumerate entire pci bus system
 381   in a given platform.
 382
 383   It is only called on the second start on the same Root Bridge.
 384
 385   @param  Controller     Parent bridge handler.
 386
 387   @retval EFI_SUCCESS    PCI enumeration finished successfully.
 388   @retval other          Some error occurred when enumerating the pci bus system.
 389
 390 **/
 391 EFI_STATUS
 392 PciEnumeratorLight (
 393   IN EFI_HANDLE                    Controller
 394   );
 395
 396 /**
 397   Get bus range from PCI resource descriptor list.
 398
 399   @param Descriptors  A pointer to the address space descriptor.
 400   @param MinBus       The min bus returned.
 401   @param MaxBus       The max bus returned.
 402   @param BusRange     The bus range returned.
 403
 404   @retval EFI_SUCCESS    Successfully got bus range.
 405   @retval EFI_NOT_FOUND  Can not find the specific bus.
 406
 407 **/
 408 EFI_STATUS
 409 PciGetBusRange (
 410   IN     EFI_ACPI_ADDRESS_SPACE_DESCRIPTOR  **Descriptors,
 411   OUT    UINT16                             *MinBus,
 412   OUT    UINT16                             *MaxBus,
 413   OUT    UINT16                             *BusRange
 414   );
 415
 416 /**
 417   This routine can be used to start the root bridge.
 418
 419   @param RootBridgeDev     Pci device instance.
 420
 421   @retval EFI_SUCCESS      This device started.
 422   @retval other            Failed to get PCI Root Bridge I/O protocol.
 423
 424 **/
 425 EFI_STATUS
 426 StartManagingRootBridge (
 427   IN PCI_IO_DEVICE *RootBridgeDev
 428   );
 429
 430 /**
 431   This routine can be used to check whether a PCI device should be rejected when light enumeration.
 432
 433   @param PciIoDevice  Pci device instance.
 434
 435   @retval TRUE      This device should be rejected.
 436   @retval FALSE     This device shouldn't be rejected.
 437
 438 **/
 439 BOOLEAN
 440 IsPciDeviceRejected (
 441   IN PCI_IO_DEVICE *PciIoDevice
 442   );
 443
 444 /**
 445   Reset all bus number from specific bridge.
 446
 447   @param Bridge           Parent specific bridge.
 448   @param StartBusNumber   Start bus number.
 449
 450 **/
 451 VOID
 452 ResetAllPpbBusNumber (
 453   IN PCI_IO_DEVICE                      *Bridge,
 454   IN UINT8                              StartBusNumber
 455   );
 456
 457 /**
 458   Dump the PPB padding resource information.
 459
 460   @param PciIoDevice     PCI IO instance.
 461   @param ResourceType    The desired resource type to dump.
 462                          PciBarTypeUnknown means to dump all types of resources.
 463 **/
 464 VOID
 465 DumpPpbPaddingResource (
 466   IN PCI_IO_DEVICE                    *PciIoDevice,
 467   IN PCI_BAR_TYPE                     ResourceType
 468   );
 469
 470 #endif