# BootGuardPei - Boot Guard PEIM

## Overview

`BootGuardPei` is a PEI driver recovered from an AMI/Intel Purley firmware
image.  The module checks Intel Boot Guard state and verifies FV Main hash data
early in PEI before the platform continues into later boot phases.

This directory contains decompiler output, not original vendor source.  The
function names are recovered labels and the types should be treated as
best-effort until confirmed against EDK2 or AMI headers.

## Module Metadata

| Field | Value |
|-------|-------|
| Module | `BootGuardPei.efi` |
| Index | `0375` |
| Source path | `PurleyPlatPkg/BootGuard/ExtendBtGSupportToDxe/Pei/BootGuardPei/` |
| Architecture | IA32 |
| Image size | `0x2040` bytes |
| Text size | `0x0ee0` bytes |
| Recovered functions | 38 |

## Build Info

- Build: DEBUG_VS2015 IA32
- AutoGen: HR6N0XMLK
- Platform: Purley (HR650X)
- Libraries linked:
  - BaseMemoryLibRepStr (rep stosb/movsb based string operations)
  - PeiPcdLib (PCD access)
  - DebugLib (debug printing and assertions)
  - PeiServicesLib (PEI services)

## Execution Flow

The recovered control flow is organized around these stages:

1. **Entry** (`_ModuleEntryPoint` @ 0xffde307c):
   - Calls `PeiCryptLibConstructor` to initialize subsystems
   - Reads MSR 0x13A (IA32_FEATURE_CONTROL) bit 32 to check Boot Guard support
   - If supported, reads MSR[31:0] for Boot Guard policy
   - Calls `GetPeiServices` to locate PeiServices pointer via SIDT
   - Installs BootGuard PPI using a GUID at data area

2. **Verification** (`BootGuardPeiEntry` @ 0xffde31BF):
   - Gets boot mode - skips if BOOT_ON_S3_RESUME (boot mode 17)
   - Allocates SHA256 context (112 bytes)
   - Calls `LocateBootGuardHashKey` to find hash key entries in HOB
   - For each FV segment (up to 2):
     - Computes SHA256 hash of the FV segment
     - Compares against stored hash key
   - On hash mismatch: reports error, sets PCD 9 to 1 (disables boot)
   - On match: continues boot

3. **SHA-256 implementation**:
   - `Sha256Init` initializes the eight SHA-256 state words.
   - `Sha256Update` accumulates data and processes 64-byte blocks.
   - `Sha256Transform` performs the compression rounds.
   - `Sha256Final` applies padding and emits the digest.
   - Constants at `dword_FFDE3F74` (SHA256 K constants)

4. **Heap Manager**:
   - Allocates 64KB pool via PeiServices AllocatePages
   - Initializes internal memory manager with free list descriptor

## Function Summary

| Address | Name | Size | Description |
|---------|------|------|-------------|
| 0xffde307c | _ModuleEntryPoint | 152 | PEI entry point - checks Boot Guard MSR |
| 0xffde31bf | BootGuardPeiEntry | 671 | Main Boot Guard verification logic |
| 0xffde3121 | LocateBootGuardHashKey | 219 | Locate hash key entries in HOB |
| 0xffde363d | IsBootGuardHashGuid | 94 | GUID match check for BootGuard hash |
| 0xffde38ea | PeiCryptLibConstructor | 101 | PEI library init + debug setup |
| 0xffde3835 | HeapManagerInit | 181 | Allocate 64KB heap via AllocatePages |
| 0xffde398e | MemMgrInit | 218 | Initialize memory descriptor |
| 0xffde37e0 | GetPeiServices | 50 | Get PeiServices ptr via SIDT |
| 0xffde3a66 | Sha256Transform | 393 | Core SHA256 block transform |
| 0xffde3ce3 | Sha256Init | 70 | SHA256 context init |
| 0xffde3d2a | Sha256Update | 197 | SHA256 data accumulation |
| 0xffde3bef | Sha256Final | 247 | SHA256 finalize with padding |
| 0xffde3963 | Sha256ContextSize | 3 | Returns sizeof(SHA256_CTX) = 112 |
| 0xffde34e6 | DebugPrint | 42 | Debug print with level check |
| 0xffde34b5 | GetDebugPeiServicesPtr | 49 | Get DebugLib PPI pointer |
| 0xffde3510 | DebugAssert | 30 | Debug assert with file/line/message |
| 0xffde3446 | GetPcdPei | 88 | Get PCD PPI pointer |
| 0xffde3791 | GetDebugLevel | 85 | Read debug level from CMOS I/O |
| 0xffde3585 | CompareMem | 184 | CompareMem with bounds checking |
| 0xffde3699 | CopyMem | 123 | CopyMem with bounds checking |
| 0xffde3004 | SetMem | 26 | memset wrapper |
| 0xffde3024 | SetMemZero | 29 | ZeroMem wrapper |
| 0xffde3064 | SetMem32 | 23 | memset32 wrapper |
| 0xffde3044 | SetMem32Loop | 33 | memset32 inner loop |
| 0xffde353a | AllocatePool | 32 | Pool allocation via PeiServices |
| 0xffde3561 | AllocateZeroPool | 34 | Zero pool allocation |

## Data References

- `unk_FFDE4C5C` - DebugLib PPI GUID
- `unk_FFDE4C9C` - PCD PPI GUID
- `unk_FFDE4CAC` - BootGuard PPI structure (function pointer table)
- `dword_FFDE3F74` - SHA256 K constants table (64 x 32-bit values)
- `unk_FFDE4CC4` - GUID for BootGuard hash key identification

## Files

- `BootGuardPei.c` - combined decompiler listing with recovered labels.
- `BootGuardPei.h` - compact navigation index for recovered functions.
- `BootGuardPei.md` - raw function table generated from the decompile pass.
- `ModuleEntryPoint.c`, `BootGuardPeiEntry.c`, `HeapManagerInit.c`,
  `PeiCryptLibConstructor.c` - focused per-function extracts.