ARM64 Guests & Emulation
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu provides robust support for ARM64 (aarch64) guest operating systems, allowing users to run ARM-based virtual machines on both native ARM hardware and x86_64 hosts. This capability is integrated into the core tools: quickget handles the acquisition of ARM64-specific images and configuration generation, while quickemu manages the execution using optimized QEMU parameters for the architecture.
The project supports a wide range of ARM64 guests, including Linux distributions and macOS. When running on an ARM64 host (such as Apple Silicon or ARM-based Linux servers), the system leverages native acceleration. On x86_64 hosts, Quickemu utilizes TCG (Tiny Code Generator) for cross-architecture emulation.
Sources: README.md:42-43, AGENTS.md:92-96
Architecture and Infrastructure
ARM64 emulation in Quickemu relies on specific QEMU machine types and firmware components to ensure compatibility and performance.
Component Overview
- Machine Type: ARM64 guests utilize the
virtmachine type in QEMU, which is designed for high-performance virtual machine use cases. - Firmware: The system uses AAVMF (Arm Virtual Machine Firmware) for UEFI support on ARM64 guests, contrasting with the standard OVMF used for x86_64.
- Acceleration:
- Native: KVM acceleration is used when the host architecture matches the guest (aarch64 on aarch64).
- Emulated: TCG is employed for cross-arch emulation (aarch64 on x86_64).
Sources: AGENTS.md:94-96, AGENTS.md:100
Virtual Machine Lifecycle
The following diagram illustrates the flow from OS selection to execution for an ARM64 guest:
The diagram shows how quickget and quickemu collaborate to handle architecture-specific requirements.
Sources: AGENTS.md:46-51, AGENTS.md:93-95
Implementation Details
Configuration and Setup
To define an ARM64 guest, the virtual machine configuration file must specify the architecture. This is typically automated by quickget when the --arch arm64 flag is provided during the initial setup.
| Parameter | Value | Description |
|---|---|---|
arch | "aarch64" | Sets the guest architecture in the VM config |
| Machine Type | virt | High-level QEMU machine type for ARM64 |
| Firmware | AAVMF | UEFI firmware used for ARM64 guests |
Sources: AGENTS.md:93-94, AGENTS.md:100
Developer Tooling for ARM64
Developers can use specific flags with quickget to test and verify ARM64 support for various distributions.
# Test ARM64 downloads for a specific OS
./quickget --arch arm64 --check <os> [release] [edition]
# Test all supported architectures for an OS
./quickget --check-all-arch <os> [release] [edition]
Sources: AGENTS.md:31-33
OS Support Logic in quickget
For an operating system to support ARM64 within the Quickemu ecosystem, it must implement specific functions within the quickget script.
arch_<os>(): A required function that explicitly declares ARM64 support. If omitted, the system defaults toamd64.os_info(): The central case statement where the OS is registered.releases_<os>(): Returns available versions, which may vary by architecture.
Sources: AGENTS.md:46-53
Dependencies and Requirements
The runtime environment for ARM64 guests involves both general and architecture-specific dependencies.
| Dependency | Platform | Purpose |
|---|---|---|
qemu | All | Base emulator/virtualizer |
AAVMF | Linux | UEFI firmware for ARM64 guests |
bash | All | Version 4.0+ required for script execution |
curl / jq | All | Used by quickget for image metadata and downloads |
Sources: AGENTS.md:97, AGENTS.md:99-100
Summary
ARM64 support in Quickemu is a first-class feature that bridges the gap between different hardware architectures. By automating the selection of the virt machine type and AAVMF firmware, Quickemu simplifies what is traditionally a complex QEMU configuration process. Whether running natively on ARM-based hardware or emulated on x86_64 via TCG, the project maintains a consistent user experience for nearly 1000 supported operating system editions.
Sources: README.md:12-16, README.md:42-43, AGENTS.md:94-96