# Decompiled AMI UEFI BIOS Source

This tree is a cleaned extraction of Lenovo HR650X / Intel Purley AMI UEFI BIOS
modules. It is not a normal vendor source checkout: most directories are
recovered firmware modules with decompiled C, reconstructed headers, IDA
metadata, and analyst-written notes.

## Repository Layout

The top level is intentionally flat. Each module directory usually contains:

| Artifact | Meaning |
| --- | --- |
| `<Module>.c` | Decompiled implementation, often with synthetic names such as `sub_1234`. |
| `<Module>.h` | Reconstructed types, globals, GUIDs, structures, and prototypes. |
| `<Module>.md` | Module-specific notes or decompiler output notes. |
| `README.md` | Human summary of phase, purpose, key functions, dependencies, and platform context. |
| `*.i64`, `*.idb`, `*.id0`, `*.id1`, `*.id2`, `*.nam`, `*.til` | IDA database artifacts. Keep these with the module that generated them. |
| `*.json`, `*.csv`, `*.txt` | Function inventories, manifests, or analysis sidecars. |

Common UEFI phase and role markers in directory names:

- `Pei` / `PEI`: Pre-EFI Initialization modules.
- `Dxe` / `DXE`: Driver Execution Environment modules.
- `Smm` / `SMM`: System Management Mode modules.
- `Ppi`: PEI-to-PEI interfaces.
- `Setup`, `Sku`, `Slot`, `Oprom`, `UsbOc`, `IioCfg`, `SmbiosDataUpdate`: board,
  SKU, setup-page, option-ROM, or platform-configuration update modules.
- GUID-named directories: modules where the original symbolic name was missing
  or less useful than the firmware GUID during extraction.

Important anchor modules include:

- `DxeCore/`: DXE foundation, protocol database, dispatcher, memory services,
  event services, image loading, and firmware volume access.
- `PeiCore/` and `DxeIpl/`: early boot core and transition into DXE.
- `PiSmmCore/`, `PiSmmIpl/`, and `PiSmmCpuDxeSmm/`: SMM infrastructure.
- `Setup/`, `AMITSE/`, `ServerMgmtSetup/`, and related `SetupConfigUpdate*`
  modules: setup UI and setup-variable handling.
- `Platform*`, `Lnv*`, `SystemBoard*`, `Oem*`, and `Sps*`: platform and vendor
  integration layers.
- `Tcg*`, `Tpm*`, `SecureBootDXE/`, and `BootGuardPei/`: measured boot,
  TPM, secure boot, and Boot Guard related code.
- `Ip*`, `TcpDxe/`, `Udp*`, `Dhcp*`, `Http*`, `Tls*`, `MnpDxe/`, `SnpDxe/`:
  UEFI network stack modules.

## Safe Cleanup Workflow

Treat module source as reverse-engineering evidence. Prefer small, reversible
readability improvements and keep provenance visible.

1. Read the module `README.md`, `<Module>.md`, and any sidecar inventories
   before editing code.
2. Preserve decompiler evidence: do not delete original synthetic symbols,
   magic constants, GUIDs, comments, IDA databases, or extraction manifests
   unless there is a separately recorded replacement.
3. Rename symbols only when the behavior is supported by local call sites,
   GUID/protocol references, strings, or known EDK II/AMI conventions.
4. Keep phase boundaries clear. PEI, DXE, SMM, runtime, setup, and option-ROM
   modules often share names but have different execution contexts.
5. Favor comments that explain firmware intent, protocol contracts, structure
   layouts, and side effects. Avoid comments that merely restate a line of C.
6. For formatting, review diffs carefully. Decompiled C can contain unusual
   control flow, casts, volatile MMIO, and ABI-sensitive structures.
7. Do not run broad automated rewrites across the tree. Work module-by-module
   and keep each diff auditable.

## Readability Checklist

- Module README has phase, purpose, platform, key functions, protocols, and
  externally visible variables or GUIDs.
- Function names distinguish entry points, dispatch callbacks, protocol
  methods, helper routines, and error paths.
- Header types are grouped by GUID/protocol, HOB, variable, MMIO/register, and
  local state structures.
- Recovered constants are named after nearby strings, register fields, setup
  variables, or protocol fields when the evidence is clear.
- Notes call out uncertainty explicitly, especially when behavior is inferred
  from partial decompilation.

## Helper Tooling

Run the read-only tree audit from the repository root:

```sh
python3 tools/bios_tree_audit.py
```

The audit prints module counts, artifact counts, phase-name buckets, and modules
that are missing common sidecar files. It does not modify the tree.

Recover original source-layout hints from debug/assert/PDB/source paths:

```sh
python3 tools/recover_original_layout.py \
  --json-out docs/original_layout_evidence.json \
  --markdown-out docs/original_layout_recovery.md
```

The recovery report groups flat extracted modules by the best package paths
visible in `DEBUG_VS2015`, `AutoGen.c`, PDB, and source-file evidence. Use it
to guide module-by-module cleanup before attempting any physical tree moves.