/**@file Hardware info library with types and accessors to parse information about PCI host bridges. Copyright 2021 - 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef __HARDWARE_INFO_PCI_HOST_BRIDGE_LIB_H__ #define __HARDWARE_INFO_PCI_HOST_BRIDGE_LIB_H__ #include #include #include // // Host Bridge resources information // #pragma pack(1) typedef struct { // // Feature tracking, initially 0 // UINT64 Version; // // Host bridge enabled attributes (EFI_PCI_ATTRIBUTE_*) // UINT64 Attributes; union { UINT32 Uint32; struct { UINT32 DmaAbove4G : 1; UINT32 NoExtendedConfigSpace : 1; UINT32 CombineMemPMem : 1; UINT32 Reserved : 29; } Bits; } Flags; // // Bus number range // UINT8 BusNrStart; UINT8 BusNrLast; UINT8 Padding[2]; // // IO aperture // UINT64 IoStart; UINT64 IoSize; // // 32-bit MMIO aperture // UINT64 MemStart; UINT64 MemSize; // // 32-bit prefetchable MMIO aperture // UINT64 PMemStart; UINT64 PMemSize; // // 64-bit MMIO aperture // UINT64 MemAbove4GStart; UINT64 MemAbove4GSize; // // 64-bit prefetchable MMIO aperture // UINT64 PMemAbove4GStart; UINT64 PMemAbove4GSize; // // MMIO accessible PCIe config space (ECAM) // UINT64 PcieConfigStart; UINT64 PcieConfigSize; } HOST_BRIDGE_INFO; #pragma pack() /** Extract the last MMIO address, either from high (64-bit) or low (32-bit) memory used by the HostBridge's apertures. @param[in] HostBridge Root bridge's resources specification @param[in] DataSize Size in bytes of the actually filled data available in the HostBridge object @param[in] HighMem 64-bit (true) or 32-bit (false) MMIO address @param[out] LastMmioAddress Pointer to last MMIO address @retval EFI_SUCCESS Operation succeeded @retval EFI_INVALID_PARAMETER One or more pointer parameters are invalid @retval EFI_INCOMPATIBLE_VERSION HostBridge information belongs to an unsupported version **/ EFI_STATUS HardwareInfoPciHostBridgeLastMmioAddress ( IN CONST HOST_BRIDGE_INFO *HostBridge, IN UINTN DataSize, IN BOOLEAN HighMem, OUT UINT64 *LastMmioAddress ); /** Interpret the HostBridge resources and extact the bus number range. @param[in] HostBridge Root bridge's resources specification @param[in] DataSize Size in bytes of the actually filled data available in the HostBridge object @param[out] BusNrStart Pointer to the Bus Number range start @param[out] BusNrLast Pointer to the Bus Number range end @retval EFI_SUCCESS Retrieved the bus number range without any issues. @retval EFI_INVALID_PARAMETER One of the parameters is invalid, either NULL pointer or size 0 @retval EFI_INCOMPATIBLE_VERSION HostBridge data of unsupported version **/ EFI_STATUS HardwareInfoPciHostBridgeGetBusNrRange ( IN CONST HOST_BRIDGE_INFO *HostBridge, IN UINTN DataSize, OUT UINTN *BusNrStart, OUT UINTN *BusNrLast ); /** Interpret the MMIO resources in HostBridge and set the apertures in 32-bit space (Mem), 64-bit space (MemAbove4G), PIO (IO) and ECAM (PcieConfig) accordingly. The 2 types of apertures in each MMIO space (prefetchable and non-prefetchable) may be merged into a single window, hence if both types of apertures are defined while the CombineMemPMem flag is set, the ranges must be contiguous. @param[in] HostBridge Root bridge's resources specification @param[in] DataSize Size in bytes of the actually filled data available in the HostBridge object @param[out] Mem Pointer to 32-bit MMIO aperture @param[out] MemAbove4G Pointer to 64-bit MMIO aperture @param[out] PMem Pointer to the 32-bit prefetchable MMIO aperture @param[out] PMemAbove4G Pointer to the 64-bit prefetchable MMIO aperture @param[out] PcieConfig Pointer to MMIO mapped PCIe config aperture (ECAM) @retval EFI_INVALID_PARAMETER HostBridge object is invalid @retval EFI_INCOMPATIBLE_VERSION HostBridge information belongs to an unsupported version @retval EFI_WARN_STALE_DATA One or more valid aperture in the HostBridge's resources were ignored because corresponding aperture pointer is NULL. @retval EFI_SUCCESS Operation executed cleanly, all valid ranges were parsed into the corresponding aperture object. **/ EFI_STATUS HardwareInfoPciHostBridgeGetApertures ( IN CONST HOST_BRIDGE_INFO *HostBridge, IN UINTN DataSize, OUT PCI_ROOT_BRIDGE_APERTURE *Io, OUT PCI_ROOT_BRIDGE_APERTURE *Mem, OUT PCI_ROOT_BRIDGE_APERTURE *MemAbove4G, OUT PCI_ROOT_BRIDGE_APERTURE *PMem, OUT PCI_ROOT_BRIDGE_APERTURE *PMemAbove4G, OUT PCI_ROOT_BRIDGE_APERTURE *PcieConfig ); /** Retrieve all flags and attributes of a host bridge describing the resources and capabilities. @param[in] HostBridge Host bridge information object @param[in] DataSize Size in bytes of the actually filled data available in the HostBridge object @param[out] Attributes Pointer to the host bridge's attributes @param[out] DmaAbove4G Pointer to the DMA Above 4G flag @param[out] NoExtendedConfigSpace Pointer to the Extended Config Space flag @param[out] CombineMemPMem Pointer to the Combine Mem and PMem flag @retval EFI_INVALID_PARAMETER HostBridge object is invalid @retval EFI_INCOMPATIBLE_VERSION HostBridge information belongs to an unsupported version @retval EFI_SUCCESS Operation executed cleanly **/ EFI_STATUS HardwareInfoPciHostBridgeGetFlags ( IN CONST HOST_BRIDGE_INFO *HostBridge, IN UINTN DataSize, OUT UINT64 *Attributes OPTIONAL, OUT BOOLEAN *DmaAbove4G OPTIONAL, OUT BOOLEAN *NoExtendedConfigSpace OPTIONAL, OUT BOOLEAN *CombineMemPMem OPTIONAL ); /** Getter that parses information from a HOST_BRIDGE_INFO object into smaller chunks of types handled by the PciHostBridgeLib. @param[in] HostBridge Host bridge information object @param[in] DataSize Size in bytes of the actually filled data available in the HostBridge object @param[out] BusNrStart Pointer to the Bus Number range start @param[out] BusNrLast Pointer to the Bus Number range end @param[out] Attributes Pointer to the host bridge's attributes @param[out] DmaAbove4G Pointer to the DMA Above 4G flag @param[out] NoExtendedConfigSpace Pointer to the Extended Config Space flag @param[out] CombineMemPMem Pointer to the Combine Mem and PMem flag @param[out] Io Pointer to the PIO aperture object @param[out] Mem Pointer to the 32-bit MMIO aperture object @param[out] MemAbove4G Pointer to the 64-bit MMIO aperture object @param[out] PMem Pointer to the 32-bit prefetchable MMIO aperture object @param[out] PMemAbove4G Pointer to the 64-bit prefetchable MMIO aperture object @param[out] PcieConfig MMIO mapped PCIe config aperture (ECAM) @retval EFI_SUCCESS Whole operation succeeded @retval EFI_INVALID_PARAMETER HostBridge object and/or non-optional output parameters are invalid @retval EFI_INCOMPATIBLE_VERSION HostBridge information provided belongs to and unsupported version @retval EFI_WARN_STALE_DATA One or more apertures having valid ranges in the HostBridge info were ignored because the correspnding aperture pointer is NULL **/ EFI_STATUS HardwareInfoPciHostBridgeGet ( IN CONST HOST_BRIDGE_INFO *HostBridge, IN UINTN DataSize, OUT UINTN *BusNrStart, OUT UINTN *BusNrLast, OUT UINT64 *Attributes OPTIONAL, OUT BOOLEAN *DmaAbove4G OPTIONAL, OUT BOOLEAN *NoExtendedConfigSpace OPTIONAL, OUT BOOLEAN *CombineMemPMem OPTIONAL, OUT PCI_ROOT_BRIDGE_APERTURE *Io OPTIONAL, OUT PCI_ROOT_BRIDGE_APERTURE *Mem OPTIONAL, OUT PCI_ROOT_BRIDGE_APERTURE *MemAbove4G OPTIONAL, OUT PCI_ROOT_BRIDGE_APERTURE *PMem OPTIONAL, OUT PCI_ROOT_BRIDGE_APERTURE *PMemAbove4G OPTIONAL, OUT PCI_ROOT_BRIDGE_APERTURE *PcieConfig OPTIONAL ); #endif // __HARDWARE_INFO_PCI_HOST_BRIDGE_LIB_H__