UEFI boot notes from a clean room
Short notes on making firmware experiments less fragile: logging, rollback, hardware assumptions, and failure modes.
Setup pressure
Firmware work punishes vague setup notes. A small mismatch in Secure Boot state, storage layout, boot order, or firmware revision can turn a working experiment into a blank screen.
Baseline checklist
Capture the machine state
Record firmware version, Secure Boot status, TPM state, disk layout, and the exact path of the boot artifact. Screenshots are useful, but plain text survives better in diffs.
Keep rollback close
Have a known-good boot entry and external recovery media ready before introducing custom boot code. The fastest debugging session is the one that can actually restart.
Separate logging paths
Serial logs are ideal. If serial is unavailable, write narrow logs to a known file path and keep the failure mode simple. Logging should not become the riskiest part of the experiment.
Failure taxonomy
| Symptom | First question |
|---|---|
| No boot entry | Was the file copied to the expected ESP path? |
| Immediate reboot | Did the loader fault before console setup? |
| Hangs after handoff | Did the memory map change after ExitBootServices? |
| Works once | Is state being cached by firmware setup? |
Closing note
The firmware layer is not mysterious because it is magical. It is mysterious because the feedback loop is bad. Improve the loop first.