Introduction

Welcome to the Patina QEMU Platforms book. This book documents the two virtual platforms maintained in the patina-qemu repository and the workflows used to build, debug, and validate them.

The primary purpose of patina-qemu is to serve as a test vehicle for the Patina project. It can also be used as a reference for a simple integration of Patina with EDK II components. The repository contains a permanent fork of OvmfPkg from EDK II adapted for Patina.

Platforms:

• QEMU Q35 - an x86_64 platform based on the Q35 chipset.
• QEMU SBSA - an AArch64 platform based on the Arm Server Base System Architecture.

What is in this book

This book is organized into the following sections:

1. Building and Running - Setting up your environment, compiling the firmware, running it in QEMU, and the rapid Patina iteration workflow used by most Patina developers.
2. Debugging - Connecting WinDbg to UEFI firmware running in QEMU and to a Windows guest OS booted on top of it.
3. Testing - Scheduled regression tests run against the default branch.
4. Performance - Collecting and interpreting boot performance data, and the size of the Patina DXE Core release binary.

Related Documentation

• Open Device Partnership (ODP)
• Patina project documentation - the main Patina book
• Patina GitHub organization
• Patina DXE Core QEMU - the Patina DXE Core binary crate consumed by this repository

QEMU Q35

QemuQ35Pkg...

• Is a derivative of OvmfPkg.
• Will not support Legacy BIOS or CSM.
• Will not support S3 sleep functionality.
• Has a 32-bit PEI phase and a 64-bit DXE phase.
• Targets a tightly constrained virtual platform based on the QEMU Q35 machine type.

By focusing solely on the Q35 chipset, this package is allowed to break compatibility with other QEMU supported chipsets in exchange for a simpler, more consistent target. The Q35 chipset can be paired with an IA32 or X64 processor to emulate PC class hardware with industry standard features like SMM and PCI-E.

Q35 Machine Type

Q35 emulates the ICH9 (I/O Controller Hub).

The advantages of ICH9 over the I440FX (the chipset QEMU emulates by default) are:

• PCI-E support, instead of just PCI.
• An integrated AHCI controller.
• No ISA bus.

For more information see the QEMU Q35 feature wiki.

Building and Running

QemuQ35Pkg uses the Patina repositories and EDK II PyTools for its build operations. See Building the Firmware for full instructions.

QEMU SBSA

QemuSbsaPkg...

• Is a derivative of OvmfPkg based on the EDK II QEMU-SBSA ARM machine type.
• Will not support Legacy BIOS or CSM.
• Will not support S3 sleep functionality.
• Has 64-bit PEI and DXE phases.
• Targets a tightly constrained virtual platform based on the QEMU ARM CPUs.

By focusing solely on the ARM chipset, this package is allowed to break compatibility with other QEMU supported chipsets. The ARM chipset can be paired with an AArch64 processor to emulate ARM-based hardware with industry standard features like TrustZone and PCI-E. Although QemuSbsaPkg leverages the SBSA machine type provided by QEMU, the features enabled in this package are not server-class platform centric.

SBSA Machine Type

SBSA is an ARM-based machine type that QEMU emulates. It provides better ARM-based platform-level support (ACPI, etc.) than the generic virt ARM machine and includes an integrated AHCI controller.

Building and Running

QemuSbsaPkg uses the Patina repositories and EDK II PyTools for its build operations. See Building the Firmware for full instructions.

Building the Firmware

Steps to set up your environment, compile, and run QemuQ35Pkg and QemuSbsaPkg.

Developer Environment

This is a Stuart-based platform, so the default environment requirements come from the How to Build with Stuart instructions.

QEMU is used to run the locally compiled firmware on a virtual platform.

• Windows: No action is needed. An external dependency in the repository provides the necessary QEMU binaries.
• Linux: Install QEMU.

This build uses edk2-pytools for its functionality. On most Linux distros, mono and nuget support require an extra step. See: A note on nuget on Linux.

CLANGPDB Toolchain

Both QemuQ35Pkg and QemuSbsaPkg use the CLANGPDB toolchain exclusively. This enables development of both architectures on Linux and Windows, native PE/COFF image generation, and PDBs that work with the uefi_debug_tools WinDbg infrastructure or lldb.

LLVM version 21 or greater is recommended for use with EDK II and related projects. It can be downloaded from LLVM itself. Add the directory containing the clang executable to your PATH (restarting the terminal if necessary) and follow the steps below to build with Stuart.

Building with Pytools

1. [Optional] Create a Python virtual environment. Generally once per workspace.

   python -m venv <name of virtual environment>
   

2. [Optional] Activate the virtual environment. Each time a new shell is opened.

   • Linux

     source <name of virtual environment>/bin/activate
     

   • Windows

     <name of virtual environment>/Scripts/activate.bat
     

3. Install Pytools. Generally once per virtual env or whenever pip-requirements.txt changes.

   pip install --upgrade -r pip-requirements.txt
   

4. Initialize and update submodules. Only when submodules have updated.

   First time setup:

   stuart_setup -c Platforms/<Package>/PlatformBuild.py
   

   Subsequent submodule updates:

   git submodule update --recursive
   

5. Initialize and update dependencies. Only as needed when ext_deps change.

   stuart_update -c Platforms/<Package>/PlatformBuild.py
   

6. Compile firmware.

   stuart_build -c Platforms/<Package>/PlatformBuild.py
   

   Use stuart_build -c Platforms/<Package>/PlatformBuild.py -h to see additional options like --clean.

7. Running QEMU.

   • Append --FlashRom to the build command and QEMU will run after the build completes, booting the new firmware.

   • Or use --FlashOnly to skip the build and launch QEMU with the last built firmware:

     stuart_build -c Platforms/<Package>/PlatformBuild.py --FlashOnly
     

Custom Build Options

SERIAL_PORT defaults:

• Q35: defaults to None to avoid unintended port conflicts in the pipeline. The build_and_run_rust_binary.py script defaults to port 50001.
• SBSA: only has a single serial port for normal world. By default, this is unset so it can send serial output to stdio. Setting it for SBSA prevents logs from coming over stdio and instead routes them to the TCP port.

Passing Build Defines

To pass build defines through stuart_build, prepend BLD_*_ to the define name and pass it on the command line. stuart_build requires values to be assigned, so add a =1 suffix for bare defines.

For example, to enable E1000 network support, instead of the traditional -D E1000_ENABLE:

stuart_build -c Platforms/<Package>/PlatformBuild.py BLD_*_E1000_ENABLE=1

References

• Installing and using Pytools
• Python virtual environments

Rapid Patina Iteration

The build_and_run_rust_binary.py script is intended for rapid development of Patina in this repository. It takes a prebuilt FD (from a previous stuart_build invocation) and patches a new Patina DXE Core into it. This greatly speeds up the development loop because none of the C components are rebuilt.

Prerequisites

The script requires that the following repositories are cloned locally:

• patina-dxe-core-qemu - the Patina DXE Core source used by this repository.
• patina-fw-patcher - the patcher tool that injects the new DXE Core into a built FD.

How it Works

The script will:

1. Build a new Patina DXE Core from patina-dxe-core-qemu for the requested platform.
2. Use the patcher to patch the new DXE Core into the existing FD.
3. Launch QEMU to execute the patched FD.

Running the Script

python build_and_run_rust_binary.py -p Q35

Use python build_and_run_rust_binary.py -h to see all related options, including the SBSA platform target and debugger configuration flags.

🐞 WinDbg + QEMU + Patina UEFI - Debugging Guide

Overview

QEMU can expose two serial ports: one for software debugging and another for hardware debugging.

• Software Debugging Serial Port Used for communicating with the UEFI SW debugger.

• Hardware Debugging Serial Port Used for low-level QEMU hardware debugging.

Each serial port can be used independently or simultaneously. Both expose the GDB Remote Serial Protocol.

WinDbg communicates with QEMU using the EXDi Interface. The EXDi interface allows WinDbg to interact with transports like the GDB Remote Serial Protocol that QEMU provides.

The ExdiGdbSrv.dll in WinDbg acts as a GDB client.

End-to-End Communication Flow

Software Debugging: WinDbg ↔ EXDi ↔ GDB Stub ↔ Serial Port ↔ UEFI Debugger

Hardware Debugging: WinDbg ↔ EXDi ↔ GDB Stub ↔ Serial Port ↔ QEMU HW

Setting Up WinDbg

• Download and install WinDbg.
• Verify that ExdiGdbSrv.dll and exdiConfigData.xml were installed into the C:\Program Files\WindowsApps\Microsoft.WinDbg.Fast_1.xxxxxxxxx\amd64 directory.
• Download the latest release of the UEFI WinDbg Extension from uefi_debug_tools releases.
• Extract its contents to %LOCALAPPDATA%\Dbg\EngineExtensions\.

Launching Patina QEMU UEFI with Debugging Enabled

The patina-qemu UEFI platform build, by default, uses a pre-compiled DXE Core binary from a NuGet feed provided by the patina-dxe-core-qemu repository. Since these binaries have debug disabled, the following steps enable debug and override the default.

• Clone the Patina DXE Core QEMU repository into a new directory.

• Build it:

  • Debug build (debugger included): cargo make q35
  • Release build: cargo make q35-release --features build_debugger

• The output file will be: /target/x86_64-unknown-uefi/debug/qemu_q35_dxe_core.efi

  Warning

  The output .efi file contains only the .pdb file name, not the full path. When using WinDbg, set the path to the directory containing the .pdb file appropriately (as described in Software Debugging).

• Return to this repository's directory and rebuild the patina-qemu UEFI using the BLD_*_DXE_CORE_BINARY_OVERRIDE command-line parameter to indicate which override DXE Core driver to use:

  stuart_build -c Platforms/QemuQ35Pkg/PlatformBuild.py GDB_SERVER=5555 SERIAL_PORT=56789 --FlashRom BLD_*_DXE_CORE_BINARY_OVERRIDE="<patina dxe core qemu repo path>/target/x86_64-unknown-uefi/debug/qemu_q35_dxe_core.efi"
  

• The stuart_build command will also launch QEMU and wait for the initial break-in:

  

  

Launching WinDbg Instances

Instance 1: Software Debugging

1. Launch WinDbg. This will connect to the QEMU SW serial port (56789).

   

2. Set symbol and source paths:

   .sympath+ <path to pdb dir> ; usually <cloned dir>\target\x86_64-unknown-uefi\debug\deps
   .srcpath+ <path to src dir> ; usually <cloned dir>\src
   

   Tip

   You can avoid setting this for every debug session by configuring the _NT_SYMBOL_PATH environment variable, for example:

   C:\repos\patina-dxe-core-qemu\target\x86_64-unknown-uefi\debug;C:\repos\patina-dxe-core-qemu\target\aarch64-unknown-uefi\debug;srv*c:\symbolspri*https://symweb.azurefd.net;srv*C:\Symbols*https://msdl.microsoft.com/download/symbols

3. Initialize the UEFI debugger extension:

   !uefiext.init
   

4. !uefiext.help lists all available commands.

   

Instance 2: Hardware Debugging (Optional)

1. Launch another WinDbg instance.

   

2. It should automatically connect to the QEMU HW serial port (5555).

🐞 WinDbg + QEMU + Patina UEFI + 🪟 Windows OS - Debugging Guide

In addition to the steps discussed in WinDbg + QEMU + Patina UEFI Debugging, this document describes how to launch Windows and perform kernel debugging on QEMU. Unlike the UEFI software debugger and the QEMU hardware debugger, Windows does not require EXDi — it natively communicates with WinDbg using the KDCOM transport.

Prepare the OS Image

1. Download the original OS image in either VHDX or QCOW2 format. If the image has never been booted before, use Hyper-V to boot it once and complete the OOBE (Out-of-Box Experience) process if any. Recommended references:

   • Enable Hyper-V on Windows 11
   • Create a Virtual Machine with Hyper-V

2. Although QEMU supports both VHDX and QCOW2 formats, using a QCOW2 image is recommended for reliability. Convert VHDX to QCOW2 with:

   qemu-img convert -f vhdx -p -c -O qcow2 Windows11.vhdx Windows11.qcow2
   

   Note

   qemu-img.exe is present in the QEMU installation path (C:\Program Files\qemu).

Launch QEMU with Patina UEFI and Windows

By default, the patina-qemu build uses a pre-compiled Patina DXE Core binary, which is sufficient to boot and debug Windows as outlined here. If debugging of the Patina UEFI or any other UEFI driver is needed, see the WinDbg + QEMU + Patina UEFI - Debugging Guide.

To compile the firmware image and launch QEMU with serial and GDB support:

stuart_build -c Platforms/QemuQ35Pkg/PlatformBuild.py GDB_SERVER=5555 SERIAL_PORT=56789 --FlashRom PATH_TO_OS="C:\Windows11.qcow2"

Enable Kernel Debugging on the QEMU Guest (Windows)

After booting to the Windows desktop, open a Command Prompt and run the following commands to enable kernel and boot debugging (boot debugging is optional):

bcdedit /dbgsettings serial debugport:1 baudrate:115200
bcdedit /set {default} debug on
bcdedit /set {default} bootdebug on
shutdown -r -t 0   :: reboot for the above settings to take effect

Launch WinDbg for Kernel Debugging

Once Windows reboots, run the following to connect WinDbg:

windbgx -k com:ipport=56789,port=127.0.0.1 -v

Or via UI:

Serial Console for UEFI

Use a terminal application such as PuTTY or Tera Term to connect to the <port number> you configured for QEMU, using the Raw TCP/IP protocol to 127.0.0.1.

Regression Testing

This repository performs scheduled testing against the default branch to detect regressions for common firmware paths. The sections below describe the categories of tests (nightly, weekly, etc.) being performed. Not all tests have been implemented yet:

• ✅ Means the regression tests are implemented and enabled.
• ❌ Means the regression tests are not implemented or enabled.

OS Boot Validation

OS boot is critical to a platform being considered "correct", but the validation and continuous integration steps performed when validating a pull request only boot to the UEFI shell, rather than any given operating system. A nightly OS boot test exists to test common ways of booting an operating system. This includes booting from an internal drive, from a USB drive, and from a PXE server.

• ✅ Q35 Internal Drive Windows Validation OS boot

• ✅ Q35 Internal Drive Ubuntu 24.04 Server OS boot

• ✅ SBSA Internal Drive Windows Validation OS boot

• ✅ SBSA Internal Drive Ubuntu 24.04 Server OS boot

• ✅ Q35 USB Drive Windows Validation OS boot

• ✅ Q35 USB Drive Ubuntu 24.04 Server OS boot

• ✅ SBSA USB Drive Windows Validation OS boot

• ✅ SBSA USB Drive Ubuntu 24.04 Server OS boot

• ❌ Q35 PXE Windows Validation OS boot

• ❌ Q35 PXE Ubuntu 24.04 Server OS boot

• ❌ SBSA PXE Windows Validation OS boot

• ❌ SBSA PXE Ubuntu 24.04 Server OS boot

The .github/workflows/nightly-os-boot.yml workflow is responsible for the nightly OS boot testing mentioned above. It first downloads and prepares the OS images that will be booted so that, once booted, they automatically shut down. The firmware is then compiled and flashed to the two virtual platforms, and BDS automatically detects the operating system and boots.

Advanced Logger Log Gathering

The advanced logger is a logger implementation for UEFI firmware that writes its log files to a special partition during boot. Since it is uncommon to need to pull logs off of a device (thanks to flashing and booting under a debugger), it can take time to notice if this functionality is broken. This nightly test ensures that platform boot logs exist and are retrievable from Windows systems once booted to the operating system.

• ✅ Q35 advanced logger boot log gathering via UEFI application
• ✅ SBSA advanced logger boot log gathering via UEFI application
• ❌ Q35 advanced logger boot log gathering via Windows Validation OS
• ❌ SBSA advanced logger boot log gathering via Windows Validation OS

Debugger Connection

This flow is exercised fairly frequently, but it is important enough that any regression should be detected immediately. Nightly tests boot with the debugger and initial breakpoint enabled, and a script sends GDB Remote Serial Protocol communication to ensure the debugger successfully connects and continues from the initial breakpoint.

• ❌ Q35 debugger connection boot
• ❌ SBSA debugger connection boot

Hibernation

While hibernation is not strictly a UEFI feature, its implementation is highly dependent on the memory layout provided by firmware via the UEFI memory map. Successful hibernation requires that runtime memory regions remain stable across boots. Historically, even minor firmware changes have broken hibernation, demonstrating how sensitive and error-prone this path can be.

To validate hibernation support, tests are implemented that repeatedly boot the operating system, extract the UEFI memory map from logs, and compare it against the previous boot to ensure memory layout stability. Each iteration then performs a hibernate-resume cycle. This process is repeated multiple times to detect nondeterministic firmware behavior that could cause resume failures.

• ❌ Q35 hibernate resume
• ❌ SBSA hibernate resume

Self-Certification Tests (SCTs)

SCTs are the de-facto way to validate a platform's firmware implementation is compliant with the UEFI specification. It is important to monitor and stay compliant with these tests. Unlike other tests documented here, SCTs are run on a weekly basis due to the time it takes to run them.

• ❌ Q35 self-certification tests
• ❌ SBSA self-certification tests

Performance Monitoring

Boot performance is an important aspect of platform firmware and must be monitored to ensure it does not degrade over time. Performance tracking is performed by the EDK II performance measurement protocol and can be retrieved from the operating system via the FBPT. We can boot to the operating system, retrieve the boot measurements, and publish the results.

Performance monitoring happens in two parts. On a weekly schedule, a workflow runs to gather the current performance measurements and produce them as an artifact. A second workflow runs when a pull request is created that updates the Patina QEMU DXE Core external dependency. This workflow performs the same performance measurements and additionally compares them against the most recent measurements from the scheduled run, commenting on the pull request with the performance changes.

• ❌ Q35 Release Performance Measurement tracking
• ❌ SBSA Release Performance Measurement tracking

Q35 Performance

Performance on Q35 is managed by a Rust component that writes and publishes the Firmware Basic Boot Performance Table (FBPT). For more information on the functionality of the performance component, see the performance component documentation in the main patina repo. This document focuses on how to collect and interpret performance results.

Collecting Performance

1. Enable the Performance Component

The performance component must be enabled to collect FBPT results. Example code can be found under Enabling Performance Measurements in the main patina repo.

2. Boot and Collect FBPT Binary

When enabled, the performance component collects FBPT results during UEFI boot. This is done by setting BLD_*_PERF_TRACE_ENABLE=TRUE as a build variable to stuart_build:

stuart_build -c Platforms/QemuQ35Pkg/PlatformBuild.py --flashrom BLD_*_PERF_TRACE_ENABLE=TRUE

For more information on the stuart system, see Building the Firmware.

To collect raw FBPT results from the UEFI shell, FbptDump.efi must be built. Add the following to your platform .dsc:

UefiTestingPkg\PerfTests\FbptDump\FbptDump.inf

The source code for FbptDump is in mu_plus.

3. Interpret Performance Results

Pip Modules

Two tools are necessary to convert the resulting .bin file into a readable HTML results file.

First, install edk2-pytool-extensions:

pip install edk2-pytool-extensions

Then, run fpdt_parser to retrieve the XML, and perf_report_generator to retrieve the final HTML page:

fpdt_parser -b path_to_bin_file.bin -x output_file_name.xml
perf_report_generator -i path_to_xml_file.xml -r output_file_name.html -s path_to_directory_with_guids/

Scripts

There are two scripts to convert the FBPT binary dump into usable results in edk2-pytool-extensions:

• fpdt_parser.py converts the .bin file into XML.
• perf_report_generator.py converts the XML into an HTML page with filtering and graphing options.

Sample Result

An example of these results can be found in the Sample Q35 Performance Report.

Patina DXE Core Release Binary Composition and Size Optimizations

This document is a reference for the current set of size-related optimizations performed on the Patina DXE Core release binary.

1. Common Rust Compiler Optimizations Focused on Reducing Binary Size

Optimization Status: Applied

[profile.release]
codegen-units = 1               # Default is 16; setting it to 1 prioritizes size over compilation speed.
debug = "full"
lto = true                      # Enables Link Time Optimization - significant size reduction.
opt-level = "s"                 # Optimize for size - significant size reduction.
split-debuginfo = "packed"
strip = "symbols"               # Remove symbol information from the final binary (not very relevant for PE files).
incremental = true

Below is the composition of the Patina DXE Core release binary for QEMU, located at target\x86_64-unknown-uefi\release\qemu_q35_dxe_core.efi. This represents the final binary after applying the non-destructive compiler optimizations outlined in PR #19:

Results: 1,162 KB down to 762 KB (a reduction of approximately 35%).

2. Logging: Reducing Binary Size by Disabling Logging

Optimization Status: Not Applied

The other substantial reduction in the release binary size is observed when logging is completely disabled, as shown below in \patina-dxe-core-qemu\Cargo.toml using release_max_level_off.

[dependencies]
log = { version = "^0.4", default-features = false, features = ["release_max_level_off"] }

Results: 762 KB to 599 KB (a reduction of approximately 160 KB (21%)).

3. Decompression: Reducing Binary Size by Defaulting to UEFI Decompression

Optimization Status: Not Applied

Defaulting to UEFI decompression in the section extractor while skipping Brotli and CRC32 can save another 140 KB.

[dependencies]
patina_section_extractor = { version = "4", registry = "patina-fw", default-features = false, features = ["uefi_decompress"] }

Results: 599 KB to 460 KB (a reduction of approximately 140 KB (23%)).

4. Debugger: Reducing Binary Size by Excluding Debugger Support

Optimization Status: Not Applied

Excluding debugger support can save another 55 KB. This reduces the size from 460 KB to ~406 KB.

#![allow(unused)]
fn main() {
// Commenting below lines will exclude debugger support
static DEBUGGER: patina_debugger::PatinaDebugger<Uart16550> =
    patina_debugger::PatinaDebugger::new(Uart16550::Io { base: 0x3F8 })
        .with_force_enable(false)
        .with_log_policy(patina_debugger::DebuggerLoggingPolicy::FullLogging);

    patina_debugger::set_debugger(&DEBUGGER);
}

[dependencies]
# Commenting below line will exclude debugger support
# patina_debugger = { version = "4", registry = "patina-fw" }

Results: 460 KB to 406 KB (a reduction of approximately 55 KB (11%)).

Release Binary Size After Above Optimizations

C:\r\patina-dxe-core-qemu>dir C:\r\patina-dxe-core-qemu\target\x86_64-unknown-uefi\release\qemu_q35_dxe_core.efi
 Volume in drive C has no label.
 Volume Serial Number is 40DF-F702

 Directory of C:\r\patina-dxe-core-qemu\target\x86_64-unknown-uefi\release

06/24/2025  04:53 PM           406,528 qemu_q35_dxe_core.efi
               1 File(s)        406,528 bytes
               0 Dir(s)  183,428,534,272 bytes free

Project MU vs Patina FV Size Comparison

Up to this point, we have seen what constitutes the Rust DXE Core binary and how it can be optimized. This section performs a platform image-level comparison between a C-based UEFI firmware image and a Rust-based Patina UEFI firmware image. There are many components that differ between the C-based UEFI and the Rust-based UEFI images. Below is a summary of the components that have been folded into the Rust DXE Core. On the left is the size represented by the Project MU-based QEMU FV file (DxeCore, RuntimeDxe, CpuDxe), and on the right the size represented by the Patina FV file (DxeCore).

The Rust binary includes the following additional features that are not available in the C-based UEFI image, with a size increase of approximately 110 KB compared to the C-based image:

• Functionality that is typically split across multiple EFI binaries (DxeCore, RuntimeDxe, CpuDxe) in C-based implementations.
• Advanced features such as built-in source-level debugging capabilities.
• Two dispatchers: pure Rust component dispatch and FFS dispatch.
• Stringent memory protection features not present in most C-based DXE Core implementations.

Sample Table