Firmware, Boot Options & TPM
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu provides a streamlined abstraction for managing virtual machine firmware and security modules, ensuring that guests—ranging from legacy BIOS-based Linux distributions to modern TPM-requiring Windows 11 environments—boot with optimal hardware configurations. By automating the selection of Open Virtual Machine Firmware (OVMF) and the integration of software-based Trusted Platform Modules (SWTPM), Quickemu eliminates the manual complexity of QEMU configuration.
The system supports a variety of boot modes including EFI (with or without SecureBoot) and Legacy BIOS, while handling architecture-specific firmware requirements for both x86_64 and ARM64 (AAVMF) guests.
Sources: README.md:10-21, README.md:104-104, AGENTS.md:79-83
Firmware Architecture & Types
Quickemu categorizes firmware based on the target architecture and the security requirements of the guest operating system. The choice of firmware is often dictated by the arch setting in the VM configuration file.
UEFI and BIOS Support
Quickemu supports three primary boot methods:
- EFI: Standard UEFI boot for modern operating systems.
- EFI with SecureBoot: Required for certain restricted environments and modern Windows installations.
- Legacy BIOS: For older operating systems that do not support UEFI.
Sources: README.md:104-104, AGENTS.md:83-83
Architecture-Specific Firmware
Firmware paths and types differ significantly between host and guest architectures:
- x86_64 Guests: Primarily utilize OVMF (Open Virtual Machine Firmware) on Linux hosts.
- ARM64 (aarch64) Guests: Utilize AAVMF firmware and the
virtmachine type. - macOS Hosts: The development environment patches Quickemu to use Nix store paths for OVMF.
Sources: AGENTS.md:27-28, AGENTS.md:81-84
Firmware Logic Flow
The following diagram illustrates how Quickemu determines the appropriate firmware and machine type based on the configuration:
This diagram shows the decision logic for selecting firmware based on guest architecture and security settings.
Sources: AGENTS.md:79-84, README.md:104-104
Trusted Platform Module (TPM)
Quickemu includes integrated support for TPM 2.0, which is a hard requirement for modern versions of Windows, including Windows 11.
Implementation and Dependencies
The TPM functionality is provided via swtpm (Software TPM), which allows the guest to perceive a physical TPM device without requiring one on the host hardware.
| Feature | Requirement | Description |
|---|---|---|
| TPM Version | 2.0 | Required for Windows 11 compatibility. |
| Dependency | swtpm | Must be installed on the host system to enable TPM features. |
| Guest Support | Windows 10/11 | Explicitly supported and optimized for Windows environments. |
Sources: README.md:92-92, AGENTS.md:88-88
TPM Integration Sequence
The sequence below demonstrates how Quickemu initializes the TPM environment before launching the QEMU process:
The interaction between the host-side swtpm utility and the QEMU process allows the guest to perform cryptographic operations.
Sources: README.md:92-92, AGENTS.md:88-88
Boot Options & Emulation Modes
Quickemu handles both native acceleration and cross-architecture emulation through specific boot flags and configurations.
Acceleration vs. Emulation
The boot performance and firmware interaction change based on whether the host and guest architectures match.
- Native Execution: Uses KVM acceleration on Linux hosts (x86_64 or aarch64) when the guest matches the host.
- Cross-Arch Emulation: Uses TCG (Tiny Code Generator) when architectures differ (e.g., running ARM64 on x86_64). KVM acceleration is not available in this mode.
Sources: AGENTS.md:79-82
Configuration Parameters
These parameters are typically defined in the <name>.conf file and interpreted by quickemu at runtime.
| Parameter | Options | Description |
|---|---|---|
arch | x86_64, aarch64 | Defines the guest CPU architecture. |
firmware | efi, bios | (Inferred) Sets the bootloader interface. |
tpm | on, off | (Inferred) Toggles the inclusion of the swtpm device. |
Sources: AGENTS.md:79-80, README.md:92-92, README.md:104-104
Platform Specific Constraints
The availability of certain firmware and boot options is restricted by the host operating system.
- Linux Hosts: Support the full suite of firmware, including OVMF (x86_64), AAVMF (aarch64), and full
swtpmintegration. - macOS Hosts: Supported as a host platform, with specific Nix-based devshell configurations to ensure proper pathing for firmware like OVMF.
- UEFI/SecureBoot: Specifically noted as supported for Linux hosts running guest VMs.
Sources: README.md:88-88, AGENTS.md:27-28, AGENTS.md:83-84
Summary of Firmware and Boot Features
Quickemu automates the complex matrix of firmware, architecture, and security requirements to provide a "just works" experience for virtual machine booting.
- Automated Selection: Automatically chooses between OVMF, AAVMF, and BIOS.
- Security Integration: Seamlessly attaches TPM 2.0 and supports SecureBoot for modern OS compliance.
- Hardware Optimized: Uses the
virtmachine type for ARM64 and optimal CPU passthrough where possible.
Sources: README.md:14-16, README.md:92-92, AGENTS.md:81-81