PiSmmCore Module

Overview

UEFI SMM Core driver -- the SMM equivalent of the DXE Core. Provides the
EFI_SMM_SYSTEM_TABLE2 (SMST) protocol services consumed by all other SMM
drivers. Responsible for SMI dispatch, SMM driver loading/resolution via
DEPEX, SMRAM pool/page allocation, and the SMM protocol handle database.
AMI additions include platform-specific SMI hooks, communication buffer
validation, and PCH RAS policy integration.

Address Range

0x2C0 - 0xB900 (46,208 bytes .text, 167 functions)
Source files compiled into this module:

• MdeModulePkg/Core/PiSmmCore/: PiSmmCore.c, Dispatcher.c, Handle.c, Smi.c,
  Page.c, Pool.c, Notify.c, Locate.c, MemoryAttributesTable.c
• AmiModulePkg/Library/SmmCoreAmiBufferValidationLib/
• PurleyPlatPkg/Override/MdeModulePkg/Library/SmmCorePlatformHookLib/
• MdeModulePkg/Library/SmmCorePerformanceLib/
• MdePkg/Library/: BaseLib, BasePrintLib, BaseMemoryLibRepStr,
  BaseDebugLibSerialPort, BasePeCoffLib, BaseCacheMaintenanceLib,
  SmmPciExpressLib
• MdeModulePkg/Library/PiSmmCoreMemoryAllocationLib/

Key Functions

Entry Points (Public API)

The following are called from outside the module (SMST function dispatch table):

• 0x3C98 SmiHandlerRegister: Register a handler for a SMI GUID
• 0x3B34 SmiHandlerInvoke: Invoke handlers for a SMI GUID (walk linked list)
• 0x41F4 SmmInstallProtocolInterface: Install protocol on a handle
• 0x48F0 SmmHandleProtocol: Get protocol interface from a handle
• 0x4A84 SmmRegisterProtocolNotify: Register for protocol install notification
• 0x4C68 SmmLocateHandle: Find handles supporting a protocol
• 0x4F80 SmmAllocatePool: Allocate from SMRAM pool
• 0x5100 SmmFreePool: Free SMRAM pool allocation
• 0x5818 InternalFreePages: Free page-aligned SMRAM

The following are internal entry points:

• 0x454 _ModuleEntryPoint (PE/COFF entry, called by DXE IPL)
• 0x34C0 SmmEntryPointWrapper (registered as root SMI handler in SMST)
• 0x2620 SmmMemoryAttributesTableCallback (registered as EndOfDxe SMI handler)
• 0x90B4 SmmAmiBufferValidationLibInit (called from SmmMain)

Internal Helpers

• 0x79A0 InternalAllocatePool: Allocates pool memory with POOL_HEADER/POOL_TAIL management.
  Small (<=0x800 bytes): uses pool free list buckets (power-of-2 indexed).
  Large (>0x800 bytes): calls page allocator, creates page header.
• 0x3A5C SmiManage: Core SMI dispatch. Walks SMI handler list at
  gSmiHandlerList (0x11508). Uses sub_627C for 16-byte GUID comparison.
  Iterates per-GUID handler chains for SmiHandlerInvoke.
• 0x6350 InitializeListHead: Internal linked list head init for SMHC,
  PRTI, SHND, IMGR, COSE structures.
• 0x9464 SmmCorePerformanceLog: Performance measurement entry.
• 0x9598 SmmCorePerformanceEndMeasure: Performance measurement exit.

State Management

Critical Global Variables (.data segment 0x11000-0x144A0)

SMI Handler Registration Table at 0x11280

This table contains an array of 32-byte entries:

struct {
    UINT64  GuidPtr;      // Pointer to EFI_GUID data (embedded in code segment)
    UINT64  HandlerFunc;  // SMI handler callback function
    UINT64  NotifyFlag;   // Registration flags (non-zero = fire notification on install)
};

Empty entry (all zeros) terminates the table. Each entry calls
SmiHandlerRegister(GuidPtr, HandlerFunc, &NotifyFlag) during SmmMain.

Data Structures

SMI Handler Structure (SMHC, 48 bytes, alloc 64)

Offset  Size  Field
0x00    4     Signature ("SMHC")
0x08    16    LIST_ENTRY Link (Flink/Blink)
0x18    8     Key (GUID pointer)
0x20    8     Handler (callback function)
0x28    8     Name (string, e.g. "smie")

Protocol Entry Structure (SMHP, 56 bytes)

Offset  Size  Field
0x00    4     Signature ("SMHP")
0x08    16    LIST_ENTRY (global protocol list)
0x18    8     ProtocolID (GUID pointer)
0x20    16    LIST_ENTRY (per-protocol interface list: PRTI entries)
0x30    16    LIST_ENTRY (notification list: NOTIFY entries)

Protocol Interface (PRTI, 64 bytes)

Offset  Size  Field
0x00    4     Signature ("PRTI")
0x08    16    LIST_ENTRY (link on handle's protocol list)
0x18    8     Handle (backpointer to SHND_ENTRY)
0x20    8     ProtocolEntry (backpointer to PROTOCOL_ENTRY)
0x30    8     Interface (protocol interface pointer)

Image Record (IMGR, 64 bytes)

Offset  Size  Field
0x00    4     Signature ("IMGR")
0x08    16    LIST_ENTRY (global image record list)
0x18    8     ImageBase (source base address)
0x20    8     ImageSize (byte count)
0x28    8     CodeSegmentCount
0x30    16    LIST_ENTRY (code section list)

Code Section (COSE, 40 bytes)

Offset  Size  Field
0x00    4     Signature ("COSE")
0x08    16    LIST_ENTRY (link on image's code list)
0x18    8     CodeBase (virtual address)
0x20    8     CodeSize (raw data size)

Pool Header (24 bytes)

Offset  Size  Field
0x00    4     Signature ("phd0"=allocated, "phf0"=free)
0x04    1     Available (0=in use, 1=free)
0x05    1     Type (5=EfiRuntimeServicesCode, 6=EfiRuntimeServicesData)
0x08    4     Size (total allocation size, must == POOL_TAIL.Size)
0x10    8     LIST_ENTRY link on pool free list

Pool Tail (16 bytes)

Offset  Size  Field
0x00    4     Signature ("ptal")
0x08    8     Size (must match POOL_HEADER.Size)

AMI Comm Buffer Mailbox (24 bytes)

Offset  Size  Field
0x00    8     Command (1 = lock)
0x08    8     Identifier (matches comm buffer identifier)
0x10    4     Sequence number (monotonically increasing)
0x14    4     Session ID
0x18    4     Status

Calling Patterns

1. SMI Dispatch Path

DXE writes CommBuffer -> triggers SMI (via GPE/APMC/ASMII)
  -> SmmEntryPointWrapper(0x34C0)
    -> Save CommBuffer/Size to gSmmCommBufferBase/Size (0x113F0/0x113F8)
    -> Set gInSmmEntryPoint flag (0x14022)
    -> Execute pre-callbacks from off_10BA0 table
    -> If AMI platform hooks present:
       -> RAS policy check (SMM communication buffer management)
       -> PCH-specific SMI dispatch (per-socket/core/memory channel)
    -> SmiManage(0x3A5C, guid=0, context)
       -> Walk gSmiHandlerList (0x11508) matching GUIDs
       -> For each match: SmiHandlerInvoke(0x3B34)
          -> Call handler function
          -> Process return codes:
             SUCCESS -> done (if GUID-specific)
             INTERRUPT_PENDING -> continue iterating
             NOT_HANDLED_0xA -> abort dispatch chain
    -> Execute post-callbacks from off_10BA8 (reverse order)
    -> Clear gInSmmEntryPoint flag
    -> DebugPrint "SmmEntryPoint Exit"

2. SMM Driver Loading (Dispatcher Path)

SmmDispatcher(0x2D94) loop:
  For each FV:
    -> Locate FV protocol
    -> Locate security/SEC2 protocol
    -> For each firmware file:
       -> Read DEPEX from FV
       -> Evaluate DEPEX (0x5DF0 - Dependency.c)
       -> If satisfied:
          -> SmmLoadImage(0x2708):
             -> Read PE32+ headers via PeCoffLoader
             -> Allocate SMRAM pages via page allocator
             -> Load sections, apply relocations
             -> LoadImage/StartImage boot services call
             -> Initialize SMM driver context (image info, section data)
          -> SmmInsertImageRecord(0x1E38):
             -> Allocate IMAGE_RECORD (64 bytes)
             -> Parse PE section headers
             -> Create CODE_SECTION entries for executable sections
             -> Link into gImageRecordList (0x11490)
             -> Update gImageRecordCount (0x11480)
             -> Update gMaxImageRecordSections (0x11488)
          -> Call driver entry point
          -> Install SMM protocols via SmmInstallProtocolInterface

3. Memory Allocation Path

SmmAllocatePool(PoolType, Size) -> 0x4F80:
  If Size+40 <= 0x800 (small allocation):
    -> Compute bucket index (power-of-2, min 32-byte slots)
    -> Walk pool free list for matching bucket
    -> Carve from existing free page or allocate new page
    -> Create POOL_HEADER ("phd0") at allocation start
    -> Create POOL_TAIL ("ptal") at allocation end
    -> Return pointer after header (offset +24)
  Else (large allocation):
    -> Compute page count: (Size+40 + 0xFFF) >> 12
    -> Walk page allocation pool (off_13F70 list)
    -> Allocate contiguous pages
    -> Create page header with type/size info
    -> Set tail signature at end of allocation
    -> Return pointer after header (offset +24)

Dependencies

Consumed (this module calls)

• UefiBootServicesTableLib (gBS): AllocatePool (BS+64), FreePool (BS+72),
  LocateProtocol (BS+320), InstallProtocolInterface (BS+328),
  LocateHandleBuffer (BS+184), HandleProtocol (BS+152),
  OpenProtocol (BS+320), LocateDevicePath (BS+312),
  LocateImage (BS+208)
• BaseMemoryLibRepStr (0x2C0): CopyMem, ZeroMem
• BaseLib (0x6134, 0x61D0, 0x6234, 0x627C, 0x6350, 0x63D8, 0x6388,
  0x6464, 0x642C, 0x62E4): linked list, memory ops, GUID cmp
• BasePrintLib (0x689C, 0x6970): AsciiSPrint, UnicodeSPrint
• BaseDebugLibSerialPort (0x7834, 0x7908, 0xB6A4): DEBUG/ASSERT via
  serial port (CMOS 0x4C, I/O ports 0x70/0x71, serial data 0x3F8 or 0x2F8)
• BasePeCoffLib (0x9C2C, 0xA170, 0xA4E4, 0xA804, 0xAE00):
  PeCoffLoaderGetPeHeader, PeCoffLoaderGetImageInfo,
  PeCoffLoaderLoadImage, PeCoffLoaderCheckImageType
• SmmPciExpressLib (0x8234): register-style PCIe config access
• AmiSmmCoreBufferValidationLib (0x8980, 0x8BE8, 0x8F44, 0x853C):
  SMM CommBuffer lock/unlock, MMIO range validation, buffer boundary check
• SmmCorePlatformHookLib (0xB158): PCH RAS policy protocol, per-socket
  SMI dispatch for memory/PCIe error handling
• BaseCacheMaintenanceLib: cache flush for loaded SMM images
• SmmCorePerformanceLib (0x9A18, 0x9464, 0x9598):
  SMM performance measurement data gathering

Consumed By (other modules call this)

• All SMM Drivers: Through EFI_SMM_SYSTEM_TABLE2 (SMST) services:
  SmmAllocatePool, SmmFreePool, SmmAllocatePages, SmmFreePages,
  SmmInstallProtocolInterface, SmmHandleProtocol, SmmLocateProtocol,
  SmmRegisterProtocolNotify, SmiHandlerRegister, SmiHandlerUnRegister,
  SmmStartupThisAp
• DXE Runtime / SMM Communication: DXE writes CommBuffer to SMRAM and
  triggers SMI; SmmEntryPoint dispatches to registered SMI handlers
• PI_SMM Driver Dispatch: The Dispatcher loads SMM drivers after DEPEX
  evaluation; drivers register their protocols/handlers via SmmMain

Notes

Build Configuration

• Debug build with full ASSERT and DEBUG enabled
• Source paths: e:\hs\MdeModulePkg\..., e:\hs\AmiModulePkg\...,
  e:\hs\PurleyPlatPkg\..., e:\hs\MdePkg\...
• Toolchain: VS2015 x64

Structure Signatures Summary

Debug Output

• Uses CMOS register 0x4C for debug level check
• I/O ports 0x70/0x71 for CMOS access
• Serial port at I/O address determined by CMOS 0x5C (0x3F8 if 0x33, else
  0x2F8)
• Debug output format: "ASSERT [%a] %a(%d): %a\n" for assertions,
  "SmmEntryPoint Entry/Exit\n" for SMI entry tracing

AMI Extensions Specific to HR650X

• SmmCoreAmiBufferValidationLib: Two-phase SMM communication buffer
  locking. Uses a mailbox protocol in a pre-allocated SMRAM page to
  coordinate lock/unlock state between DXE and SMM. Protects against
  re-entrant/buffer-overrun attacks.
• SmmCorePlatformHookLib: Integrates with Purley platform RAS policy
  protocol for per-socket/core/channel SMI dispatch. Used by
  SmmEntryPoint to dispatch SMI to platform-specific error handlers.
• The SMI handler table at 0x11280 can contain up to 7+ entries (32 bytes
  each, zero-terminated), registered at SmmMain by GUID + handler function.