OvmfPkg/Include/Library/PciHostBridgeUtilityLib.h

   1 /** @file
   2   Provide common utility functions to PciHostBridgeLib instances in
   3   ArmVirtPkg and OvmfPkg.
   4
   5   Copyright (C) 2016, Red Hat, Inc.
   6   Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
   7   Copyright (c) 2020, Huawei Corporation. All rights reserved.<BR>
   8
   9   SPDX-License-Identifier: BSD-2-Clause-Patent
  10
  11 **/
  12
  13 #ifndef __PCI_HOST_BRIDGE_UTILITY_LIB_H__
  14 #define __PCI_HOST_BRIDGE_UTILITY_LIB_H__
  15
  16
  17 #include <Library/PciHostBridgeLib.h>
  18
  19
  20 /**
  21   Utility function to initialize a PCI_ROOT_BRIDGE structure.
  22
  23   @param[in]  Supports               Supported attributes.
  24
  25   @param[in]  Attributes             Initial attributes.
  26
  27   @param[in]  AllocAttributes        Allocation attributes.
  28
  29   @param[in]  DmaAbove4G             DMA above 4GB memory.
  30
  31   @param[in]  NoExtendedConfigSpace  No Extended Config Space.
  32
  33   @param[in]  RootBusNumber          The bus number to store in RootBus.
  34
  35   @param[in]  MaxSubBusNumber        The inclusive maximum bus number that can
  36                                      be assigned to any subordinate bus found
  37                                      behind any PCI bridge hanging off this
  38                                      root bus.
  39
  40                                      The caller is repsonsible for ensuring
  41                                      that RootBusNumber <= MaxSubBusNumber. If
  42                                      RootBusNumber equals MaxSubBusNumber, then
  43                                      the root bus has no room for subordinate
  44                                      buses.
  45
  46   @param[in]  Io                     IO aperture.
  47
  48   @param[in]  Mem                    MMIO aperture.
  49
  50   @param[in]  MemAbove4G             MMIO aperture above 4G.
  51
  52   @param[in]  PMem                   Prefetchable MMIO aperture.
  53
  54   @param[in]  PMemAbove4G            Prefetchable MMIO aperture above 4G.
  55
  56   @param[out] RootBus                The PCI_ROOT_BRIDGE structure (allocated
  57                                      by the caller) that should be filled in by
  58                                      this function.
  59
  60   @retval EFI_SUCCESS                Initialization successful. A device path
  61                                      consisting of an ACPI device path node,
  62                                      with UID = RootBusNumber, has been
  63                                      allocated and linked into RootBus.
  64
  65   @retval EFI_OUT_OF_RESOURCES       Memory allocation failed.
  66 **/
  67 EFI_STATUS
  68 EFIAPI
  69 PciHostBridgeUtilityInitRootBridge (
  70   IN  UINT64                   Supports,
  71   IN  UINT64                   Attributes,
  72   IN  UINT64                   AllocAttributes,
  73   IN  BOOLEAN                  DmaAbove4G,
  74   IN  BOOLEAN                  NoExtendedConfigSpace,
  75   IN  UINT8                    RootBusNumber,
  76   IN  UINT8                    MaxSubBusNumber,
  77   IN  PCI_ROOT_BRIDGE_APERTURE *Io,
  78   IN  PCI_ROOT_BRIDGE_APERTURE *Mem,
  79   IN  PCI_ROOT_BRIDGE_APERTURE *MemAbove4G,
  80   IN  PCI_ROOT_BRIDGE_APERTURE *PMem,
  81   IN  PCI_ROOT_BRIDGE_APERTURE *PMemAbove4G,
  82   OUT PCI_ROOT_BRIDGE          *RootBus
  83   );
  84
  85
  86 /**
  87   Utility function to uninitialize a PCI_ROOT_BRIDGE structure set up with
  88   PciHostBridgeUtilityInitRootBridge().
  89
  90   @param[in] RootBus  The PCI_ROOT_BRIDGE structure, allocated by the caller and
  91                       initialized with PciHostBridgeUtilityInitRootBridge(),
  92                       that should be uninitialized. This function doesn't free
  93                       RootBus.
  94 **/
  95 VOID
  96 EFIAPI
  97 PciHostBridgeUtilityUninitRootBridge (
  98   IN PCI_ROOT_BRIDGE *RootBus
  99   );
 100
 101
 102 /**
 103   Utility function to inform the platform that the resource conflict happens.
 104
 105   @param[in] Configuration  Pointer to PCI I/O and PCI memory resource
 106                             descriptors. The Configuration contains the
 107                             resources for all the root bridges. The resource
 108                             for each root bridge is terminated with END
 109                             descriptor and an additional END is appended
 110                             indicating the end of the entire resources. The
 111                             resource descriptor field values follow the
 112                             description in
 113                             EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
 114                             .SubmitResources().
 115 **/
 116 VOID
 117 EFIAPI
 118 PciHostBridgeUtilityResourceConflict (
 119   IN VOID  *Configuration
 120   );
 121
 122
 123 #endif // __PCI_HOST_BRIDGE_UTILITY_LIB_H__