LegacyRegion2 DXE Driver

Overview

The LegacyRegion2 DXE driver manages read/write/execute permissions for the
legacy memory region (0xC0000 - 0xFFFFF) on Intel Purley/Purley Refresh
platforms. It controls PAM (Programmable Attribute Map) registers in the
chipset's PCI-to-LPC bridge to enable or disable decode of legacy VGA BIOS
and option ROM regions.

This driver is the LegacyRegion2 protocol producer. It consumes the
LegacyRegion protocol (from the CSM / Legacy Platform Driver) to access
the low-level PAM I/O ports, and publishes the LegacyRegion2 protocol
with enhanced locking semantics over the original LegacyRegion interface.

File Information

Memory Layout

GUIDs Discovered

Region Descriptor Table

The PAM attribute map divides the 0xC0000-0xFFFFF range into 13 sub-regions:

Type values map to PAM register bit positions (each 2-bit field = read-enable + write-enable).

PAM Attribute Bit Layout

Each PAM register packs 4 region attributes (types N..N+3) into a 32-bit value:

Bit      31 30  29 28  27 26  25 24  ...  7 6  5 4  3 2  1 0
Field    [A3]    [A2]    [A1]    [A0]
         2 bits  2 bits  2 bits  2 bits

Each 2-bit field:

• Bit 0: Read Enable
• Bit 1: Write Enable

Types 0-6: attributes in the "read port" PAM register (I/O 0x30000C0).
Types 7-12: attributes in the "write port" PAM register (I/O 0x30000C4).

Protocol Flow

ModuleEntryPoint (0x350)

  +-> Save gImageHandle, gST, gBS, gRT (lib constructors)

  +-> GetHobList (0xAC4)
     +-> Scan gST->ConfigurationTable for HOB_LIST_GUID
     +-> Return cached HOB list pointer

  +-> WheaSupportEntry (0x408)
        +-> gBS->LocateProtocol(LEGACY_REGION_PROTOCOL)
        +-> gBS->LocateProtocol(LEGACY_REGION2_PROTOCOL)
        +-> Read gPamCapabilities
        +-> InstallMultipleProtocolInterfaces(LEGACY_REGION2_PROTOCOL)

Function Map (Original to Renamed)

Key Functions Detail

WheaSupportEntry (0x408)

Driver initialisation. Locates LegacyRegion and LegacyRegion2 protocols,
reads PAM capabilities from the LegacyRegion2 protocol's internal state,
builds the protocol function table, and installs it.

ProgramPamRegisters (0x594)

The core PAM programming routine. Iterates the 13-entry region descriptor
table, detects overlaps with the requested range, reads current PAM register
values via the LegacyRegion protocol's I/O abstractions, modifies the 2-bit
attribute fields, and writes them back. Handles both "low" (types 0-6) and
"high" (types 7-12) PAM registers with bit position mapping.

LegacyRegion2Decode (0x898)

Validates that [StartAddress, StartAddress+Length) falls within 0xC0000-0xFFFFF.
Returns EFI_INVALID_PARAMETER if the range extends beyond these boundaries.

LegacyRegion2Program (0x8BC)

Programs PAM attributes for the given range. Checks LegacyRegion2 internal
write-disable state (at offsets +0x06F4 and +0x06F1) to decide whether to
force write-enable. Delegates to ProgramPamRegisters.

LegacyRegion2ProgramLock (0x930)

Like Program but always passes LegacyDecode=2 (override). Checks the same
write-disable state before calling ProgramPamRegisters.

GetHobList (0xAC4)

Scans the System Table's Configuration Table for an entry whose VendorGuid
matches {7739F24C-93D7-11D4-9A3A-0090273FC14D}. Returns the associated
VendorTable pointer, which is the HOB list used by DxeHobLib.

ReadUnaligned64 (0xC0C)

BaseLib helper: reads 8 bytes from any address (may be unaligned).

DebugAssert / DebugAssertPrint (0xA84, 0x9FC)

Debug library wrappers. DebugAssertPrint checks CMOS register 0x4B for
platform type and routes to the appropriate debug output.

Global Variables

Strings Referenced

All strings reside in .rdata:

Call Graph

ModuleEntryPoint (0x350)

  +-> DebugAssert (0xA84)  [called for each NULL check]
     +-> GetHobListCache (0x97C) [lazy init]

  +-> GetHobList (0xAC4)
     +-> IsHobListConfigEntry (0xB9C)
     |     +-> ReadUnaligned64 (0xC0C) [x4]
     +-> DebugAssertPrint (0x9FC)
     +-> DebugAssert (0xA84)

  +-> WheaSupportEntry (0x408)
        +-> DebugAssertPrint (0x9FC)
     +-> GetHobListCache (0x97C)
        +-> DebugAssert (0xA84)
        +-> gBS->LocateProtocol (x2)
        +-> gBS->InstallMultipleProtocolInterfaces

Import Table (IAT)

Dependencies

• EFI_LEGACY_REGION_PROTOCOL -- provided by CSM/LegacyPlatform driver
• EFI_LEGACY_REGION2_PROTOCOL -- provided by SMM/other driver (for capabilities)
• UefiBootServicesTableLib -- gImageHandle, gST, gBS globals
• UefiRuntimeServicesTableLib -- gRT global
• DxeHobLib -- HOB list access via configuration table
• BaseLib -- ReadUnaligned64

Notes

1. The HOB list GUID {7739F24C-93D7-11D4-9A3A-0090273FC14D} is not a standard
   UEFI specification GUID (standard is gEfiDxeServicesTableGuid). This is a
   platform-specific GUID published by the DXE firmware during boot.

2. The driver contains embedded CmosDebugLib logic that reads CMOS register
   0x4B through I/O ports 0x70/0x71 to determine platform type (IPMI/BMC mode)
   before routing debug output.

3. PAM register ports 0x30000C0 and 0x30000C4 are chipset-specific PCIe
   configuration space registers in the P2SB (Primary-to-Sideband) bridge.

4. The original source file path indicates this is from
   PurleyPlatPkg\Legacy\Dxe\LegacyRegion\LegacyRegion.c -- the single source
   file builds both the LegacyRegion (SMM) and LegacyRegion2 (DXE) drivers
   via compile-time flags.

5. All assertion strings reference EDK2 MdePkg library paths, confirming
   this uses standard EDK2 DebugLib, BaseLib, and HobLib implementations
   with PurleyPlatPkg-specific platform overrides.