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 #include <Library/PciHostBridgeLib.h>
  17
  18 /**
  19   Utility function to initialize a PCI_ROOT_BRIDGE structure.
  20
  21   @param[in]  Supports               Supported attributes.
  22
  23   @param[in]  Attributes             Initial attributes.
  24
  25   @param[in]  AllocAttributes        Allocation attributes.
  26
  27   @param[in]  DmaAbove4G             DMA above 4GB memory.
  28
  29   @param[in]  NoExtendedConfigSpace  No Extended Config Space.
  30
  31   @param[in]  RootBusNumber          The bus number to store in RootBus.
  32
  33   @param[in]  MaxSubBusNumber        The inclusive maximum bus number that can
  34                                      be assigned to any subordinate bus found
  35                                      behind any PCI bridge hanging off this
  36                                      root bus.
  37
  38                                      The caller is repsonsible for ensuring
  39                                      that RootBusNumber <= MaxSubBusNumber. If
  40                                      RootBusNumber equals MaxSubBusNumber, then
  41                                      the root bus has no room for subordinate
  42                                      buses.
  43
  44   @param[in]  Io                     IO aperture.
  45
  46   @param[in]  Mem                    MMIO aperture.
  47
  48   @param[in]  MemAbove4G             MMIO aperture above 4G.
  49
  50   @param[in]  PMem                   Prefetchable MMIO aperture.
  51
  52   @param[in]  PMemAbove4G            Prefetchable MMIO aperture above 4G.
  53
  54   @param[out] RootBus                The PCI_ROOT_BRIDGE structure (allocated
  55                                      by the caller) that should be filled in by
  56                                      this function.
  57
  58   @retval EFI_SUCCESS                Initialization successful. A device path
  59                                      consisting of an ACPI device path node,
  60                                      with UID = RootBusNumber, has been
  61                                      allocated and linked into RootBus.
  62
  63   @retval EFI_OUT_OF_RESOURCES       Memory allocation failed.
  64 **/
  65 EFI_STATUS
  66 EFIAPI
  67 PciHostBridgeUtilityInitRootBridge (
  68   IN  UINT64                    Supports,
  69   IN  UINT64                    Attributes,
  70   IN  UINT64                    AllocAttributes,
  71   IN  BOOLEAN                   DmaAbove4G,
  72   IN  BOOLEAN                   NoExtendedConfigSpace,
  73   IN  UINT8                     RootBusNumber,
  74   IN  UINT8                     MaxSubBusNumber,
  75   IN  PCI_ROOT_BRIDGE_APERTURE  *Io,
  76   IN  PCI_ROOT_BRIDGE_APERTURE  *Mem,
  77   IN  PCI_ROOT_BRIDGE_APERTURE  *MemAbove4G,
  78   IN  PCI_ROOT_BRIDGE_APERTURE  *PMem,
  79   IN  PCI_ROOT_BRIDGE_APERTURE  *PMemAbove4G,
  80   OUT PCI_ROOT_BRIDGE           *RootBus
  81   );
  82
  83 /**
  84   Utility function to uninitialize a PCI_ROOT_BRIDGE structure set up with
  85   PciHostBridgeUtilityInitRootBridge().
  86
  87   @param[in] RootBus  The PCI_ROOT_BRIDGE structure, allocated by the caller and
  88                       initialized with PciHostBridgeUtilityInitRootBridge(),
  89                       that should be uninitialized. This function doesn't free
  90                       RootBus.
  91 **/
  92 VOID
  93 EFIAPI
  94 PciHostBridgeUtilityUninitRootBridge (
  95   IN PCI_ROOT_BRIDGE  *RootBus
  96   );
  97
  98 /**
  99   Utility function to return all the root bridge instances in an array.
 100
 101   @param[out] Count                  The number of root bridge instances.
 102
 103   @param[in]  Attributes             Initial attributes.
 104
 105   @param[in]  AllocAttributes        Allocation attributes.
 106
 107   @param[in]  DmaAbove4G             DMA above 4GB memory.
 108
 109   @param[in]  NoExtendedConfigSpace  No Extended Config Space.
 110
 111   @param[in]  BusMin                 Minimum Bus number, inclusive.
 112
 113   @param[in]  BusMax                 Maximum Bus number, inclusive.
 114
 115   @param[in]  Io                     IO aperture.
 116
 117   @param[in]  Mem                    MMIO aperture.
 118
 119   @param[in]  MemAbove4G             MMIO aperture above 4G.
 120
 121   @param[in]  PMem                   Prefetchable MMIO aperture.
 122
 123   @param[in]  PMemAbove4G            Prefetchable MMIO aperture above 4G.
 124
 125   @return                            All the root bridge instances in an array.
 126 **/
 127 PCI_ROOT_BRIDGE *
 128 EFIAPI
 129 PciHostBridgeUtilityGetRootBridges (
 130   OUT UINTN                     *Count,
 131   IN  UINT64                    Attributes,
 132   IN  UINT64                    AllocationAttributes,
 133   IN  BOOLEAN                   DmaAbove4G,
 134   IN  BOOLEAN                   NoExtendedConfigSpace,
 135   IN  UINTN                     BusMin,
 136   IN  UINTN                     BusMax,
 137   IN  PCI_ROOT_BRIDGE_APERTURE  *Io,
 138   IN  PCI_ROOT_BRIDGE_APERTURE  *Mem,
 139   IN  PCI_ROOT_BRIDGE_APERTURE  *MemAbove4G,
 140   IN  PCI_ROOT_BRIDGE_APERTURE  *PMem,
 141   IN  PCI_ROOT_BRIDGE_APERTURE  *PMemAbove4G
 142   );
 143
 144 /**
 145   Utility function to free root bridge instances array from
 146   PciHostBridgeUtilityGetRootBridges().
 147
 148   @param[in] Bridges  The root bridge instances array.
 149   @param[in] Count    The count of the array.
 150 **/
 151 VOID
 152 EFIAPI
 153 PciHostBridgeUtilityFreeRootBridges (
 154   IN PCI_ROOT_BRIDGE  *Bridges,
 155   IN UINTN            Count
 156   );
 157
 158 /**
 159   Utility function to inform the platform that the resource conflict happens.
 160
 161   @param[in] Configuration  Pointer to PCI I/O and PCI memory resource
 162                             descriptors. The Configuration contains the
 163                             resources for all the root bridges. The resource
 164                             for each root bridge is terminated with END
 165                             descriptor and an additional END is appended
 166                             indicating the end of the entire resources. The
 167                             resource descriptor field values follow the
 168                             description in
 169                             EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
 170                             .SubmitResources().
 171 **/
 172 VOID
 173 EFIAPI
 174 PciHostBridgeUtilityResourceConflict (
 175   IN VOID  *Configuration
 176   );
 177
 178 #endif // __PCI_HOST_BRIDGE_UTILITY_LIB_H__