/** @file
  EnglishDxe -- UEFI Unicode Collation English DXE Driver Header

  This DXE driver produces the EFI_UNICODE_COLLATION_PROTOCOL (and optionally
  EFI_UNICODE_COLLATION2_PROTOCOL) for English-language FAT file system string
  operations. It implements case conversion, string collation (pattern matching
  with wildcards * and ?, and character ranges [...]), and FAT-format string
  conversion.

  The driver initializes two 256-byte translation tables (byte_10A0 for
  upper-casing, byte_12A0 for lower-casing) and a character-classification table
  (byte_1398) at startup. These tables map each byte value 0x00-0xFF through
  case conversion and identify which characters are "printable" alphanumeric
  characters (for FAT file name legal character checks).

  Source: MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/
  Source file: UnicodeCollationEng.c
  Build: VS2015, DEBUG, X64
  PDB: EnglishDxe.pdb

Copyright (c) HR650X BIOS Decompilation Project
**/

#ifndef __ENGLISH_DXE_H__
#define __ENGLISH_DXE_H__

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

//
// ---------------------------------------------------------------------------
// GUIDs
// ---------------------------------------------------------------------------

///
/// {1D85CD7F-F43D-11D2-9A0C-0090273FC14D}
/// EFI_UNICODE_COLLATION_PROTOCOL_GUID
/// Defined in MdePkg/Protocol/UnicodeCollation.h
///
#define EFI_UNICODE_COLLATION_PROTOCOL_GUID \
  { 0x1D85CD7F, 0xF43D, 0x11D2, { 0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D } }

///
/// {7739F24C-93D7-11D4-9A3A-0090273FC14D}
/// EFI_UNICODE_COLLATION2_PROTOCOL_GUID
/// Defined in MdePkg/Protocol/UnicodeCollation.h
///
#define EFI_UNICODE_COLLATION2_PROTOCOL_GUID \
  { 0x7739F24C, 0x93D7, 0x11D4, { 0x9A, 0x3A, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D } }

///
/// {36232936-0E76-31C8-A13A-3AF2FC1C3932}
/// gEfiHobListGuid -- used to locate the HOB list via System Table
/// ConfigurationTable.
///
#define EFI_HOB_LIST_GUID \
  { 0x36232936, 0x0E76, 0x31C8, { 0xA1, 0x3A, 0x3A, 0xF2, 0xFC, 0x1C, 0x39, 0x32 } }

//
// ---------------------------------------------------------------------------
// Protocol Structures
// ---------------------------------------------------------------------------

///
/// EFI_UNICODE_COLLATION_PROTOCOL
/// Provides services for Unicode string case conversion, collation,
/// and FAT file name matching.
///
typedef struct _EFI_UNICODE_COLLATION_PROTOCOL {
  ///
  /// Converts all Unicode characters in a string to their upper-case equivalents.
  /// @param This       Pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  /// @param String     The string to convert to upper case.
  ///
  VOID (EFIAPI *StriUpper)(
    IN struct _EFI_UNICODE_COLLATION_PROTOCOL *This,
    IN OUT CHAR16 *String
  );

  ///
  /// Converts all Unicode characters in a string to their lower-case equivalents.
  /// @param This       Pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  /// @param String     The string to convert to lower case.
  ///
  VOID (EFIAPI *StriLower)(
    IN struct _EFI_UNICODE_COLLATION_PROTOCOL *This,
    IN OUT CHAR16 *String
  );

  ///
  /// Performs a case-insensitive comparison of two strings, supporting
  /// wildcard pattern matching.
  /// @param This       Pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  /// @param S1         First string (the string to compare).
  /// @param S2         Second string (may contain wildcards *, ?, [...]).
  /// @retval TRUE      The strings match.
  /// @retval FALSE     The strings do not match.
  ///
  BOOLEAN (EFIAPI *StriColl)(
    IN struct _EFI_UNICODE_COLLATION_PROTOCOL *This,
    IN CHAR16 *S1,
    IN CHAR16 *S2
  );

  ///
  /// Converts an 8-bit ASCII string to a FAT-format Unicode string.
  /// @param This       Pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  /// @param FatSize    Size of the Fat buffer in bytes.
  /// @param String     8-bit ASCII input string.
  /// @param FatOutput  Output buffer for FAT-format Unicode string.
  ///
  BOOLEAN (EFIAPI *StrToFat)(
    IN struct _EFI_UNICODE_COLLATION_PROTOCOL *This,
    IN UINTN FatSize,
    IN CHAR8 *String,
    OUT CHAR16 *FatOutput
  );

  ///
  /// Converts a Unicode string to a FAT file name, replacing characters that
  /// are not legal in FAT file names with '_' (underscore).
  /// @param This       Pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  /// @param String     Unicode input string.
  /// @param FatSize    Size of the output buffer.
  /// @param FatOutput  Output buffer for FAT file name.
  ///
  BOOLEAN (EFIAPI *StrToFat1)(
    IN struct _EFI_UNICODE_COLLATION_PROTOCOL *This,
    IN CHAR16 *String,
    IN UINTN FatSize,
    OUT CHAR8 *FatOutput
  );

  ///
  /// The supported language code for this protocol instance (e.g. "eng", "en").
  ///
  CHAR8 *SupportedLanguages;
} EFI_UNICODE_COLLATION_PROTOCOL;

//
// ---------------------------------------------------------------------------
// Global Data
// ---------------------------------------------------------------------------

///
/// Upper-case translation table (256 bytes at 0x10A0).
/// Maps each byte value to its upper-case equivalent.
/// byte_10A0[c] = upper-case of character c (for c < 0x100).
/// byte_10A0[c + 256] = flags byte (bit 0 set = legal FAT file name char).
///
extern UINT8 byte_10A0[];

///
/// Lower-case translation table (256 bytes at 0x12A0).
/// Maps each byte value to its lower-case equivalent.
///
extern UINT8 byte_12A0[];

///
/// Priority/classification table (256 bytes at 0x1398).
/// Stores the sort priority for ASCII-range characters used during
/// FAT directory ordering. Initialized during entry point.
///
extern UINT8 byte_1398[];

///
/// Debug output device protocol pointer, cached after first lookup via
/// gEfiHobListGuid configuration table entry. Used by DebugAssert/DebugPrint.
///
extern UINT64 qword_1088;

///
/// Cached pointer to the HOB list, obtained from System Table configuration
/// table during entry.
///
extern UINT64 qword_1090;

//
// ---------------------------------------------------------------------------
// Function Prototypes
// ---------------------------------------------------------------------------

///
/// Driver entry point. Called by ModuleEntryPoint after UEFI boot services
/// and runtime services library initialization.
///
/// Initializes case-conversion tables (byte_10A0, byte_12A0, byte_1398)
/// for ASCII-range characters, then installs the EFI_UNICODE_COLLATION_PROTOCOL
/// on a new handle.
///
/// @param ImageHandle     The firmware allocated handle for the EFI image.
/// @param SystemTable     A pointer to the EFI System Table.
///
/// @retval EFI_SUCCESS    The protocol was installed successfully.
/// @retval !EFI_SUCCESS   Protocol installation failed.
///
EFI_STATUS
EFIAPI
UnicodeCollationEngEntryPoint(
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE *SystemTable
);

///
/// Converts a string to upper case using the byte_10A0 translation table.
/// For characters > 0xFF, leaves them unchanged.
///
/// @param This    Pointer to the protocol instance.
/// @param String  Null-terminated Unicode string to convert.
///
/// @return The last non-zero character processed, or 0xFF if the string
///         contained only characters > 0xFF.
///
UINTN
EFIAPI
EngStriUpper(
  IN EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN OUT CHAR16 *String
);

///
/// Converts a string to lower case using the byte_12A0 translation table.
/// For characters > 0xFF, leaves them unchanged.
///
/// @param This    Pointer to the protocol instance.
/// @param String  Null-terminated Unicode string to convert.
///
/// @return The last non-zero character processed, or 0xFF if the string
///         contained only characters > 0xFF.
///
UINTN
EFIAPI
EngStriLower(
  IN EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN OUT CHAR16 *String
);

///
/// Case-insensitive string comparison with wildcard support.
/// Supports:
///   *  -- Matches zero or more characters
///   ?  -- Matches any single character
///   [...] -- Character range (e.g., [a-z], [abc])
///   [!...] -- Negated character range
///
/// @param This  Pointer to the protocol instance.
/// @param S1    String to compare (no wildcards expected).
/// @param S2    Pattern (may contain wildcards).
///
/// @retval TRUE   S1 matches the pattern S2.
/// @retval FALSE  S1 does not match S2.
///
BOOLEAN
EFIAPI
EngStriColl(
  IN EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN CHAR16 *S1,
  IN CHAR16 *S2
);

///
/// Converts an ASCII string to a FAT-format Unicode string by simple
/// byte-to-word expansion.
///
/// @param This      Pointer to the protocol instance.
/// @param FatSize   Size of the output buffer in bytes.
/// @param String    8-bit ASCII input string.
/// @param FatOutput Output buffer for Unicode result.
///
/// @return The last character copied, or 0 on empty input.
///
CHAR8
EFIAPI
EngStrToFat(
  IN EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN UINTN FatSize,
  IN CHAR8 *String,
  OUT CHAR16 *FatOutput
);

///
/// Converts a Unicode string to a FAT file name (8.3 format).
/// Dots and spaces are skipped; printable alphanumeric characters are
/// lower-cased; all other characters are replaced with '_' (underscore).
///
/// @param This      Pointer to the protocol instance.
/// @param String    Unicode input string.
/// @param FatSize   Size of the output buffer.
/// @param FatOutput Output buffer for the FAT file name.
///
/// @return 0 if all characters were valid FAT characters, 1 if any
///         replacements with '_' were made.
///
CHAR8
EFIAPI
EngMetaiMatch(
  IN EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN CHAR16 *String,
  IN UINTN FatSize,
  OUT CHAR8 *FatOutput
);

///
/// Retrieves the debug output device (a protocol located via the HOB list).
/// Results are cached in qword_1088 after the first successful lookup.
///
/// @return Pointer to the debug output device interface, or NULL if not found.
///
VOID *
GetDebugOutputDevice(
  VOID
);

///
/// Debug assertion handler. Reads the CMOS diagnostic output device
/// configuration (CMOS index 0x4B) to determine where to send assertion
/// output. Calls the debug output device's assertion handler if the
/// error level matches.
///
/// @param FileName     Source file name of the assertion.
/// @param LineNumber   Line number of the assertion.
/// @param Description  Assertion description string.
///
VOID
EFIAPI
DebugAssert(
  IN CONST CHAR8 *FileName,
  IN UINTN LineNumber,
  IN CONST CHAR8 *Description
);

///
/// Debug print function. Formats and sends a debug message through the
/// debug output device.
///
/// @param ErrorLevel  Debug error level mask.
/// @param Format      Format string.
/// @param ...         Variable arguments for format string.
///
VOID
EFIAPI
DebugPrint(
  IN UINTN ErrorLevel,
  IN CONST CHAR8 *Format,
  ...
);

///
/// Locates the HOB (Hand-Off Block) list from the UEFI System Table
/// configuration table. Searches for the gEfiHobListGuid entry in
/// SystemTable->ConfigurationTable[].
///
/// Results are cached in qword_1090 after the first successful lookup.
///
/// @return Pointer to the start of the HOB list, or NULL if not found.
///
VOID *
GetHobList(
  VOID
);

///
/// Reads an unaligned 64-bit value from memory. Used by EDK2 BaseLib.
/// If Buffer is NULL, triggers a debug assertion.
///
/// @param Buffer  Pointer to the (potentially unaligned) 64-bit value.
///
/// @return The 64-bit value read from memory.
///
UINT64
EFIAPI
ReadUnaligned64(
  IN CONST UINT64 *Buffer
);

///
/// Checks whether a protocol identified by its GUID is already installed
/// by comparing the GUID pointed to by Buffer to a reference GUID.
///
/// Used during HOB list lookup to match configuration table entries.
///
/// @param a1      Unused context parameter (reserved).
/// @param Buffer  Pointer to a configuration table entry (EFI_CONFIGURATION_TABLE).
///
/// @retval TRUE   The GUIDs match (protocol is installed).
/// @retval FALSE  The GUIDs do not match.
///
BOOLEAN
EFIAPI
IsProtocolInstalled(
  IN UINTN a1,
  IN EFI_CONFIGURATION_TABLE *Buffer
);

#endif /* __ENGLISH_DXE_H__ */