/**
 * @file OpromUpdateDxeLightningRidgeEXECB4.h
 *
 * @brief OpromUpdateDxeLightningRidgeEXECB4 - UEFI DXE driver for configuring
 *        PCIe Option ROM (OpROM) update policy on the Lightning Ridge EXEC B4
 *        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 B4 platform. Compared to the EXEC B1/B2/B3
 *   variants, this module is significantly smaller -- it registers a stub
 *   OpROM update callback interface with a single "not supported" callback
 *   (sub_48C returns 0x800000000000000E = EFI_UNSUPPORTED), indicating that
 *   the EXEC B4 platform does not perform any OpROM updates.
 *
 *   The driver performs the following at entry:
 *     1. Locates the UBA board-type protocol for Lightning Ridge EXEC B4
 *        using gBS->LocateProtocol() with GUID E03E0D46-5263-4845-B0A4-58D57B3177E2.
 *     2. Calls the protocol's registration function to install an
 *        OpROM update protocol interface (identified by GUID
 *        CD1F9574-DD03-4196-96AD-4965146F9665).
 *     3. The registered interface contains the signature "PSET", version 1,
 *        and a single callback pointer to sub_48C which returns EFI_UNSUPPORTED.
 *
 * DEPENDENCIES (Protocols consumed):
 *   - UBA LightningRidgeEXECB4 Board-Type Protocol
 *     (GUID: E03E0D46-5263-4845-B0A4-58D57B3177E2)
 *     This protocol is located and used to register the OpROM update config.
 *   - 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.
 *   - DebugLib Protocol
 *     (GUID: 36232936-0E76-31C8-A13A-3AF2FC1C3932)
 *     Used for debug output / assertions.
 *
 * DEPENDENCIES (Protocols produced):
 *   - UBA LightningRidgeEXECB4 OpROM Update Protocol
 *     (GUID: CD1F9574-DD03-4196-96AD-4965146F9665)
 *     Installed via the board-type protocol's registration function with
 *     a stub callback returning EFI_UNSUPPORTED.
 *
 * KEY DIFFERENCES FROM EXEC B1/B2/B3:
 *   - No PCIe configuration tables (no table A/B/C, no slot table)
 *   - No GetConfigA/B/C or SetPcieSlotNumber callbacks
 *   - Only a single stub function registered
 *   - The OpROM update protocol interface block is only 24 bytes (vs 48 bytes)
 *   - The registered configuration simply reports "unsupported" for any operation
 *
 * @note This module is index 0039 in the BIOS FFS and is specific to the
 *       Lightning Ridge EXEC B4 platform.
 */

#ifndef _OPROM_UPDATE_DXE_LIGHTNING_RIDGE_EXEC_B4_H_
#define _OPROM_UPDATE_DXE_LIGHTNING_RIDGE_EXEC_B4_H_

#include "../uefi_headers/Uefi.h"

// ============================================================================
// GUID Definitions
// ============================================================================

///
/// UBA_LIGHTNING_RIDGE_EXEC_B4_BOARD_TYPE_PROTOCOL_GUID
/// Protocol GUID used with gBS->LocateProtocol() to obtain the UBA board-type
/// protocol interface for the Lightning Ridge EXEC B4 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_B4_BOARD_TYPE_PROTOCOL_GUID \
  { 0xE03E0D46, 0x5263, 0x4845, { 0xB0, 0xA4, 0x58, 0xD5, 0x7B, 0x31, 0x77, 0xE2 } }

///
/// OPROM_UPDATE_PROTOCOL_REGISTRATION_GUID
/// GUID passed to the UBA protocol registration function to identify the
/// OpROM update configuration interface being registered.
/// {CD1F9574-DD03-4196-96AD-4965146F9665}
///
#define OPROM_UPDATE_PROTOCOL_REGISTRATION_GUID \
  { 0xCD1F9574, 0xDD03, 0x4196, { 0x96, 0xAD, 0x49, 0x65, 0x14, 0x6F, 0x96, 0x65 } }

///
/// DEBUG_LIB_PROTOCOL_GUID
/// GUID for the DebugLib protocol used by this module for debug output
/// and assertion handling.
/// {36232936-0E76-31C8-A13A-3AF2FC1C3932}
///
#define DEBUG_LIB_PROTOCOL_GUID \
  { 0x36232936, 0x0E76, 0x31C8, { 0xA1, 0x3A, 0x3A, 0xF2, 0xFC, 0x1C, 0x39, 0x32 } }

///
/// 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 } }

// ============================================================================
// Constants
// ============================================================================

///
/// 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

///
/// Platform type encoded in CMOS register 0x4B:
///   1 = Lightning Ridge EXEC B1/B4 variant
///
#define OPROM_PLATFORM_TYPE_LIGHTNING_RIDGE  1

///
/// Debug output level masks.
///
#define DEBUG_CMOS_MASK                     0x80

///
/// Signature of the OpROM update protocol interface.
/// "PSET" (little-endian: 0x54455350).
///
#define OPROM_UPDATE_PROTOCOL_SIGNATURE     "PSET"

///
/// Size of the OpROM update protocol interface data block (in bytes).
///
#define OPROM_UPDATE_PROTOCOL_DATA_SIZE     24

///
/// Return value for "unsupported" OpROM operation.
/// This is the status returned by the stub callback.
///
#define OPROM_UNSUPPORTED                   0x800000000000000EULL

// ============================================================================
// Structure Definitions
// ============================================================================

///
/// OPROM_UPDATE_PROTOCOL_INTERFACE
/// Minimal stub protocol interface registered by this driver.
///
/// Unlike the EXEC B1/B2/B3 variants which register a full 4-callback
/// structure (0x38 bytes), the EXEC B4 variant registers only a 24-byte
/// stub interface. It contains:
///   - "PSET" signature (4 bytes)
///   - Version field (4 bytes)
///   - Single callback pointer to sub_48C (8 bytes)
///   - Second copy of the same pointer or reserved (8 bytes)
///
/// The single callback returns EFI_UNSUPPORTED (0x800000000000000E),
/// indicating that OpROM updates are not supported on this platform.
///
typedef struct {
  ///
  /// Signature "PSET" identifying this as an OpROM update protocol.
  ///
  UINT32  Signature;  // "PSET" = 0x54455350

  ///
  /// Version of this interface (1).
  ///
  UINT32  Version;

  ///
  /// Callback function pointer.
  /// Returns EFI_UNSUPPORTED for all operations.
  ///
  /// @return EFI_UNSUPPORTED (0x800000000000000E).
  ///
  EFI_STATUS
  (*OpromOperation) (
    VOID
    );

  ///
  /// Reserved or second copy of the callback pointer.
  /// In the binary, this contains the same value as the first pointer.
  ///
  UINT64  Reserved;
} OPROM_UPDATE_PROTOCOL_STUB_INTERFACE;

///
/// UBA_OPROM_UPDATE_BOARD_TYPE_PROTOCOL
///
/// The protocol interface obtained via gBS->LocateProtocol() using the GUID
/// UBA_LIGHTNING_RIDGE_EXEC_B4_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
  ///                            (OPROM_UPDATE_PROTOCOL_REGISTRATION_GUID).
  /// @param[in] ConfigData      Pointer to the OPROM_UPDATE_PROTOCOL_STUB_INTERFACE
  ///                            structure.
  /// @param[in] ConfigDataSize  Size of the configuration data in bytes (24).
  ///
  /// @return EFI_STATUS.
  ///
  EFI_STATUS
  (EFIAPI *RegisterOpromUpdateConfig) (
    IN VOID                                  *This,
    IN EFI_GUID                              *ProtocolGuid,
    IN OPROM_UPDATE_PROTOCOL_STUB_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 OpromUpdateDxeLightningRidgeEXECB4.
 *
 * 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 B4 board-type protocol, and registers the OpROM update
 * stub configuration 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
  );

/**
 * Stub OpROM operation callback.
 *
 * This is the only callback registered by the EXEC B4 platform.
 * It returns EFI_UNSUPPORTED (0x800000000000000E), indicating that
 * OpROM updates are not supported on this platform variant.
 *
 * @return EFI_UNSUPPORTED  Always returns the unsupported status.
 */
EFI_STATUS
OpromOperationUnsupported (
  VOID
  );

/**
 * Locates the DebugLib/OpROM protocol interface.
 *
 * Allocates pool memory, initializes the OpROM update protocol stub interface
 * structure, resolves the DebugLib protocol via gBS->LocateProtocol() using
 * GUID DEBUG_LIB_PROTOCOL_GUID (36232936-0E76-31C8-A13A-3AF2FC1C3932),
 * and caches the result.
 *
 * Results are cached in the global variable gOpromUpdateProtocol.
 *
 * @return Pointer to the OpROM update protocol interface,
 *         or NULL if pool allocation or protocol location fails.
 */
VOID *
GetDebugLibProtocol (
  VOID
  );

/**
 * Debug print function (wraps the UEFI DebugLib protocol).
 *
 * Resolves the DebugLib protocol interface via GetDebugLibProtocol()
 * and calls its output function 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 B4
 *   - 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.
 *
 * @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 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.
 *
 * @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
  );

#endif /* _OPROM_UPDATE_DXE_LIGHTNING_RIDGE_EXEC_B4_H_ */