GitBucket
Newer
Ajax Dong
/**
* @file OpromUpdateDxeLightningRidgeEXECB3.c
*
* @brief OpROM Update DXE Driver for LightningRidge EXEC B3 Platform.
*
* This is a UBA (Unified Board Architecture) board-type DXE driver that
* registers PCIe Option ROM (OpROM) update configuration tables for the
* LightningRidge EXEC B3 server platform (Intel Purley family).
*
* == Architecture Overview ==
* The driver follows the standard UBA board-type pattern:
* 1. Entry point caches UEFI globals from SystemTable
* 2. HOB list is resolved via ConfigurationTable for platform info
* 3. Platform debug banner ("UBA:OpromUpdate-TypeLightningRidgeEXECB3") is emitted
* 4. UBA_CONFIG_PROTOCOL (GUID {E03E0D46...}) is located via gBS->LocateProtocol()
* 5. A PBDS structure (48 bytes) with 5 callbacks is registered via RegisterConfig
*
* The 5 callbacks registered in the PBDS structure:
* [0] @+0x08: IsPcieSlotConfigured() - Slot range validation via PCI config space
* [1] @+0x10: OpromGetConfigA() - Zero-initialized table (terminator)
* [2] @+0x18: OpromGetConfigB() - PCIe config table (6 entries)
* [3] @+0x20: OpromGetConfigC() - Extended PCIe config table (10 entries)
* [4] @+0x28: OpromSetSlotNumber() - Slot number setter (always 0)
*
* == Key Differences from EXECB1/EXECB2 ==
* - Platform string: "UBA:OpromUpdate-TypeLightningRidgeEXECB3"
* - PDB: OpromUpdateDxeLightningRidgeEXECB3.pdb
* - Otherwise structurally identical (same GUIDs, same callbacks, same data tables)
*
* == Binary Info ==
* - Index: 31 of 427 PE files in HR650X BIOS
* - SHA256: d58f84d1adb92017d59b450e242cac64939aadc6e24a35da7573064e7b531022
* - PDB GUID: {2E401ABE-49E9-4BD3-969B-AF5A00349AA6}, Age 1
* - Source path: e:\hs\PurleyRpPkg\Uba\UbaMain\Dxe\TypeLightningRidgeEXECB3\OpromUpdateDxe\
* - Build: HR6N0XMLK\DEBUG_VS2015\X64
*/
#include "OpromUpdateDxeLightningRidgeEXECB3.h"
/*==============================================================================
* GUID Definitions (stored in .rdata at fixed image offsets)
*============================================================================*/
/**
* EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID
* Standard UEFI protocol for PCI Root Bridge IO operations (config space access).
* GUID: {2F707EBB-4A1A-11D4-9A38-0090273FC14D}
* Image address: 0xCE0
* Used by IsPcieSlotConfigured() via gBS->LocateProtocol().
*/
STATIC CONST EFI_GUID gEfiPciRootBridgeIoProtocolGuid =
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID;
/**
* UBA_DEBUG_LIB_PROTOCOL_GUID
* Debug library protocol for UBA framework debug output and assertions.
* GUID: {36232936-0E76-31C8-A13A-3AF2FC1C3932}
* Image address: 0xCF0
* Resolved lazily by GetDebugLibProtocol().
*/
STATIC CONST EFI_GUID gUbaDebugLibProtocolGuid =
UBA_DEBUG_LIB_PROTOCOL_GUID;
/**
* UBA_CONFIG_PROTOCOL_GUID
* Board-type configuration protocol for LightningRidge EXEC B3.
* Provides RegisterConfig function at vtable offset 0x10.
* GUID: {E03E0D46-5263-4845-B0A4-58D57B3177E2}
* Image address: 0xD00
*/
STATIC CONST EFI_GUID gUbaConfigProtocolGuid =
UBA_CONFIG_PROTOCOL_GUID;
/**
* EFI_HOB_LIST_GUID
* Used to locate the HOB (Hand-Off Block) list via SystemTable->ConfigurationTable.
* GUID: {7739F24C-93D7-11D4-9A3A-0090273FC14D}
* Image address: 0xD10 (first 8 bytes), 0xD18 (second 8 bytes)
*/
STATIC CONST EFI_GUID gEfiHobListGuid =
EFI_HOB_LIST_GUID;
/**
* OPROM_UPDATE_CONFIG_DATA_GUID
* Configuration type GUID for the PBDS structure.
* Passed to UBA_CONFIG_PROTOCOL.RegisterConfig().
* GUID: {371BD79C-DE79-4C5F-AA2B-BC9EBEFA988F}
* Image address: 0xEF0
*/
STATIC CONST EFI_GUID gOpromUpdateConfigDataGuid =
OPROM_UPDATE_CONFIG_DATA_GUID;
/*==============================================================================
* Global Variable Definitions (.data segment, image addr 0xF30-0xF5F)
*============================================================================*/
//
// UEFI standard protocol pointer caches (set by _ModuleEntryPoint)
// Image addr 0xF30: gST
// Image addr 0xF38: gBS
// Image addr 0xF40: gImageHandle
// Image addr 0xF48: gRT
//
EFI_SYSTEM_TABLE *gST = NULL;
EFI_BOOT_SERVICES *gBS = NULL;
EFI_HANDLE gImageHandle = NULL;
EFI_RUNTIME_SERVICES *gRT = NULL;
//
// Cached protocol/hand-off block pointers (resolved lazily)
// Image addr 0xF50: gOpromProtocol (UBA DebugLib protocol cache)
// Image addr 0xF58: gHobList (HOB list pointer cache)
//
UBA_DEBUG_LIB_PROTOCOL *gOpromProtocol = NULL;
VOID *gHobList = NULL;
/*==============================================================================
* Configuration Data Structures
*============================================================================*/
/**
* PCIE_SLOT_RANGE table (image addr 0xED0, 8 entries of 4 bytes = 32 bytes)
*
* Encodes PCIe BDF slot ranges for 8 possible slots.
* Read by IsPcieSlotConfigured() using byte-level stride of 4:
* Byte[-1] = Bus (or flags)
* Byte[0] = Device number
* Byte[+1] = Function number (or continuation)
*
* The combined BDF address: ((Device | (Function << 8)) << 8 | Bus) << 8
* Entry 0: Bus=0x00, Dev=0x03, Func=0x00 -> 0x30000 (BDF 00:03.0)
* Entry 1: Bus=0x00, Dev=0x01, Func=0x80 -> 0x80010000 (BDF 00:01.0 with flag?)
* Entry 2: Bus=0x00, Dev=0x02, Func=0x80 -> 0x80020000 (BDF 00:02.0 with flag?)
* Entry 3: Bus=0x02, Dev=0x03, Func=0x80 -> 0x80030200 (BDF 02:03.2 with flag?)
* Entry 4: Bus=0x00, Dev=0x02, Func=0x00 -> 0x20000 (BDF 00:02.0)
* Entry 5: Bus=0x00, Dev=0x01, Func=0x00 -> 0x10000 (BDF 00:01.0)
* Entry 6: Bus=0x05, Dev=0x1c, Func=0x00 -> 0x1c0500 (BDF 05:1c.0)
* Entry 7: Bus=0x00, Dev=0x03, Func=0x80 -> 0x80030000 (BDF 00:03.0 with flag?)
*
* The Func=0x80 entries (entries 1,2,3,7) appear to encode a secondary
* bus segment indicator (bit 7 set) rather than an actual function number.
*/
STATIC CONST PCIE_SLOT_RANGE mPcieSlotRanges[8] = {
{ 0x00, 0x03, 0x00, 0x00 }, /* Entry 0: BDF 00:03.0 */
{ 0x00, 0x01, 0x80, 0x00 }, /* Entry 1: BDF 00:01.0 (seg 0x80) */
{ 0x00, 0x02, 0x80, 0x00 }, /* Entry 2: BDF 00:02.0 (seg 0x80) */
{ 0x02, 0x03, 0x80, 0x00 }, /* Entry 3: BDF 02:03.2 (seg 0x80) */
{ 0x00, 0x02, 0x00, 0x00 }, /* Entry 4: BDF 00:02.0 */
{ 0x00, 0x01, 0x00, 0x00 }, /* Entry 5: BDF 00:01.0 */
{ 0x05, 0x1C, 0x00, 0x00 }, /* Entry 6: BDF 05:1C.0 */
{ 0x00, 0x03, 0x80, 0x00 }, /* Entry 7: BDF 00:03.0 (seg 0x80) */
};
/**
* Config Table A (image addr 0xD20, 64 bytes of zeros)
*
* Primary PCIe topology table. All zeros on this platform.
* Acts as a terminator/sentinel - the UBA framework interprets this
* as "no primary configuration". The function OpromGetConfigA() simply
* returns a pointer to this zeroed area.
*
* The 0xFFFFFFFF at the end (offset 0xD50) might be a terminator value.
*/
STATIC CONST UINT64 mConfigTableA[8] = { 0, 0, 0, 0, 0, 0, 0, 0 };
/**
* Config Table B (image addr 0xD60, 6 entries of 8 bytes = 48 bytes)
*
* Device configuration entries for PCIe root ports and endpoints.
* Each entry is 8 bytes, encoding:
* Bytes 0-3: Entry descriptor (type, flags, bus/device/function)
* Bytes 4-7: Extended descriptor (vendor/device ID, range info)
*
* Raw data (little-endian 64-bit values):
* [0] 0x0002000100000001 Type=1, flags=0x00020001, ...
* [1] 0x4801080215288086 Vendor=0x8086, Device=0x1528 (Intel I350)
* [2] 0x0000002d01000000 Revision=0, Class=0x01000000
* [3] 0x0000002c00000001 SubVendor=0x0001, SubSystem=0x0000002c
* [4] 0xff2fff2e00000001 Slot range: 0x2e-0x2f (or 0xff2f-0xff)
* [5] 0x0200010000000100 Extended config
*/
STATIC CONST UINT64 mConfigTableB[6] = {
0x0002000100000001ULL,
0x4801080215288086ULL,
0x0000002d01000000ULL,
0x0000002c00000001ULL,
0xff2fff2e00000001ULL,
0x0200010000000100ULL,
};
/**
* Config Table C (image addr 0xE60, 10 entries of 8 bytes = 80 bytes)
*
* Extended device configuration entries.
* These appear to describe Intel Ethernet controller configurations
* including Intel I350 (0x1521, 0x1522) and 82599ES (0x10D3, 0x10FB).
*
* Raw data (little-endian 64-bit values):
* [0] 0x00010100358010d3 Dev=0x10D3:3580 (Intel 82599ES)
* [1] 0x0100358015210000 Dev=0x1521:3580 (Intel I350 variant)
* [2] 0x35b0152100000001 Dev=0x1521:35B0 (Intel I350 variant)
* [3] 0x1522000000010100 Dev=0x1522:3580 (Intel I350 variant)
* [4] 0x0000000101003580 Dev=0x...:3580 (Intel I350)
* [5] 0x0001010035561521 Dev=0x1521:3556 (Intel I350)
* [6] 0x0101355710fb0000 Dev=0x10FB:3557 (Intel 82599ES)
* [7] 0x3558152800000101 Dev=0x1528:3558 (Intel I350)
* [8] 0x1528000001010101 Dev=0x1528 (Intel I350)
* [9] 0x00000101010135c5 Extended entry
*/
STATIC CONST UINT64 mConfigTableC[10] = {
0x00010100358010d3ULL,
0x0100358015210000ULL,
0x35b0152100000001ULL,
0x1522000000010100ULL,
0x0000000101003580ULL,
0x0001010035561521ULL,
0x0101355710fb0000ULL,
0x3558152800000101ULL,
0x1528000001010101ULL,
0x00000101010135c5ULL,
};
/**
* OPROM_UPDATE_CONFIG (PBDS structure at image addr 0xF00, 48 bytes)
*
* Registered with the UBA_CONFIG_PROTOCOL.RegisterConfig() call in
* _ModuleEntryPoint. Contains 5 callback function pointers that the
* UBA framework uses to query platform-specific OpROM update info.
*
* The .reloc section has entries for the address range 0xF08-0xF28
* (the function pointer fields), ensuring proper relocation at runtime.
*/
STATIC CONST OPROM_UPDATE_CONFIG mOpromUpdateConfig = {
.Signature = 0x53444250, /* 'PBDS' */
.Version = 1,
.IsPcieSlotConfigured = (UINT64)(UINTN)IsPcieSlotConfigured,
.OpromGetConfigA = (UINT64)(UINTN)OpromGetConfigA,
.OpromGetConfigB = (UINT64)(UINTN)OpromGetConfigB,
.OpromGetConfigC = (UINT64)(UINTN)OpromGetConfigC,
.OpromSetSlotNumber = (UINT64)(UINTN)OpromSetSlotNumber,
};
/*==============================================================================
* Function Implementations
*============================================================================*/
/**
* @brief UEFI DXE driver entry point.
*
* Called by the DXE Dispatcher after all dependencies are resolved.
*
* Initialization sequence:
* 1. Cache ImageHandle, SystemTable, BootServices, RuntimeServices globals
* 2. Resolve the HOB list via GetHobList() (uses SystemTable->ConfigurationTable)
* 3. Emit the platform identification banner via DebugPrint()
* 4. Locate UBA_CONFIG_PROTOCOL by GUID {E03E0D46-5263-4845-B0A4-58D57B3177E2}
* 5. Call the protocol's RegisterConfig (vtable[2] @ offset 0x10) with:
* - Config type GUID: {371BD79C-DE79-4C5F-AA2B-BC9EBEFA988F}
* - Config data: &mOpromUpdateConfig (PBDS, 48 bytes)
* - Data size: 48 (sizeof(OPROM_UPDATE_CONFIG))
*
* @param[in] ImageHandle UEFI image handle for this driver.
* @param[in] SystemTable UEFI system table pointer.
*
* @return EFI_SUCCESS Configuration registered successfully.
* @return EFI_UNSUPPORTED/... LocateProtocol or RegisterConfig failure.
*
* @note The UefiBootServicesTableLib and UefiRuntimeServicesTableLib
* library constructors set the module-level gImageHandle, gST,
* gBS, and gRT globals. The entry point's explicit caching here
* duplicates that functionality for safety.
*/
EFI_STATUS
EFIAPI
_ModuleEntryPoint (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
{
EFI_STATUS Status;
VOID *UbaConfigProtocol; /* Protocol interface from LocateProtocol */
UINT64 ConfigBuffer; /* Output buffer for LocateProtocol */
//
// Step 1: Cache UEFI standard protocol pointers.
// These are also set by the library constructors in
// UefiBootServicesTableLib and UefiRuntimeServicesTableLib,
// but we cache them explicitly here for robustness.
//
gImageHandle = ImageHandle;
gST = SystemTable;
gBS = SystemTable->BootServices;
gRT = SystemTable->RuntimeServices;
//
// Step 2: Resolve the HOB (Hand-Off Block) list.
// This walks SystemTable->ConfigurationTable[] looking for the entry
// with VendorGuid == EFI_HOB_LIST_GUID ({7739F24C-...}).
// The associated VendorTable pointer is the HOB list header.
// Result is cached in gHobList (image addr 0xF58).
//
GetHobList ();
//
// Step 3: Print the platform identification banner.
// ErrorLevel 0x80000000 is the UBA-specific debug severity mask.
//
DebugPrint (0x80000000, "UBA:OpromUpdate-TypeLightningRidgeEXECB3\n");
//
// Step 4: Locate the UBA_CONFIG_PROTOCOL.
// GUID {E03E0D46-5263-4845-B0A4-58D57B3177E2} identifies the
// platform-specific UBA configuration protocol.
//
ConfigBuffer = 0;
Status = gBS->LocateProtocol (
&gUbaConfigProtocolGuid,
NULL, /* No registration */
(VOID **)&ConfigBuffer /* Output interface */
);
if (EFI_ERROR (Status)) {
return Status;
}
//
// Step 5: Call the protocol's RegisterConfig function.
// The function pointer is at vtable index 2 (offset 0x10).
// Signature:
// EFI_STATUS (*RegisterConfig)(
// VOID *This,
// CONST EFI_GUID *ConfigGuid,
// CONST VOID *ConfigData,
// UINTN ConfigDataSize
// );
//
// Parameters:
// ConfigGuid = &gOpromUpdateConfigDataGuid
// {371BD79C-DE79-4C5F-AA2B-BC9EBEFA988F}
// ConfigData = &mOpromUpdateConfig (PBDS structure, 48 bytes)
// DataSize = 48 (sizeof(OPROM_UPDATE_CONFIG))
//
UbaConfigProtocol = (VOID *)ConfigBuffer;
return ((EFI_STATUS (*)(VOID *, CONST EFI_GUID *, CONST VOID *, UINTN))
(*((UINT64 **)UbaConfigProtocol) + 2)) ( /* vtable[2] = offset 0x10 */
UbaConfigProtocol,
&gOpromUpdateConfigDataGuid,
&mOpromUpdateConfig,
sizeof (OPROM_UPDATE_CONFIG)
);
}
/**
* @brief Lazily resolves and caches the UBA DebugLib protocol.
*
* Called on first use from DebugPrint() or DebugAssert(). The protocol
* is resolved only once and cached in gOpromProtocol (image addr 0xF50).
*
* Resolution steps:
* 1. Check cache: if gOpromProtocol is non-NULL, return immediately
* 2. Pool check: allocate and free a 31-byte pool. If only <= 0x10 bytes
* available, return NULL (minimum pool size sanity check)
* 3. LocateProtocol: call gBS->LocateProtocol() with
* UBA_DEBUG_LIB_PROTOCOL_GUID {36232936-0E76-31C8-A13A-3AF2FC1C3932}
* 4. On success, cache the result and return; on failure, cache NULL
*
* @return Pointer to UBA_DEBUG_LIB_PROTOCOL, or NULL if:
* - Pool allocation check fails (<= 0x10 bytes)
* - gBS->LocateProtocol() fails
*
* @note The pool allocation/free sequence (UINTN type 31, then free) is
* a UEFI memory subsystem sanity check inherited from the library.
*/
UBA_DEBUG_LIB_PROTOCOL *
GetDebugLibProtocol (
VOID
)
{
UINTN PoolSize; /* Dummy pool allocation for size check */
UINT64 ProtocolPtr; /* Output buffer for LocateProtocol */
//
// Return cached pointer if already resolved.
//
if (gOpromProtocol != NULL) {
return gOpromProtocol;
}
//
// Check available pool size by allocating and immediately freeing.
// Type 31 is EfiBootServicesData in this platform's memory map.
// If only <= 0x10 bytes available, return NULL.
//
gBS->AllocatePool (EfiBootServicesData, 31, (VOID **)&PoolSize);
gBS->FreePool ((VOID *)PoolSize);
if (PoolSize <= 0x10) {
gOpromProtocol = NULL;
return NULL;
}
//
// Resolve the UBA DebugLib protocol.
//
ProtocolPtr = 0;
if (EFI_ERROR (gBS->LocateProtocol (
&gUbaDebugLibProtocolGuid,
NULL,
(VOID **)&ProtocolPtr
))) {
gOpromProtocol = NULL;
return NULL;
}
gOpromProtocol = (UBA_DEBUG_LIB_PROTOCOL *)ProtocolPtr;
return gOpromProtocol;
}
/**
* @brief Platform-aware debug output with CMOS-based board type detection.
*
* Reads CMOS register 0x4B (via legacy I/O ports 0x70/0x71) to determine
* the board platform type, which selects the debug output mask:
*
* Platform type 1 (LightningRidge):
* Debug mask = 0x80000004
* Platform type 2 or 3 (other platforms):
* Debug mask = 0x80000006
*
* If CMOS register 0x4B reads as 0 (uninitialized), falls back to MMIO
* read at physical address 0xFDAF0490 bit 1, ORed with 1, to determine
* the platform type.
*
* Debug output is only emitted when (ErrorLevel & DebugMask) != 0.
* The function returns 4 (not 0) when output is suppressed but the
* protocol and platform check succeeded - this distinguishes "suppressed"
* from "protocol missing".
*
* @param[in] ErrorLevel Debug message severity level mask.
* @param[in] Format Printf-compatible format string.
* @param[in] ... Variable arguments for format string.
*
* @return Non-zero Debug output was emitted or successfully suppressed.
* @return 0 DebugLib protocol not available (GetDebugLibProtocol failed).
*/
UINTN
EFIAPI
DebugPrint (
IN UINTN ErrorLevel,
IN CONST CHAR8 *Format,
...
)
{
VA_LIST VaList;
UBA_DEBUG_LIB_PROTOCOL *Protocol;
UINTN PlatformType; /* CMOS platform type value */
UINTN DebugMask; /* Platform-specific debug mask */
//
// Resolve the DebugLib protocol (lazy initialization).
//
Protocol = GetDebugLibProtocol ();
if (Protocol == NULL) {
return 0;
}
//
// Read CMOS register 0x4B to determine the board platform type.
// CMOS access sequence:
// 1. Read index register (0x70) to preserve NMI disable bit
// 2. Write index with NMI-disabled + 0x4B
// 3. Read data register (0x71)
//
PlatformType = IoRead8 (0x70); /* Save NMI state */
IoWrite8 (0x70, (PlatformType & 0x80) | 0x4B); /* Select CMOS 0x4B */
PlatformType = IoRead8 (0x71); /* Read platform type */
//
// If CMOS returned > 3 and == 0, the register is uninitialized.
// Fall back to MMIO at 0xFDAF0490 (GPIO or strapping register).
// Extract bit 1, OR with 1 to get platform type 1 or 3.
//
if (PlatformType > 3) {
if (PlatformType == 0) {
PlatformType = (*(volatile UINT8 *)0xFDAF0490 & 2) | 1;
}
}
//
// Select debug mask based on platform type.
//
if (PlatformType == 1) {
DebugMask = 0x80000004; /* LightningRidge specific mask */
} else {
DebugMask = 0x80000006; /* Other platform mask */
}
//
// Check if the error level matches the platform debug mask.
// If no bits match, suppress the output.
//
if ((DebugMask & ErrorLevel) == 0) {
return 4; /* Successfully suppressed (not error) */
}
//
// Call the protocol's DebugPrint function at vtable offset 0x00.
// The protocol's DebugPrint uses VA_LIST, not variadic args.
//
VA_START (VaList, Format);
return ((UINTN (*)(UINTN, CONST CHAR8 *, VA_LIST))
Protocol->DebugPrint) (ErrorLevel, Format, VaList);
}
/**
* @brief ASSERT failure handler via DebugLib protocol.
*
* Called when an ASSERT() condition evaluates to FALSE in the module.
* Routes to the UBA DebugLib protocol's assertion handler at protocol
* vtable offset 0x08.
*
* The assertion information includes the source file path, line number,
* and a text description of the assertion condition.
*
* @param[in] FileName Full path to the source file containing the assert.
* @param[in] LineNumber Line number of the assertion in the source file.
* @param[in] Description Text description of the failing assertion condition.
*/
VOID
DebugAssert (
IN CONST CHAR8 *FileName,
IN UINTN LineNumber,
IN CONST CHAR8 *Description
)
{
UBA_DEBUG_LIB_PROTOCOL *Protocol;
//
// Resolve the DebugLib protocol (lazy initialization).
//
Protocol = GetDebugLibProtocol ();
if (Protocol != NULL) {
//
// Call the protocol's assertion handler at vtable offset 0x08.
//
((VOID (*)(CONST CHAR8 *, UINTN, CONST CHAR8 *))
Protocol->DebugAssert) (FileName, LineNumber, Description);
}
}
/**
* @brief Locate the HOB (Hand-Off Block) list from UEFI configuration table.
*
* The HOB list pointer is stored in the UEFI system table's configuration
* table array, keyed by EFI_HOB_LIST_GUID ({7739F24C-93D7-11D4-9A3A-
* 0090273FC14D}). This function scans gST->ConfigurationTable[] to find it.
*
* The system table layout for HOB access:
* gST->NumberOfTableEntries = *(UINTN *)(gST + 0x68)
* gST->ConfigurationTable = *(EFI_CONFIGURATION_TABLE **)(gST + 0x70)
* Each entry is 24 bytes: EFI_GUID (16) + VOID* (8)
*
* Once found, the result is cached in gHobList (image addr 0xF58) for
* O(1) subsequent access.
*
* Error handling:
* - If the HOB list GUID is NOT found in any ConfigurationTable entry,
* triggers DebugAssert with status 0x800000000000000E (EFI_NOT_FOUND)
* - If the resolved pointer is NULL, another DebugAssert is triggered
* - Both ASSERTs reference e:\hs\MdePkg\Library\DxeHobLib\HobLib.c
* (lines 54 and 55)
*
* @return Pointer to the HOB list, or NULL if not found / resolution fails.
*/
VOID *
GetHobList (
VOID
)
{
UINTN Index;
UINTN TableCount;
EFI_CONFIGURATION_TABLE *ConfigTable;
//
// Return cached pointer if already resolved.
//
if (gHobList != NULL) {
return gHobList;
}
gHobList = NULL;
//
// Access the configuration table array from the system table.
// SystemTable + 0x68 = NumberOfTableEntries (UINTN)
// SystemTable + 0x70 = ConfigurationTable (EFI_CONFIGURATION_TABLE *)
//
TableCount = gST->NumberOfTableEntries;
ConfigTable = gST->ConfigurationTable;
//
// Iterate through the configuration table entries to find the HOB list.
// Each entry is 24 bytes: 16-byte VendorGuid + 8-byte VendorTable pointer.
// We compare the first 8 bytes and next 8 bytes separately via
// ReadUnaligned64 against the reference GUID halves.
//
if (ConfigTable != NULL) {
for (Index = 0; Index < TableCount; Index++) {
if (IsHobListGuid (&ConfigTable[Index].VendorGuid)) {
//
// Found the HOB list GUID. The associated VendorTable pointer
// is the HOB list (PHIT HOB header).
//
gHobList = (VOID *)ConfigTable[Index].VendorTable;
break;
}
}
}
//
// If we didn't find the GUID in any table entry, trigger an ASSERT.
//
if (gHobList == NULL) {
DebugPrint (
0x80000000,
"\nASSERT_EFI_ERROR (Status = %r)\n",
0x800000000000000EULL /* EFI_NOT_FOUND status */
);
DebugAssert (
"e:\\hs\\MdePkg\\Library\\DxeHobLib\\HobLib.c",
54,
"!EFI_ERROR (Status)"
);
}
//
// If the resolved pointer is NULL, trigger another ASSERT.
//
if (gHobList == NULL) {
DebugAssert (
"e:\\hs\\MdePkg\\Library\\DxeHobLib\\HobLib.c",
55,
"mHobList != ((void *) 0)"
);
}
return gHobList;
}
/**
* @brief Check if a GUID matches EFI_HOB_LIST_GUID using 64-bit halves.
*
* Compares the input GUID against the reference EFI_HOB_LIST_GUID
* ({7739F24C-93D7-11D4-9A3A-0090273FC14D}) by splitting both into
* two 64-bit halves and comparing each half via ReadUnaligned64().
*
* The reference GUID halves are stored at:
* 0xD10: First 8 bytes = {7739F24C-93D7-11D4}
* 0xD18: Second 8 bytes = {9A3A0090-273FC14D}
*
* This avoids potential alignment issues that could arise from
* direct EFI_GUID struct comparison, since EFI_GUID has specific
* alignment requirements (4-byte aligned Data1).
*
* @param[in] Guid Pointer to the GUID to compare.
*
* @return TRUE The GUID matches EFI_HOB_LIST_GUID.
* @return FALSE The GUID does not match.
*/
BOOLEAN
IsHobListGuid (
IN EFI_GUID *Guid
)
{
//
// Compare the GUID as two 64-bit halves.
// First half: Data1(4) + Data2(2) + Data3(2) = 8 bytes (little-endian)
// Second half: Data4(8) = 8 bytes
//
return (ReadUnaligned64 (&gEfiHobListGuid) == ReadUnaligned64 (Guid))
&& (ReadUnaligned64 ((UINT8 *)&gEfiHobListGuid + 8)
== ReadUnaligned64 ((UINT8 *)Guid + 8));
}
/**
* @brief Read a 64-bit value from an (possibly unaligned) pointer.
*
* Directly dereferences a 64-bit pointer without alignment checks.
* Asserts via DebugAssert() if the pointer is NULL.
*
* This function is the module-level implementation of the BaseLib
* ReadUnaligned64() function, with the same behavior.
*
* Source path (from ASSERT string):
* e:\hs\MdePkg\Library\BaseLib\Unaligned.c, line 192
*
* @param[in] Buffer Pointer to read from (must not be NULL).
*
* @return The 64-bit value at the Buffer address.
*/
UINT64
ReadUnaligned64 (
IN CONST VOID *Buffer
)
{
//
// Assert if the pointer is NULL.
//
if (Buffer == NULL) {
DebugAssert (
"e:\\hs\\MdePkg\\Library\\BaseLib\\Unaligned.c",
192,
"Buffer != ((void *) 0)"
);
}
//
// Dereference the pointer directly.
//
return *(CONST UINT64 *)Buffer;
}
/**
* @brief Check if a PCIe BDF address is within a configured slot's range.
*
* UBA framework callback, invoked by the platform to determine if a
* PCIe device at the given BDF address should receive an OpROM update.
*
* Algorithm:
* 1. Iterate the 8 mPcieSlotRanges entries at image addr 0xED0
* 2. For each slot entry where the corresponding SlotMask bit is CLEAR
* (bit=0 means the slot is NOT already configured and needs checking):
* a. Compute the BDF address from the 3-byte descriptor:
* combined = ((Device | (Function << 8)) << 8 | Bus) << 8
* This creates a PciLib address offset (register field = 0)
* b. Open EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL via gBS->LocateProtocol()
* c. Read PCI config register offset 0x19 (Secondary Bus Number / BIST)
* d. Read PCI config register offset 0x1A (Subordinate Bus / Hdr Type)
* e. Check: BIST_val <= PcieBdfAddr <= HdrType_val
* (The BIST and Header Type registers are repurposed on Intel
* chipsets to encode secondary bus range information for PCIe
* root ports)
* 3. Return TRUE if any slot range contains the target BDF address
*
* Note: gBS->LocateProtocol() is called INSIDE the loop for each slot,
* not cached. This is how the original binary behaves.
*
* @param[in] PcieBdfAddr PCIe BDF address to test (bus:device:function).
* Encoded as a 64-bit PciLib address with the
* register offset bits set to 0.
* @param[in] SlotMask Bitmask of slots (bits 0-7). A clear bit means
* the slot should be checked. A set bit means
* the slot is already configured.
*
* @return TRUE The PCIe BDF address falls within a configured slot range.
* @return FALSE The BDF is outside all slot ranges, or the PCI Root Bridge
* IO protocol could not be located.
*/
BOOLEAN
IsPcieSlotConfigured (
IN UINT64 PcieBdfAddr,
IN UINT32 SlotMask
)
{
CONST UINT8 *SlotData; /* Pointer walking through slot config table */
BOOLEAN Found; /* Result accumulator */
UINT16 SlotIndex; /* Loop counter for 8 slot entries */
UINT32 CurrentMask; /* Local copy of SlotMask (updated by loop) */
//
// Initialize the table pointer to start BEFORE the first entry.
// The original code uses &unk_ED1 as the base, then reads 3 bytes
// at offsets [-1, 0, +1], advancing by 4 each iteration.
// Our implementation uses direct indexing into mPcieSlotRanges[],
// which avoids the +1 offset trick.
//
SlotData = (CONST UINT8 *)&mPcieSlotRanges;
Found = FALSE;
CurrentMask = SlotMask;
//
// Iterate each of the 8 PCIe slot range entries.
//
for (SlotIndex = 0; SlotIndex < 8; SlotIndex++) {
//
// Check if this slot bit is clear in the mask.
// A clear bit (0) means the slot is NOT yet configured and
// should be checked for device presence.
//
if (((CurrentMask >> SlotIndex) & 1) == 0) {
UINT8 BusByte; /* Byte at slot entry offset 0 (Bus) */
UINT8 DevByte; /* Byte at slot entry offset 1 (Device) */
UINT8 FuncByte; /* Byte at slot entry offset 2 (Function) */
UINT64 SlotBdfAddr; /* Computed BDF address for this slot */
UINT64 PciRootBridgeIo; /* Protocol interface from LocateProtocol */
UINT8 RegValue19; /* Value of PCI config register 0x19 */
UINT8 RegValue1A; /* Value of PCI config register 0x1A */
//
// Extract the 3 bytes from the slot entry.
// In the original assembly:
// v8 = byte[-1] (mPcieSlotRanges[SlotIndex].Bus)
// v9 = byte[0] (mPcieSlotRanges[SlotIndex].Device)
// v10 = byte[+1] (mPcieSlotRanges[SlotIndex].Function)
//
BusByte = mPcieSlotRanges[SlotIndex].Bus;
DevByte = mPcieSlotRanges[SlotIndex].Device;
FuncByte = mPcieSlotRanges[SlotIndex].Function;
//
// Compute the BDF address from the 3-byte descriptor.
// Formula: ((Device | (Function << 8)) << 8 | Bus) << 8
// This gives a PciLib-style address with register field = 0.
//
SlotBdfAddr = (((DevByte | ((UINT64)FuncByte << 8)) << 8)
| (UINT64)BusByte) << 8;
//
// Open EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL to access PCI config space.
// Note: This is done INSIDE the loop per the original binary behavior.
// The protocol GUID is {2F707EBB-4A1A-11D4-9A38-0090273FC14D}.
//
gBS->LocateProtocol (
&gEfiPciRootBridgeIoProtocolGuid,
NULL,
(VOID **)&PciRootBridgeIo
);
if (PciRootBridgeIo != 0) {
//
// Read PCI config space register at offset 0x19.
// On PCIe root ports, this is typically the Secondary Bus Number
// register. On standard PCI devices, this is BIST (Built-In Self Test).
// Intel chipsets repurpose this register to encode the start of
// the secondary bus range for this slot.
//
// The Pci.Read function at vtable index 7 (offset 0x38) is used.
// Signature:
// Pci.Read(This, Width=0 (Uint8), Address, Count, Buffer)
//
((VOID (*)(UINT64, UINT64, UINT64, UINT64, UINT8 *))
(*((UINT64 **)PciRootBridgeIo) + 7)) ( /* vtable[7] = offset 0x38 */
PciRootBridgeIo,
0, /* EfiPciWidthUint8 */
SlotBdfAddr | 0x19, /* Address: BDF | register 0x19 */
1, /* Count: 1 byte */
&RegValue19
);
//
// Read PCI config space register at offset 0x1A.
// This is the Subordinate Bus Number register on PCIe root ports,
// or Header Type on standard devices. Encodes the end of the
// secondary bus range for this slot.
//
((VOID (*)(UINT64, UINT64, UINT64, UINT64, UINT8 *))
(*((UINT64 **)PciRootBridgeIo) + 7)) (
PciRootBridgeIo,
0,
SlotBdfAddr | 0x1A, /* Address: BDF | register 0x1A */
1,
&RegValue1A
);
//
// Check if the target BDF address falls within the slot's range.
// If reg_0x19 <= PcieBdfAddr <= reg_0x1A, the device at this
// BDF is in the slot's secondary bus range.
//
if ((PcieBdfAddr >= RegValue19) && (PcieBdfAddr <= RegValue1A)) {
Found = TRUE;
}
}
}
}
return Found;
}
/**
* @brief Get pointer to Config Table A (primary PCIe topology).
*
* UBA framework callback registered in PBDS at offset +0x10.
* Returns a pointer to mConfigTableA (image addr 0xD20), which is
* a zero-initialized 64-byte buffer. On the LightningRidge EXEC B3
* platform, this table is unused - it acts as a terminator/null
* sentinel for the UBA framework.
*
* @param[out] ConfigTable Receives pointer to mConfigTableA.
*
* @return EFI_SUCCESS Always.
*/
EFI_STATUS
OpromGetConfigA (
OUT VOID **ConfigTable
)
{
*ConfigTable = (VOID *)&mConfigTableA;
return EFI_SUCCESS;
}
/**
* @brief Get pointer to Config Table B (6 PCIe root port entries).
*
* UBA framework callback registered in PBDS at offset +0x18.
* Returns pointer to mConfigTableB (image addr 0xD60) with 6 entries
* of 8 bytes each.
*
* The table encodes PCIe root port configuration for OpROM updates,
* including vendor/device IDs (Intel I350 - 0x8086:0x1528) and slot
* range information.
*
* @param[out] ConfigTable Receives pointer to mConfigTableB.
* @param[out] EntryCount Receives entry count (always 6).
*
* @return EFI_SUCCESS Always.
*/
EFI_STATUS
OpromGetConfigB (
OUT VOID **ConfigTable,
OUT UINTN *EntryCount
)
{
*ConfigTable = (VOID *)&mConfigTableB;
*EntryCount = 6;
return EFI_SUCCESS;
}
/**
* @brief Get pointer to Config Table C (10 extended PCIe entries).
*
* UBA framework callback registered in PBDS at offset +0x20.
* Returns pointer to mConfigTableC (image addr 0xE60) with 10 entries
* of 8 bytes each.
*
* The table contains extended device configuration for various Intel
* Ethernet controllers:
* - 0x8086:0x10D3 Intel 82599ES 10 Gigabit Ethernet
* - 0x8086:0x1521 Intel I350 Gigabit Ethernet
* - 0x8086:0x1522 Intel I350 Gigabit Ethernet (alternate)
* - 0x8086:0x1528 Intel I350 Gigabit Ethernet
* - 0x8086:0x10FB Intel 82599ES 10 Gigabit Ethernet (alternate)
*
* @param[out] ConfigTable Receives pointer to mConfigTableC.
* @param[out] EntryCount Receives entry count (always 10).
*
* @return EFI_SUCCESS Always.
*/
EFI_STATUS
OpromGetConfigC (
OUT VOID **ConfigTable,
OUT UINTN *EntryCount
)
{
*ConfigTable = (VOID *)&mConfigTableC;
*EntryCount = 10;
return EFI_SUCCESS;
}
/**
* @brief Set PCIe slot number callback.
*
* UBA framework callback registered in PBDS at offset +0x28.
* On the LightningRidge EXEC B3 platform, this function always sets
* the slot number to 0 and logs a debug message.
*
* The debug message: "[UBA]:SetPcieSlotNumber callback - %d\n"
* with argument 0, indicating that slot enumeration should start
* from slot number 0 for this platform.
*
* @param[out] SlotNumber Receives the slot number (always 0).
*
* @return EFI_SUCCESS Always.
*/
EFI_STATUS
OpromSetSlotNumber (
OUT UINT8 *SlotNumber
)
{
//
// Always set slot number to 0 on this platform.
//
*SlotNumber = 0;
//
// Log the slot assignment: "[UBA]:SetPcieSlotNumber callback - 0\n"
//
DebugPrint (0x80000000, "[UBA]:SetPcieSlotNumber callback - %d\n", 0);
return EFI_SUCCESS;
}
/*==============================================================================
* Module Summary
*
* == Binary Identity ==
* File: OpromUpdateDxeLightningRidgeEXECB3.efi
* Index: 31 of 427 PE files in HR650X BIOS
* Size: 4224 bytes (6 PE sections)
* SHA256: d58f84d1adb92017d59b450e242cac64939aadc6e24a35da7573064e7b531022
* PDB: OpromUpdateDxeLightningRidgeEXECB3.pdb
* PDB GUID: {2E401ABE-49E9-4BD3-969B-AF5A00349AA6}, Age 1
*
* == Source Path (from PDB) ==
* e:\hs\Build\HR6N0XMLK\DEBUG_VS2015\X64\PurleyRpPkg\Uba\UbaMain\Dxe\
* TypeLightningRidgeEXECB3\OpromUpdateDxe\OpromUpdateDxe\DEBUG\
* OpromUpdateDxeLightningRidgeEXECB3.pdb
*
* == Protocol GUIDs Used ==
* 0xCE0: {2F707EBB-4A1A-11D4-9A38-0090273FC14D} EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
* 0xCF0: {36232936-0E76-31C8-A13A-3AF2FC1C3932} UBA_DEBUG_LIB_PROTOCOL
* 0xD00: {E03E0D46-5263-4845-B0A4-58D57B3177E2} UBA_CONFIG_PROTOCOL (EXECB3)
* 0xD10: {7739F24C-93D7-11D4-9A3A-0090273FC14D} EFI_HOB_LIST_GUID
* 0xEF0: {371BD79C-DE79-4C5F-AA2B-BC9EBEFA988F} OPROM_UPDATE_CONFIG_DATA
*
* == PCI Devices Identified in Config Tables ==
* 0x8086:0x1528 Intel I350 Gigabit Ethernet
* 0x8086:0x1521 Intel I350 GB Ethernet (alternate variant)
* 0x8086:0x1522 Intel I350 GB Ethernet (another variant)
* 0x8086:0x10D3 Intel 82599ES 10 Gigabit Ethernet
* 0x8086:0x10FB Intel 82599ES 10 Gigabit (alternate variant)
*
* == Compiled Library Paths (from ASSERT strings) ==
* e:\hs\MdePkg\Library\UefiBootServicesTableLib\UefiBootServicesTableLib.c
* e:\hs\MdePkg\Library\UefiRuntimeServicesTableLib\UefiRuntimeServicesTableLib.c
* e:\hs\MdePkg\Library\DxeHobLib\HobLib.c
* e:\hs\MdePkg\Library\BaseLib\Unaligned.c
*
* == Section Layout ==
* HEADER 0x000-0x2C0 PE headers and DOS stub
* .text 0x2C0-0x8DF Executable code (12 functions)
* .rdata 0x8E0-0xB3F Read-only data (strings, debug info)
* .data 0xB40-0xB73 Uninitialized globals (zeros)
* 0xB74-0xBFF PDB/RSDS debug record
* seg004 0xBE0-0xC3F Second PDB path string
* .xdata 0x1000-0x105F Exception handling data
* .reloc 0x1060-0x1073 Base relocations (6 entries for PBDS func ptrs)
*
* == Function Index ==
* 0x0390: _ModuleEntryPoint Entry Point (EFIAPI)
* 0x048C: IsPcieSlotConfigured PBDS callback [0] @+0x08
* 0x05B8: OpromGetConfigA PBDS callback [1] @+0x10
* 0x05C8: OpromGetConfigB PBDS callback [2] @+0x18
* 0x05DC: OpromGetConfigC PBDS callback [3] @+0x20
* 0x05F0: OpromSetSlotNumber PBDS callback [4] @+0x28
* 0x0614: GetDebugLibProtocol Helper (lazy protocol resolver)
* 0x0694: DebugPrint Helper (CMOS-based debug output)
* 0x071C: DebugAssert Helper (assert handler)
* 0x075C: GetHobList Helper (HOB list resolver)
* 0x0834: IsHobListGuid Helper (GUID comparator)
* 0x08A4: ReadUnaligned64 Helper (unaligned read)
*============================================================================*/