OvmfPkg/Library/HardwareInfoLib/HardwareInfoPciHostBridgeLib.h

   1 /**@file
   2   Hardware info library with types and accessors to parse information about
   3   PCI host bridges.
   4
   5   Copyright 2021 - 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __HARDWARE_INFO_PCI_HOST_BRIDGE_LIB_H__
  11 #define __HARDWARE_INFO_PCI_HOST_BRIDGE_LIB_H__
  12
  13 #include <Uefi/UefiBaseType.h>
  14 #include <Uefi/UefiSpec.h>
  15 #include <Library/PciHostBridgeLib.h>
  16
  17 //
  18 // Host Bridge resources information
  19 //
  20 #pragma pack(1)
  21 typedef struct {
  22   //
  23   // Feature tracking, initially 0
  24   //
  25   UINT64    Version;
  26
  27   //
  28   // Host bridge enabled attributes (EFI_PCI_ATTRIBUTE_*)
  29   //
  30   UINT64    Attributes;
  31
  32   union {
  33     UINT32    Uint32;
  34     struct {
  35       UINT32    DmaAbove4G            : 1;
  36       UINT32    NoExtendedConfigSpace : 1;
  37       UINT32    CombineMemPMem        : 1;
  38       UINT32    Reserved              : 29;
  39     } Bits;
  40   } Flags;
  41
  42   //
  43   // Bus number range
  44   //
  45   UINT8     BusNrStart;
  46   UINT8     BusNrLast;
  47
  48   UINT8     Padding[2];
  49
  50   //
  51   // IO aperture
  52   //
  53   UINT64    IoStart;
  54   UINT64    IoSize;
  55
  56   //
  57   // 32-bit MMIO aperture
  58   //
  59   UINT64    MemStart;
  60   UINT64    MemSize;
  61
  62   //
  63   // 32-bit prefetchable MMIO aperture
  64   //
  65   UINT64    PMemStart;
  66   UINT64    PMemSize;
  67
  68   //
  69   // 64-bit MMIO aperture
  70   //
  71   UINT64    MemAbove4GStart;
  72   UINT64    MemAbove4GSize;
  73
  74   //
  75   // 64-bit prefetchable MMIO aperture
  76   //
  77   UINT64    PMemAbove4GStart;
  78   UINT64    PMemAbove4GSize;
  79
  80   //
  81   // MMIO accessible PCIe config space (ECAM)
  82   //
  83   UINT64    PcieConfigStart;
  84   UINT64    PcieConfigSize;
  85 } HOST_BRIDGE_INFO;
  86 #pragma pack()
  87
  88 /**
  89   Extract the last MMIO address, either from high (64-bit) or low (32-bit)
  90   memory used by the HostBridge's apertures.
  91
  92   @param[in]  HostBridge      Root bridge's resources specification
  93   @param[in]  DataSize        Size in bytes of the actually filled
  94                               data available in the HostBridge object
  95   @param[in]  HighMem         64-bit (true) or 32-bit (false) MMIO
  96                               address
  97   @param[out] LastMmioAddress Pointer to last MMIO address
  98
  99   @retval EFI_SUCCESS               Operation succeeded
 100   @retval EFI_INVALID_PARAMETER     One or more pointer parameters are
 101                                     invalid
 102   @retval EFI_INCOMPATIBLE_VERSION  HostBridge information belongs to
 103                                     an unsupported version
 104 **/
 105 EFI_STATUS
 106 HardwareInfoPciHostBridgeLastMmioAddress (
 107   IN CONST  HOST_BRIDGE_INFO  *HostBridge,
 108   IN        UINTN             DataSize,
 109   IN        BOOLEAN           HighMem,
 110   OUT       UINT64            *LastMmioAddress
 111   );
 112
 113 /**
 114   Interpret the HostBridge resources and extact the bus number
 115   range.
 116
 117   @param[in]  HostBridge   Root bridge's resources specification
 118   @param[in]  DataSize     Size in bytes of the actually filled
 119                            data available in the HostBridge object
 120   @param[out] BusNrStart   Pointer to the Bus Number range start
 121   @param[out] BusNrLast    Pointer to the Bus Number range end
 122
 123   @retval EFI_SUCCESS               Retrieved the bus number range
 124                                     without any issues.
 125   @retval EFI_INVALID_PARAMETER     One of the parameters is invalid,
 126                                     either NULL pointer or size 0
 127   @retval EFI_INCOMPATIBLE_VERSION  HostBridge data of unsupported
 128                                     version
 129 **/
 130 EFI_STATUS
 131 HardwareInfoPciHostBridgeGetBusNrRange (
 132   IN CONST  HOST_BRIDGE_INFO  *HostBridge,
 133   IN        UINTN             DataSize,
 134   OUT       UINTN             *BusNrStart,
 135   OUT       UINTN             *BusNrLast
 136   );
 137
 138 /**
 139   Interpret the MMIO resources in HostBridge and set the apertures
 140   in 32-bit space (Mem), 64-bit space (MemAbove4G), PIO (IO) and
 141   ECAM (PcieConfig) accordingly.
 142
 143   The 2 types of apertures in each MMIO space (prefetchable and
 144   non-prefetchable) may be merged into a single window, hence if both
 145   types of apertures are defined while the CombineMemPMem flag is set,
 146   the ranges must be contiguous.
 147
 148   @param[in]  HostBridge   Root bridge's resources specification
 149   @param[in]  DataSize     Size in bytes of the actually filled
 150                            data available in the HostBridge object
 151   @param[out] Mem          Pointer to 32-bit MMIO aperture
 152   @param[out] MemAbove4G   Pointer to 64-bit MMIO aperture
 153   @param[out] PMem         Pointer to the 32-bit prefetchable MMIO aperture
 154   @param[out] PMemAbove4G  Pointer to the 64-bit prefetchable MMIO aperture
 155   @param[out] PcieConfig   Pointer to MMIO mapped PCIe config aperture (ECAM)
 156
 157   @retval EFI_INVALID_PARAMETER     HostBridge object is invalid
 158   @retval EFI_INCOMPATIBLE_VERSION  HostBridge information belongs to
 159                                     an unsupported version
 160   @retval EFI_WARN_STALE_DATA       One or more valid aperture in the
 161                                     HostBridge's resources were ignored
 162                                     because corresponding aperture pointer
 163                                     is NULL.
 164   @retval EFI_SUCCESS               Operation executed cleanly, all valid
 165                                     ranges were parsed into the corresponding
 166                                     aperture object.
 167 **/
 168 EFI_STATUS
 169 HardwareInfoPciHostBridgeGetApertures (
 170   IN  CONST HOST_BRIDGE_INFO          *HostBridge,
 171   IN        UINTN                     DataSize,
 172   OUT       PCI_ROOT_BRIDGE_APERTURE  *Io,
 173   OUT       PCI_ROOT_BRIDGE_APERTURE  *Mem,
 174   OUT       PCI_ROOT_BRIDGE_APERTURE  *MemAbove4G,
 175   OUT       PCI_ROOT_BRIDGE_APERTURE  *PMem,
 176   OUT       PCI_ROOT_BRIDGE_APERTURE  *PMemAbove4G,
 177   OUT       PCI_ROOT_BRIDGE_APERTURE  *PcieConfig
 178   );
 179
 180 /**
 181   Retrieve all flags and attributes of a host bridge describing the
 182   resources and capabilities.
 183
 184   @param[in]  HostBridge            Host bridge information object
 185   @param[in]  DataSize              Size in bytes of the actually filled
 186                                     data available in the HostBridge object
 187   @param[out] Attributes            Pointer to the host bridge's attributes
 188   @param[out] DmaAbove4G            Pointer to the DMA Above 4G flag
 189   @param[out] NoExtendedConfigSpace Pointer to the Extended Config Space flag
 190   @param[out] CombineMemPMem        Pointer to the Combine Mem and PMem flag
 191
 192   @retval EFI_INVALID_PARAMETER     HostBridge object is invalid
 193   @retval EFI_INCOMPATIBLE_VERSION  HostBridge information belongs to
 194                                     an unsupported version
 195   @retval EFI_SUCCESS               Operation executed cleanly
 196 **/
 197 EFI_STATUS
 198 HardwareInfoPciHostBridgeGetFlags (
 199   IN CONST  HOST_BRIDGE_INFO  *HostBridge,
 200   IN        UINTN             DataSize,
 201   OUT       UINT64            *Attributes               OPTIONAL,
 202   OUT       BOOLEAN           *DmaAbove4G               OPTIONAL,
 203   OUT       BOOLEAN           *NoExtendedConfigSpace    OPTIONAL,
 204   OUT       BOOLEAN           *CombineMemPMem           OPTIONAL
 205   );
 206
 207 /**
 208   Getter that parses information from a HOST_BRIDGE_INFO object
 209   into smaller chunks of types handled by the PciHostBridgeLib.
 210
 211   @param[in]  HostBridge            Host bridge information object
 212   @param[in]  DataSize              Size in bytes of the actually filled
 213                                     data available in the HostBridge object
 214   @param[out] BusNrStart            Pointer to the Bus Number range start
 215   @param[out] BusNrLast             Pointer to the Bus Number range end
 216   @param[out] Attributes            Pointer to the host bridge's attributes
 217   @param[out] DmaAbove4G            Pointer to the DMA Above 4G flag
 218   @param[out] NoExtendedConfigSpace Pointer to the Extended Config Space flag
 219   @param[out] CombineMemPMem        Pointer to the Combine Mem and PMem flag
 220   @param[out] Io                    Pointer to the PIO aperture object
 221   @param[out] Mem                   Pointer to the 32-bit MMIO aperture object
 222   @param[out] MemAbove4G            Pointer to the 64-bit MMIO aperture object
 223   @param[out] PMem                  Pointer to the 32-bit prefetchable MMIO
 224                                     aperture object
 225   @param[out] PMemAbove4G           Pointer to the 64-bit prefetchable MMIO
 226                                     aperture object
 227   @param[out] PcieConfig            MMIO mapped PCIe config aperture (ECAM)
 228
 229   @retval EFI_SUCCESS               Whole operation succeeded
 230   @retval EFI_INVALID_PARAMETER     HostBridge object and/or non-optional
 231                                     output parameters are invalid
 232   @retval EFI_INCOMPATIBLE_VERSION  HostBridge information provided belongs to
 233                                     and unsupported version
 234   @retval EFI_WARN_STALE_DATA       One or more apertures having valid ranges
 235                                     in the HostBridge info were ignored because
 236                                     the correspnding aperture pointer is NULL
 237 **/
 238 EFI_STATUS
 239 HardwareInfoPciHostBridgeGet (
 240   IN CONST  HOST_BRIDGE_INFO          *HostBridge,
 241   IN        UINTN                     DataSize,
 242   OUT       UINTN                     *BusNrStart,
 243   OUT       UINTN                     *BusNrLast,
 244   OUT       UINT64                    *Attributes               OPTIONAL,
 245   OUT       BOOLEAN                   *DmaAbove4G               OPTIONAL,
 246   OUT       BOOLEAN                   *NoExtendedConfigSpace    OPTIONAL,
 247   OUT       BOOLEAN                   *CombineMemPMem           OPTIONAL,
 248   OUT       PCI_ROOT_BRIDGE_APERTURE  *Io                       OPTIONAL,
 249   OUT       PCI_ROOT_BRIDGE_APERTURE  *Mem                      OPTIONAL,
 250   OUT       PCI_ROOT_BRIDGE_APERTURE  *MemAbove4G               OPTIONAL,
 251   OUT       PCI_ROOT_BRIDGE_APERTURE  *PMem                     OPTIONAL,
 252   OUT       PCI_ROOT_BRIDGE_APERTURE  *PMemAbove4G              OPTIONAL,
 253   OUT       PCI_ROOT_BRIDGE_APERTURE  *PcieConfig               OPTIONAL
 254   );
 255
 256 #endif // __HARDWARE_INFO_PCI_HOST_BRIDGE_LIB_H__