Boot types
how each system boots for contributors
A section's Boot key, efi, bios or platform, picks rulegen.py's rules by architecture: x86_64 efi or bios, aarch64, riscv64 and loongarch64 efi only, s390x and ppc64 platform, their default; rulegen.py refuses any other value or a missing one. efi adds per-system firmware copies as two pflash drives.
On the map: architectures
▶ Watch this deck — 7 scenes, ~5 min
Worth seeing first
- The support matrix — which systems boot which way
01 Three ways to start a machine
The Boot key of a section is efi, bios or platform. It picks the generated rules, the firmware files and the QEMU options of the .run script.
Before QEMU can boot a cloud image, someone has to decide what starts the guest. A PC can start through UEFI firmware or through an old-style BIOS, and a mainframe or a POWER machine starts in its own way. So every section in the data can carry a Boot key, with one of three values: efi, bios or platform. ubuntu-cloud-24.04.x86_64 says Boot=efi. That one word decides which rules rulegen.py writes for the system, which firmware files it needs, and what its .run script hands to QEMU. This deck follows the word from the INI file to the command line.
Details and sources
Details
Bootis an enum ofplatform,efiandbios(rulegen.py:17-20); which values a section may use depends on its architecture, and only s390x and ppc64 sections may leave the key out, gettingplatform(rulegen.py:300-333). data/README.md documents the key the same way (data/README.md:34-38).- The running example's section:
Arch=x86_64,Boot=efi,Release=24.04(data/ubuntu.ini:237-242). - The rules are chosen from the architecture and the boot type (rulegen.py:804-821); the next scenes take them in turn.
- That a PC starts through UEFI or BIOS and that s390x and POWER machines have loaders of their own is general QEMU knowledge (derived).
Read more
- The support matrix shows the boot type of every system; the INI keys.
02 Architecture first, then boot type
x86_64 has efi and bios rules; aarch64, riscv64 and loongarch64 have efi rules; s390x and ppc64 boot platform. rulegen.py refuses every other combination, naming the section and the values to use.
rulegen.py decides in two steps: first the architecture, then the boot type. An x86_64 section can say efi or bios, and each gets its own pair of rules: one for the .qcow2 image and its provisioning boot, one for the .run script. aarch64, riscv64 and loongarch64 know only efi. s390x and ppc64 have one pair each, and start the platform's way. rulegen.py checks the combination before it writes a single rule. Any other one, such as bios on aarch64 or efi on s390x, stops it with an error that names the section and the values that would work. So every system it does write gets something that boots it.
Details and sources
Details
BOOT_BY_ARCHlists the boot types each architecture has rules for, andload_bootchecks every section against it while the INI file is read: noBooton an architecture other than s390x and ppc64, or a value the architecture has no rules for, raises an error naming the section and the values to use (rulegen.py:300-333), whichmainreports asFILE: error: ...before printing any rule of that file (rulegen.py:753-757).- The dispatch, after the download rules of each image: x86_64 prints
ruleset_x86_64_efiorruleset_x86_64_bios; aarch64, riscv64 and loongarch64 print their_efiruleset; s390x and ppc64 printruleset_s390xandruleset_ppc64(rulegen.py:804-821). - Each ruleset is a pair:
X.run(the launcher) andX.qcow2(the overlay and the provisioning boot), for example rulegen.py:593-610. - Every image gets the common rules (
GARDEN_SYSTEMS,all::,X.meta-data,X.user-data,clean::) and its download rules whatever its boot type (rulegen.py:777-803, rulegen.py:453-478). - The messages, from tests/check-rulegen.sh:
Image 'test-cloud.aarch64' has Boot=bios, which aarch64 does not support, use efiandImage 'test-cloud.s390x' has Boot=efi, which s390x does not support, use platform(tests/check-rulegen.sh:189-212).
for contributors
In the code
- The rulesets are Python format strings with
.RECIPEPREFIX=+(rulegen.py:726-738); see rulegen.py.
03 What efi adds
An efi system's .qcow2 and .run need X.efi-code.qcow2 and X.efi-vars.qcow2, attached as two pflash drives. A bios system has neither.
Here's what the word changes for ubuntu-cloud-24.04.x86_64. Because it's efi, its image depends on two more files: a copy of the UEFI firmware code and its own store of UEFI variables, both in qcow2 format and named after the system. The .run script waits for them too. When it starts QEMU, it adds two flash drives: the code, read-only, and the variables, writable, so the boot entries the guest saves stay with that one system. A bios system has neither file and no flash drives; QEMU's built-in BIOS starts it. The disk, the network and the provisioning boot are the same.
Details and sources
Details
ruleset_x86_64_efi:X.runhasX.efi-code.qcow2andX.efi-vars.qcow2as order-only prerequisites, andX.qcow2has them as prerequisites, words 3 and 4 passed to the command line (rulegen.py:593-610).ruleset_x86_64_bioshas neither (rulegen.py:612-629).- The efi command line adds
-drive if=pflash,format=qcow2,unit=0,file=CODE,readonly=on -drive if=pflash,format=qcow2,unit=1,file=VARS(mk/010-qemu-x86_64.mk:13-26); the bios one has no firmware option (mk/010-qemu-x86_64.mk:27-39). In the.runscript it isdefault_qemu_boot_firmware_option, whichQEMU_BOOT_FIRMWARE_OPTIONoverrides (mk/010-qemu-x86_64.mk:67, :76). - The per-system copies are made by
%.x86_64.efi-code.qcow2and%.x86_64.efi-vars.qcow2from the sharedefi-code.x86_64.imgandefi-vars.x86_64.img, converted with$(QEMU_IMG)(mk/010-qemu-x86_64.mk:324-329); the man page names them the same way (image-garden.1:159-167). - centos-cloud-9.x86_64 is one of the six bios systems (data/centos.ini:8-12). That QEMU's q35 machine starts with its built-in SeaBIOS when no firmware is given is QEMU's default (derived).
Read more
- UEFI firmware per system: where the copies come from.
04 The platform's own way
s390x and ppc64 sections have no Boot key, so they are platform. Their .run scripts have no firmware options; QEMU's machine loads its own loader.
On s390x and ppc64 there's nothing to choose. QEMU's s390-ccw-virtio machine loads its own boot loader, and the pseries machine its own firmware, from QEMU's data files, not from a file that image-garden copies. So their sections in the data leave the Boot key out, and rulegen.py's default, platform, fits them. Ubuntu 24.04 on s390x is one. Its .run script has no firmware option at all: the CPU, the machine, memory, the disk, the random number generator and the network. In the snap, each of those architectures' QEMU components carries the loader its machine needs.
Details and sources
Details
- The s390x and ppc64 command lines have the CPU, machine, memory, SMP, display, storage, RNG and network options and no firmware option (mk/010-qemu-s390x.mk:10-21, mk/010-qemu-ppc64.mk:10-21).
- ubuntu-cloud-24.04.s390x has no
Bootkey (data/ubuntu.ini:258-262); neither has any s390x or ppc64 section in the data (counted at the tag: 22).platformis the default only on these two architectures, and the only value rulegen.py accepts there (rulegen.py:300-333). - The snap's QEMU part gives each component "the firmware and option ROMs that machines of that system load":
s390-ccw.imgfor qemu-s390x,slof.bin,vof.binand others for qemu-ppc64 (snap/snapcraft.yaml:380-410). That the machines load them by default is QEMU's behaviour (derived).
Read more
- Six architectures: the machines and CPUs.
05 Where else the boot type is read for contributors
rulegen.py --systems-meta writes _X_boot into data/000-systems.mk; define-instance picks its efi, bios or platform branch from it. Ubuntu Core's hand-written rules are all efi.
The boot type matters after the rules, too. rulegen.py also writes each system's group, release, architecture and boot type into a small metadata file, and image-garden.mk starts with it. Named instances depend on that. When your project defines an instance of ubuntu-cloud-24.04, image-garden looks up the base system's boot type there and picks the matching branch, efi, bios or platform, so the instance boots exactly like its base. Ubuntu Core isn't in the INI files at all. Its rules are written by hand, and every Ubuntu Core system boots efi, on both of its architectures.
Details and sources
Details
- With
--systems-meta FILE, rulegen.py appends_X_group,_X_group_upper,_X_release,_X_archand_X_bootfor each system (rulegen.py:824-833); the Makefile buildsdata/000-systems.mkthat way from every INI file (Makefile:60-64) and puts it first inimage-garden.mk(Makefile:48-50). define-instancereads_$(base)_boot, and_$(base)_archfor the QEMU rules, and has an efi, a bios and a platform branch (mk/020-instances.mk:47-56, mk/020-instances.mk:81-146).- Ubuntu Core's
.runand.qcow2rules call the x86_64 and aarch64 EFI emitters and depend on theefi-codeandefi-varscopies (mk/050-ubuntu-core.mk:23-53).
06 When Boot is wrong or missing
A wrong value: has Boot='uefi', use one of platform, efi, bios. A missing one on x86_64: has no Boot=, use efi or bios for x86_64. Both stop the build, naming the file and the section.
Two mistakes are easy to make when you add a section, and rulegen.py catches both. Misspell the value, say uefi, and it stops the build, naming the INI file and the section, and listing the three values Boot can take. Leave Boot out on x86_64, or on one of the other efi architectures, and it stops too. Only s390x and ppc64 may leave it out, because they boot one way. This message names the section again and says what to use there: efi or bios on x86_64, efi on the rest. Either way the half-written rules file is deleted, and the fix is one line in your section.
Details and sources
Details
load_bootreadsBootand checks it againstBOOT_BY_ARCH: a value that is not a boot type fails inchoice, which names the key, the value and the allowed ones; a missingBootis accepted only on s390x and ppc64 (rulegen.py:288-297, rulegen.py:300-333).mainturns the error intoSystemExit(f"{filename}: error: {exc}")(rulegen.py:753-757), so the build ofdata/050-example.gen.mkfails (Makefile:57-58).- The two messages are tested:
bad-boot.ini: error: Image 'test-cloud.x86_64' has Boot='uefi', use one of platform, efi, biosandno-boot-x86_64.ini: error: Image 'test-cloud.x86_64' has no Boot=, use efi or bios for x86_64(tests/check-rulegen.sh:189-200). On aarch64, riscv64 and loongarch64 the second endsuse efi for aarch64and so on. .DELETE_ON_ERRORin the top-level Makefile removes the.gen.mkthe failed rulegen.py left, so the next make tries again (Makefile:16-18).- data/README.md:
Bootis required for x86_64 (efiorbios) and for aarch64, riscv64 and loongarch64 (efi); s390x and ppc64 default toplatform(data/README.md:34-38). example-cloud-1anddata/example.iniare made-up names.
Read more
07 Where to go from here
Next: UEFI firmware per system, the support matrix, named instances, the six machines, Secure Boot and the TPM, and the INI keys.
So one word in a section picks the rules, the firmware and the QEMU options. From here, the firmware deck shows where the UEFI code and variables come from, and why some Arm systems need an older build. The support matrix shows which systems boot which way. Named instances inherit their base's boot type, and their deck shows the rest they inherit. The architectures deck has the machine behind each column, the Secure Boot deck the strictest kind of efi, and the INI deck every other key of a section.
Details and sources
Read more
Basis of the statements on this page
Read in rulegen.py, data/*.ini, mk/010-qemu-*.mk, mk/020-instances.mk and mk/050-ubuntu-core.mk of image-garden at the tag in garden.commit ("code"). The counts were taken from the INI files at the tag. The rulegen.py error messages are those tests/check-rulegen.sh expects (code). What QEMU's machines load without a firmware option is derived from QEMU's defaults.
Which rules each combination gets
| Arch | Boot=efi | Boot=bios | Boot=platform | Boot missing |
|---|---|---|---|---|
| x86_64 | ruleset_x86_64_efi | ruleset_x86_64_bios | error | error |
| aarch64 | ruleset_aarch64_efi | error | error | error |
| riscv64 | ruleset_riscv64_efi | error | error | error |
| loongarch64 | ruleset_loongarch64_efi | error | error | error |
| s390x | error | error | ruleset_s390x | ruleset_s390x |
| ppc64 | error | error | ruleset_ppc64 | ruleset_ppc64 |
"error" means rulegen.py stops with FILE: error: Image 'SECTION' has no Boot=, use VALUES for ARCH or ... has Boot=X, which ARCH does not support, use VALUES, and the .gen.mk is deleted (rulegen.py:300-333, rulegen.py:804-821). A value that is no boot type at all, such as uefi, gives has Boot='uefi', use one of platform, efi, bios.
What each boot type adds
| efi | bios | platform | |
|---|---|---|---|
| Per-system files | X.efi-code.qcow2, X.efi-vars.qcow2 | none | none |
| Shared files | efi-code.ARCH.img, efi-vars.ARCH.img | none | none |
| QEMU options | two -drive if=pflash, unit 0 read-only | none | none |
| Override | QEMU_BOOT_FIRMWARE_OPTION | ||
| Systems at the tag | 111 sections, plus every Ubuntu Core system | 6 x86_64 sections | the 22 s390x and ppc64 sections |
The bios systems
amazonlinux-cloud-2.x86_64, centos-cloud-9.x86_64, centos-cloud-10.x86_64, oracle-cloud-7.x86_64, oracle-cloud-8.x86_64, oracle-cloud-9.x86_64 (data/amazonlinux.ini:8-14, data/centos.ini:8-26, data/oracle.ini:10-35). Their aarch64 sections, where there are any, boot efi.
Roads from here
SYSTEMS · distributions
- The support matrix — which systems boot efi, bios or platform
UBUNTU CORE · all snaps
- Ubuntu Core with Secure Boot and a TPM — Secure Boot, the strictest efi there is
ARCHITECTURES · machines and firmware
- UEFI firmware per system — where the UEFI code and variables of an efi system come from
- Six architectures, six QEMU machines — the QEMU machine behind each architecture
RUNTIME · make rules and the CLI
- Named instances — named instances, which inherit the boot type of their base
BUILD TIME · data and rules
- The .ini files in data/ — every other key of a section