/**
 * @file SecFlashUpdDXE.h
 * @brief Secure Flash Update DXE Driver - Header
 *
 * Handles authenticated BIOS updates via UEFI capsule update mechanism.
 * Registers a Flash_Ready_To_Lock callback that finds and processes
 * capsule update data from UEFI Runtime Services variables.
 *
 * Source: HR650X BIOS, index 0063
 * Module: SecFlashUpdDXE.efi
 * Image size: 0x1e60 (7.5 KB)
 * Arch: x86_64
 * Compiled from: AmiModulePkg/SecureFlash/SecFlashUpd/SecFlashUpdDxe.c
 */

#ifndef __SECFLASHUPDDXE_H__
#define __SECFLASHUPDDXE_H__

#include <Uefi.h>
#include <Protocol/DxeSmmReadyToLock.h>
#include <Guid/EventGroup.h>
#include <Guid/HobList.h>
#include <Protocol/Pcd.h>
#include <Guid/CapsuleVendor.h>

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

/// AMI Flash Update Protocol GUID
/// Used to communicate with AMI SecureFlash infrastructure
#define AMI_FLASH_UPD_PROTOCOL_GUID \
  { 0x974231D5, 0xED4B, 0x44D1, { 0x88, 0x70, 0xCE, 0x51, 0x5C, 0xC1, 0x4D, 0x68 } }

/// Capsule Update Data Variable GUID
/// Used to locate capsule payload in UEFI variables
#define CAPSULE_UPDATE_DATA_VARIABLE_GUID \
  { 0x711C703F, 0xC285, 0x4B10, { 0xA3, 0xB0, 0x36, 0xEC, 0xBD, 0x3C, 0x8B, 0xE2 } }

/// DXE SMM Ready To Lock Protocol GUID
#define DXE_SMM_READY_TO_LOCK_PROTOCOL_GUID \
  { 0x49D34AE7, 0x9454, 0x4551, { 0x8F, 0x71, 0x46, 0x7D, 0x8C, 0x0E, 0x4E, 0xF5 } }

/// Event Ready To Boot GUID - trigger group for ReadyToBoot event
#define EVENT_READY_TO_BOOT_GUID \
  { 0x60FF8964, 0xE906, 0x41D0, { 0xAF, 0xED, 0xF2, 0x41, 0xE9, 0x74, 0xE0, 0x8E } }

/// HOB List GUID
#define HOB_LIST_GUID \
  { 0x7739F24C, 0x93D7, 0x11D4, { 0x9A, 0x3A, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D } }

/// PCD Protocol GUID
#define PCD_PROTOCOL_GUID \
  { 0x11B34006, 0xD85B, 0x4D0A, { 0xA2, 0x90, 0xD5, 0xA7, 0x13, 0x10, 0xEF, 0x07 } }

//=============================================================================
// Variable and Protocol Names (Wide Strings)
//=============================================================================

#define AMI_FLASH_UPD_VARIABLE_NAME  L"AmiFlashUpd"
#define CAPSULE_UPDATE_DATA_NAME     L"CapsuleUpdateData"

//=============================================================================
// Global Variables
//=============================================================================

extern EFI_HANDLE           gImageHandle;
extern EFI_SYSTEM_TABLE    *gST;
extern EFI_BOOT_SERVICES   *gBS;
extern EFI_RUNTIME_SERVICES *gRT;
extern VOID                *gHobList;
extern PCD_PROTOCOL        *mPcd;

//=============================================================================
// Function Declarations
//=============================================================================

/**
 * Entry point for SecFlashUpdDXE driver.
 *
 * Initializes global UEFI table pointers, registers the Flash_Ready_To_Lock
 * callback, and publishes the event group pointer.
 *
 * @param[in] ImageHandle  Handle of this EFI image
 * @param[in] SystemTable  Pointer to EFI System Table
 * @return EFI_STATUS
 */
EFI_STATUS
EFIAPI
ModuleEntryPoint (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE *SystemTable
  );

/**
 * Initializes UEFI boot/runtime services global pointers.
 *
 * Sets gImageHandle, gST, gBS, gRT from the system table,
 * calls HobList initialization, then publishes the event group.
 *
 * @param[in] ImageHandle  Handle of this EFI image
 * @return 0 on success
 */
EFI_STATUS
SecFlashUpdDriverInit (
  IN EFI_HANDLE ImageHandle
  );

/**
 * Creates the ReadyToBoot event and registers callback.
 *
 * Creates an event in the EFI_EVENT_GROUP_READY_TO_BOOT group,
 * then installs the DXE_SMM_READY_TO_LOCK protocol.
 *
 * @param[in] ImageHandle  Handle of this EFI image
 * @param[in] SystemTable  Pointer to EFI System Table
 * @return EFI_STATUS
 */
EFI_STATUS
SecFlashUpdRegisterCallbacks (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE *SystemTable
  );

/**
 * Flash_Ready_To_Lock notification callback.
 *
 * Called when the system is about to lock flash. Iterates through
 * "CapsuleUpdateData" (and "CapsuleUpdateData0", "CapsuleUpdateData1", ...)
 * UEFI variables, locates the first valid capsule payload, and triggers
 * the secure flash update process.
 *
 * @param[in] Event   Event that triggered this callback
 * @param[in] Context Not used
 * @return EFI_STATUS
 */
EFI_STATUS
EFIAPI
FlashReadyToLockCallback (
  IN EFI_EVENT  Event,
  IN VOID      *Context
  );

/**
 * Retrieves the HOB list pointer.
 *
 * Locates the HOB list by searching the system configuration table for
 * the EFI_HOB_LIST_GUID entry, or falls back to the BootServices
 * HOB protocol pointer.
 *
 * @return Pointer to the HOB list, or NULL if not found
 */
VOID *
GetHobList (
  VOID
  );

//=============================================================================
// Print / Debug Helpers (from UEFI BaseLib and DebugLib)
//=============================================================================

/**
 * Debug print function - prints message if debug level matches.
 *
 * @param[in] ErrorLevel  Debug error level mask
 * @param[in] Format      Format string
 * @param[in] ...          Variable arguments
 */
VOID
DebugPrint (
  IN UINTN       ErrorLevel,
  IN CONST CHAR8 *Format,
  ...
  );

/**
 * Assertion failure handler.
 *
 * Called when an ASSERT condition is FALSE. Prints the filename,
 * line number, and assertion expression.
 *
 * @param[in] FileName    Source file name
 * @param[in] LineNumber   Line number of the assertion
 * @param[in] Description  Assertion expression text
 */
VOID
EFIAPI
AssertHandler (
  IN CONST CHAR8 *FileName,
  IN UINTN        LineNumber,
  IN CONST CHAR8 *Description
  );

/**
 * Converts an EFI_STATUS code to a human-readable string.
 *
 * @param[in] Status  EFI status value to convert
 * @return Pointer to a static string describing the status
 */
CONST CHAR8 *
StatusToString (
  IN EFI_STATUS Status
  );

/**
 * Converts a value to a string representation in the given base.
 *
 * @param[in]  Value  Value to convert
 * @param[out] Buffer Output buffer
 * @param[in]  Base   Numeric base (10 or 16)
 * @param[in]  Signed If TRUE, treat as signed value
 * @return Pointer to the last character written
 */
CHAR8 *
ValueToString (
  IN  INT64   Value,
  OUT CHAR8  *Buffer,
  IN  UINTN   Base,
  IN  BOOLEAN Signed
  );

/**
 * Parses a decimal or hexadecimal integer from a wide string.
 *
 * @param[in]  String    Pointer to the wide string to parse
 * @param[out] EndString On return, points past the last parsed character
 * @param[in]  Base      Numeric base (defaults to decimal if 0)
 * @return Parsed integer value
 */
UINTN
ParseInteger (
  IN  CONST CHAR16 *String,
  OUT CONST CHAR16 **EndString,
  IN  INTN          Base
  );

/**
 * Unicode (wide) string formatting function - vsnprintf equivalent.
 *
 * Formats a wide string with the given format string and variable
 * argument list, writing up to 'MaxSize' characters to 'Buffer'.
 *
 * @param[out] Buffer   Output wide string buffer
 * @param[in]  MaxSize  Maximum number of wide characters to write
 * @param[in]  Format   Format string (supports %s, %S, %d, %x, %X, %08x, %r, %g, etc.)
 * @param[in]  VaList   Variable argument list
 * @return Number of wide characters written (excluding null terminator)
 */
UINTN
UnicodeVSPrint (
  OUT CHAR16       *Buffer,
  IN  UINTN         MaxSize,
  IN  CONST CHAR16 *Format,
  IN  VA_LIST       VaList
  );

/**
 * Unicode string formatting wrapper (sprintf equivalent).
 *
 * @param[out] Buffer   Output wide string buffer
 * @param[in]  MaxSize  Maximum number of wide characters to write
 * @param[in]  Format   Format string
 * @param[in]  ...      Variable arguments
 * @return Number of wide characters written
 */
UINTN
UnicodeSPrint (
  OUT CHAR16       *Buffer,
  IN  UINTN         MaxSize,
  IN  CONST CHAR16 *Format,
  ...
  );

/**
 * Reads a 64-bit unaligned value from memory.
 *
 * @param[in] Buffer  Pointer to the unaligned buffer (must not be NULL)
 * @return 64-bit value read from the buffer
 */
UINT64
ReadUnaligned64 (
  IN CONST VOID *Buffer
  );

/**
 * Checks whether a HOB entry matches a specific GUID.
 *
 * Compares the first 16 bytes of a HOB entry against a GUID stored
 * as two 8-byte halves at fixed addresses.
 *
 * @param[in] HobEntry  Pointer to the HOB entry to check
 * @return TRUE if the HOB entry matches, FALSE otherwise
 */
BOOLEAN
IsHobGuidMatch (
  IN CONST VOID *HobEntry
  );

#endif /* __SECFLASHUPDDXE_H__ */