x86_64
q35, OVMF, efi or bios for users for contributors
x86_64 guests run on QEMU's q35 machine with -cpu max, under KVM with four vCPUs on a PC and emulated with one elsewhere; every system in the data has an x86_64 build, booting OVMF (efi) or QEMU's BIOS (bios), and only here do the Ubuntu Core +tpm systems boot with Secure Boot and a TPM.
On the map: architectures
▶ Watch this deck — 8 scenes, ~6 min
Worth seeing first
- Six architectures, six QEMU machines — the machine, CPU and accelerator rules every architecture shares
01 Where image-garden is most at home
x86_64 is the tier 1 host and the widest column of the support matrix: every system name has an x86_64 build. image-garden make ubuntu-cloud-24.04.x86_64.run is this map's running example.
Most of the time you'll run image-garden on a PC, and that's where it's most at home. The README ranks an x86_64 host tier one: production-ready, well tested, with guests running at native speed. It's also where the choice is widest. Every system name in the data has an x86_64 build, and a few exist only here. ubuntu-cloud-24.04.x86_64, the system this map follows, is one of them. This deck is the one place for running x86_64 guests: the machine and its CPU, how fast it runs, the two ways to boot, the systems, where QEMU comes from, and what's worth knowing first.
Details and sources
Details
- The README's host tiers: x86\_64 is tier 1, "Production-ready", "Native execution", 4 default vCPUs, "Full support, well-tested" (README.md:384-396). The table is about the host; guests of another architecture are emulated.
- Every one of the 61 cloud system names has an x86\_64 build (counted at the pinned commit), and 13 Ubuntu Core systems are x86\_64 ones.
- What the architectures share (
-accel help, the vCPU rule) is in six architectures; this deck says what is particular to x86\_64.
for contributors
In the code
- The running example's section:
[ubuntu-cloud-24.04.x86_64],Arch=x86_64,Boot=efi,Release=24.04(data/ubuntu.ini:237-242); Ubuntu Core's systems (mk/050-ubuntu-core.mk:4-16).
Read more
02 q35, CPU max and KVM
qemu-system-x86_64 -machine q35,accel=kvm:tcg -cpu max, -smp 4 on an x86_64 host and -smp 1 elsewhere, -m 2048. QEMU_SMP_OPTION and QEMU_MEM_OPTION override them for one run.
Make the .run script and look inside. QEMU's x86 emulator starts a q35 machine, a modern PC chipset, with the CPU model called max: every feature the accelerator can offer. On a PC, the script finds KVM and asks for kvm:tcg, so the guest runs on your own processor at nearly full speed, with four CPUs, because x86_64 is your host's architecture. Build the same system on an Arm host and it's emulated with TCG, many times slower, with one CPU. Memory is two gigabytes either way. QEMU_SMP_OPTION and QEMU_MEM_OPTION change both for a single run.
Details and sources
Details
- The
.runscript runs-accel helpwhen it starts and uses,accel=kvm:tcgwhenkvmis listed, else,accel=tcg; the host's own architecture gets 4 vCPUs, every other one 1 (six architectures). - Memory defaults to 2048 MiB.
QEMU_SMP_OPTIONandQEMU_MEM_OPTIONfrom the environment replace the defaults for one run; see the .run script. - The
-cpumodel is written into the.runscript when make creates it; it is not a run-time variable. - "q35 is a modern PC chipset" and "
maxoffers every feature the accelerator can" are QEMU's documentation (derived): under KVMmaxpasses through what the host CPU supports, under TCG it is everything QEMU emulates.
for contributors
In the code
QEMU_SYSTEM_X86_64(the snap'sqemu-system-x86-64app in the snap, elseqemu-system-x86_64fromPATH),QEMU_SYSTEM_X86_64_MACHINE = q35,QEMU_CPU_X86_64 ?= max,QEMU_SMP_X86_64 = 1(mk/010-qemu-x86_64.mk:4-7).- The accelerator test and the recorded
-smp(mk/010-qemu-x86_64.mk:63-65); the overrides (:72-74);-cpuin the command array (:95). - The native count of 4 (mk/010-qemu.mk:5-6),
GARDEN_HOST_ARCH(mk/000-garden.mk:14-18),QEMU_MEM_SIZE = 2048(mk/010-qemu.mk:9-12). - The network card carries
-smbios type=41, as on aarch64 and unlike riscv64 (mk/010-qemu-x86_64.mk:8-11).
Read more
03 Two ways to boot, and Secure Boot
Most systems boot efi, OVMF from per-system copies; six boot bios, QEMU's own BIOS. The +tpm systems get the Secure Boot pair, OVMF_CODE_4M.secboot.fd and OVMF_VARS_4M.ms.fd, on q35,smm=on.
x86_64 is the one architecture with a choice of boot. Most systems boot efi: they start OVMF, the PC build of EDK2, from their own copies of the firmware code and variables. Six boot bios instead, Amazon Linux 2, CentOS 9 and 10, and Oracle Linux 7, 8 and 9, and boot QEMU's own BIOS with no firmware files at all. OVMF comes from your distribution's ovmf package, from the snap's x86_64 component, or from a QEMU you built. And only x86_64 has Secure Boot: the Ubuntu Core +tpm systems boot OVMF's Secure Boot build, with Microsoft's keys enrolled and an emulated TPM.
Details and sources
Details
- The six bios systems:
amazonlinux-cloud-2,centos-cloud-9,centos-cloud-10,oracle-cloud-7,oracle-cloud-8andoracle-cloud-9, all on x86\_64; their aarch64 builds, where they exist, boot efi. A bios system has no firmware files and no firmware option; the snap's component carriesbios-256k.bin, the BIOS QEMU's PC machines load by default (snap/snapcraft.yaml:395-401; what QEMU loads is derived). - An efi system gets its own
X.efi-code.qcow2andX.efi-vars.qcow2, copied from the first OVMF build found: theovmfpackage's paths (Debian, Ubuntu, Arch, openSUSE), the snap'sqemu-x86-64component, then$GARDEN_X86_64_PREFIX/share/qemu/. The whole story is in UEFI firmware per system. - Secure Boot needs
OVMF_CODE_4M.secboot.fdandOVMF_VARS_4M.ms.fdfrom the same build (Ubuntu'sovmfpackage, or the snap's component), for the four +tpm systems only; see Secure Boot and TPM.
for contributors
In the code
- rulegen.py allows
efiandbioson x86\_64 (rulegen.py:302-309) and printsruleset_x86_64_efiorruleset_x86_64_bios(rulegen.py:804-808). The sections: data/amazonlinux.ini:8-14, data/centos.ini:8-26, data/oracle.ini:10-35. - The BIOS command line has no firmware option (mk/010-qemu-x86_64.mk:27-39). The OVMF lists (mk/010-qemu-x86_64.mk:260-280), the copies (:316-329), the Secure Boot pair (:282-308) and
q35,smm=on(mk/050-ubuntu-core.mk:55-61). - Known discrepancy: Plain firmware code and variables are searched separately. The two lists are searched one by one, unlike the Secure Boot pair, so a host with half a pair at an earlier path could mix builds (suspected, not run).
Read more
04 Every system has an x86_64 build
61 cloud systems and 13 Ubuntu Core systems. Only on x86_64: archlinux-cloud, oracle-cloud-7, the 13 end-of-life Ubuntu interims, ubuntu-core-16, -18, -20 and the four +tpm systems.
Which systems can you run here? On x86_64, the short answer is all of them. Each of the sixty-one cloud system names has an x86_64 build, and Ubuntu Core adds thirteen more. Some exist nowhere else. Arch Linux and Oracle Linux 7 are x86_64 only, and so are the thirteen Ubuntu interim releases past their end of life, which fetch their packages from the old releases archive. Ubuntu Core 16, 18 and 20 have no Arm image, and the four +tpm systems are made for x86_64 alone. To see them, run image-garden make list-systems, and keep the lines that end in x86_64.
Details and sources
Details
- 61 cloud system names, each with an
.x86_64build (counted at the pinned commit), and 13 Ubuntu Core systems; the full table is in the support matrix and in this deck's reference. - x86\_64 only:
archlinux-cloud,oracle-cloud-7, and the 13 end-of-life interims 16.10 to 24.10, "x86\_64, fetched from archived release URLs", whose apt usesold-releases.ubuntu.com(README.md:684-697); Ubuntu Core 16, 18 and 20 and the four +tpm systems (README.md:699-718). image-garden make list-systemsprints every system, one per line; the grep is ordinary shell.image-garden make allbuilds every system of your host's architecture.
for contributors
In the code
- data/archlinux.ini:8-12, data/oracle.ini:10-14; Ubuntu Core's systems and "Ubuntu Core 16, 18 and 20 have no aarch64 image" (mk/050-ubuntu-core.mk:4-16).
list-systemsprintsGARDEN_SYSTEMS(mk/000-garden.mk:85-87);all::collects the systems ofGARDEN_ARCH, the host's architecture by default (rulegen.py:456-459, mk/000-garden.mk:16-18).
Read more
05 The snap, the container or your distribution
Snap: the qemu-x86-64 component, installed on x86_64 hosts by the install hook. Container: x86_64-softmmu plus the ovmf package. Ubuntu: qemu-system-x86 and ovmf, and swtpm for the +tpm systems.
The emulator and its firmware can come from three places. The snap keeps them in a component called qemu-x86-64, with dashes, and installs it by itself on a PC. On an Arm host you add it with snap install image-garden+qemu-x86-64; until you do, the snap's stand-in for QEMU shows a message with that command. The container builds QEMU with x86_64 among its targets, adds Ubuntu's ovmf package for Secure Boot, and is published for x86_64 and aarch64 hosts. On a distribution, install its x86 QEMU and OVMF: on Ubuntu, that's the packages qemu-system-x86 and ovmf. The +tpm systems also need swtpm, the TPM emulator.
Details and sources
Details
- The snap installs the component for the host's architecture when it is installed and refreshed, so
qemu-x86-64on an x86\_64 host; a snap installed from a file installs no component (snap/hooks/install:6-13, snap/hooks/post-refresh:9-28). The component carries "the 64-bit x86 system emulator (QEMU) as well as the corresponding EFI firmware (EDK2) and the Secure Boot EFI firmware of Ubuntu (OVMF)" (snap/snapcraft.yaml:59-66). - Without it, QEMU's stand-in shows "It seems that the component with QEMU x86-64 is not installed" and
snap install image-garden+qemu-x86-64(qemu-stubs/qemu-system-x86_64:9-31), and making an efi system stops with "install qemu-x86-64 component to use x86\_64 emulation". - The container builds
x86_64-softmmuamong six targets (Dockerfile:33), installsovmfandswtpm(Dockerfile:78-91) and pointsGARDEN_X86_64_PREFIXat its QEMU's firmware (Dockerfile:98-102). It is published for x86\_64 and aarch64 hosts (.gitlab-ci.yml:1238-1276). - On Ubuntu:
qemu-system-x86,ovmf, andswtpmfor the +tpm systems, withqemu-utilsandxorrisofor any system. Distribution packages may be older than the upstream release (the maintainer's statement).
for contributors
In the code
- image-garden's CI installs those packages on Ubuntu (.gitlab-ci.yml:292-311). The snap's component files (snap/snapcraft.yaml:395-401, :645-665); the component check before the firmware copy (mk/010-qemu-x86_64.mk:310-316).
Read more
06 Inside: one makefile, two rule sets for contributors
mk/010-qemu-x86_64.mk: program, machine, CPU, SMP, the EFI and BIOS command lines and the .run emitters. rulegen.py accepts Boot=efi or bios and prints ruleset_x86_64_efi or _bios.
If you maintain image-garden, here's where x86_64 lives. Its own makefile in the mk directory names the program, q35, CPU max and one CPU, and holds two QEMU command lines: one with the firmware flash drives, one without. The .run emitter for a TPM adds swtpm and secure flash. rulegen.py lets an x86_64 section say efi or bios, refuses anything else, and prints the matching rule set. The firmware search lists are defaults a project can replace. Ubuntu Core's +tpm systems set their own machine, q35 with SMM switched on. In CI, the x86_64 stage runs on KVM runners, and its failures block the pipeline, except for systems past their end of life.
Details and sources
Details
- The makefile: program, machine, CPU, SMP and network (mk/010-qemu-x86_64.mk:3-11);
QEMU_SYSTEM_X86_64_EFI_CMDLINEand_BIOS_CMDLINEfor the provisioning boot (:12-39);EMIT_QEMU_SYSTEM_X86_64_EFI_RUN_COMMAND,…_WITH_TPMand…_BIOS_RUN_COMMANDfor the.runscript (:46-108, :218-259). The TPM variant addsEMIT_SWTPM_STARTand-global driver=cfi.pflash01,property=secure,value=on(:134-135). BOOT_BY_ARCHandload_boot: x86\_64 takesefiorbios; a missing or other value is an error naming the section and the allowed values (rulegen.py:300-333); the rule sets (rulegen.py:593-629), chosen at rulegen.py:804-808.- The search lists and
QEMU_CPU_X86_64use?=;QEMU_SYSTEM_X86_64_MACHINEandQEMU_SMP_X86_64use=, which a target-specific assignment such as the +tpm one overrides (mk/050-ubuntu-core.mk:55). - CI:
.systems-x86_64runs on runners taggedlinux,x86_64,kvm; the stage blocks "but for the systems past their end of life" (.gitlab-ci.yml:78-91, :624-633).
Read more
07 Worth knowing on x86_64
EL 10 needs x86-64-v3: QEMU_CPU_X86_64=Haswell, with QEMU_ACCEL_MACHINE_PROP=,accel=tcg on an older host. The snap writes x86-64 with dashes. For a big-endian guest use s390x.
A few things catch people out here. Rocky 10 and the other rebuilds of Red Hat Enterprise Linux 10 need an x86-64-v3 processor, Haswell or newer. Under KVM, CPU max is your own processor, so an older host can't boot them: set QEMU_CPU_X86_64 to Haswell and let TCG emulate it, slowly. In the snap, names use dashes: the component is qemu-x86-64 and the app qemu-system-x86-64, while systems and files keep x86_64. x86 is little-endian, like Arm and RISC-V, so for byte order bugs, test on s390x. And if /dev/kvm isn't writable, image-garden prints a loud warning: join the kvm group.
Details and sources
Details
- README: "Rocky 10 (and other RHEL 10 derivatives) require at least Haswell CPU (x86\_64-v3). Set
QEMU_CPU_X86_64=Haswellor newer if needed" (README.md:677-681). With KVM,-cpu maxoffers what the host CPU has (derived), so a host without x86-64-v3 cannot give it. Under TCG, set both:image-garden make QEMU_CPU_X86_64=Haswell SYSTEM.runand run it withQEMU_ACCEL_MACHINE_PROP=,accel=tcg. QEMU_CPU_X86_64is set with?=, so it can come from the environment as well as the make command line (mk/010-qemu-x86_64.mk:6); it is written into the.runscript when make creates it, so remake the script after changing it.QEMU_ACCEL_MACHINE_PROPis read when the script runs (mk/010-qemu-x86_64.mk:72).- Snap app names cannot contain underscores, so the app is
qemu-system-x86-64and runsqemu-system-x86_64(snap/snapcraft.yaml:149-152, mk/010-qemu-x86_64.mk:3-4). - x86\_64, aarch64 and riscv64 Linux are little-endian and s390x is big-endian (derived, general knowledge); image-garden's own comment calls the ppc64 systems little-endian (mk/000-garden.mk:14-16).
- The
/dev/kvmwarning and its advice (image-garden:670-709) are shown in six architectures.
for contributors
In the code
- image-garden's own CI once tested EL 10 that way, with
QEMU_CPU_X86_64: HaswellandQEMU_ACCEL_MACHINE_PROP: ",accel=tcg"(commit 128bbd5, "ci: disable kvm on emulated x86_64-v3").
Read more
08 Where to go from here
Next: boot types, UEFI firmware, Secure Boot and the TPM, the support matrix, snap components, the container in CI and the .run script.
So x86_64 is a q35 machine with CPU max, running under KVM on your PC, booting OVMF or QEMU's BIOS, with every system in the data. From here, the boot deck shows what efi and bios change in the rules, and the firmware deck where OVMF is found. The Secure Boot deck covers the +tpm systems, and the support matrix sets x86_64 beside the other five. The snap components deck explains qemu-x86-64, the container in CI deck covers runners with and without KVM, and the run script deck every knob of a boot.
Details and sources
Read more
Basis of the statements on this page
Read in the README, mk/010-qemu-x86_64.mk, mk/010-qemu.mk, mk/000-garden.mk, mk/050-ubuntu-core.mk, rulegen.py, data/*.ini, snap/snapcraft.yaml, snap/hooks/install, qemu-stubs/qemu-system-x86_64, the Dockerfile and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). The system counts were taken from the INI files at that commit. What q35, -cpu max and the BIOS do inside QEMU, and byte order, are derived from QEMU's documentation and general knowledge. Nothing was run for this page.
x86_64 at a glance
| Fact | Value |
|---|---|
| QEMU program | qemu-system-x86_64; in the snap the image-garden.qemu-system-x86-64 app |
| Machine | q35; q35,smm=on for the +tpm systems |
| CPU | max |
| Accelerator | kvm:tcg when QEMU lists KVM, else tcg |
| vCPUs | 4 on an x86\_64 host, 1 elsewhere |
| Memory | -m 2048 |
| Boot types | efi and bios |
| Firmware (efi) | OVMF, copied to efi-code.x86_64.img and efi-vars.x86_64.img, then per system X.efi-code.qcow2 and X.efi-vars.qcow2 |
| Firmware (Secure Boot) | OVMF_CODE_4M.secboot.fd and OVMF_VARS_4M.ms.fd, copied to efi-secboot-code.x86_64.img and efi-secboot-vars.x86_64.img |
| Firmware (bios) | none; QEMU's own BIOS |
| Network | -netdev user, virtio-net-pci, -smbios type=41 |
| Snap component | qemu-x86-64, installed by the snap on x86\_64 hosts |
| Container | QEMU with x86_64-softmmu, ovmf, swtpm; images for x86\_64 and aarch64 hosts |
| Ubuntu packages | qemu-system-x86, ovmf, and swtpm for +tpm |
| Host tier | 1: production-ready |
| Byte order | little-endian (derived) |
Systems
All 61 cloud system names have an x86\_64 build, so NAME.x86_64 exists for every row of the support matrix, plus 13 Ubuntu Core systems.
| Boot | Systems |
|---|---|
| bios | amazonlinux-cloud-2, centos-cloud-9, centos-cloud-10, oracle-cloud-7, oracle-cloud-8, oracle-cloud-9 |
| efi | the other 55 cloud systems, and ubuntu-core-16, -18, -20, -22, -24, -26 and -22+dangerous, -24+dangerous, -26+dangerous |
| efi with Secure Boot and a TPM | ubuntu-core-24+tpm, -24+dangerous+tpm, -26+tpm, -26+dangerous+tpm |
Only on x86\_64: archlinux-cloud, oracle-cloud-7, ubuntu-cloud-16.10, 17.04, 17.10, 18.10, 19.04, 19.10, 20.10, 21.04, 21.10, 22.10, 23.04, 23.10, 24.10, ubuntu-core-16, -18, -20 and the four +tpm systems.
Run-time knobs
| Variable | Effect |
|---|---|
QEMU_ACCEL_MACHINE_PROP | replaces ,accel=kvm:tcg, such as ,accel=tcg |
QEMU_SMP_OPTION, QEMU_MEM_OPTION | replace -smp N and -m 2048 |
QEMU_BOOT_FIRMWARE_OPTION | replaces the two pflash drives of an efi system |
QEMU_CPU_X86_64 | make variable or environment: the -cpu model written into a new .run script, Haswell for EL 10 under TCG |
See the .run script for every run-time variable.
for contributors
Where it is set
| Fact | Source |
|---|---|
| Program, machine, CPU, SMP, network | mk/010-qemu-x86_64.mk:3-11 |
| Accelerator test | mk/010-qemu-x86_64.mk:63 |
| Native vCPU count, memory | mk/010-qemu.mk:5-12 |
| Boot types allowed | rulegen.py:302-309 |
| OVMF lists and copies | mk/010-qemu-x86_64.mk:260-329 |
q35,smm=on for +tpm | mk/050-ubuntu-core.mk:55 |
| Snap component | snap/snapcraft.yaml:59-66, snap/hooks/install:6-13 |
| Container | Dockerfile:33, Dockerfile:78-102, .gitlab-ci.yml:1238-1276 |
| Host tier | README.md:384-396 |
| Make variable | Effect |
|---|---|
QEMU_SMP_X86_64 | the default -smp |
QEMU_SYSTEM_X86_64 (?=) | the QEMU program |
QEMU_EDK2_CODE_X86_64, QEMU_EDK2_VARS_X86_64 (?=) | the OVMF search lists |
QEMU_EDK2_SECBOOT_CODE_X86_64, QEMU_EDK2_SECBOOT_VARS_X86_64 (?=) | the Secure Boot search lists |
GARDEN_X86_64_PREFIX (environment) | appends a self-built QEMU's share/qemu firmware |
See six architectures for how the defaults are set.
Roads from here
SYSTEMS · distributions
- The support matrix — every system on every architecture, side by side
UBUNTU CORE · all snaps
- Ubuntu Core with Secure Boot and a TPM — the +tpm systems, Secure Boot and the emulated TPM
ARCHITECTURES · machines and firmware
- Boot types — what efi and bios change in the rules, and how a section picks one
- UEFI firmware per system — where OVMF is searched for, and the per-system copies
RUNTIME · make rules and the CLI
- The .run script — memory, CPUs and the accelerator of one boot
SNAP · snap-only features
- Snap components — how the snap's qemu-x86-64 component is installed
CONTAINER · OCI image
- Running the container in CI — the container on CI runners with and without /dev/kvm