UEFI Shell for Firmware Engineers
How to use UEFI Shell as a pre-OS debug environment instead of treating it as a simple command prompt.
The machine does not boot into the OS.
There is no JTAG session. Serial log is incomplete. Setup still opens, but the boot flow dies somewhere after BDS.
At that moment, UEFI Shell becomes more than a convenience command prompt. It becomes the closest thing to a live firmware inspection room.
Device handles
Use dh, devtree, drivers, and connect to inspect how firmware discovered and connected devices.
Filesystem mapping
Use map -r, fs0:, ls, and cd to verify ESP, USB, and removable media visibility.
NVRAM variables
Use dmpstore and bcfg to inspect BootOrder, BootNext, Boot####, SecureBoot, and setup variables.
Memory and registers
Use memmap, mem, and mm for memory map and raw address inspection when the platform allows it.
Automation
Use startup.nsh for repeated validation, manufacturing flow, or recovery scripts.
A useful mental model
UEFI Shell is not the OS.
It does not prove that a Windows driver will bind, and it does not prove that Linux will like your ACPI namespace. But it can prove something earlier and often more important:
Did firmware expose the expected object before the OS started?Real world example: USB recovery does not appear
Start with the Shell side:
Shell> map -r
Shell> fs0:
FS0:\> lsIf no fsX: mapping appears for the USB drive, the problem may be USB controller initialization, mass storage driver binding, filesystem format, or device connection policy. If fs0: exists but the expected EFI file is missing, the problem is the media layout.
Real world example: BootNext ignored
Shell> dmpstore BootNext
Shell> dmpstore BootOrder
Shell> bcfg boot dumpIf BootNext is missing, BDS cannot consume it. If BootNext points to a nonexistent Boot####, the variable exists but the boot target is invalid.
Common pitfall: Shell state is not always stable
fs0: is not a permanent disk identity. It is a mapping created from current device discovery order.
That means this is fragile:
fs0:\EFI\BOOT\BOOTX64.EFIwhen multiple USB drives or disks are attached.
A robust debug note should record both the map output and the device path, not only the fs0: alias.
Minimal command set
| Item | Value | Note |
|---|---|---|
| map -r | Refresh device mapping | First command when USB, ESP, or removable media visibility is unclear. |
| fs0: | Switch filesystem | Use only after checking map output. |
| dmpstore | Dump variables | Best for BootOrder, BootNext, SecureBoot, db, dbx, setup variables. |
| bcfg | Manage boot options | Useful for manual boot option recovery and BDS debug. |
| drivers | List loaded drivers | Good for checking whether expected DXE drivers loaded. |
| dh | Dump handles | Useful when protocol installation or driver binding is suspected. |
| memmap | Memory map | Useful before ExitBootServices-related investigation. |
| mm | Memory modify/read | Powerful but dangerous. Record original values first. |
Firmware Engineer Notes
I usually treat Shell as a checkpoint between firmware policy and OS behavior.
If the expected boot variable, handle, filesystem, or driver is already missing in Shell, do not waste time debugging the OS first. If Shell looks correct but OS still fails, move to ACPI, PCI, driver, or security policy layers.
Related notes
- Filesystem Mapping in UEFI Shell
- dmpstore Deep Dive
- bcfg Deep Dive
- UEFI Shell Memory Commands
- Boot Failure Playbook
Found this useful?
Save it or share it with someone learning firmware, BIOS/UEFI, and embedded systems.
Nội dung liên quan
Một số bài viết, ghi chú hoặc project có liên quan đến nội dung bạn vừa đọc.
Boot Failure Playbook
A firmware engineer playbook for debugging missing boot options, invalid BootOrder, broken Device Paths, and BDS boot failures.
Firmware Debug Toolbox Overview
A practical knowledge map for UEFI Shell, ACPI, PCI, image analysis, security validation, and OS-side firmware debugging tools.
UEFI Shell Filesystem Mapping
A practical guide to map, fs0, removable media, ESP visibility, and why Shell filesystem aliases can change.
Biến note thành bài viết hoàn chỉnh
Notes là nơi ghi nhanh khái niệm.