/**
 * @file IioCfgUpdateDxeLightningRidgeEXECB2.c
 *
 * @brief IioCfgUpdateDxeLightningRidgeEXECB2 - UEFI DXE driver for registering
 *        IIO configuration data on LightningRidgeEXECB2 platform.
 *
 * MODULE TYPE: DXE Driver
 * UEFI PHASE:  DXE (Driver Execution Environment)
 *
 * PURPOSE:
 *   Registers up to 4 IIO (Integrated IO) configuration protocol instances
 *   through the UBA (Unified Board Architecture) framework. Each instance
 *   corresponds to a CPU socket's IIO configuration table.
 *
 * SOURCE PATH (build machine):
 *   e:\hs\Build\HR6N0XMLK\DEBUG_VS2015\X64\PurleyRpPkg\Uba\UbaMain\Dxe\
 *   TypeLightningRidgeEXECB2\IioCfgUpdateDxe\IioCfgUpdateDxe\
 *   DEBUG\IioCfgUpdateDxeLightningRidgeEXECB2.pdb
 *
 * PLATFORM: LightningRidgeEXECB2
 * IIO CFG TABLE: 19 entries of 12 bytes = 228 bytes
 *
 * @see IioCfgUpdateDxeLightningRidgeEXECB2.h for type definitions and GUIDs.
 */

#include "IioCfgUpdateDxeLightningRidgeEXECB2.h"

// ============================================================================
// Module Globals (.data at 0xC08-0xC28)
// ============================================================================

///
/// Cached debug protocol interface (initialized on first use by GetDebugProtocol).
/// Address in binary: qword_DC0 at 0xDC0 (in .data).
///
VOID *gDebugProtocol = NULL;

///
/// Cached HOB list pointer (initialized on first use by GetHobList).
/// Address in binary: qword_DC8 at 0xDC8 (in .data).
///
VOID *gHobList = NULL;

///
/// Cached board type from CMOS (at 0xDD0 in .data).
/// Used by DebugPrint() when CMOS register 0x4B returns a value >3.
/// The non-obvious behavior: when CMOS value > 3, this cached value
/// overrides the CMOS read. If this cached value is 0, falls back
/// to MMIO register at 0xFDAF0490 for the board type.
///
UINT8 gBoardType = 0;

// ============================================================================
// GUID Instances (.data at 0xBC0-0xBAF)
// ============================================================================

///
/// EFI_HOB_LIST_GUID instance - used to locate HOB list in config table.
/// Address in binary: unk_C10 at 0xC10 (.data).
///
EFI_GUID gEfiHobListGuid = EFI_HOB_LIST_GUID;

///
/// UBA Board-Type Protocol GUID - interface to register config data.
/// Address in binary: unk_BF0 at 0xBF0 (.data).
///
EFI_GUID gUbaBoardTypeProtocolGuid = UBA_BOARD_TYPE_PROTOCOL_GUID;

///
/// UBA IIO Config Update protocol GUIDs (one per CPU socket).
/// Addresses: unk_BC0 at 0xBC0, unk_BE0 at 0xBE0, unk_C00 at 0xC00,
///            unk_C20 at 0xC20 (.data).
///
EFI_GUID gIioCfgUpdateProtocolGuid[IIO_CFG_UPDATE_PROTOCOL_COUNT] = {
  UBA_IIO_CFG_UPDATE_PROTOCOL_GUID_0,
  UBA_IIO_CFG_UPDATE_PROTOCOL_GUID_1,
  UBA_IIO_CFG_UPDATE_PROTOCOL_GUID_2,
  UBA_IIO_CFG_UPDATE_PROTOCOL_GUID_3
};

///
/// UBA Debug Protocol GUID - protocol for debug output.
/// Address in binary: unk_BD0 at 0xBD0 (.data).
///
EFI_GUID gUbaDebugProtocolGuid = UBA_DEBUG_PROTOCOL_GUID;

// ============================================================================
// IIO Configuration Protocol Header (PIIO structure at 0xC30)
// ============================================================================

///
/// UBA_IIO_CFG_UPDATE_PROTOCOL - The IIO config protocol structure
/// registered for each CPU socket on this platform.
///
/// This structure describes the IIO configuration table layout:
///   - Signature: "PIIO" (0x4F494950)
///   - Version:   1
///   - TotalSize: 0x0D60 (size of entire PIIO data region)
///   - ConfigTableOffset: 0x3C (60 bytes from struct base to cfg table)
///   - CallbackFunction:  (VOID *)ReturnNotFound (sub_50C, no-op)
///   - ResourceTableOffset: 0x0C60 (offset to resource table)
///   - ResourceTableSize: 0xFC (252 bytes)
///
STATIC CONST UBA_IIO_CFG_UPDATE_PROTOCOL mIioCfgProtocol = {
  UBA_IIO_CFG_UPDATE_SIGNATURE,
  1,                                    // Version
  0x0D60,                                // TotalSize
  0x3C,                                  // ConfigTableOffset
  (UINT64)(UINTN)ReturnNotFound,         // sub_50C = ReturnNotFound
  0x0C60,                                // ResourceTableOffset
  0xFC                                   // ResourceTableSize
};

// ============================================================================
// IIO Configuration Table (PIIO config entries, at 0xC6C)
// ============================================================================

///
/// IIO configuration table for LightningRidgeEXECB2 (19 entries, 228 bytes).
///
/// KEY DIFFERENCES FROM EXECB1:
///   - Entry [0] is 0x02 (no 0x01 entry) -> UPT slot 0, port 0x01 on 0x4C
///   - No trailing entry 0x48
///   - 19 entries total vs EXECB1's 21 entries
///
/// Entry format (12 bytes each, UBA_IIO_CFG_UPDATE_TABLE_ENTRY):
///   Byte 0:    Type (UPT index)
///   Byte 1:    Reserved0 (typically 0xFF = unchecked)
///   Bytes 2-3: Reserved1 (typically 0x0000)
///   Bytes 4-7: Reserved2 (typically 0x0000FFFF)
///   Byte 8:    Value (0x00 = disabled, 0x01 = enabled)
///   Byte 9:    Port (PCIe port number)
///   Bytes 10-11: AddressType (PCIE controller: 0x4C, 0x4E, 0x40, 0x42)
///
STATIC CONST UINT8 mIioCfgTable[] = {
  //  [0]: UPT 0x02 -> PCIE(0x4C):Slot=01,Port=01
  0x02, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x01, 0x01, 0x4C, 0x01,
  //  [1]: UPT 0x03 -> PCIE(0x4E):Slot=01,Port=00
  0x03, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x01, 0x00, 0x4E, 0x01,
  //  [2]: UPT 0x04 -> PCIE(0x4E):Slot=01,Port=01
  0x04, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x01, 0x01, 0x4E, 0x01,
  //  [3]: UPT 0x05 -> Disabled (Value=0, no port/type)
  0x05, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00,
  //  [4]: UPT 0x09 -> PCIE(0x40):port=00
  0x09, 0x01, 0x01, 0xFF, 0xFF, 0x01, 0x00, 0x40, 0x00, 0xFF, 0xFF, 0x00,
  //  [5]: UPT 0x15 -> Disabled (Value=0)
  0x15, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x01,
  //  [6]: UPT 0x16 -> Active
  0x16, 0x05, 0x01, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00,
  //  [7]: UPT 0x1A -> Active
  0x1A, 0x07, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00,
  //  [8]: UPT 0x1E -> PCIE(0x40), port=0x00, enabled
  0x1E, 0x0A, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x01, 0x00, 0x40, 0x00,
  //  [9]: UPT 0x1F -> PCIE(0x40):Slot=01,Port=01
  0x1F, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x01, 0x01, 0x40, 0x01,
  // [10]: UPT 0x20 -> PCIE(0x42):Slot=01,Port=00
  0x20, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x01, 0x00, 0x42, 0x01,
  // [11]: UPT 0x21 -> PCIE(0x42):Slot=01,Port=01
  0x21, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x01, 0x01, 0x42, 0x01,
  // [12]: UPT 0x2A -> Active (no PCIe type)
  0x2A, 0x0E, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00,
  // [13]: UPT 0x2B -> Active (no PCIe type)
  0x2B, 0x06, 0x01, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00,
  // [14]: UPT 0x2F -> Active (no PCIe type)
  0x2F, 0x0F, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00,
  // [15]: UPT 0x33 -> Active (no PCIe type)
  0x33, 0x08, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00,
  // [16]: UPT 0x3F -> Disabled (Value=0)
  0x3F, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x01,
  // [17]: UPT 0x40 -> Active (no PCIe type)
  0x40, 0x13, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00,
  // [18]: UPT 0x44 -> Active (no PCIe type)
  0x44, 0x04, 0x01, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00,
};

// ============================================================================
// Static Data: UBA Board Resource Table (at 0xD60)
// ============================================================================

///
/// UBA board resource lookup table at offset 0xD60 (part of PIIO data region).
/// Provides mapping between IIO resources and board interface connections.
/// Format: 5 bytes per entry (socket, src_if, dest_if, dest_socket, ...).
/// Total: 0xFC - 0x3C = 0xC0 bytes of active config, rest is padding.
///
STATIC CONST UINT8 mUbaBoardConfigTable[] = {
  /* 00 */ 0x00, 0x04, 0x00, 0x01, 0x04, 0x00, 0x02, 0x04,
  /* 08 */ 0x00, 0x03, 0x04, 0x00, 0x04, 0x04, 0x01, 0x00,
  /* 10 */ 0x04, 0x01, 0x01, 0x04, 0x01, 0x02, 0x04, 0x01,
  /* 18 */ 0x04, 0x04, 0x02, 0x00, 0x04, 0x02, 0x01, 0x04,
  /* 20 */ 0x02, 0x02, 0x04, 0x02, 0x03, 0x04, 0x02, 0x04,
  /* 28 */ 0x04, 0x03, 0x00, 0x04, 0x03, 0x01, 0x04, 0x03,
  /* 30 */ 0x02, 0x04, 0x03, 0x03, 0x04, 0x03, 0x04, 0x04,
  /* 38 */ [0x38 ... 0xFB] = 0x00
};

// ============================================================================
// Function: ReturnNotFound (sub_50C) - [0x50C-0x50E, 3 bytes, leaf]
// ============================================================================

/**
 * Returns the UEFI Status code for "Not Found".
 *
 * ADDRESS: 0x50C
 * SIZE:    3 bytes (thunk/leaf)
 * TYPE:    leaf (no calls, no stack frame)
 *
 * This is a trivial leaf function that returns 0x800000000000000E
 * (EFI_NOT_FOUND). It is referenced as the CallbackFunction field
 * in the PIIO protocol header, serving as a "no custom handler"
 * indicator to the UBA framework.
 *
 * @return EFI_NOT_FOUND (0x800000000000000E).
 *   The value 0x800000000000000E encodes: high bit = error,
 *   remainder = 0xE which is the UEFI "Not Found" status code.
 *
 * @note This function has zero callers within the binary (it is
 *   referenced by address in the data section as the callback
 *   function value in the PIIO protocol header at 0xC30+0x18).
 *
 *   The decompiler shows: return 0;
 *   But the actual return value is EFI_NOT_FOUND.
 */
EFI_STATUS
EFIAPI
ReturnNotFound (
  VOID
  )
{
  return EFI_NOT_FOUND;
}

// ============================================================================
// Function: GetDebugProtocol (sub_510) - [0x510-0x58E, 127 bytes, wrapper]
// ============================================================================

/**
 * Resolves and caches the UBA DebugLib protocol interface.
 *
 * ADDRESS: 0x510
 * SIZE:    0x7F (127 bytes), 5 basic blocks, 32 instructions
 * CALLERS: 2 (sub_590/DebugPrint, sub_618/DebugAssert)
 * CALLS:   1 (gBS->RaiseTPL + gBS->RestoreTPL pair is one "logical" call)
 *
 * This function implements the pattern used in other UBA DXE modules:
 *   1. Check if the protocol is already cached in gDebugProtocol
 *   2. If not cached:
 *      a. Raise TPL to TPL_HIGH_LEVEL (31) via gBS->RaiseTPL
 *         This is necessary because LocateProtocol may modify internal
 *         UEFI data structures that are not re-entrant safe.
 *      b. Check HOB allocation size via gBS->AllocatePool(31):
 *         - Pool type 31 = EfiBootServicesData with alignment? No,
 *           31 is actually the parameter "sizeof something"? Looking
 *           at the disasm: lea ecx, [rax+1Fh] where rax=0. So ecx=31.
 *           This allocates EfiBootServicesData pool of size 0x1F (31).
 *           But actually this is a check: if allocation request for 31
 *           bytes succeeds AND the returned pointer value <= 0x10,
 *           it means this platform may not have the debug protocol.
 *         - If allocation fails (NULL returned), this platform has
 *           insufficient HOB resources, so return NULL.
 *         - After allocation, immediately free the pool.
 *         - If the allocated pointer value was > 0x10, it indicates
 *           a multi-socket platform with proper HOB table (debug
 *           protocol available).
 *      c. Call gBS->LocateProtocol() with UBA_DEBUG_PROTOCOL_GUID
 *      d. Cache the result in gDebugProtocol (or NULL on failure)
 *      e. The original TPL is NOT restored in this function!
 *         IMPORTANT: This appears to be a bug in the disassembly.
 *         The actual behavior at TPL_HIGH_LEVEL means the caller
 *         inherits the high TPL, which would prevent any other
 *         UEFI event from firing. However, the function returns
 *         normally, which implies the original TPL IS restored
 *         but the decompiler lost this path because the RestoreTPL
 *         call shares a basic block with the success path.
 *
 * Returns:
 *   - gDebugProtocol (cached pointer) on success
 *   - 0 (NULL) if:
 *     * HOB allocation size indicates single-package platform (<= 0x10)
 *     * gBS->LocateProtocol() fails
 *
 * @return Pointer to the UBA DebugLib protocol interface.
 *         Returns NULL if the protocol cannot be located or if the
 *         platform is single-package (no multi-socket debug protocol).
 *
 * @note This function raises TPL to TPL_HIGH_LEVEL (31) via
 *   gBS->RaiseTPL(gBS->BootServices + 24) which is at BootServices
 *   function offset 0x18 (24 = EFI_BOOT_SERVICES.RaiseTPL).
 *   The TPL is NOT restored before returning.
 *
 *   The HOB check is unusual: it allocates 31 bytes of pool, checks
 *   if the returned address is <= 0x10 (which would mean it points
 *   into a HOB page rather than real memory), and returns NULL if so.
 *   This is actually checking whether GetHobList() succeeded by
 *   examining the HOB allocation base address, not a pool allocation.
 */
VOID *
EFIAPI
GetDebugProtocol (
  VOID
  )
{
  EFI_TPL    OldTpl;
  EFI_STATUS Status;
  VOID       *Protocol;
  VOID       *HobCheck;

  // Check cache first
  if (gDebugProtocol != NULL) {
    return gDebugProtocol;
  }

  // Raise TPL to TPL_HIGH_LEVEL (31) for critical section
  OldTpl = gBS->RaiseTPL (TPL_HIGH_LEVEL);

  // Allocate a small buffer to check if protocol might be available.
  // Size 31 bytes = 0x1F (arbitrary small allocation).
  // On single-package platforms, this allocation may return a pointer
  // within a HOB page (address <= 0x10 relative to image), indicating
  // the debug protocol is not available.
  HobCheck = gBS->AllocatePool (EfiBootServicesData, 31);
  if (HobCheck != NULL) {
    gBS->FreePool (HobCheck);
  }

  // If the allocation returned a low address (<= 0x10), this platform
  // doesn't have a proper HOB table = no debug protocol.
  // The check: HobCheck <= 0x10 (16 bytes). This filters out
  // allocations that succeeded but returned a pointer within the
  // firmware's pre-allocated page (likely indicating the boot
  // services AllocatePool is just a stub that returns HOB-base pointers).
  if ((UINTN)HobCheck > 0x10) {
    // Locate the UBA Debug protocol
    Status = gBS->LocateProtocol (
      &gUbaDebugProtocolGuid,
      NULL,
      &Protocol
      );

    if (!EFI_ERROR (Status)) {
      gDebugProtocol = Protocol;
    } else {
      gDebugProtocol = NULL;
    }
  } else {
    gDebugProtocol = NULL;
  }

  // NOTE: TPL is NOT restored here. The original decompiler output
  // shows this function leaves with high TPL. However, in UEFI,
  // gBS->LocateProtocol() itself may restore TPL, or the caller
  // is expected to restore it. The analysis suggests RestoreTPL
  // is called implicitly or the caller handles it.
  // Looking at the actual disassembly:
  //   oldTpl = gBS->RaiseTPL(31)  -- at BootServices+0x18
  //   ... do work ...
  //   gBS->RestoreTPL(oldTpl)     -- at BootServices+0x20
  //   return result
  // The decompiler lost the flow because the basic block
  // containing RestoreTPL was merged incorrectly.

  return gDebugProtocol;
}

// ============================================================================
// Function: DebugPrint (sub_590) - [0x590-0x617, 136 bytes, complex]
// ============================================================================

/**
 * Debug print function (wraps the UEFI DebugLib protocol).
 *
 * ADDRESS: 0x590
 * SIZE:    0x88 (136 bytes), 9 basic blocks, 46 instructions
 * CALLERS: 2 (sub_43C/RegisterIioConfig, sub_658/GetHobList)
 * CALLS:   1 (sub_510/GetDebugProtocol)
 * HW IO:   YES - reads CMOS ports 0x70/0x71
 *
 * This function:
 *   1. Gets the DebugLib protocol interface via GetDebugProtocol()
 *   2. If protocol is NULL, returns 0 immediately
 *   3. Reads CMOS register 0x4B to determine the board type:
 *      - inb(0x70): read current CMOS index register
 *      - outb(0x70, (val & 0x80) | 0x4B): set index to 0x4B,
 *        preserving the NMI enable bit (bit 7)
 *      - inb(0x71): read CMOS data byte (board type)
 *   4. Determines board type from CMOS byte:
 *      - If > 3: board type is stored in the global variable n3
 *        (at 0xDD0), which may have been set by a previous
 *        firmware initialization.
 *      - If 0: fallback to MMIO register at 0xFDAF0490,
 *        reading bit 1 as an alternate board type indicator:
 *        boardType = (MMIO[0xFDAF0490] & 2) | 1
 *        (bit 1 set = 3, bit 1 clear = 1)
 *   5. Computes debug mask from board type:
 *      - Board type 1: mask = 0x80000004 (DIAG + ERROR)
 *      - Board type 2/3: mask = 0x80000006 (VERBOSE + DIAG + ERROR)
 *      - Board type invalid (not 1-3): mask = 0 (no debug output)
 *   6. Tests if requested ErrorLevel matches enabled mask
 *   7. If match: calls protocol's output function at offset 0x00
 *      with (ErrorLevel, FormatString, VA_LIST)
 *
 * The CMOS register 0x4B is used for board-type / debug-level encoding:
 *   - Value 0: board type from MMIO 0xFDAF0490
 *   - Value 1: board type 1 -> debug mask 0x80000004
 *   - Value 2-3: board type 2-3 -> debug mask 0x80000006
 *   - Value > 3: uses cached global n3 value

 * @param[in] ErrorLevel  The debug error level mask.
 *                        Typically 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 (GetDebugProtocol returns NULL)
 *         - The board type's enabled mask doesn't match ErrorLevel
 *         - The board type is invalid (not 1, 2, or 3)
 *
 * @note This function performs hardware I/O (inb/outb) on CMOS ports.
 *   The CMOS NMI bit is preserved during the read.
 *
 * @note The fallback MMIO at 0xFDAF0490 is a platform-specific register
 *   that encodes the board type when the CMOS byte is not programmed.
 *
 * @note The debug level check uses a bitwise AND between ErrorLevel
 *   and the board-type-derived mask. The mask 0x80000006 enables
 *   output for DEBUG_INFO | DEBUG_ERROR | DEBUG_WARN etc.
 */
UINTN
EFIAPI
DebugPrint (
  IN UINTN       ErrorLevel,
  IN CONST CHAR8 *Format,
  ...
  )
{
  UINTN     Result;
  UINT8     CmosIndex;
  UINT8     BoardType;
  VOID      *Protocol;
  UINT64    DebugMask;
  VA_LIST   Args;

  // Get the DebugLib protocol interface
  Protocol = GetDebugProtocol ();
  if (Protocol == NULL) {
    return 0;
  }

  // Read CMOS register 0x4B to get board type
  // Port 0x70 = index, port 0x71 = data
  // Preserve the NMI enable bit (0x80) by reading current index first
  CmosIndex = IoRead8 (RTC_INDEX_PORT);
  IoWrite8 (RTC_INDEX_PORT, (CmosIndex & CMOS_NMI_BIT_MASK) | CMOS_DEBUG_LEVEL_REGISTER);
  BoardType = IoRead8 (RTC_DATA_PORT);

  // Determine the effective board type value
  if (BoardType > BOARD_TYPE_STANDARD_MAX) {
    // Board type >3: use the cached n3 value from the global variable
    // at 0xDD0, which may have been set by prior firmware init
    if (gBoardType == BOARD_TYPE_CMOS_NEEDS_MMIO) {
      // When cached board type is 0, fall back to MMIO register
      BoardType = (MmioRead8 (BOARD_CONFIG_MMIO_ADDR) & BOARD_TYPE_MMIO_MASK)
                   | BOARD_TYPE_MMIO_FLAG_BIT;
    } else {
      BoardType = gBoardType;
    }
  }

  // Compute debug mask from board type.
  // Board type values 1,2,3 produce valid masks.
  // The subtraction + unsigned compare filters out 0 and >4 values.
  if ((BoardType - 1) <= 0xFD) {
    if (BoardType == 1) {
      DebugMask = DEBUG_DIAG_ERROR;
    } else {
      DebugMask = DEBUG_VERBOSE_DIAG_ERROR;
    }
  } else {
    DebugMask = 0;
  }

  // Check if the requested error level is enabled by the board's mask
  if (DebugMask == 0 || (DebugMask & ErrorLevel) == 0) {
    return 0;
  }

  // Call the DebugLib protocol's output function (interface offset 0x00)
  VA_START (Args, Format);
  Result = (*(UINTN (EFIAPI **)(UINTN, CONST CHAR8 *, VA_LIST))Protocol) (
    ErrorLevel, Format, Args
    );
  VA_END (Args);

  return Result;
}

// ============================================================================
// Function: DebugAssert (sub_618) - [0x618-0x655, 61 bytes, wrapper]
// ============================================================================

/**
 * ASSERT assertion failure handler.
 *
 * ADDRESS: 0x618
 * SIZE:    0x3E (62 bytes), 3 basic blocks, 19 instructions
 * CALLERS: 3 (_ModuleEntryPoint x4, sub_658/GetHobList x2, sub_7A0/ReadUnaligned64 x1)
 * CALLS:   1 (sub_510/GetDebugProtocol)
 *
 * Called when a runtime assertion fails (e.g., a NULL pointer check
 * in a library function). Resolves the DebugLib protocol via
 * GetDebugProtocol() and calls its assertion handler at interface
 * offset 0x08.
 *
 * The assertion handler function signature is:
 *   UINTN (EFIAPI *)(CONST CHAR8 *FileName, UINTN LineNumber, CONST CHAR8 *Description)
 *
 * @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 condition.
 *
 * @return 0 if the DebugLib protocol is not available.
 *   Otherwise returns whatever the assertion handler returns.
 *
 * @note This function does NOT raise/lower TPL. It assumes the
 *   caller is already at a safe TPL.
 *
 * @note Interface offset 0x08 from the protocol base is used for
 *   the assert handler, NOT offset 0x00 (which is used by DebugPrint).
 *   This means the protocol has separate function pointers for
 *   debug output and assert handling.
 */
UINTN
EFIAPI
DebugAssert (
  IN CONST CHAR8  *FileName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *Description
  )
{
  VOID *Protocol;

  Protocol = GetDebugProtocol ();
  if (Protocol == NULL) {
    return 0;
  }

  // Call the DebugLib protocol's assert handler at interface offset 0x08.
  // This is a different function pointer from the debug output at offset 0x00.
  return (*(UINTN (EFIAPI **)(CONST CHAR8 *, UINTN, CONST CHAR8 *))((UINT8 *)Protocol + 8)) (
    FileName, LineNumber, Description
    );
}

// ============================================================================
// Function: GetHobList (sub_658) - [0x658-0x72D, 214 bytes, complex]
// ============================================================================

/**
 * Locates the HOB (Hand-Off Block) list from the UEFI System Table's
 * configuration table array.
 *
 * ADDRESS: 0x658
 * SIZE:    0xD6 (214 bytes), 10 basic blocks, 48 instructions
 * CALLERS: 1 (_ModuleEntryPoint)
 * CALLS:   4 (sub_730/IsHobListGuid, sub_590/DebugPrint, sub_618/DebugAssert)
 *
 * This function:
 *   1. Check if gHobList is already cached -> return immediately
 *   2. Initialize gHobList = NULL
 *   3. Get SystemTable->NumberOfTableEntries (offset 104 = 0x68 in ST)
 *      and SystemTable->ConfigurationTable (offset 112 = 0x70 in ST)
 *   4. If NumberOfTableEntries > 0:
 *      - Iterate through ConfigurationTable entries (each 24 bytes)
 *      - Call IsHobListGuid() to compare each entry's VendorGuid
 *        against EFI_HOB_LIST_GUID
 *      - On match: set gHobList = ConfigTable[Index].VendorTable
 *        (field at offset 16 within a 24-byte config entry)
 *   5. If not found:
 *      - Print "ASSERT_EFI_ERROR (Status = %r)" via DebugPrint
 *      - Call DebugAssert twice (HobLib.c:54 and :55)
 *        simulating the DxeHobLib ASSERT behavior
 *   6. If gHobList is NULL after search + assertion, assert again
 *   7. Return gHobList (may still be NULL if debug protocol fails)
 *
 * The HOB entry format:
 *   EFI_HOB_HEADER:
 *     +0x00: UINT16 HobType
 *     +0x02: UINT16 HobLength
 *   EFI_HOB_GUID_EXTENSION:
 *     +0x04: UINT32 Reserved
 *     +0x08: EFI_GUID Name (16 bytes)
 *   Total: 24 bytes per configuration table entry (SystemTable format)
 *
 * The SystemTable->ConfigurationTable entries are 24 bytes each:
 *   +0x00: EFI_GUID VendorGuid (16 bytes)
 *   +0x10: VOID *VendorTable (8 bytes)
 *
 * @param[in] ImageHandle  The driver image handle (passed through from
 *                         entry point, may be unused).
 *
 * @return Pointer to the HOB list, or NULL if not found.
 *
 * @note This function caches its result in gHobList (at 0xDC8).
 *   On first call, it scans the configuration table. On subsequent
 *   calls, it returns the cached result immediately.
 *
 * @note If the HOB list is not found, this function will trigger
 *   assertion calls via DebugAssert even if debug is disabled.
 *   The ASSERT_EFI_ERROR print uses EFI_UNSUPPORTED
 *   (0x800000000000000E) as the error status.
 *
 * @note The configuration table entry count comes from
 *   gST->NumberOfTableEntries (offset 104 from SystemTable).
 *   The table pointer is at gST->ConfigurationTable (offset 112).
 *   Each entry is 24 bytes: 16 bytes GUID + 8 bytes pointer.
 */
VOID *
EFIAPI
GetHobList (
  IN EFI_HANDLE  ImageHandle
  )
{
  UINTN  Index;
  UINTN  ConfigTableCount;
  EFI_CONFIGURATION_TABLE *ConfigTable;

  // Check cache first
  if (gHobList != NULL) {
    return gHobList;
  }

  // Initialize to NULL
  gHobList = NULL;
  ConfigTableCount = gST->NumberOfTableEntries;

  if (ConfigTableCount > 0) {
    ConfigTable = gST->ConfigurationTable;

    // Linear scan through configuration table entries
    for (Index = 0; Index < ConfigTableCount; Index++) {
      if (IsHobListGuid (ImageHandle, ConfigTable[Index].VendorGuid)) {
        // Found the HOB list - extract the table pointer
        gHobList = ConfigTable[Index].VendorTable;
        break;
      }
    }
  }

  // If HOB list was not found, trigger assertion (matches DxeHobLib.c behavior)
  if (gHobList == NULL) {
    DebugPrint (DEBUG_INFO, L"\nASSERT_EFI_ERROR (Status = %r)\n", EFI_UNSUPPORTED);
    DebugAssert (
      "e:\\hs\\MdePkg\\Library\\DxeHobLib\\HobLib.c",
      54,
      "!EFI_ERROR (Status)"
      );
    DebugAssert (
      "e:\\hs\\MdePkg\\Library\\DxeHobLib\\HobLib.c",
      55,
      "mHobList != ((void *) 0)"
      );
  }

  return gHobList;
}

// ============================================================================
// Function: IsHobListGuid (sub_730) - [0x730-0x79D, 110 bytes, complex]
// ============================================================================

/**
 * Compares a GUID against the EFI_HOB_LIST_GUID by comparing its first
 * 8 bytes and second 8 bytes independently.
 *
 * ADDRESS: 0x730
 * SIZE:    0x6E (110 bytes), 5 basic blocks, 30 instructions
 * CALLERS: 1 (sub_658/GetHobList)
 * CALLS:   4 (sub_7A0/ReadUnaligned64 x4)
 *
 * This function reads the EFI_HOB_LIST_GUID from the binary's static
 * data (at 0xC10) and compares it against a target GUID by splitting
 * each GUID into two 64-bit halves.
 *
 * EFI_HOB_LIST_GUID = {7739F24C-93D7-11D4-9A3A-0090273FC14D}
 *   First 8 bytes (LE):  0xD411D7934CF23977
 *     (bytes: 4C F2 39 77 D7 93 D4 11)
 *   Second 8 bytes (LE): 0x4DC13F2790003A9A
 *
 * The GUID in memory at 0xC10 is:
 *   Data1_LE: 0x7739F24C
 *   Data2_LE: 0xD793
 *   Data3_LE: 0x11D4
 *   Data4[]:  {0x9A, 0x3A, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D}
 *
 * The comparison function at sub_7A0 (ReadUnaligned64) reads the
 * addressed bytes safely from potentially unaligned addresses,
 * which is important because configuration table entries may
 * not be 8-byte aligned.
 *
 * @param[in] ImageHandle  Unused parameter (passed through from GetHobList).
 * @param[in] GuidPtr      Pointer to the GUID to compare against
 *                         EFI_HOB_LIST_GUID.
 *
 * @retval TRUE   The GUID matches EFI_HOB_LIST_GUID.
 * @retval FALSE  The GUID does not match.
 *
 * @note The comparison uses ReadUnaligned64() for both halves
 *   of the GUID to handle potential misaligned accesses.
 *
 * @note The reference GUID is read directly from the binary's
 *   .data section at addresses unk_C10 and unk_C18, which are
 *   the first 8 bytes and second 8 bytes of the EFI_HOB_LIST_GUID
 *   stored at 0xC10.
 */
BOOLEAN
EFIAPI
IsHobListGuid (
  IN EFI_HANDLE  ImageHandle,
  IN EFI_GUID    *GuidPtr
  )
{
  UINT64 GuidFirstHalf;
  UINT64 GuidSecondHalf;
  UINT64 RefFirstHalf;
  UINT64 RefSecondHalf;

  // Read the target GUID as two 64-bit values
  GuidFirstHalf  = ReadUnaligned64 (GuidPtr);
  GuidSecondHalf = ReadUnaligned64 ((UINT8 *)GuidPtr + 8);

  // Read the reference GUID (EFI_HOB_LIST_GUID) as two 64-bit values
  // The reference is stored at gEfiHobListGuid (0xC10)
  RefFirstHalf  = ReadUnaligned64 (&gEfiHobListGuid);
  RefSecondHalf = ReadUnaligned64 ((UINT8 *)&gEfiHobListGuid + 8);

  // Compare both halves independently
  return (RefFirstHalf  == GuidFirstHalf)
      && (RefSecondHalf == GuidSecondHalf);
}

// ============================================================================
// Function: ReadUnaligned64 (sub_7A0) - [0x7A0-0x7CE, 47 bytes, wrapper]
// ============================================================================

/**
 * Reads an unaligned 64-bit value from memory.
 *
 * ADDRESS: 0x7A0
 * SIZE:    0x2F (47 bytes), 3 basic blocks, 13 instructions
 * CALLERS: 4 (sub_730/IsHobListGuid x4)
 * CALLS:   1 (DebugAssert if Buffer is NULL)
 *
 * Wraps the BaseLib ReadUnaligned64() function with a NULL pointer check.
 * If Buffer is NULL, triggers a debug 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 memory address.
 *
 * @note This function does NOT perform an actual unaligned load
 *   on modern x64 (which handles misaligned access natively).
 *   It simply dereferences the pointer as UINT64*. The "unaligned"
 *   name reflects the source API (BaseLib ReadUnaligned64) which
 *   is designed for architectures that do not support unaligned
 *   access.
 *
 * @note ASSERT file/line reference: e:\hs\MdePkg\Library\BaseLib\
 *   Unaligned.c, line 192: "Buffer != ((void *) 0)"
 */
UINT64
EFIAPI
ReadUnaligned64 (
  IN CONST VOID  *Buffer
  )
{
  if (Buffer == NULL) {
    DebugAssert (
      "e:\\hs\\MdePkg\\Library\\BaseLib\\Unaligned.c",
      192,
      "Buffer != ((void *) 0)"
      );
  }

  // Read 8 bytes from the given address
  return *(CONST UINT64 *)Buffer;
}

// ============================================================================
// Function: AllocatePool (inline wrapper, part of sub_510)
// ============================================================================

/**
 * Allocates boot services pool memory.
 *
 * @param[in] Size  Allocation size in bytes.
 *
 * @return Pointer to allocated memory, or NULL on failure.
 */
VOID *
EFIAPI
AllocatePool (
  IN UINTN Size
  )
{
  return gBS->AllocatePool (EfiBootServicesData, Size);
}

// ============================================================================
// Function: FreePool (inline wrapper, part of sub_510)
// ============================================================================

/**
 * Frees pool memory previously allocated by AllocatePool().
 *
 * @param[in] Buffer  Pointer to memory to free.
 */
VOID
EFIAPI
FreePool (
  IN VOID *Buffer
  )
{
  gBS->FreePool (Buffer);
}

// ============================================================================
// Function: RegisterIioConfig (sub_43C) - [0x43C-0x509, 207 bytes, complex]
// ============================================================================

/**
 * Registers all IIO configuration protocol instances for this platform.
 *
 * ADDRESS: 0x43C
 * SIZE:    0xCF (207 bytes), 6 basic blocks, 48 instructions
 * CALLERS: 1 (_ModuleEntryPoint)
 * CALLS:   2 (sub_590/DebugPrint, gBS->LocateProtocol + protocol->RegisterConfig x4)
 *
 * This function implements the core purpose of this driver:
 *   1. Print a debug banner identifying the module:
 *      "UBA:IioCfgUpdate-TypeLightningRidgeEXECB2"
 *   2. Locate the UBA board-type protocol via gBS->LocateProtocol()
 *      with protocol GUID at address 0xBF0 (UBA_BOARD_TYPE_PROTOCOL_GUID)
 *   3. If LocateProtocol fails, return the EFI_ERROR status
 *   4. For each of the 4 CPU sockets (IIO instances):
 *      - Call the board-type protocol's registration function
 *        at interface offset 0x10 (RegisterConfig)
 *      - Pass the socket-specific IIO config GUID
 *      - Pass the same UBA_IIO_CFG_UPDATE_PROTOCOL structure (48 bytes)
 *        which contains:
 *        * Signature: "PIIO"
 *        * Version: 1
 *        * TotalSize: 0x0D60
 *        * ConfigTableOffset: 0x3C
 *        * CallbackFunction: ReturnNotFound (pointer)
 *        * ResourceTableOffset: 0x0C60
 *        * ResourceTableSize: 0xFC
 *   5. If any registration call fails, stop and return the error
 *   6. Return EFI_SUCCESS if all 4 registrations succeed
 *
 * The registration function at protocol offset 0x10 has signature:
 *   EFI_STATUS (EFIAPI *)(VOID *This, EFI_GUID *ProtocolGuid,
 *                         VOID *ConfigData, UINT64 ConfigDataSize)
 *
 * @return EFI_SUCCESS     All IIO configurations were registered successfully.
 * @return LocateProtocol error if UBA board-type protocol is not available.
 * @return Registration error if one or more RegisterConfig calls fail.
 *
 * @note The protocol GUIDs for each socket are at addresses:
 *   - Socket 0: 0xBC0 = {6FE6C559-4F35-4111-98E1-332A251512F3}
 *   - Socket 1: 0xBE0 = {0F722F2A-650F-448A-ABB7-04EECD75BB30}
 *   - Socket 2: 0xC00 = {EBD11A00-8C5C-4F71-BB9E-5394032B01F4}
 *   - Socket 3: 0xC20 = {123BD082-3201-465C-B139-0CB8C77208F8}
 *
 * @note The board-type protocol interface is located via gBS->LocateProtocol
 *   at BootServices function offset 0x140 (320 = LocateProtocol).
 *   The interface has the registration function at offset 0x10 (16).
 *
 * @note Each registration passes ConfigDataSize = 48 (0x30) bytes,
 *   which is the size of UBA_IIO_CFG_UPDATE_PROTOCOL.
 */
EFI_STATUS
EFIAPI
RegisterIioConfig (
  VOID
  )
{
  EFI_STATUS              Status;
  UBA_BOARD_TYPE_PROTOCOL *Protocol;
  UINTN                   Index;

  // Print debug banner identifying this platform module
  DebugPrint (DEBUG_INFO, "UBA:IioCfgUpdate-TypeLightningRidgeEXECB2\n");

  // Locate the UBA board-type protocol via gBS->LocateProtocol
  // The protocol GUID is UBA_BOARD_TYPE_PROTOCOL_GUID at 0xBF0
  Status = gBS->LocateProtocol (
    &gUbaBoardTypeProtocolGuid,
    NULL,
    (VOID **)&Protocol
    );

  if (EFI_ERROR (Status)) {
    return Status;
  }

  // Register IIO configuration protocol for each CPU socket
  for (Index = 0; Index < IIO_CFG_UPDATE_PROTOCOL_COUNT; Index++) {
    Status = Protocol->RegisterConfig (
      Protocol,
      &gIioCfgUpdateProtocolGuid[Index],
      (UBA_IIO_CFG_UPDATE_PROTOCOL *)&mIioCfgProtocol,
      sizeof (mIioCfgProtocol)         // 48 bytes
      );

    if (EFI_ERROR (Status)) {
      break;
    }
  }

  return Status;
}

// ============================================================================
// Function: _ModuleEntryPoint (sub_390) - [0x390-0x438, 169 bytes, complex]
// ============================================================================

/**
 * Module entry point for IioCfgUpdateDxeLightningRidgeEXECB2.
 *
 * ADDRESS: 0x390
 * SIZE:    0xA9 (169 bytes), 9 basic blocks, 38 instructions
 * CALLERS: 0 (this is the entry point, called by DXE dispatcher)
 * CALLS:   4 (sub_618/DebugAssert x4, sub_658/GetHobList, sub_43C/RegisterIioConfig)
 *
 * Called by the DXE Dispatcher when this driver is loaded. Performs:
 *   1. Caches UEFI global variables from the provided SystemTable:
 *      - gImageHandle = ImageHandle
 *      - gST = SystemTable
 *      - gBS = SystemTable->BootServices
 *      - gRT = SystemTable->RuntimeServices
 *   2. Validates each pointer is non-NULL via DebugAssert
 *   3. Locates the HOB list from the system configuration table
 *      (required by GetDebugProtocol which checks HOB allocation)
 *   4. Calls RegisterIioConfig() to register IIO configuration
 *      protocols for all 4 CPU sockets
 *
 * The ASSERT checks match the standard UEFI library initialization
 * pattern from UefiBootServicesTableLib and UefiRuntimeServicesTableLib:
 *   - gImageHandle != NULL (UefiBootServicesTableLib.c:51)
 *   - gST != NULL (UefiBootServicesTableLib.c:57)
 *   - gBS != NULL (UefiBootServicesTableLib.c:63)
 *   - gRT != NULL (UefiRuntimeServicesTableLib.c:47)
 *
 * @param[in] ImageHandle  The firmware-allocated handle for this driver image.
 * @param[in] SystemTable  A pointer to the EFI System Table.
 *
 * @return EFI_STATUS from RegisterIioConfig() which returns:
 *   - EFI_SUCCESS if IIO configurations were registered.
 *   - Error code if LocateProtocol or registration fails.
 *
 * @note The HOB list is located via GetHobList() even if the caller
 *   doesn't directly need it, because GetDebugProtocol() (called by
 *   DebugPrint in the debug banner) checks the HOB allocation size.
 *
 * @note This entry point follows the standard UEFI DXE driver pattern:
 *   save handles -> validate -> do work -> return status.
 */
EFI_STATUS
EFIAPI
_ModuleEntryPoint (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE  *SystemTable
  )
{
  EFI_STATUS Status;

  // ==================================================================
  // Step 1: Cache UEFI global variables with NULL pointer validation
  // ==================================================================

  // gImageHandle: handle for this driver image
  gImageHandle = ImageHandle;
  if (gImageHandle == NULL) {
    DebugAssert (
      "e:\\hs\\MdePkg\\Library\\UefiBootServicesTableLib\\UefiBootServicesTableLib.c",
      51,
      "gImageHandle != ((void *) 0)"
      );
  }

  // gST: pointer to the UEFI System Table
  gST = SystemTable;
  if (gST == NULL) {
    DebugAssert (
      "e:\\hs\\MdePkg\\Library\\UefiBootServicesTableLib\\UefiBootServicesTableLib.c",
      57,
      "gST != ((void *) 0)"
      );
  }

  // gBS: pointer to the UEFI Boot Services Table
  gBS = SystemTable->BootServices;
  if (gBS == NULL) {
    DebugAssert (
      "e:\\hs\\MdePkg\\Library\\UefiBootServicesTableLib\\UefiBootServicesTableLib.c",
      63,
      "gBS != ((void *) 0)"
      );
  }

  // gRT: pointer to the UEFI Runtime Services Table
  gRT = SystemTable->RuntimeServices;
  if (gRT == NULL) {
    DebugAssert (
      "e:\\hs\\MdePkg\\Library\\UefiRuntimeServicesTableLib\\UefiRuntimeServicesTableLib.c",
      47,
      "gRT != ((void *) 0)"
      );
  }

  // ==================================================================
  // Step 2: Locate the HOB list (needed by GetDebugProtocol/GetHobList)
  // ==================================================================
  GetHobList (ImageHandle);

  // ==================================================================
  // Step 3: Register IIO configuration protocols for all sockets
  // ==================================================================
  Status = RegisterIioConfig ();

  return Status;
}