Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

14 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Learning EDK II

A practical, ground-up guide to understanding, building, running, and security-testing UEFI firmware using TianoCore's EDK II — the open-source reference implementation of UEFI.

It's written for two audiences at once:

  • Novices who have never opened a firmware codebase and want a mental model plus a working build/run/debug loop.
  • Security engineers who already know memory-safety and vuln research and want to map those skills onto the boot process: where the attack surface is, how to reach it, and how to test it (static analysis, dynamic debugging, fuzzing, sanitizers, coverage).

If you read this top to bottom you'll go from "what even is UEFI" to "I have a modified firmware image running under a debugger with a fuzzer hitting a DXE service and CodeQL flagging the bug."


1. What is UEFI, and what is EDK II?

UEFI (Unified Extensible Firmware Interface) is the specification for the software that runs before your operating system — from the first instruction the CPU executes out of reset, up through handing control to the OS loader. It replaced legacy BIOS. It defines a rich C ABI of services, protocols, and data structures that firmware exposes to drivers and to the OS.

Two specs matter:

  • UEFI spec — the interfaces visible to OS loaders and 3rd-party drivers (Boot Services, Runtime Services, protocols, the boot manager, variables).
  • PI (Platform Initialization) spec — the internal architecture of the firmware itself (the SEC/PEI/DXE phases, PEIMs, DXE drivers, HOBs, PPIs).

EDK II is the open-source codebase (maintained by TianoCore) that implements those specs. It's what real vendor firmware is built on top of, and it's what you'll read, build, and break here. Related repos you'll meet:

Repo Role
tianocore/edk2 Core, mostly platform-independent code (the DXE Core, MdePkg, OvmfPkg, ShellPkg, …).
edk2-platforms Board/silicon-specific code (e.g. BoardX58Ich10).
edk2-non-osi Vendor binaries/blobs that can't ship under the OSI license.
Intel FSP Firmware Support Package — closed-source silicon init consumed by the open code.

Why security people care: firmware runs before — and more privileged than — the OS and hypervisor. A bug in DXE or (worse) in SMM (ring −2) can undermine Secure Boot, persist across OS reinstalls, and is invisible to most host defenses. 204 bootloader/firmware CVEs were reported in 2024 alone.


2. The boot flow (the single most important mental model)

Execution moves through phases, each with less-privileged, more-featureful code than the last. Untrusted input enters at different points in different phases — knowing which phase you're in tells you what's initialized, what the attack surface is, and what debug tooling is available.

Power on
   │
  SEC   Security phase. First code out of reset (often ROM). Sets up a
   │    temporary stack (cache-as-RAM), finds and verifies the PEI core.
   │
  PEI   Pre-EFI Initialization. Runs in a memory-constrained world; brings up
   │    main DRAM. Made of PEIMs communicating via PPIs. Produces HOBs
   │    (Hand-Off Blocks) describing the platform for the next phase.
   │
  DXE   Driver Execution Environment. The big one. Full C environment, memory
   │    available. The DXE Core dispatches DXE drivers that publish PROTOCOLS
   │    onto the Boot Services table. Most of EDK II lives here.
   │
  BDS   Boot Device Selection. Applies boot policy: which device/OS to load,
   │    Secure Boot verification, the boot menu, console setup.
   │
  TSL   Transient System Load. The OS loader (e.g. GRUB, Windows Boot Manager)
   │    runs as a UEFI application, still able to call Boot Services.
   │
  RT    Runtime. ExitBootServices() has been called; the OS is up. Only
   │    Runtime Services (a small subset, e.g. variable + time) remain callable.
   │
  SMM   System Management Mode — runs ORTHOGONALLY to all of the above, at
        ring −2, entered via SMIs. Persists into OS runtime. The crown-jewel
        attack surface: an SMI handler that trusts an OS-supplied pointer is a
        classic privilege-escalation primitive.

Key globals you'll see everywhere, established during DXE:

  • gST — the System Table (root of everything).
  • gBS — Boot Services (memory alloc, protocol handling, events, image load). Valid only before ExitBootServices().
  • gRT — Runtime Services (variables, time, reset) — survive into the OS.

3. How the codebase is organized (and how to read it)

EDK II looks huge and alien at first. It isn't — it's extremely regular once you learn its five file types and the package/module structure. Read the dedicated guide for a worked example:

➡️ Reading the Codebase

The 60-second version:

  • Packages are the top-level unit (MdePkg, MdeModulePkg, OvmfPkg, UefiCpuPkg, SecurityPkg, ShellPkg, …). A package groups related modules and declarations.
  • Modules are individual drivers/apps/libraries inside a package.
  • Five file extensions carry all the build metadata:
File Answers the question
.dec What does this package declare? — GUIDs, protocols, PCDs, library classes it exposes.
.dsc What do I build, and with which library instances? — the build recipe.
.inf What is this one module? — its sources, dependencies, entry point, module type.
.fdf How is the final flash image laid out? — firmware volumes, sections, the reset vector.
.c/.h The actual code.

Reading trick: start from a module's .inf, read [Sources] for the files, [LibraryClasses]/[Protocols]/[Pcd] for its dependencies, and [Defines] ENTRY_POINT for where execution starts. To find who implements a protocol, grep the code for its GUID.


4. The learning path

Follow these in order. Each links to a focused guide.

  1. Build it → Compiling on Linux Get the toolchain, run edksetup, and produce your first firmware image (OVMF, which is runnable in QEMU).
  2. Run it → Testing Platforms overview, then QEMU + OVMF or Simics. Boot your build to the UEFI Shell and run an application.
  3. Debug it → Source-level debugging with GDB Break on firmware code, load symbols at the right address, single-step DXE.
  4. Analyze it statically → CodeQL on EDK II Build a database, run the C/C++ security queries, write a custom query for a firmware-specific bug pattern.
  5. Test its security → Security Testing overview Threat model, attack surface, then hands-on fuzzing: BreakingBoot · BBClient · Code coverage.

5. Where the security action is (quick map)

If you're here to find bugs, these are the high-value targets and the tools that reach them. Details in Security Testing.

Attack surface Why it's juicy Reach it with
SMM / SMI handlers ring −2, persists into OS; CommBuffer TOCTOU & pointer callouts CodeQL patterns, Simics, chipsec
DXE services & protocols parse attacker-influenced data (FV, images, network) FuzzUEr / BBClient fuzzing, uefi_asan
UEFI variable services untrusted, persistent, feed Secure Boot fuzzing + static analysis
PE/COFF image loader loads third-party & OS binaries CodeQL, fuzzing
Firmware volume parsing attacker-supplied capsules / update images FuzzUEr (ProcessFirmwareVolume)
Network stack (PXE/HTTP boot) remote, pre-OS fuzzing, CodeQL

Companion tooling built in this org:

  • FuzzUEr — fuzzing UEFI interfaces on EDK II (found 20 zero-days).
  • firness — automated harness generation for UEFI interfaces.
  • uefi_asan — AddressSanitizer adapted to the freestanding UEFI environment.

6. Repository contents

learning-edk2/
├── README.md                       ← you are here (start + mental model)
├── Codebase/
│   └── Reading-the-Codebase.md     how EDK II is structured & how to navigate it
├── Compiling/
│   └── Linux-Compiling.md          toolchain, edksetup, building OVMF
├── Executing/
│   ├── README.md                   QEMU vs Simics
│   ├── QEMU-Emulation.md           QEMU+OVMF and the EmulatorPkg host
│   ├── Simics-Simulation.md        custom firmware in Simics
│   └── GDB-Debugging.md            source-level debugging under QEMU
├── CodeQL/
│   └── CodeQL.md                   static analysis: DB creation, queries, custom
└── Testing/
    ├── Security-Testing.md         threat model + attack surface + method
    ├── BreakingBoot.md             the BreakingBoot fuzzing shell app
    ├── BBClient.md                 the BBClient service fuzzer
    └── CodeCoverage.md             coverage with the Simics UEFI tracker

7. External references worth bookmarking

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors