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 ARM Virt - 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

High-Level Overview of Rust Integration

At a high level, there are two basic approaches to integrate Rust code into a UEFI build process:

1. Build the code using Rust tools in a stand-alone workspace to produce an .efi binary that is later integrated into the Firmware Device (FD) image.
2. Add support to the EDK II build infrastructure to compile the Rust source code alongside the C source code when processing each module specified in a DSC file.

The Patina project uses the first option of pre-compiling Rust-based modules to produce .efi binaries, then adding the file paths to the platform .fdf file to be ingested when creating the firmware volumes and final firmware device file.

There are several reasons why this approach was chosen:

1. The Rust toolchain is not integrated into the EDK II build system, so it is not possible to build Rust code directly from the EDK II build system without adding additional complexity to the build process.
2. Rust uses Cargo as its build system, which is opinionated about how it builds, organizes files in a workspace, and manages dependencies. This conflicts with the EDK II build system, which is also opinionated about how it builds, organizes files, and manages dependencies. The two do not complement each other.
3. Rust tooling and crate management get in the way of normal C development, forcing all C developers to understand and manage Rust toolchains and environments just to continue building C code.
4. C toolchain management and EDK II-specific build complexities get in the way of normal Rust development, coupling what is otherwise a publicly well-documented and standardized Rust build process with other systems that do not add value to Rust development.
5. Keeping C code and Rust code in a single workspace encourages the development of Rust code that is tightly coupled with C code, which is directly in opposition to the Patina goal of pure Rust UEFI firmware.
6. Using a binary allows the EDK II and C build process to be skipped entirely when just editing Rust code (with binary patching). Since the Rust build is significantly faster than an EDK II C build, this allows Rust changes to be tested in seconds instead of minutes.

Stand-Alone Build Integration

The Patina DXE Core QEMU repository provides an .efi DXE Core binary that is ingested by this repository: one binary for ArmVirt (AARCH64) and one for Q35 (X64).

The binaries are published in that repository as GitHub releases - patina-dxe-core-qemu Releases.

This repository, Patina QEMU UEFI, automatically pulls the release version specified in QemuPkg/Binaries/DXECORE.QEMU_ext_dep.json during the patina-qemu firmware build process.

The QemuQ35Pkg.fdf and QemuArmVirtPkg.fdf files both include the binary the same way, differing only in the DXE Core binary's file name (qemu_q35_dxe_core.efi vs. qemu_armvirt_dxe_core.efi). The ArmVirt version is shown below for reference:

FILE DXE_CORE = 23C9322F-2AF2-476A-BC4C-26BC88266C71 {
!ifdef $(DXE_CORE_BINARY_OVERRIDE)
  SECTION PE32 = $(DXE_CORE_BINARY_OVERRIDE)                                  # User defined override
!else
  !if $(TARGET) == RELEASE
    SECTION PE32 = $(DXE_CORE_PATH)/release/qemu_armvirt_dxe_core.efi # Nuget feed release build
  !else
    SECTION PE32 = $(DXE_CORE_PATH)/debug/qemu_armvirt_dxe_core.efi
  !endif
!endif
  SECTION UI = "DxeCore"
}

The DXE_CORE_PATH variable is automatically set by the build system to the location of the downloaded binaries.

Stand-Alone Build Options

These .fdf files also support a DXE_CORE_BINARY_OVERRIDE build variable that can be set on the command line to take precedence over the default binary:

stuart_build -c Platforms\QemuQ35Pkg\PlatformBuild.py --FlashRom BLD_*_DXE_CORE_BINARY_OVERRIDE="<new dxe core file path>"

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 Arm Virt

QemuArmVirtPkg...

• Is a derivative of ArmVirtPkg based on the QEMU ARM-Virt machine type.
• Will not support Legacy BIOS or CSM.
• Will not support S3 sleep functionality.
• Has 64-bit SEC 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.

Building and Running

QemuArmVirtPkg 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 QemuArmVirtPkg.

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 QemuArmVirtPkg 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.
• ARM Virt: defaults to None. When set, a separate virtio serial port is exposed on the specified TCP port for use by the software debugger. Log output continues to be sent to stdio regardless of this setting, consistent with Q35 where the serial port is separate from debugcon used for logging.

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 ARM Virt 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

• ✅ ArmVirt Internal Drive Windows Validation OS boot

• ✅ ArmVirt Internal Drive Ubuntu 24.04 Server OS boot

• ✅ Q35 USB Drive Windows Validation OS boot

• ✅ Q35 USB Drive Ubuntu 24.04 Server OS boot

• ✅ ArmVirt USB Drive Windows Validation OS boot

• ✅ ArmVirt USB Drive Ubuntu 24.04 Server OS boot

• ❌ Q35 PXE Windows Validation OS boot

• ❌ Q35 PXE Ubuntu 24.04 Server OS boot

• ❌ ArmVirt PXE Windows Validation OS boot

• ❌ ArmVirt 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. In addition to the nightly schedule, this workflow also runs on pull requests to catch OS boot regressions before they merge.

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
• ✅ ArmVirt advanced logger boot log gathering via UEFI application
• ❌ Q35 advanced logger boot log gathering via Windows Validation OS
• ❌ ArmVirt 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
• ❌ ArmVirt 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
• ❌ ArmVirt 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
• ❌ ArmVirt 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
• ❌ ArmVirt Release Performance Measurement tracking

Self Certification Tests

The UEFI Self Certification Tests (SCT) are an EFI application suite managed by TianoCore that allow Platform Vendors and IHVs (Independent Hardware Vendors) to test their platform's conformance to the UEFI specification.

The core managed repository is located at edk2-test and the releases section contains the associated binaries for testing. Simply pick the application type and necessary architecture.

Here is a quick rundown of the different test types provided by the SCTs. However, the focus of these instructions is to prepare the system for the UEFI SCTs.

• UEFI SCT: Focuses on Platform / System conformance to the UEFI specification, both in terms of functionality and expected interfaces (such as return values under specific circumstances).
• IHV SCT: Focuses on Device and Driver conformance to the UEFI specification.
• SCRT: Focuses on Runtime conformance to the UEFI specification.
• EMS: Focuses on network stack conformance.

There are also two execution modes available to users wishing to run the SCTs: Native mode (host only) and Passive mode (host & target).

For detailed information, refer to the User Guide.

Running the SCTs

These instructions run the SCTs in Native mode, which is to say, directly on the machine. The first thing to note is that the SCTs expect at least 100MB of free space on the disk where they are installed. The typical workflow for a physical platform is to load a USB drive with the installer, then install the SCTs to a local drive. Since this is a virtual platform, the installer is instead placed on the virtual drive and the SCTs are installed to that same location.

Build the platform

The first step is to build the platform with enough space on the virtual drive. The commands shown throughout this document are for the Q35 platform, but similar steps apply to QemuArmVirtPkg. By default, Q35 only creates a virtual drive with 60MB of space, so that default must be overridden via a build variable provided on the command line.

stuart_build -c Platforms/QemuQ35Pkg/PlatformBuild.py TARGET=RELEASE BLD_*_MEMORY_PROTECTION=FALSE VIRTUAL_DRIVE_SIZE=200 EMPTY_DRIVE=TRUE --FlashRom

Loading the SCTs on the drive

If the above command was run, QEMU should have opened, loaded to the UEFI shell, and shut down (assuming the default startup.nsh was not cancelled). If it did not close, simply close QEMU. All that mattered was that the platform was built and the drive was created.

The next step is to download the SCT binaries from the releases section of the edk2-test GitHub repository, specifically:

• For QemuQ35Pkg: SctPackageX64.7z
• For QemuArmVirtPkg: SctPackageAARCH64.tar.gz

Unzip the archive and place everything from the appropriate package at the root of the virtual hard drive created in the previous step. For Q35, this is SctPackageX64. At the root of the drive, there should now be 3 items: X64, InstallX64.efi, SctStartup.nsh. Delete STARTUP.NSH if it exists.

Install the SCTs

Now that the files are placed and the virtual drive is unmounted, load back into QEMU:

stuart_build -c Platforms/QemuQ35Pkg/PlatformBuild.py TARGET=RELEASE SHUTDOWN_AFTER_RUN=FALSE --FlashOnly

From the UEFI shell:

1. FS0:
2. InstallX64.efi

Follow the prompts to install the SCTs to the only drive space available.

Running

It is easiest to run the SCTs in user mode (a GUI). However, it is also possible to run them through the shell command line only.

The SCTs provide a User Guide covering advanced usage. A simple test run is described below.

From the root of FS0::

1. cd SCT
2. SCT -u
3. Press enter on "Test Case Management".
4. Select / deselect test groups to run by pressing space.
5. Each test group has either one or two levels of drill down. Tests or test groups can be selected / deselected at any level.
6. Press F9 to run the tests.

The below commands show how to generate a report after the tests have completed.

1. FS0:
2. cd SCT
3. SCT -u
4. Test Report Generator
5. F2
6. Type the name of the file and press enter.
7. Close QEMU.
8. Open the VHD and navigate to SCT/Report, then open the report.
9. (Optional) Logs for each test are located at SCT/Log.

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

TpmShellApp on QEMU Platforms

Platform-specific guidance for running TpmShellApp on the QEMU Q35 and Arm Virt platforms.

Table of Contents

• FDF Placement
• Protocol Availability
• Running on QEMU Arm Virt
• Running on QEMU Q35
• Hash Algorithm Configuration
• Expected Behavior with MinimumLib
• Event Log and Replay
• Findings

FDF Placement

On Arm Virt, add the INF to FV.FvMain. On Q35, add it to FV.DXEFV:

INF SecurityPkg/Applications/TpmShellApp/TpmShellApp.inf

Protocol Availability

The EFI_TCG2_PROTOCOL is installed by Tcg2Dxe.efi, which only loads when TPM2_ENABLE=TRUE.

Running on QEMU Arm Virt

On QEMU Arm Virt, the TpmShellApp is placed directly in the firmware volume, which is mapped as an FSx: device in the UEFI shell. Build with:

stuart_build -c Platforms/QemuArmVirtPkg/PlatformBuild.py --FlashRom BLD_*_TPM2_ENABLE=TRUE

At the UEFI shell, run:

Shell> TpmShellApp.efi help
Shell> TpmShellApp.efi info
Shell> TpmShellApp.efi eventlog
Shell> TpmShellApp.efi replay

Or navigate to the correct FS mapping first:

Shell> map -r
Shell> FS0:
FS0:\> TpmShellApp.efi info

Running on QEMU Q35

On Q35, shell applications are loaded from a virtual drive (FAT filesystem image), not directly from the firmware volume. The FILE_REGEX build parameter controls which binaries are copied to the virtual drive:

stuart_build -c Platforms/QemuQ35Pkg/PlatformBuild.py --FlashRom \
  BLD_*_TPM2_ENABLE=TRUE \
  FILE_REGEX=TpmShellApp.efi

At the UEFI shell, find the virtual drive's FS mapping (typically backed by a PCI device, not Fv(...)) and run:

Shell> map -r
Shell> FS0:
FS0:\> TpmShellApp.efi info

If the app is not found, verify the virtual drive was created with the binary:

Shell> FS0:
FS0:\> dir

Hash Algorithm Configuration

Both QEMU platforms set PcdTpm2HashMask to 0x02 (SHA256 only). This means the app will typically only see SHA256 as supported and active, even though swtpm may support all five algorithms. To see additional algorithms, update PcdTpm2HashMask in the platform DSC.

Expected Behavior with MinimumLib

Both QEMU platforms use DxeTcg2PhysicalPresenceMinimumLib when TPM is enabled. This library has specific behaviors that affect TpmShellApp results:

setpcr with Already-Active Banks

When the requested banks match the currently active banks, Tcg2Dxe sends TCG2_PHYSICAL_PRESENCE_NO_ACTION to the PP library. MinimumLib processes NO_ACTION successfully, returning EFI_SUCCESS.

Shell> TpmShellApp setpcr 0x2    (SHA256 already active)
Submitting SetActivePcrBanks with parameter 2
Status: Success
Request submitted. Changes will take effect after reboot.

setpcr with Different Banks

When the requested banks differ from active banks, Tcg2Dxe sends TCG2_PHYSICAL_PRESENCE_SET_PCR_BANKS to the PP library. MinimumLib rejects this operation as it only supports Clear operations.

Shell> TpmShellApp setpcr 0x4    (SHA384, not currently active)
Submitting SetActivePcrBanks with parameter 4
Status: Unsupported
SetActivePcrBanks failed.

This is expected and correct behavior — MinimumLib is designed to block PCR bank changes.

logall Expected Behavior

If the platform only has SHA256 registered (default), logall requests the same bank that's already active, resulting in a NO_ACTION → EFI_SUCCESS. If additional algorithms were registered, it would request banks different from the active set, triggering a SET_PCR_BANKS rejection.

lastresponse Expected Behavior

Reports the result stored in the Tcg2PhysicalPresence NV variable by ProcessRequest. If no prior SetActivePcrBanks was processed through a reboot cycle, the response will show no operation present.

Shell> TpmShellApp lastresponse
  Operation present: NO
  Response code:     0

Event Log and Replay

eventlog on QEMU

The eventlog command dumps the crypto-agile TCG2 event log. On QEMU with the default SHA256-only configuration, each event contains a single SHA256 digest.

Shell> TpmShellApp.efi eventlog

[TCG2 Event Log]

Spec ID Event: 1 algorithm(s)
  SHA256 (alg 0xb, digest 32 bytes)

Event 1: PCR 0 EV_S_CRTM_VERSION (0x8)
  SHA256: ab cd ef ...
  Event data: 2 bytes
Event 2: PCR 0 EV_EFI_PLATFORM_FIRMWARE_BLOB (0x80000008)
  SHA256: 01 23 45 ...
  Event data: 16 bytes
...
Total: N event(s)

If PcdTpm2HashMask is updated to enable additional algorithms (e.g., 0x06 for SHA256 + SHA384), each event will contain multiple digests — one per active algorithm.

replay on QEMU

The replay command replays extend operations from the event log to compute expected PCR values, then reads the actual PCR values from the TPM via SubmitCommand and compares them.

Shell> TpmShellApp.efi replay

[Event Log Replay]

Replayed N event(s) across 1 algorithm(s).

PCR 0:
  SHA256 Replayed: aa bb cc ...
  SHA256 Actual:   aa bb cc ...
  Result: PASS

PCR 1:
  SHA256 Replayed: 11 22 33 ...
  SHA256 Actual:   11 22 33 ...
  Result: PASS

...
Summary: M PCR bank(s) verified, M PASS, 0 FAIL

On a freshly booted QEMU platform with swtpm, all PCRs should show PASS. A FAIL indicates that either the event log is incomplete (e.g., truncated) or an extend operation occurred outside the logged event flow.

Replay with Multiple Algorithms

When multiple hash algorithms are active, the replay verifies each algorithm independently. Algorithms not supported by BaseCryptLib (e.g., SM3_256) are skipped with a message:

PCR 0:
  SHA256 Replayed: ...
  SHA256 Actual:   ...
  Result: PASS
  SM3_256: (replay not supported, skipped)

Truncated Event Log

If the firmware's event log buffer was exhausted, the eventlog and replay commands print a warning:

Warning: Event log was truncated.

For replay, a truncated log means the replayed PCR values will not include all extensions, so mismatches are expected.

Findings

April 2026:

Example:

• Tpm2HashMask is updated to 0x06 (i.e. SHA256 + SHA384 supported).

• SHA384 support is removed from Tcg2Pei and Tcg2Dxe.

• Build/Run the Q35 platform.

• TPM reports SHA256 as the only active PCR bank.

• Tcg2Pei recognizes there is a mismatch between platform support (i.e. Tpm2HashMask) and TPM active banks. It activates SHA384 and triggers a ResetCold.

• TPM reports SHA256 + SHA384 as active PCR banks.

• HashLibBaseCryptoRouterPei and HashLibBaseCryptoRouterDxe set PcdTcg2HashAlgorithmBitmap based on successfully registered hash algorithms.

• Tcg2Pei registers SHA256 but is unable to register SHA384.

• Tcg2Dxe registers SHA256 but is unable to register SHA384.

• Tcg2Dxe sets local variables based on what the TPM reports and PcdTcg2HashAlgorithmBitmap.

  mTcgDxeData.BsCap.HashAlgorithmBitmap = TpmHashAlgorithmBitmap & PcdGet32 (PcdTcg2HashAlgorithmBitmap);
  mTcgDxeData.BsCap.ActivePcrBanks      = ActivePCRBanks & PcdGet32 (PcdTcg2HashAlgorithmBitmap);
  

• Tcg2Protocol is installed with only SHA256 support reported even though SHA384 is active.

TPM on QEMU Arm Virt

This document describes the TPM 2.0 architecture for the QEMU Arm Virt platform. Arm Virt uses a dual-CRB design with an FF-A (Firmware Framework for Arm A-Profile) mediated communication path between the normal world and the secure world.

Table of Contents

• Requirements
• Build Configuration
• Platform Memory Layout
• Architecture Overview
• Secure Partitions
• CRB Regions
• FF-A Communication Protocol
• Hash Library Architecture
• Physical Presence Interface
• ACPI Integration
• swtpm Setup
• Communication Flow
• PCDs Reference

Requirements

See swtpm Setup for the full setup commands.

Build Configuration

The TPM is disabled by default. To enable it, set BLD_*_TPM2_ENABLE=TRUE on the command line or in a BuildConfig.conf file placed at the root level of the repo:

stuart_build -c Platforms/QemuArmVirtPkg/PlatformBuild.py --FlashRom BLD_*_TPM2_ENABLE=TRUE

The following defines control TPM behavior in QemuArmVirtPkg.dsc:

When TPM2_ENABLE=TRUE, the build additionally passes -DTPM2_ENABLE to the C compiler via build options, allowing C code to use #ifdef TPM2_ENABLE guards.

Platform Memory Layout

The Arm Virt platform defines two distinct TPM memory regions:

The Internal CRB address is published via PCDs:

• PcdTpmBaseAddress = 0x40200000
• PcdTpmMaxAddress = 0x40204FFF (5 localities × 0x1000)

The Internal CRB is marked as EfiACPIMemoryNVS via a HOB in ArmPlatformLibQemu.c so the OS can locate it through the ACPI TPM2 table.

Architecture Overview

┌──────────────────────────────────────────────────────────────────────────────────┐
│ UEFI Firmware (AARCH64)                                                          │
│                                                                                  │
│  ┌─── SEC Phase ──────────────────────────────────────────────────────────────┐  │
│  │                                                                            │  │
│  │  Tpm2StartupLib                                                            │  │
│  │    │ 1. Tpm2RequestUseTpm()                                                │  │
│  │    │ 2. Tpm2Startup(TPM_SU_CLEAR)                                          │  │
│  └────┼───────────────────────────────────────────────────────────────────────┘  │
│       ▼                                                                          │
│  ┌─── DXE Phase ──────────────────────────────────────────────────────────────┐  │
│  │                                                                            │  │
│  │  HashLibBaseCryptoRouterDxe + HashInstanceLib*                             │  │
│  │    │ 1. Constructors register each enabled hash algorithm                  │  │
│  │    │ 2. Filtered by PcdTpm2HashMask → PcdTcg2HashAlgorithmBitmap           │  │
│  │    ▼                                                                       │  │
│  │  Tcg2Dxe                                                                   │  │
│  │    │ 1. Verify PcdTpmInstanceGuid is TPM 2.0                               │  │
│  │    │ 2. Verify no TpmErrorHob is present                                   │  │
│  │    │ 3. Tpm2RequestUseTpm()                                                │  │
│  │    │ 4. Query TPM capabilities                                             │  │
│  │    │     ├── Manufacturer                                                  │  │
│  │    │     ├── Firmware version                                              │  │
│  │    │     └── Max cmd/resp size                                             │  │
│  │    │ 5. Get supported/active PCR banks filtered by → HashAlgorithmBitmap   │  │
│  │    │ 6. Decide SupportedEventLogs (TCG_1_2 only if SHA1 active)            │  │
│  │    │ 7. SetupEventLog                                                      │  │
│  │    │     ├── Allocate log area(s)                                          │  │
│  │    │     └── Acquire and log pre-DXE HOB(s)                                │  │
│  │    │ 8. Register events                                                    │  │
│  │    │     ├── ReadyToBoot                                                   │  │
│  │    │     ├── ExitBootServices                                              │  │
│  │    │     └── ExitBootServices Failed                                       │  │
│  │    │ 9. Register protocol notifies                                         │  │
│  │    │     ├── VariableWriteArch (SecureBoot)                                │  │
│  │    │     └── ResetNotification (TPM shutdown)                              │  │
│  │    │ 10. Install Tcg2Protocol                                              │  │
│  │    ▼                                                                       │  │
│  │  Tcg2AcpiFfa                                                               │  │
│  │    │ 1. Publish TPM2 ACPI table                                            │  │
│  │    │ 2. Publish SSDT with TPM0 device node                                 │  │
│  └────┼───────────────────────────────────────────────────────────────────────┘  │
│       ▼                                                                          │
│  ┌─── BDS Phase ──────────────────────────────────────────────────────────────┐  │
│  │                                                                            │  │
│  │  DeviceBootManagerAfterConsole                                             │  │
│  │    │ 1. Tcg2PhysicalPresenceLibProcessRequest (NULL)                       │  │
│  │    │ 2. Process any pending PP request before shell launch                 │  │
│  │    │ 3. Create TCG2_PHYSICAL_PRESENCE_VARIABLE if it doesn't exist         │  │
│  └────┼───────────────────────────────────────────────────────────────────────┘  │
│       ▼                                                                          │
│  ┌─── UEFI Shell ─────────────────────────────────────────────────────────────┐  │
│  │                                                                            │  │
│  │  UEFI Shell / OS / TpmShellApp                                             │  │
│  │    │ 1. gBS->LocateProtocol(&gEfiTcg2ProtocolGuid)                         │  │
│  │    │ 2. Tcg2Protocol->GetCapability / SetActivePcrBanks / etc.             │  │
│  └────┼───────────────────────────────────────────────────────────────────────┘  │
│       ▼                                                                          │
│  Tpm2DeviceLibFfa ─ writes to Internal CRB @ 0x40200000                          │
│       │             then sends FF-A DirectReq2 to the TpmService                 │
│       │                                                                          │
├───────┼──────────────────────────────────────────────────────────────────────────┤
│ EL3 (SPMC / TF-A) ─ routes FF-A message to partition 0x8002                      │
├───────┼──────────────────────────────────────────────────────────────────────────┤
│       ▼                                                                          │
│ SECURE WORLD (SEL1)                                                              │
│                                                                                  │
│  MSSP (MsSecurePartition, id=0x8002)                                             │
│       │                                                                          │
│       ▼                                                                          │
│  TpmServiceLib ─ State machine (IDLE → READY → COMPLETE → IDLE)                  │
│       │                                                                          │
│       ▼                                                                          │
│  TpmServiceStateTranslationLib ─ Translates CRB style communications             │
│       │                          to the style supported by the TPM               │
│       │                          i.e. FIFO for QEMU Arm Virt                     │
│       │  Library Responsibilities:                                               │
│       │  1. Copy command from Internal CRB → local buffer                        │
│       │  2. Write command to External CRB @ 0x0c000000                           │
│       │  3. Trigger execution on external TPM through the CRB MMIO               │
│       │  4. Read response from External CRB                                      │
│       │  5. Copy response back to Internal CRB                                   │
│       │                                                                          │
├───────┼──────────────────────────────────────────────────────────────────────────┤
│       ▼                                                                          │
│  QEMU TPM device (MMIO @ 0x0c000000)                                             │
│       │                                                                          │
│       ▼                                                                          │
│  Unix socket ─ swtpm process (--tpm2)                                            │
└──────────────────────────────────────────────────────────────────────────────────┘

Secure Partitions

Two FF-A Secure Partitions are involved in TPM operations.

MSSP — Microsoft Secure Services Partition (id=0x8002)

Configured in Platforms/QemuArmVirtPkg/fdts/qemu_virt_mssp_rust_config.dts:

The MSSP hosts the TPM service and is granted access to both CRB regions:

device-regions {
    internal_tpm_crb {
        base-address = <0x40200000>;
        pages-count = <0x10>;
        attributes = <SECURE_RW>;
    };
    external_tpm_crb {
        base-address = <0x0c000000>;
        pages-count = <0x10>;
        attributes = <SECURE_RW>;
    };
};

The MSSP publishes three service UUIDs. The TPM service UUID is:

17b862a4-1806-4faf-86b3-089a58353861

Key libraries running inside the MSSP:

• TpmServiceLib — handles incoming FF-A messages, implements the CRB state machine (IDLE → cmdReady → READY → start → COMPLETE → goIdle → IDLE). Note that this service is based on the CRB over FF-A specification released by ARM. See: TPM Service Command Response Buffer Interface Over FF-A
• TpmServiceStateTranslationLib — translates between the Internal CRB (CRB interface) and the External CRB (which may be CRB or FIFO depending on QEMU configuration). On QEMU Arm Virt the external interface is FIFO.

StMM — Standalone MM Partition (id=0x8001)

Configured in Platforms/QemuArmVirtPkg/fdts/qemu_virt_stmm_config.dts:

The StMM partition hosts secure variable storage (FTW, VariableRuntimeDxe), and the Tcg2StandaloneMmArm driver which processes Physical Presence Interface commands from the normal world for NV variable access.

CRB Regions

CRB Register Layout (PTP CRB Interface)

Each locality occupies 0x1000 bytes. The CRB register layout is defined by the TCG PC Client Platform TPM Profile (PTP) specification (and mirrored in TpmPtp.h):

• TCG PC Client Platform TPM Profile (PTP) Specification — Section 6 "Command Response Buffer Interface" describes LocalityState, LocalityControl, InterfaceId, CrbControlRequest, CrbControlStart, CrbControlCommand*/CrbControlResponse*, and the shared CrbDataBuffer.

Internal CRB (0x40200000)

This is the CRB visible to normal-world firmware (DXE drivers and UEFI applications). Tpm2DeviceLibFfa writes TPM commands into this CRB's data buffer and reads responses from it. The Internal CRB uses the standard CRB register interface. It is the TPM service's responsibility to set up and maintain this region. The goal is for this region to mimic a normal MMIO CRB region, with the added caveat that an FF-A message must be sent for any register modification to take effect.

The normal-world code performs MMIO writes to the CRB control registers (cmdReady, Start, goIdle) and then sends FF-A messages to notify the secure partition. The secure partition reads the command data from the Internal CRB, proxies it to the External CRB, and writes the response back.

External CRB (0x0c000000)

This is the QEMU-emulated TPM device MMIO region. It is only accessible from the secure world i.e. the TPM Service within the MSSP secure partition. On QEMU Arm Virt, this region presents a FIFO interface (not CRB), which the TpmServiceStateTranslationLib handles by detecting the interface type at initialization and using the appropriate FIFO command/response protocol (burst-count reads, data register writes).

The external CRB connects to the swtpm process through QEMU's chardev/tpmdev infrastructure:

QEMU args: -chardev socket,id=chrtpm,path={BUILD_OUTPUT_BASE}/swtpm-sock
           -tpmdev emulator,id=tpm0,chardev=chrtpm

FF-A Communication Protocol

All TPM commands from normal world to secure world use FF-A Direct Request/Response messaging (FFA_MSG_SEND_DIRECT_REQ2 / FFA_MSG_SEND_DIRECT_RESP2) to/from the TPM Service.

Service Discovery

On first use, Tpm2DeviceLibFfa discovers the TPM service partition:

ArmFfaLibGetPartitionInfo(&gTpm2ServiceFfaGuid, &TpmPartInfo);

This queries the SPMC (EL3) for the partition hosting UUID 17b862a4-1806-4faf-86b3-089a58353861, which returns partition ID 0x8002. This information can be found in the manifest of the secure partition.

Function IDs

The TPM2_FFA_START function carries a qualifier in Arg1:

The TPM2_FFA_MANAGE_LOCALITY function carries a qualifier in Arg1:

Note that for both TPM2_FFA_START and TPM2_FFA_MANAGE_LOCALITY Arg2 specifies the locality to take action upon.

FF-A Message Sequence (Per TPM Command)

A locality must first be requested before any commands can be sent to the TPM via that locality's CRB region. The active locality must be relinquished before another locality is requested. The entity currently engaging with the TPM is responsible for relinquishing the active locality when it is no longer in use. If the locality being requested is CLOSED, a DENIED error is returned. If the locality being relinquished is not the current active locality, a DENIED error is returned.

A single TPM command requires multiple FF-A round trips:

sequenceDiagram
    participant NW as Normal World
    participant SW as Secure World (MSSP)

    Note over NW: Write LocalityControl = request access
    NW->>SW: FFA DirectReq2(START, LOCALITY)
    Note over SW: LocalityX becomes active
    SW-->>NW: FFA DirectResp2(SUCCESS)

    Note over NW: Write CrbControlRequest = cmdReady
    NW->>SW: FFA DirectReq2(START, COMMAND)
    Note over SW: State: IDLE → READY<br/>(prepare external TPM)
    SW-->>NW: FFA DirectResp2(SUCCESS)

    Note over NW: Write command to CrbDataBuffer<br/>Write CrbControlStart = 1
    NW->>SW: FFA DirectReq2(START, COMMAND)
    Note over SW: State: READY → COMPLETE<br/>• Copy cmd from Internal CRB<br/>• Write cmd to External CRB<br/>• Trigger external TPM<br/>• Read response from External CRB<br/>• Copy response to Internal CRB
    SW-->>NW: FFA DirectResp2(SUCCESS)

    Note over NW: Read response from CrbDataBuffer<br/>Write CrbControlRequest = goIdle
    NW->>SW: FFA DirectReq2(START, COMMAND)
    Note over SW: State: COMPLETE → IDLE<br/>(idle external TPM)
    SW-->>NW: FFA DirectResp2(SUCCESS)

    rect rgba(200, 200, 200, 0.2)
        Note over NW,SW: OPTIONAL
        Note over NW: Write LocalityControl = relinquish access
        NW->>SW: FFA DirectReq2(START, LOCALITY)
        Note over SW: LocalityX is relinquished
        SW-->>NW: FFA DirectResp2(SUCCESS)
    end

If the secure partition is preempted by a non-secure interrupt during processing, the FF-A call returns EFI_INTERRUPT_PENDING. The normal-world code handles this by calling ArmFfaLibRun() in a loop until the operation completes. Note that this can only happen if ns-interrupts-action in the secure partition's manifest is set to 0x02, otherwise, the non-secure interrupt is queued and the service continues execution until it completes or responds with a YIELD.

Hash Library Architecture

Tcg2Dxe uses HashLibBaseCryptoRouterDxe with all hash instance libraries included.

Registration Flow

1. HashLibBaseCryptoRouterConstructor resets PcdTcg2HashAlgorithmBitmap to 0.
2. Each HashInstanceLib constructor calls RegisterHashInterfaceLib().
3. RegisterHashInterfaceLib() checks the algorithm against PcdTpm2HashMask (0x02 = SHA256 only). Algorithms not in the mask return EFI_UNSUPPORTED.

Hash Algorithm Bitmask Values

The bit positions used in PcdTpm2HashMask, PcdTcg2HashAlgorithmBitmap, and the EFI_TCG2_BOOT_SERVICE_CAPABILITY.HashAlgorithmBitmap field are defined by the EFI TCG2 protocol and the TCG algorithm registry:

• UEFI TCG2 Protocol Specification — see EFI_TCG2_BOOT_HASH_ALG_* (SHA1 = BIT0, SHA256 = BIT1, SHA384 = BIT2, SHA512 = BIT3, SM3_256 = BIT4).
• TCG Algorithm Registry — canonical list of TPM hash algorithm IDs.

For this platform, PcdTpm2HashMask = 0x02 enables SHA256 only.

Filtering Chain

PcdTpm2HashMask (0x02)
        │
        ▼
RegisterHashInterfaceLib() ── gates which HashInstanceLibs register
        │
        ▼
PcdTcg2HashAlgorithmBitmap ── result of all successful registrations
        │
        ▼
Tcg2Dxe intersects with TPM-reported capabilities
        │
        ▼
Final ActivePcrBanks / HashAlgorithmBitmap in EFI_TCG2_BOOT_SERVICE_CAPABILITY

Physical Presence Interface

Library Selection

The MinimumLib implementation:

• Auto-confirms TPM Clear operations without user prompting.
• Rejects SET_PCR_BANKS, LOG_ALL_DIGESTS, and other operations with TCG_PP_RETURN_TPM_OPERATION_RESPONSE_FAILURE.
• Does not create or use TCG2_PHYSICAL_PRESENCE_FLAGS_VARIABLE.

ProcessRequest in BDS

Tcg2PhysicalPresenceLibProcessRequest() is invoked from the platform's DeviceBootManagerLib during DeviceBootManagerAfterConsole(), before the shell launches. It:

1. Reads the Tcg2PhysicalPresence NV variable (creates it if missing).
2. Executes any pending PP request stored in the variable.
3. Stores the result back for ReturnOperationResponseToOsFunction() to report.

Tcg2StandaloneMmArm (Secure World)

The Tcg2StandaloneMmArm driver runs in the StMM partition (id=0x8001). It handles Physical Presence NV variable operations when called from the DXE-phase PP library via MM communicate. This is necessary because NV variable writes go through the secure variable store in StMM.

ACPI Integration

TPM2 ACPI Table

Published by Tcg2AcpiFfa.c:

TPM ACPI Device (SSDT)

An SSDT is published with a TPM0 device node containing:

• _HID patched with the TPM manufacturer ID read from hardware.
• _CRS with a QWordMemory resource pointing to PcdTpmBaseAddress through PcdTpmMaxAddress.
• _DSM implementing TCG PPI operations 1–8 for OS-initiated Physical Presence requests.
• An FFixedHw OperationRegion for FF-A DirectReq2 passthrough from the OS.

swtpm Setup

Installation

swtpm requires Unix sockets, so it must run in a Linux environment. On Windows, use WSL (Windows Subsystem for Linux).

# Windows (from a WSL terminal)
wsl --install          # if WSL is not yet enabled
wsl                    # enter the WSL environment

# Ubuntu/Debian (native or WSL)
sudo apt install swtpm swtpm-tools

# Fedora
sudo dnf install swtpm swtpm-tools

Manual Setup

Create the TPM state directory and start swtpm before launching QEMU:

mkdir -p /tmp/mytpm1
swtpm socket \
  --tpmstate dir=/tmp/mytpm1 \
  --ctrl type=unixio,path=/tmp/mytpm1/swtpm-sock \
  --tpm2 \
  --log level=20

Automatic Setup (QemuRunner)

When SWTPM_ENABLE=TRUE, QemuRunner.py automatically starts swtpm as a subprocess before launching QEMU. The swtpm state directory is set to BUILD_OUTPUT_BASE and the Unix socket is placed at {BUILD_OUTPUT_BASE}/swtpm-sock:

# Platforms/QemuArmVirtPkg/Plugins/QemuRunner/QemuRunner.py
@staticmethod
def StartSwTpm(tpm_dir, tpm_sock):
    """Starts the swtpm emulator and returns its Popen handle."""
    cmd = [
        "swtpm", "socket",
        "--tpmstate", f"dir={tpm_dir}",
        "--ctrl", f"type=unixio,path={tpm_sock}",
        "--tpm2",
        "--log", "level=1",
    ]
    return subprocess.Popen(cmd)

swtpm is started before QEMU launches. QemuRunner then waits (up to 30 seconds) for the Unix socket to appear before starting QEMU, and terminates the swtpm process so it doesn't outlive the run. SWTPM is enabled by default. Disable it by setting SWTPM_ENABLE=FALSE on the command line or in the BuildConfig.conf file.

QEMU Arguments

When SWTPM_ENABLE=TRUE, QemuRunner.py adds the following to the QEMU command line (with the socket path under BUILD_OUTPUT_BASE):

-chardev socket,id=chrtpm,path={BUILD_OUTPUT_BASE}/swtpm-sock
-tpmdev emulator,id=tpm0,chardev=chrtpm
-device tpm-tis-device,tpmdev=tpm0

The -device tpm-tis-device argument is Arm-specific. It attaches a sysbus TIS-compatible TPM device to the Arm Virt machine at the Internal CRB address 0x40200000. This differs from Q35, which uses the ISA/PCI tpm-tis device instead (see TPM on QEMU Q35).

Communication Flow

Complete path from a shell application to swtpm:

TpmShellApp (UEFI Shell)
  │ gBS->LocateProtocol(&gEfiTcg2ProtocolGuid)
  │ Tcg2Protocol->SetActivePcrBanks(0x02)
  ▼
Tcg2Dxe (EFI_TCG2_PROTOCOL)
  │ Validates bank mask against HashAlgorithmBitmap
  │ Calls Tcg2PhysicalPresenceLibSubmitRequestToPreOSFunction()
  │   ├── MinimumLib: rejects SET_PCR_BANKS → returns EFI_UNSUPPORTED
  │   └── MinimumLib: NO_ACTION (already-active) → writes to NV variable → EFI_SUCCESS
  ▼
Tpm2CommandLib (for direct TPM commands like GetCapability)
  │ Serializes TPM2_CC command structure into byte buffer
  │ Calls Tpm2SubmitCommand(cmdBuffer, cmdSize, rspBuffer, &rspSize)
  ▼
Tpm2DeviceLibFfa — FfaTpm2SubmitCommand()
  │ PtpCrbTpmCommand(CrbReg = PcdTpmBaseAddress)
  │
  │ ┌─ STEP 1: cmdReady ──────────────────────────────────────────┐
  │ │  MmioWrite32(&CrbReg->CrbControlRequest, PTP_CRB_CONTROL    │
  │ │              _AREA_REQUEST_COMMAND_READY)                   │
  │ │  Tpm2ServiceStart(QUALIFIER_COMMAND, 0) ── FF-A ──► MSSP    │
  │ └─────────────────────────────────────────────────────────────┘
  │
  │ ┌─ STEP 2: submit ────────────────────────────────────────────┐
  │ │  CopyMem(CrbReg->CrbDataBuffer, cmdBuffer, cmdSize)         │
  │ │  MmioWrite32(&CrbReg->CrbControlStart, 1)                   │
  │ │  Tpm2ServiceStart(QUALIFIER_COMMAND, 0) ── FF-A ──► MSSP    │
  │ └─────────────────────────────────────────────────────────────┘
  │
  │                    ════ WORLD SWITCH ════
  │
  │   MSSP (secure world, partition 0x8002):
  │     TpmServiceLib: state READY → execute
  │     TpmServiceStateTranslationLib:
  │       1. Read command from Internal CRB data buffer
  │       2. CopyCommandData() → write to External CRB @ 0x0c000000 (FIFO)
  │       3. StartCommand() → trigger TPM execution
  │       4. CopyResponseData() → read response from External CRB
  │       5. Write response to Internal CRB data buffer
  │
  │                    ════ QEMU MMIO ════
  │
  │     QEMU TPM device @ 0x0c000000
  │       └── Unix socket ──── swtpm process
  │
  │                    ════ WORLD SWITCH BACK ════
  │
  │ ┌─ STEP 3: goIdle ────────────────────────────────────────────┐
  │ │  Read response from CrbReg->CrbDataBuffer                   │
  │ │  MmioWrite32(&CrbReg->CrbControlRequest, PTP_CRB_CONTROL    │
  │ │              _AREA_REQUEST_GO_IDLE)                         │
  │ │  Tpm2ServiceStart(QUALIFIER_COMMAND, 0) ── FF-A ──► MSSP    │
  │ └─────────────────────────────────────────────────────────────┘
  ▼
Response returned to caller

PCDs Reference

Required PCDs (set when TPM2_ENABLE=TRUE)

Memory Type PCDs

Conditional PCDs (TPM2_CONFIG_ENABLE=TRUE)

TPM on QEMU Q35

This document describes the TPM 2.0 architecture for the QEMU Q35 platform. Q35 uses a direct CRB/FIFO path between firmware and the TPM device.

Table of Contents

• Requirements
• Build Configuration
• Platform Memory Layout
• Architecture Overview
• TPM Device Library Stack
• Hash Library Architecture
• Physical Presence Interface
• swtpm Setup
• Communication Flow
• PCDs Reference

Requirements

See swtpm Setup for the full setup commands.

Build Configuration

The TPM is disabled by default. To enable it, set BLD_*_TPM2_ENABLE=TRUE on the command line or in a BuildConfig.conf file placed at the root level of the repo:

stuart_build -c Platforms/QemuQ35Pkg/PlatformBuild.py --FlashRom BLD_*_TPM2_ENABLE=TRUE

The following defines control TPM behavior in QemuQ35Pkg.dsc:

Platform Memory Layout

Q35 uses the standard x86 TPM memory-mapped I/O region:

The firmware communicates directly with the TPM device via MMIO, and QEMU forwards the I/O to swtpm over a Unix socket.

The base address comes from the SecurityPkg package declaration default (PcdTpmBaseAddress = 0xFED40000). The Q35 DSC does not override it explicitly. The Tcg2ConfigPei driver detects the TPM at this address during PEI.

Architecture Overview

┌──────────────────────────────────────────────────────────────────────────────────┐
│ UEFI Firmware (x86_64)                                                           │
│                                                                                  │
│  ┌─── PEI Phase ──────────────────────────────────────────────────────────────┐  │
│  │                                                                            │  │
│  │  Tcg2ConfigPei                                                             │  │
│  │    │ 1. Detect TPM 1.2 vs 2.0 at 0xFED40000                                │  │
│  │    │ 2. Set PcdTpmInstanceGuid                                             │  │
│  │    ▼                                                                       │  │
│  │  HashLibBaseCryptoRouterPei + HashInstanceLib*                             │  │
│  │    │ 1. Constructors register each enabled hash algorithm                  │  │
│  │    │ 2. Filtered by PcdTpm2HashMask → PcdTcg2HashAlgorithmBitmap           │  │
│  │    ▼                                                                       │  │
│  │  Tcg2Pei                                                                   │  │
│  │    │ 1. Tpm2RequestUseTpm()                                                │  │
│  │    │ 2. Tpm2Startup(TPM_SU_CLEAR)                                          │  │
│  │    │ 3. SyncPcrAllocationsAndPcrMask()                                     │  │
│  │    │ 4. Tpm2SelfTest()                                                     │  │
│  │    │ 5. Measure firmware volumes (CRTM) into PCR[0-7]                      │  │
│  │    │ 6. Install TpmInitializedPpi                                          │  │
│  └────┼───────────────────────────────────────────────────────────────────────┘  │
│       ▼                                                                          │
│  ┌─── DXE Phase ──────────────────────────────────────────────────────────────┐  │
│  │                                                                            │  │
│  │  HashLibBaseCryptoRouterDxe + HashInstanceLib*                             │  │
│  │    │ 1. Constructors register each enabled hash algorithm                  │  │
│  │    │ 2. Filtered by PcdTpm2HashMask → PcdTcg2HashAlgorithmBitmap           │  │
│  │    ▼                                                                       │  │
│  │  Tcg2Dxe                                                                   │  │
│  │    │ 1. Verify PcdTpmInstanceGuid is TPM 2.0                               │  │
│  │    │ 2. Verify no TpmErrorHob is present                                   │  │
│  │    │ 3. Tpm2RequestUseTpm()                                                │  │
│  │    │ 4. Query TPM capabilities                                             │  │
│  │    │     ├── Manufacturer                                                  │  │
│  │    │     ├── Firmware version                                              │  │
│  │    │     └── Max cmd/resp size                                             │  │
│  │    │ 5. Get supported/active PCR banks filtered by → HashAlgorithmBitmap   │  │
│  │    │ 6. Decide SupportedEventLogs (TCG_1_2 only if SHA1 active)            │  │
│  │    │ 7. SetupEventLog                                                      │  │
│  │    │     ├── Allocate log area(s)                                          │  │
│  │    │     └── Acquire and log pre-DXE HOB(s)                                │  │
│  │    │ 8. Register events                                                    │  │
│  │    │     ├── ReadyToBoot                                                   │  │
│  │    │     ├── ExitBootServices                                              │  │
│  │    │     └── ExitBootServices Failed                                       │  │
│  │    │ 9. Register protocol notifies                                         │  │
│  │    │     ├── VariableWriteArch (SecureBoot)                                │  │
│  │    │     └── ResetNotification (TPM shutdown)                              │  │
│  │    │ 10. Install Tcg2Protocol                                              │  │
│  └────┼───────────────────────────────────────────────────────────────────────┘  │
│       ▼                                                                          │
│  ┌─── BDS Phase ──────────────────────────────────────────────────────────────┐  │
│  │                                                                            │  │
│  │  DeviceBootManagerAfterConsole                                             │  │
│  │    │ 1. Tcg2PhysicalPresenceLibProcessRequest (NULL)                       │  │
│  │    │ 2. Process any pending PP request before shell launch                 │  │
│  │    │ 3. Create TCG2_PHYSICAL_PRESENCE_VARIABLE if it doesn't exist         │  │
│  └────┼───────────────────────────────────────────────────────────────────────┘  │
│       ▼                                                                          │
│  ┌─── UEFI Shell ─────────────────────────────────────────────────────────────┐  │
│  │                                                                            │  │
│  │  UEFI Shell / OS / TpmShellApp                                             │  │
│  │    │ 1. gBS->LocateProtocol(&gEfiTcg2ProtocolGuid)                         │  │
│  │    │ 2. Tcg2Protocol->GetCapability / SetActivePcrBanks / etc.             │  │
│  └────┼───────────────────────────────────────────────────────────────────────┘  │
│       ▼                                                                          │
│  Tpm2DeviceLibDTpm ─ direct MMIO reads/writes to 0xFED40000                      │
│       │                                                                          │
├───────┼──────────────────────────────────────────────────────────────────────────┤
│       ▼                                                                          │
│  QEMU TPM TIS device (-device tpm-tis,tpmdev=tpm0)                               │
│       │                                                                          │
│       ▼                                                                          │
│  Unix socket ─ swtpm process (--tpm2)                                            │
└──────────────────────────────────────────────────────────────────────────────────┘

TPM Device Library Stack

Q35 uses two different patterns for accessing the TPM, depending on the firmware phase:

PEI Phase: Direct MMIO (Tpm2DeviceLibDTpm)

Tcg2Pei
  │ Tpm2SubmitCommand()
  ▼
Tpm2DeviceLibDTpm
  │ Auto-detects CRB vs TIS vs FIFO via InterfaceId register
  │ DTpm2SubmitCommand() dispatches:
  │   CRB  → PtpCrbTpmCommand()
  │   FIFO → Tpm2TisTpmCommand()
  │   TIS  → Tpm2TisTpmCommand()
  ▼
Direct MMIO to 0xFED40000

Tpm2DeviceLibDTpm reads the InterfaceId register at PcdTpmBaseAddress + 0x30 to determine the interface type. QEMU's tpm-tis device presents a TIS/FIFO interface.

DXE Phase: Router Pattern (Tpm2DeviceLibRouter)

Tcg2Dxe
  │ Tpm2SubmitCommand()
  ▼
Tpm2DeviceLibRouterDxe
  │ Delegates to registered TPM2_DEVICE_INTERFACE
  ▼
Tpm2InstanceLibDTpm (constructor registers with router)
  │ DTpm2SubmitCommand() — same dispatch as PEI
  ▼
Direct MMIO to 0xFED40000

The router pattern exists to support future scenarios where multiple TPM device types could coexist. The router accepts only the instance whose ProviderGuid matches PcdTpmInstanceGuid.

Other DXE Drivers: TCG2 Protocol (Tpm2DeviceLibTcg2)

Most DXE drivers that need TPM access use Tpm2DeviceLibTcg2, which goes through the TCG2 Protocol rather than direct MMIO. Only Tcg2Dxe itself uses Tpm2DeviceLibRouter with direct MMIO.

CRB Register Layout

If the TPM presents a CRB interface (as opposed to TIS/FIFO), the register layout is defined by the TCG PC Client Platform TPM Profile (PTP) specification. See:

• TCG PC Client Platform TPM Profile (PTP) Specification — Section 6 "Command Response Buffer Interface" describes LocalityState, LocalityControl, InterfaceId, CrbControlRequest, CrbControlStart, CrbControlCommand*/CrbControlResponse*, and the shared CrbDataBuffer.

The key register for this platform is InterfaceId at PcdTpmBaseAddress + 0x30, which Tpm2DeviceLibDTpm reads to decide between CRB and TIS/FIFO dispatch paths.

TIS Register Layout

QEMU's tpm-tis device presents a TIS (TPM Interface Specification) / FIFO interface. The register layout is defined by:

• TCG PC Client Specific TPM Interface Specification (TIS) — defines Access, IntEnable/IntVector, STS (with commandReady, tpmGo, dataAvail, burstCount), DataFifo, and the Vid/Did/Rid identification registers.

The TIS flow uses BurstCount from the STS register to pace reads and writes through the DataFifo register, one burst at a time.

Hash Library Architecture

Tcg2Dxe uses HashLibBaseCryptoRouterDxe while Tcg2Pei uses HashLibBaseCryptoRouterPei with all hash instance libraries included.

Registration Flow

1. HashLibBaseCryptoRouterConstructor resets PcdTcg2HashAlgorithmBitmap to 0.
2. Each HashInstanceLib constructor calls RegisterHashInterfaceLib().
3. RegisterHashInterfaceLib() checks the algorithm against PcdTpm2HashMask (0x02 = SHA256 only). Algorithms not in the mask return EFI_UNSUPPORTED.

Hash Algorithm Bitmask Values

The bit positions used in PcdTpm2HashMask, PcdTcg2HashAlgorithmBitmap, and the EFI_TCG2_BOOT_SERVICE_CAPABILITY.HashAlgorithmBitmap field are defined by the EFI TCG2 protocol and the TCG algorithm registry:

• UEFI TCG2 Protocol Specification — see EFI_TCG2_BOOT_HASH_ALG_* (SHA1 = BIT0, SHA256 = BIT1, SHA384 = BIT2, SHA512 = BIT3, SM3_256 = BIT4).
• TCG Algorithm Registry — canonical list of TPM hash algorithm IDs.

For this platform, PcdTpm2HashMask = 0x02 enables SHA256 only.

Filtering Chain

PcdTpm2HashMask (0x02)
        │
        ▼
RegisterHashInterfaceLib() ── gates which HashInstanceLibs register
        │
        ▼
PcdTcg2HashAlgorithmBitmap ── result of all successful registrations
        │
        ▼
Tcg2Dxe intersects with TPM-reported capabilities
        │
        ▼
Final ActivePcrBanks / HashAlgorithmBitmap in EFI_TCG2_BOOT_SERVICE_CAPABILITY

Physical Presence Interface

Library Selection

The MinimumLib implementation:

• Auto-confirms TPM Clear operations without user prompting.
• Rejects SET_PCR_BANKS, LOG_ALL_DIGESTS, and other operations with TCG_PP_RETURN_TPM_OPERATION_RESPONSE_FAILURE.
• Does not create or use TCG2_PHYSICAL_PRESENCE_FLAGS_VARIABLE.

ProcessRequest in BDS

Tcg2PhysicalPresenceLibProcessRequest() is invoked from the platform's DeviceBootManagerLib during DeviceBootManagerAfterConsole(), before the shell launches. It:

1. Reads the Tcg2PhysicalPresence NV variable (creates it if missing).
2. Executes any pending PP request stored in the variable.
3. Stores the result back for ReturnOperationResponseToOsFunction() to report.

swtpm Setup

Installation

swtpm requires Unix sockets, so it must run in a Linux environment. On Windows, use WSL (Windows Subsystem for Linux).

# Windows (from a WSL terminal)
wsl --install          # if WSL is not yet enabled
wsl                    # enter the WSL environment

# Ubuntu/Debian (native or WSL)
sudo apt install swtpm swtpm-tools

# Fedora
sudo dnf install swtpm swtpm-tools

Manual Setup

Create the TPM state directory and start swtpm before launching QEMU:

mkdir -p /tmp/mytpm1
swtpm socket \
  --tpmstate dir=/tmp/mytpm1 \
  --ctrl type=unixio,path=/tmp/mytpm1/swtpm-sock \
  --tpm2 \
  --log level=20

Automatic Setup (QemuRunner)

When SWTPM_ENABLE=TRUE, QemuRunner.py automatically starts swtpm as a subprocess before launching QEMU. The swtpm state directory is set to BUILD_OUTPUT_BASE and the Unix socket is placed at {BUILD_OUTPUT_BASE}/swtpm-sock:

# Platforms/QemuQ35Pkg/Plugins/QemuRunner/QemuRunner.py
@staticmethod
def StartSwTpm(tpm_dir, tpm_sock):
    """Starts the swtpm emulator and returns its Popen handle."""
    cmd = [
        "swtpm", "socket",
        "--tpmstate", f"dir={tpm_dir}",
        "--ctrl", f"type=unixio,path={tpm_sock}",
        "--tpm2",
        "--log", "level=1",
    ]
    return subprocess.Popen(cmd)

swtpm is started before QEMU launches. QemuRunner then waits (up to 30 seconds) for the Unix socket to appear before starting QEMU, and terminates the swtpm process so it doesn't outlive the run. SWTPM is enabled by default. Disable it by setting SWTPM_ENABLE=FALSE on the command line or in the BuildConfig.conf file.

QEMU Arguments

When SWTPM_ENABLE=TRUE, QemuRunner.py adds the following to the QEMU command line (with the socket path under BUILD_OUTPUT_BASE):

-chardev socket,id=chrtpm,path={BUILD_OUTPUT_BASE}/swtpm-sock
-tpmdev emulator,id=tpm0,chardev=chrtpm
-device tpm-tis,tpmdev=tpm0

The -device tpm-tis argument is Q35-specific — it attaches a TIS-compatible TPM device to the Q35 chipset at the standard address 0xFED40000.

Communication Flow

Complete path from a shell application to swtpm:

TpmShellApp (UEFI Shell)
  │ gBS->LocateProtocol(&gEfiTcg2ProtocolGuid)
  │ Tcg2Protocol->SetActivePcrBanks(0x02)
  ▼
Tcg2Dxe (EFI_TCG2_PROTOCOL)
  │ Validates bank mask against HashAlgorithmBitmap
  │ Calls Tcg2PhysicalPresenceLibSubmitRequestToPreOSFunction()
  │   ├── MinimumLib: rejects SET_PCR_BANKS → returns EFI_UNSUPPORTED
  │   └── MinimumLib: NO_ACTION (already-active) → writes NV variable → EFI_SUCCESS
  ▼
Tpm2CommandLib (for direct TPM commands like GetCapability)
  │ Serializes TPM2 command structure into byte buffer
  │ Calls Tpm2SubmitCommand(cmdBuffer, cmdSize, rspBuffer, &rspSize)
  ▼
Tpm2DeviceLibRouter → Tpm2InstanceLibDTpm
  │ DTpm2SubmitCommand() — detects interface type (TIS on QEMU)
  ▼
Tpm2TisTpmCommand (Tpm2Tis.c)
  │ 1. TisPcPrepareCommand: set TIS_PC_STS_COMMAND_READY
  │ 2. Write command bytes to DataFifo (paced by BurstCount)
  │ 3. Set TIS_PC_STS_GO to start execution
  │ 4. Poll STS for DataAvail (90 second timeout)
  │ 5. Read response header from DataFifo
  │ 6. Read remaining response bytes (paced by BurstCount)
  │ 7. Set TIS_PC_STS_READY (return to idle)
  ▼
MMIO to 0xFED40000 (QEMU TIS device)
  │
  ▼
QEMU tpm-tis device ──── Unix socket ──── swtpm process

PCDs Reference

Required PCDs (set when TPM2_ENABLE=TRUE)

Memory Type PCDs

Conditional PCDs (TPM_CONFIG_ENABLE=TRUE)