GitBucket
Newer
Ajax Dong
/**
* @file OpromUpdateDxeLightningRidgeEXECB1.h
*
* @brief OpromUpdateDxeLightningRidgeEXECB1 - UEFI DXE driver for configuring
* PCIe Option ROM (OpROM) update policy on the Lightning Ridge EXEC B1
* platform via the UBA (Unified Board Architecture) framework.
*
* MODULE TYPE: UBA Board-Type DXE Driver
* UEFI PHASE: DXE (Driver Execution Environment)
*
* PURPOSE:
* This driver is part of Lenovo's UBA (Unified Board Architecture) framework.
* It registers platform-specific PCIe OpROM update configuration data for
* the Lightning Ridge EXEC B1 platform. The configuration describes which
* PCIe slots/devices should receive OpROM updates and which OpROM images
* to associate with each device.
*
* The driver performs the following at entry:
* 1. Locates the UBA board-type protocol for Lightning Ridge EXEC B1
* using gBS->LocateProtocol() with GUID E03E0D46-5263-4845-B0A4-58D57B3177E2.
* 2. Calls the protocol's registration function to install an
* OpROM update configuration protocol interface (GUID at 0xF00).
* 3. The configuration interface provides 4 callbacks:
* - GetConfigA(): Returns pointer to PciRootBridgeIo config table A
* - GetConfigB(): Returns pointer to PciRootBridgeIo config table B (6 entries)
* - GetConfigC(): Returns pointer to PciRootBridgeIo config table C (10 entries)
* - SetPcieSlotNumber(): Sets/clears slot number for OpROM binding
*
* DEPENDENCIES (Protocols consumed):
* - UBA LightningRidgeEXECB1 Board-Type Protocol
* (GUID: E03E0D46-5263-4845-B0A4-58D57B3177E2)
* This protocol is located and used to register the OpROM update config.
* - EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
* (GUID: 2F707EBB-4A1A-11D4-9A38-0090273FC14D)
* Used by the UBA framework to perform PCI config space reads for slot
* population detection.
* - EFI_HOB_LIST_GUID
* (GUID: 7739F24C-93D7-11D4-9A3A-0090273FC14D)
* Used to locate the HOB list from the system configuration table for
* PCI enumeration information.
*
* DEPENDENCIES (Protocols produced):
* - UBA LightningRidgeEXECB1 OpROM Update Protocol
* (GUID: defined at 0xF00, signature "PBDS")
* Installed via the board-type protocol's registration function with
* a callback-based configuration interface.
*
* HARDWARE ACCESS:
* - CMOS ports 0x70/0x71: Read CMOS register 0x4B to determine platform
* type / debug level.
* - MMIO 0xFDAF0490: Fallback board configuration register on some platforms.
* - PCI configuration space (indirectly via EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL):
* Reads PCI config registers 0x19 (BIST) and 0x1A (Header Type) at
* specific BDF addresses to detect populated PCIe slots.
*
* PCI DEVICES CONFIGURED:
* - Intel I350 Gigabit Ethernet (0x8086 0x1528) on root ports
* - Intel I350 Gigabit Ethernet (0x8086 0x1521) on root ports
* - Intel 82599ES 10 Gigabit Ethernet (0x8086 0x10FB)
* - Various PCIe slots with configurable OpROM binding
*
* @note This module is index 0016 in the BIOS FFS and is specific to the
* Lightning Ridge EXEC B1 platform.
*/
#ifndef _OPROM_UPDATE_DXE_LIGHTNING_RIDGE_EXEC_B1_H_
#define _OPROM_UPDATE_DXE_LIGHTNING_RIDGE_EXEC_B1_H_
#include "../uefi_headers/Uefi.h"
// ============================================================================
// GUID Definitions
// ============================================================================
///
/// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID
/// GUID for the EFI PCI Root Bridge I/O Protocol, used to perform PCI
/// configuration space read/write operations.
/// {2F707EBB-4A1A-11D4-9A38-0090273FC14D}
///
#define EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID \
{ 0x2F707EBB, 0x4A1A, 0x11D4, { 0x9A, 0x38, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D } }
///
/// EFI_HOB_LIST_GUID
/// GUID used to locate the HOB (Hand-Off Block) list in the system
/// configuration table. The HOB list provides system initialization
/// information such as PCI resource allocation.
/// {7739F24C-93D7-11D4-9A3A-0090273FC14D}
///
#define EFI_HOB_LIST_GUID \
{ 0x7739F24C, 0x93D7, 0x11D4, { 0x9A, 0x3A, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D } }
///
/// UBA_LIGHTNING_RIDGE_EXEC_B1_BOARD_TYPE_PROTOCOL_GUID
/// Protocol GUID used with gBS->LocateProtocol() to obtain the UBA board-type
/// protocol interface for the Lightning Ridge EXEC B1 platform.
/// This protocol's interface has a registration function at offset 0x10 (16)
/// that registers the OpROM update configuration.
/// {E03E0D46-5263-4845-B0A4-58D57B3177E2}
///
#define UBA_LIGHTNING_RIDGE_EXEC_B1_BOARD_TYPE_PROTOCOL_GUID \
{ 0xE03E0D46, 0x5263, 0x4845, { 0xB0, 0xA4, 0x58, 0xD5, 0x7B, 0x31, 0x77, 0xE2 } }
///
/// EFI_PCI_ENUMERATION_COMPLETE_PROTOCOL_GUID
/// This GUID is sent as part of the protocol registration to signal that
/// the PCI enumeration has been completed on this platform.
/// {7739F24C-93D7-11D4-9A3A-0090273FC14D}
///
#define EFI_PCI_ENUMERATION_COMPLETE_PROTOCOL_GUID \
{ 0x7739F24C, 0x93D7, 0x11D4, { 0x9A, 0x3A, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D } }
// ============================================================================
// Constants
// ============================================================================
///
/// Maximum number of PCIe slot entries in the slot configuration table.
///
#define OPROM_UPDATE_MAX_SLOTS 8
///
/// Size of each PCIe configuration table entry (in bytes).
///
#define OPROM_UPDATE_ENTRY_SIZE 0x30
///
/// Number of entries in PCIe configuration table B.
///
#define OPROM_UPDATE_TABLE_B_ENTRIES 6
///
/// Number of entries in PCIe configuration table C.
///
#define OPROM_UPDATE_TABLE_C_ENTRIES 10
///
/// Debug message severity mask. Used with the DebugLib protocol.
///
#define DEBUG_INFO 0x80000000
///
/// CMOS debug level register. Port 0x70 selects the CMOS register;
/// port 0x71 reads/writes the value.
/// Register 0x4B is used for debug level / platform detection control.
///
#define CMOS_DEBUG_LEVEL_REGISTER 0x4B
///
/// CMOS index port (RTC address register).
///
#define RTC_INDEX_PORT 0x70
///
/// CMOS data port (RTC data register).
///
#define RTC_DATA_PORT 0x71
///
/// Board configuration MMIO register address (used for platform type fallback).
///
#define BOARD_CONFIG_MMIO_ADDR 0xFDAF0490ULL
///
/// PCI configuration space register offset for BIST (Built-In Self Test).
///
#define PCI_REG_BIST 0x19
///
/// PCI configuration space register offset for Header Type.
///
#define PCI_REG_HEADER_TYPE 0x1A
///
/// Platform type encoded in CMOS register 0x4B:
/// 1 = Lightning Ridge EXEC B1
/// 2 = Another platform variant
/// 3 = Another platform variant
///
#define OPROM_PLATFORM_TYPE_LIGHTNING_RIDGE 1
///
/// Debug output level masks.
///
#define DEBUG_CMOS_MASK 0x80
///
/// Signature of the OpROM update configuration protocol interface.
/// "PBDS" = PciBridgeDeviceStructure (little-endian: 0x53444250).
///
#define OPROM_UPDATE_PROTOCOL_SIGNATURE "PBDS"
// ============================================================================
// Structure Definitions
// ============================================================================
///
/// OPROM_PCIE_SLOT_ENTRY
/// Slot configuration entry describing a PCIe BDF (Bus/Device/Function)
/// address to check for slot population.
///
/// Each entry is 4 bytes. An array of 8 entries defines which PCIe slots
/// on the platform should be checked for presence of a device. The driver
/// reads PCI config registers at each BDF address using the PciRootBridgeIo
/// protocol to determine if the slot is populated.
///
typedef struct {
///
/// Byte 0: PCI Bus number. Also combined with byte3 of the previous entry.
///
UINT8 Bus;
///
/// Byte 1: PCI Device number (bits [4:0]) and Function number (bits [7:5]).
/// Encoded in PCI expression format.
///
UINT8 DeviceFunction;
///
/// Byte 2: Reserved / extended address information.
///
UINT8 ExtendedInfo;
///
/// Byte 3: Continuation byte from previous slot entry. When the driver
/// reads PCI config registers at this slot, it combines this byte
/// with the current entry's Bus and DeviceFunction to form the
/// complete PCI address for EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS.
///
UINT8 PrevEntryExtra;
} OPROM_PCIE_SLOT_ENTRY;
///
/// OPROM_PCIE_CONFIG_ENTRY
/// Single entry in a PCIe OpROM configuration table.
///
/// Each entry describes a PCIe device or root port configuration. The format
/// is 0x30 bytes and contains device identification and slot binding info.
///
typedef struct {
///
/// Type of this entry (1 = PCIe root port, 2 = PCIe-to-PCI bridge, etc.).
///
UINT32 Type;
///
/// Attribute flags for this PCIe device entry.
///
UINT32 Attributes;
///
/// Vendor ID (lower 16 bits) and Device ID (upper 16 bits) of the
/// PCIe device. In little-endian storage: bytes 0-1=VendorId, 2-3=DeviceId.
/// Example: 0x15802886 -> Vendor=0x8086 (Intel), Device=0x1528.
///
UINT32 VendorDeviceId;
///
/// Subsystem Vendor ID (lower 16 bits) and Subsystem ID (upper 16 bits).
///
UINT32 SubVendorSubSystemId;
///
/// Revision ID and/or class code of the PCIe device.
///
UINT32 RevisionClassCode;
///
/// Reserved for alignment or additional configuration flags.
///
UINT32 Reserved0;
///
/// First slot/data field. May contain slot number, BDF, or offset value.
///
UINT32 SlotInfo0;
///
/// Second slot/data field.
///
UINT32 SlotInfo1;
///
/// Third slot/data field.
///
UINT32 SlotInfo2;
///
/// Fourth slot/data field.
///
UINT32 SlotInfo3;
///
/// Padding to reach 0x30 bytes. End of entry.
///
UINT32 Reserved1;
} OPROM_PCIE_CONFIG_ENTRY;
///
/// OPROM_UPDATE_CONFIG_TABLE
/// Fixed-size header for an OpROM update configuration table, followed by
/// a variable-length array of OPROM_PCIE_CONFIG_ENTRY structures.
///
typedef struct {
///
/// Reserved/padding data at the start of the table (0x30 bytes of zeros).
///
UINT8 Reserved[0x30];
///
/// Variable-length array of PCIe configuration entries.
///
OPROM_PCIE_CONFIG_ENTRY Entries[];
} OPROM_UPDATE_CONFIG_TABLE;
///
/// OPROM_UPDATE_PROTOCOL_INTERFACE
/// Callback-based protocol interface registered by this driver.
///
/// The interface structure is identified by the signature "PBDS" at the
/// start of the data block. It provides four callbacks that the UBA
/// framework uses to obtain platform-specific PCIe OpROM update data.
///
typedef struct {
///
/// Reserved field (may indicate number of callbacks or version).
///
UINT64 Reserved;
///
/// Callback 0: GetConfigA.
/// Returns a pointer to the first PCIe configuration table.
///
/// @param[out] ConfigData Pointer to receive the configuration table address.
///
/// @return EFI_SUCCESS (always returns 0).
///
EFI_STATUS
(*GetConfigA) (
OUT VOID **ConfigData
);
///
/// Callback 1: GetConfigB.
/// Returns a pointer to the second PCIe configuration table and its
/// entry count.
///
/// @param[out] ConfigData Pointer to receive the configuration table address.
/// @param[out] EntryCount Number of OPROM_PCIE_CONFIG_ENTRY entries (6).
///
/// @return EFI_SUCCESS (always returns 0).
///
EFI_STATUS
(*GetConfigB) (
OUT VOID **ConfigData,
OUT UINT32 *EntryCount
);
///
/// Callback 2: GetConfigC.
/// Returns a pointer to the third PCIe configuration table and its
/// entry count.
///
/// @param[out] ConfigData Pointer to receive the configuration table address.
/// @param[out] EntryCount Number of OPROM_PCIE_CONFIG_ENTRY entries (10).
///
/// @return EFI_SUCCESS (always returns 0).
///
EFI_STATUS
(*GetConfigC) (
OUT VOID **ConfigData,
OUT UINT32 *EntryCount
);
///
/// Callback 3: SetPcieSlotNumber.
/// Sets/clears the PCIe slot number for OpROM binding purposes.
/// On this platform, the initial call clears the slot number to 0.
///
/// @param[out] SlotNumber The slot number to set (initially 0).
///
/// @return EFI_SUCCESS (always returns 0).
///
EFI_STATUS
(*SetPcieSlotNumber) (
OUT UINT8 *SlotNumber
);
} OPROM_UPDATE_PROTOCOL_INTERFACE;
// ============================================================================
// UBA Board-Type Protocol Interface
// ============================================================================
///
/// UBA_OPROM_UPDATE_BOARD_TYPE_PROTOCOL
///
/// The protocol interface obtained via gBS->LocateProtocol() using the GUID
/// UBA_LIGHTNING_RIDGE_EXEC_B1_BOARD_TYPE_PROTOCOL_GUID.
///
/// This protocol is used to register platform-specific OpROM update
/// configuration data. The registration function is at offset 0x10 within
/// the interface structure.
///
typedef struct {
///
/// Unknown fields at offsets 0x00-0x0F (may contain protocol revision,
/// header, or other methods).
///
UINT64 Reserved0;
UINT64 Reserved1;
///
/// Function at offset 0x10. Registers the OpROM update configuration.
///
/// @param[in] This Pointer to the UBA board-type protocol interface.
/// @param[in] ProtocolGuid GUID of the protocol to register
/// (the OpROM update protocol GUID).
/// @param[in] ConfigData Pointer to the OPROM_UPDATE_PROTOCOL_INTERFACE
/// structure containing the callbacks.
/// @param[in] ConfigDataSize Size of the configuration data in bytes.
///
/// @return EFI_STATUS.
///
EFI_STATUS
(EFIAPI *RegisterOpromUpdateConfig) (
IN VOID *This,
IN EFI_GUID *ProtocolGuid,
IN OPROM_UPDATE_PROTOCOL_INTERFACE *ConfigData,
IN UINT32 ConfigDataSize
);
} UBA_OPROM_UPDATE_BOARD_TYPE_PROTOCOL;
// ============================================================================
// Global Variable Declarations
// ============================================================================
//
// UEFI Boot Services Table pointer (cached by UefiBootServicesTableLib).
//
extern EFI_SYSTEM_TABLE *gST;
extern EFI_BOOT_SERVICES *gBS;
extern EFI_RUNTIME_SERVICES *gRT;
extern EFI_HANDLE gImageHandle;
///
/// Pointer to the HOB (Hand-Off Block) list, obtained from the system
/// configuration table by searching for the EFI_HOB_LIST_GUID entry.
/// Used to determine if PCI enumeration has completed.
///
extern VOID *gHobList;
// ============================================================================
// Function Declarations
// ============================================================================
/**
* Module entry point for OpromUpdateDxeLightningRidgeEXECB1.
*
* Initializes UEFI global variables (gImageHandle, gST, gBS, gRT), resolves the
* DebugLib protocol for debug output, logs a debug banner, locates the UBA
* Lightning Ridge EXEC B1 board-type protocol, and registers the OpROM update
* configuration data by calling the board-type protocol's registration function.
*
* @param[in] ImageHandle The firmware-allocated handle for this driver image.
* @param[in] SystemTable A pointer to the EFI System Table.
*
* @return EFI_SUCCESS The configuration was successfully registered.
* @return EFI_INVALID_PARAMETER ImageHandle or SystemTable is NULL.
* @return Other The UBA protocol could not be located or
* the registration failed.
*/
EFI_STATUS
EFIAPI
_ModuleEntryPoint (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
);
/**
* Checks whether a given PCI bus/device/function address falls within any
* of the configured PCIe slot address ranges.
*
* For each of the 8 configured slots, the function reads PCI configuration
* space registers at offsets 0x19 (BIST) and 0x1A (Header Type) using the
* EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. If the target address v1 falls between
* the BIST value and Header Type value (inclusive) for any slot, the slot
* is considered a match.
*
* @param[in] BdfAddress PCI Bus/Device/Function address to check.
* @param[in] Reserved Unused parameter (reserved for future use).
*
* @retval TRUE The specified BDF address is within a configured PCIe slot.
* @retval FALSE The specified BDF address is not in any configured slot.
*/
BOOLEAN
IsPcieSlotConfigured (
IN UINT64 BdfAddress,
IN UINT32 Reserved
);
/**
* Locates the DebugLib protocol interface.
*
* Allocates pool memory, initializes the OpROM update protocol interface
* structure with the four callbacks, resolves the DebugLib protocol via
* gBS->LocateProtocol() using GUID 36232936-0E76-31C8-A13A-3AF2FC1C3932,
* and caches the result.
*
* The callbacks provided are:
* - OpromGetConfigA: Returns Config Table A (at 0xD20)
* - OpromGetConfigB: Returns Config Table B (at 0xD60, 6 entries)
* - OpromGetConfigC: Returns Config Table C (at 0xE60, 10 entries)
* - OpromSetSlotNumber: Clears slot number and logs debug message
*
* Results are cached in the global variable qword_F50 (gOpromUpdateProtocol).
*
* @return Pointer to the DebugLib/OpROM update protocol interface,
* or NULL if pool allocation or protocol location fails.
*
* @retval NULL The protocol could not be resolved or memory allocation failed.
*/
VOID *
GetDebugLibProtocol (
VOID
);
/**
* Debug print function (wraps the UEFI DebugLib protocol).
*
* Resolves the DebugLib protocol interface via GetDebugLibProtocol()
* and calls its output function at offset 0x08 if the debug level
* determined by CMOS register 0x4B matches the requested severity mask.
*
* The CMOS register 0x4B determines the platform type:
* - 0x00 (or > 3 with bit check): Platform variant
* - 0x01: Lightning Ridge EXEC B1
* - 0x02-0x03: Other platform variants
*
* @param[in] ErrorLevel The debug error level mask (e.g., DEBUG_INFO = 0x80000000).
* @param[in] Format A format string for the debug message.
* @param[in] ... Variable arguments for the format string.
*
* @return The return value from the DebugLib protocol's output function,
* or 0 if the protocol is not available or the debug level mask
* does not match.
*/
UINTN
EFIAPI
DebugPrint (
IN UINTN ErrorLevel,
IN CONST CHAR8 *Format,
...
);
/**
* ASSERT assertion failure handler.
*
* Called when a runtime assertion fails. Resolves the DebugLib protocol
* via GetDebugLibProtocol() and calls its assertion failure handler
* at offset 0x08.
*
* @param[in] FileName Source file name where the assertion occurred.
* @param[in] LineNumber Line number of the assertion.
* @param[in] Description Description of the failed assertion.
*
* @return 0 if the DebugLib protocol is not available.
*/
UINTN
DebugAssert (
IN CONST CHAR8 *FileName,
IN UINTN LineNumber,
IN CONST CHAR8 *Description
);
/**
* Locates the HOB (Hand-Off Block) list from the UEFI System Table's
* configuration table array.
*
* Iterates through SystemTable->ConfigurationTable[] looking for an entry
* whose VendorGuid matches EFI_HOB_LIST_GUID (7739f24c-93d7-11d4-9a3a-0090273fc14d).
* The comparison is done by matching the first 8 bytes and second 8 bytes of
* the GUID separately using ReadUnaligned64().
*
* Results are cached in the global variable qword_F58 (gHobList).
*
* @param[in] ImageHandle The driver image handle (passed through from entry,
* may be unused by this implementation).
*
* @return Pointer to the HOB list, or NULL if not found.
*/
VOID *
GetHobList (
IN EFI_HANDLE ImageHandle
);
/**
* Compares a GUID against the EFI_HOB_LIST_GUID by comparing its first 8 bytes
* and second 8 bytes independently.
*
* Uses unaligned 64-bit reads. The GUID at offset 0xD10 contains the
* expected EFI_HOB_LIST_GUID first half, and the GUID at offset 0xD18
* contains the second half.
*
* @param[in] ImageHandle Unused parameter (for compatibility with entry point).
* @param[in] GuidPtr Pointer to the GUID to compare.
*
* @retval TRUE The GUID matches EFI_HOB_LIST_GUID.
* @retval FALSE The GUID does not match.
*/
BOOLEAN
IsHobListGuid (
IN EFI_HANDLE ImageHandle,
IN EFI_GUID *GuidPtr
);
/**
* Reads an unaligned 64-bit value from memory.
*
* Wraps the BaseLib ReadUnaligned64() function with a NULL pointer check
* assertion. If the Buffer pointer is NULL, the function triggers an
* assertion via DebugAssert.
*
* @param[in] Buffer Pointer to the memory to read. Must not be NULL.
*
* @return The 64-bit value read from the given address.
*/
UINT64
ReadUnaligned64 (
IN CONST VOID *Buffer
);
// ============================================================================
// Callback Function Declarations
// ============================================================================
/**
* Callback: GetConfigA.
* Returns a pointer to PCIe configuration table A (at runtime address 0xD20).
* This table contains the primary PCIe root port/bridge configuration entries
* for the Lightning Ridge EXEC B1 platform.
*
* @param[out] ConfigData Pointer to receive the configuration table address.
*
* @return EFI_SUCCESS (always returns 0).
*/
EFI_STATUS
OpromGetConfigA (
OUT VOID **ConfigData
);
/**
* Callback: GetConfigB.
* Returns a pointer to PCIe configuration table B (at runtime address 0xD60)
* and the number of entries (6) in the table.
*
* Table B contains additional PCIe device configuration entries.
*
* @param[out] ConfigData Pointer to receive the configuration table address.
* @param[out] EntryCount Number of entries in the table (6).
*
* @return EFI_SUCCESS (always returns 0).
*/
EFI_STATUS
OpromGetConfigB (
OUT VOID **ConfigData,
OUT UINT32 *EntryCount
);
/**
* Callback: GetConfigC.
* Returns a pointer to PCIe configuration table C (at runtime address 0xE60)
* and the number of entries (10) in the table.
*
* Table C contains additional PCIe device configuration entries, likely
* for additional slots or devices on the platform.
*
* @param[out] ConfigData Pointer to receive the configuration table address.
* @param[out] EntryCount Number of entries in the table (10).
*
* @return EFI_SUCCESS (always returns 0).
*/
EFI_STATUS
OpromGetConfigC (
OUT VOID **ConfigData,
OUT UINT32 *EntryCount
);
/**
* Callback: SetPcieSlotNumber.
* Sets the PCIe slot number for OpROM binding. On the Lightning Ridge
* EXEC B1 platform, this function clears the slot number to 0 and
* logs a debug message.
*
* @param[out] SlotNumber Pointer to receive the slot number (set to 0).
*
* @return EFI_SUCCESS (always returns 0).
*/
EFI_STATUS
OpromSetSlotNumber (
OUT UINT8 *SlotNumber
);
#endif /* _OPROM_UPDATE_DXE_LIGHTNING_RIDGE_EXEC_B1_H_ */