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

01 Three ways to start a machine

BOOT TYPES what starts the guest? UEFI firmware a legacy BIOS the machine's own loader Boot=efi Boot=bios Boot=platform [ubuntu-cloud-24.04.x86_64] URL=https://cloud-images… Arch=x86_64 Boot=efi Release=24.04 rulegen.py which make rules which firmware files what .run gives QEMU one word, from the INI file to the QEMU command line
A guest starts through UEFI firmware, a legacy BIOS or its machine's own loader; the Boot key says efi, bios or platform. The section of ubuntu-cloud-24.04.x86_64 says Boot=efi, and rulegen.py turns that into make rules, firmware files and the options of the .run script

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

  • Boot is an enum of platform, efi and bios (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, getting platform (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

02 Architecture first, then boot type

ARCHITECTURE, THEN BOOT TYPE Arch Boot rules rulegen.py writes x86_64 efi .qcow2 + .run, with UEFI firmware bios .qcow2 + .run, with QEMU's BIOS aarch64, riscv64, loongarch64 efi .qcow2 + .run, with UEFI firmware s390x, ppc64 platform .qcow2 + .run, the platform's way aarch64 bios rulegen.py stops: no rules at all Image 'example-cloud-1.aarch64' has Boot=bios, which aarch64 does not support, use efi
rulegen.py picks rules by architecture, then boot type: x86_64 efi and bios each get a .qcow2 and .run pair; aarch64, riscv64 and loongarch64 get efi rules; s390x and ppc64 get one pair, booting platform; any other combination, such as bios on aarch64, stops rulegen.py with an error that names the section and the values to use

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_ARCH lists the boot types each architecture has rules for, and load_boot checks every section against it while the INI file is read: no Boot on 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), which main reports as FILE: 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_efi or ruleset_x86_64_bios; aarch64, riscv64 and loongarch64 print their _efi ruleset; s390x and ppc64 print ruleset_s390x and ruleset_ppc64 (rulegen.py:804-821).
  • Each ruleset is a pair: X.run (the launcher) and X.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 efi and Image 'test-cloud.s390x' has Boot=efi, which s390x does not support, use platform (tests/check-rulegen.sh:189-212).

for contributors

In the code

03 What efi adds

WHAT EFI ADDS ubuntu-cloud-24.04.x86_64, efi the download, a qcow2 in the cache ubuntu-cloud-24.04.x86_64.seed.iso ubuntu-cloud-24.04.x86_64.efi-code.qcow2 ubuntu-cloud-24.04.x86_64.efi-vars.qcow2 -drive if=pflash,unit=0,…,readonly=on -drive if=pflash,unit=1,… code read-only, variables writable, in .run boot entries the guest saves stay with this system centos-cloud-9.x86_64, bios the download, a qcow2 in the cache centos-cloud-9.x86_64.seed.iso no firmware files, no flash drives: QEMU's built-in BIOS starts it
ubuntu-cloud-24.04.x86_64 boots efi: its .qcow2 needs the download, the seed.iso and two more files, its own .efi-code.qcow2 and .efi-vars.qcow2, which the .run script attaches as pflash unit 0, read-only, and unit 1, writable. centos-cloud-9.x86_64 boots bios: the download and the seed.iso only, no flash drives, and QEMU's built-in BIOS starts it

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.run has X.efi-code.qcow2 and X.efi-vars.qcow2 as order-only prerequisites, and X.qcow2 has them as prerequisites, words 3 and 4 passed to the command line (rulegen.py:593-610). ruleset_x86_64_bios has 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 .run script it is default_qemu_boot_firmware_option, which QEMU_BOOT_FIRMWARE_OPTION overrides (mk/010-qemu-x86_64.mk:67, :76).
  • The per-system copies are made by %.x86_64.efi-code.qcow2 and %.x86_64.efi-vars.qcow2 from the shared efi-code.x86_64.img and efi-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

04 The platform's own way

PLATFORM s390-ccw-virtio pseries s390-ccw.img slof.bin from QEMU's own data files [ubuntu-cloud-24.04.s390x] URL=https://cloud-images… SHA256SUMS=https://cloud-images… Arch=s390x Release=24.04 # no Boot: platform -cpu qemu -machine s390-ccw-virtio,accel=… -m 2048 -smp 1 -nographic -drive …qcow2 -device virtio-blk -device virtio-rng-pci -netdev user … virtio-net-pci no firmware option in the snap: the qemu-s390x and qemu-ppc64 components carry these loaders
QEMU's s390-ccw-virtio machine loads s390-ccw.img and the pseries machine slof.bin from QEMU's own data files. The section of ubuntu-cloud-24.04.s390x has no Boot key, so it is platform, and its .run script passes no firmware option, only CPU, machine, memory, disk, random number generator and network. In the snap, the qemu-s390x and qemu-ppc64 components carry the loaders

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 Boot key (data/ubuntu.ini:258-262); neither has any s390x or ppc64 section in the data (counted at the tag: 22). platform is 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.img for qemu-s390x, slof.bin, vof.bin and others for qemu-ppc64 (snap/snapcraft.yaml:380-410). That the machines load them by default is QEMU's behaviour (derived).

Read more

05 Where else the boot type is read for contributors

WHERE ELSE IT IS READ rulegen.py _ubuntu-cloud-24.04.x86_64_group := ubuntu _ubuntu-cloud-24.04.x86_64_release := 24.04 _ubuntu-cloud-24.04.x86_64_boot := efi data/000-systems.mk, the start of image-garden.mk $(eval $(call define-instance,ubuntu-cloud-24.04,webserver)) in .image-garden.mk efi bios platform the instance boots like its base Ubuntu Core: no INI section, rules written by hand in mk/050-ubuntu-core.mk every system efi, on x86_64 and aarch64
rulegen.py --systems-meta writes each system's group, release, architecture and boot type, such as _ubuntu-cloud-24.04.x86_64_boot := efi, into data/000-systems.mk, the first part of image-garden.mk. A named instance defined with define-instance looks up its base's boot type there and picks the efi, bios or platform branch. Ubuntu Core's rules are hand-written in mk/050-ubuntu-core.mk and boot efi on x86_64 and aarch64

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

06 When Boot is wrong or missing

COMMON MISTAKES [example-cloud-1.x86_64] Arch=x86_64 Boot=uefi data/example.ini: error: Image 'example-cloud-1.x86_64' has Boot='uefi', use one of platform, efi, bios [example-cloud-1.x86_64] Arch=x86_64 # no Boot only s390x and ppc64 may leave Boot out: they boot platform data/example.ini: error: Image 'example-cloud-1.x86_64' has no Boot=, use efi or bios for x86_64 data/050-example.gen.mk is deleted; the fix is one line: Boot=efi
Two mistakes, both caught by rulegen.py. Boot=uefi stops the build with data/example.ini: error: Image 'example-cloud-1.x86_64' has Boot='uefi', use one of platform, efi, bios. A section without Boot on x86_64 stops it with has no Boot=, use efi or bios for x86_64; only s390x and ppc64 may leave Boot out. The half-written data/050-example.gen.mk is deleted, and the fix is one line in the section

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_boot reads Boot and checks it against BOOT_BY_ARCH: a value that is not a boot type fails in choice, which names the key, the value and the allowed ones; a missing Boot is accepted only on s390x and ppc64 (rulegen.py:288-297, rulegen.py:300-333). main turns the error into SystemExit(f"{filename}: error: {exc}") (rulegen.py:753-757), so the build of data/050-example.gen.mk fails (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, bios and no-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 ends use efi for aarch64 and so on.
  • .DELETE_ON_ERROR in the top-level Makefile removes the .gen.mk the failed rulegen.py left, so the next make tries again (Makefile:16-18).
  • data/README.md: Boot is required for x86_64 (efi or bios) and for aarch64, riscv64 and loongarch64 (efi); s390x and ppc64 default to platform (data/README.md:34-38).
  • example-cloud-1 and data/example.ini are made-up names.

07 Where to go from here

ROADS Boot types Firmware UEFI code and variables The support matrix who boots which way Named instances what they inherit Six architectures the machine behind each Secure Boot and TPM the strictest efi INI keys the rest of a section
Roads from boot types: UEFI firmware per system, the support matrix, named instances, the six machines, Secure Boot and the TPM, and the INI keys

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

ArchBoot=efiBoot=biosBoot=platformBoot missing
x86_64ruleset_x86_64_efiruleset_x86_64_bioserrorerror
aarch64ruleset_aarch64_efierrorerrorerror
riscv64ruleset_riscv64_efierrorerrorerror
loongarch64ruleset_loongarch64_efierrorerrorerror
s390xerrorerrorruleset_s390xruleset_s390x
ppc64errorerrorruleset_ppc64ruleset_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

efibiosplatform
Per-system filesX.efi-code.qcow2, X.efi-vars.qcow2nonenone
Shared filesefi-code.ARCH.img, efi-vars.ARCH.imgnonenone
QEMU optionstwo -drive if=pflash, unit 0 read-onlynonenone
OverrideQEMU_BOOT_FIRMWARE_OPTION
Systems at the tag111 sections, plus every Ubuntu Core system6 x86_64 sectionsthe 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

UBUNTU CORE · all snaps

ARCHITECTURES · machines and firmware

RUNTIME · make rules and the CLI

  • Named instances — named instances, which inherit the boot type of their base

BUILD TIME · data and rules