s390x
s390-ccw-virtio, big-endian for users for contributors
s390x, the only big-endian architecture image-garden runs: twelve Ubuntu and Fedora systems on QEMU's s390-ccw-virtio machine with CPU qemu, booted by the machine's own loader with no firmware files, a ccw disk and PCI network, emulated by TCG on one vCPU unless the host is s390x.
On the map: architectures
▶ Watch this deck — 9 scenes, ~7 min
Worth seeing first
- Six architectures, six QEMU machines — the machine, CPU and accelerator choices every architecture shares
01 The big-endian one
Twelve s390x systems, Ubuntu 18.04 to 26.10 and Fedora 42 to 45, all big-endian: image-garden make ubuntu-cloud-24.04.s390x.run.
Say your code reads binary files, hashes structures or speaks a network protocol, and every machine you test on is little-endian. Then a whole class of mistakes never shows up. s390x, the architecture of IBM's mainframes, is big-endian, the only big-endian architecture image-garden runs, and that's exactly why people test there. There are twelve systems: Ubuntu from 18.04 and Fedora from 42. You build ubuntu-cloud-24.04.s390x like any other, with one make command for its .run script. Unless your host is a mainframe, it's emulated, so give it time. This deck shows the machine, how it boots, what emulation costs, the installs that bring it, and the gotchas.
Details and sources
Details
- The other five architectures run little-endian systems only: ppc64's are Ubuntu's little-endian ppc64el images (mk/000-garden.mk:14-16); that s390x is big-endian and the others are little-endian is general architecture knowledge (derived).
- Ubuntu on s390x: 18.04, 20.04, 22.04, 24.04, 25.04, 25.10, 26.04, 26.10; Fedora on s390x: 42 and later (README.md:643-649, README.md:692-697).
- On a host that is not s390x, QEMU has no KVM for the guest and runs it under TCG (derived; see emulation is slow).
for contributors
In the data
S390Xis one of rulegen.py's six architectures (rulegen.py:23-29). The running example is data/ubuntu.ini:258-262; the first is data/ubuntu.ini:95-99, the Fedora sections run from data/fedora.ini:87-91 to data/fedora.ini:168-172. No other INI file hasArch=s390x(counted at the commit: 12 sections).- The release notes that added the architecture: "Initial support for s390x system emulation ... Ubuntu (since Ubuntu 18.04) as well as Fedora (since 42)" (NEWS:620-622).
Read more
02 The s390-ccw-virtio machine
qemu-system-s390x -machine s390-ccw-virtio -cpu qemu, -smp 1 (4 on s390x), -m 2048. virtio-blk is a ccw device here; virtio-net-pci and virtio-rng-pci sit on zPCI.
The .run script starts QEMU's s390x emulator on the s390-ccw-virtio machine, a virtual mainframe made for virtio devices, with the CPU model called qemu. It gets one CPU, or four on an s390x host, and the usual two gigabytes. Mainframes attach devices through channels rather than PCI, and QEMU follows suit: the disk, asked for as plain virtio-blk, becomes a channel device, a CCW device. So does the cloud-init seed during the provisioning boot. The network card and the random number generator, though, are named as PCI devices, and QEMU carries them over zPCI, the mainframe's own PCI. The guest's kernel sees both kinds.
Details and sources
Details
QEMU_SYSTEM_S390Xis the snap'sqemu-system-s390xapp in the snap, elseqemu-system-s390xfromPATH;QEMU_SYSTEM_S390X_MACHINE = s390-ccw-virtio,QEMU_CPU_S390X = qemu,QEMU_SMP_S390X = 1, the network-netdev userwithvirtio-net-pci, and the disk-device virtio-blk,drive=drive0,bootindex=0(mk/010-qemu-s390x.mk:3-21).- Memory
-m 2048,-nographic, and-device virtio-rng-pciare common to every architecture; the host's own architecture gets 4 CPUs (mk/010-qemu.mk:5-13, mk/010-qemu.mk:45). - On s390x, QEMU resolves the device name
virtio-blktovirtio-blk-ccw, a device on the channel subsystem, and places PCI devices such asvirtio-net-pciandvirtio-rng-pcion the machine's zPCI bus; the guest's kernel needs zPCI support for them, which the Ubuntu and Fedora kernels have (derived from QEMU's device aliases and the s390x PCI support; not run here). - The snap's s390x component carries
efi-virtio.rom, the option ROM file QEMU loads for avirtio-net-pcicard (snap/snapcraft.yaml:407-408).
for contributors
In the rules
- The provisioning boot adds the seed ISO as
-drive ...,media=cdromwith-device virtio-blk,drive=drive1(rulegen.py:697-704).
Read more
03 Booting with the machine's own loader general version
No firmware files: QEMU's s390-ccw.img loader boots the disk with bootindex=0. The seed is attached only for the provisioning boot.
On x86_64, aarch64 or riscv64, most systems boot through UEFI firmware, found on your host or in the snap and copied for each system. s390x needs none of that. QEMU's mainframe machine loads its own small boot loader from QEMU's data files, and the loader starts the disk marked as boot index zero, your system's overlay. So there's no firmware package to install and nothing next to the image but the qcow2 and the .run script. Making them takes one provisioning boot with the cloud-init seed attached; every later boot needs the .run script alone.
Details and sources
Details
- The s390x
.runcommand line has no firmware option; the disk hasbootindex=0(mk/010-qemu-s390x.mk:10-21). - The snap's s390x component carries
s390-ccw.imgfrom QEMU's build (snap/snapcraft.yaml:407-408). That the s390-ccw-virtio machine loads it by default and that it boots the device with the lowest boot index is QEMU's behaviour (derived). make cleanremoves*.s390x.qcow2(mk/010-qemu-s390x.mk:70-72).
Read more
04 Platform boot in the data and the rules for contributors in place of the general version
s390x sections have no Boot, so platform; rulegen.py prints ruleset_s390x: a .run rule without firmware and a .qcow2 rule with one provisioning boot.
Here's how the data says that. The s390x sections leave the Boot key out. rulegen.py knows s390x boots one way, platform, so a missing key means platform, and any other value is an error that names the section. For every s390x section it prints the same pair of rules. The .run rule writes the s390x command line into the script, with no firmware option. The qcow2 rule waits for the download and the seed, makes the overlay with qemu-img, and runs one provisioning boot with the seed as a second virtio disk, logging to the qcow2.log file. Named instances take the same platform branch.
Details and sources
Details
- s390x and ppc64 boot one way,
platform, the default whenBootis not given; another value fails with "Image '...' has Boot=..., which s390x does not support, use platform" (rulegen.py:300-333). The running example has noBootkey (data/ubuntu.ini:258-262), and neither has any s390x section. - rulegen.py prints
ruleset_s390xfor every s390x section: a.runrule that emitsEMIT_QEMU_SYSTEM_S390X_RUN_COMMAND, and a.qcow2rule that depends on the download and the seed ISO, creates the overlay withqemu-img create -band runsQEMU_SYSTEM_S390X_CMDLINEwith the seed, underset -o pipefail, into.qcow2.log(rulegen.py:688-705, rulegen.py:818-819). - Named instances of an s390x system use the
platformbranch (mk/020-instances.mk:126-144).
Read more
05 Emulated, on one CPU general version
Without an s390x host, QEMU uses TCG and -smp 1. Making and booting one Ubuntu image took up to 16.2 minutes on x86_64; QEMU_SMP_OPTION adds CPUs.
Unless your host is an s390x machine itself, an IBM Z or a LinuxONE, there's no KVM for this guest. The .run script asks QEMU each time it starts, finds only TCG, and every mainframe instruction is translated in software. That's slow, and one CPU makes it slower: four go only to your host's own architecture. To give you a feel for it, making and booting one Ubuntu image once has taken up to sixteen minutes on an x86_64 machine. So set long timeouts, and for your own runs, set QEMU_SMP_OPTION to give the guest more CPUs.
Details and sources
Details
- The
.runscript asksqemu-system-s390x -accel helpeach time and usesaccel=kvm:tcgwhenkvmis listed, elseaccel=tcg(mk/010-qemu-s390x.mk:31, mk/010-qemu-s390x.mk:38). KVM for an s390x guest needs an s390x host (derived). - s390x guests get 1 vCPU, and 4 when the host is s390x (mk/010-qemu-s390x.mk:6, mk/010-qemu.mk:5-6). The README lists s390x hosts as tier 3, "Native where KVM is available" (README.md:389-396).
- The 16.2 minutes is the longest time recorded for one Ubuntu s390x image, made and booted once with
-smp 2on an x86\_64 machine (.gitlab-ci.yml:960-969). - QEMU runs the guest's vCPUs in parallel threads under TCG, so more CPUs can help (derived).
Read more
06 How image-garden's CI tests s390x for contributors in place of the general version
Stage s390x: three jobs on x86_64 runners, GARDEN_TEST_BOOT_ONLY, -smp 2, 40 minutes per system, allow_failure: true.
Without an s390x host there's no KVM, so QEMU translates every instruction with TCG, on one CPU. image-garden's own pipeline tests s390x exactly that way, in a stage of its own on x86_64 runners: Fedora in one job, Ubuntu in two. Each job only makes and boots every image once, skipping spread, with -smp 2 and a gigabyte of memory, and gives each system forty minutes. The jobs run on version tags and by hand elsewhere, and may fail without holding anything up. The comments record the cost: about thirteen minutes for four Fedora images, and up to sixteen for one Ubuntu image.
Details and sources
Details
- Every system job sets
QEMU_SMP_OPTION: -smp 2andQEMU_MEM_OPTION: -m 1024(.gitlab-ci.yml:568-569);.systems-emulatedruns on runners taggedqemu-emulated,linux,x86_64, setsGARDEN_TEST_BOOT_ONLY: "1"andGARDEN_CI_SYSTEM_TIMEOUT: 40m,allow_failure: true, and is manual outside version tags (.gitlab-ci.yml:663-690). - Boot only:
tests/ci/run-systems.shmakesSYSTEM.ARCH.run, checks--query, and stops there (tests/ci/run-systems.sh:62-72). - The three jobs:
s390x: [fedora]45 minutes, "12.9 minutes on novigrad; calvin took up to 8.2 for one";s390x: [ubuntu 1/2]105 minutes, "35.2 minutes on novigrad; calvin took up to 16.2 for one";s390x: [ubuntu 2/2]115 minutes, "39.9 minutes on novigrad; calvin took up to 18.7 for one" (.gitlab-ci.yml:950-981). The slide gives the first Ubuntu job's figure. - The CI installs Ubuntu's
qemu-system-s390xpackage (.gitlab-ci.yml:292-310).
Read more
07 Snap, container or packages
Snap: snap install image-garden+qemu-s390x. Container: s390x-softmmu, no prefix. Ubuntu: qemu-system-s390x.
Every install can run it. In the snap, QEMU for s390x is a component: snap install image-garden+qemu-s390x. The snap adds only your host's own component by itself, so on a PC you add this one by hand. It brings the emulator and the machine's boot loader. Forget it, and you find out after the image has downloaded: the provisioning boot stops with a notice that names the command. The container builds QEMU with s390x among its targets, and needs no firmware prefix for it. On a distribution, install its s390x QEMU, which on Ubuntu is the package qemu-system-s390x.
Details and sources
Details
- The
qemu-s390xcomponent: "This component contains the s390x 64-bit system emulator (QEMU)" (snap/snapcraft.yaml:81-86); the build gives itqemu-system-s390x, the keymaps,efi-virtio.romands390-ccw.img(snap/snapcraft.yaml:381-394, snap/snapcraft.yaml:407-408). - The install hook installs
+qemu-$(uname -m)(with_made-) and+pkgproxy, so on an x86\_64 host the s390x component is added by hand (snap/hooks/install:6-14, README.md:309-324). - Without it, the snap's stand-in for
qemu-system-s390xprints a notice box, "It seems that the component with QEMU s390x is not installed", andsnap install image-garden+qemu-s390x, and exits 1 (qemu-stubs/qemu-system-s390x:9-31). s390x has no firmware to copy, so the first QEMU to run is the provisioning boot, after the download. - The container's QEMU target list includes
s390x-softmmu(Dockerfile:33); it setsGARDEN_*_PREFIXonly for the four efi architectures (Dockerfile:98-102). - On Ubuntu the emulator is the
qemu-system-s390xpackage. Distribution packages of image-garden may be older than the upstream release (the maintainer's statement).
for contributors
In the tree
- s390x has no firmware copy rule; the first QEMU run is the
.qcow2rule's provisioning boot (rulegen.py:697-704). - image-garden's CI installs Ubuntu's
qemu-system-s390xpackage (.gitlab-ci.yml:292-310).
Read more
08 Gotchas, byte order first
Little-endian assumptions in file formats, hashes over raw structs and hand-made byte swaps fail on s390x; so does code that relies on signed char. Emulated jobs need long timeouts and should not block.
So what breaks on s390x? Mostly byte order. Code that copies four bytes straight into an integer reads a little-endian file format correctly on a PC, and gets a different number here. A hash or checksum computed over a raw struct changes too. Code that swaps bytes unconditionally, instead of converting to network byte order, works on x86 by accident and fails here. And plain char is unsigned. Those failures are the point: they're why you test on s390x. Then the practical ones: give every job a far longer timeout, and don't let an emulated job hold up your pipeline.
Details and sources
Details
- Byte order: s390x stores the most significant byte first; x86\_64, and the aarch64, riscv64, loongarch64 and ppc64el systems image-garden runs, store the least significant first. Reading a little-endian on-disk or on-wire format by copying bytes into an integer, hashing the bytes of a struct, or swapping bytes unconditionally instead of using
htonl/ntohlor explicit little-endian decoding, all give different results on s390x (derived: general architecture knowledge, not in image-garden's tree). char: the s390x Linux ABI makes plaincharunsigned, as on aarch64 and POWER; x86\_64 makes it signed (derived).- The README: tier 3 hosts "May timeout in CI, non-fatal failures" (README.md:389-396).
- The spread backend in the README and in image-garden's own
spread.yamlappends$ARCH, oruname -m, to the system name; on an x86\_64 host, setARCH=s390xto test s390x (spread.yaml:43-47).
for contributors
In image-garden's CI
- The emulated jobs are boot only, 40 minutes per system,
allow_failure: true, and manual outside version tags (.gitlab-ci.yml:663-690).
Read more
09 Where to go from here
Next: six architectures, boot types, the support matrix, ppc64, snap components, the container in CI and the .run script.
So s390x is one machine, one loader, a channel disk and twelve big-endian systems. From here, the architectures deck sets it beside the other five machines. The boot types deck explains platform next to efi and bios, and the support matrix shows its systems among the rest. The ppc64 deck covers the other platform-boot architecture, a little-endian one. The snap components deck shows how components install, the container deck runs it in CI, and the run script deck gives a slow guest more CPUs.
Details and sources
Read more
- Six architectures, boot types, the support matrix, ppc64.
- Snap components, the container in CI, the .run script.
- The other architectures: x86_64, aarch64, riscv64, loongarch64.
Read more
Basis of the statements on this page
Read in mk/010-qemu-s390x.mk, mk/010-qemu.mk, mk/000-garden.mk, rulegen.py, data/ubuntu.ini, data/fedora.ini, snap/snapcraft.yaml, snap/hooks/install, qemu-stubs/qemu-system-s390x, the Dockerfile, .gitlab-ci.yml and the README of image-garden at the commit in garden.commit ("code"). The CI timings are the comments in .gitlab-ci.yml. What QEMU does with the device names on s390x, that s390x is big-endian, and the C ABI notes are general knowledge ("derived"). Nothing was run for this page.
The s390x machine
| Fact | Value | Where |
|---|---|---|
| QEMU binary | qemu-system-s390x; in the snap the image-garden.qemu-system-s390x app | QEMU_SYSTEM_S390X |
| Machine | s390-ccw-virtio | QEMU_SYSTEM_S390X_MACHINE |
| CPU | qemu | QEMU_CPU_S390X |
| vCPUs | 1, or 4 on an s390x host | QEMU_SMP_S390X, QEMU_SMP_OPTION |
| Memory | 2048 MiB | QEMU_MEM_SIZE, QEMU_MEM_OPTION |
| Accelerator | kvm:tcg when QEMU lists KVM, else tcg | QEMU_ACCEL_MACHINE_PROP |
| Disk | -device virtio-blk,drive=drive0,bootindex=0, a virtio-blk-ccw device (derived) | QEMU_STORAGE_OPTION |
| Seed (provisioning boot) | -device virtio-blk,drive=drive1, media=cdrom, also ccw (derived) | the .qcow2 rule |
| Network | -netdev user, -device virtio-net-pci, on zPCI (derived) | QEMU_NET_OPTION |
| Random numbers | -device virtio-rng-pci, on zPCI (derived) | QEMU_RNG_OPTION |
| Display | -nographic | QEMU_DISPLAY_OPTION |
| Boot | platform: no firmware files; QEMU's s390-ccw.img loader | |
| Snap component | qemu-s390x: qemu-system-s390x, keymaps, efi-virtio.rom, s390-ccw.img | snap/snapcraft.yaml |
| Container | QEMU built with s390x-softmmu; no GARDEN_S390X_PREFIX | Dockerfile |
| Ubuntu package | qemu-system-s390x | |
| Byte order | big-endian (derived) |
Sources: mk/010-qemu-s390x.mk:3-21, mk/010-qemu.mk:5-13, mk/010-qemu.mk:45, rulegen.py:300-333, rulegen.py:688-705, snap/snapcraft.yaml:407-408, Dockerfile:33.
The twelve systems
| System | Image | Boot |
|---|---|---|
ubuntu-cloud-18.04.s390x | bionic-server-cloudimg-s390x.img | platform |
ubuntu-cloud-20.04.s390x | focal-server-cloudimg-s390x.img | platform |
ubuntu-cloud-22.04.s390x | jammy-server-cloudimg-s390x.img | platform |
ubuntu-cloud-24.04.s390x | noble-server-cloudimg-s390x.img | platform |
ubuntu-cloud-25.04.s390x | ubuntu-25.04-server-cloudimg-s390x.img | platform |
ubuntu-cloud-25.10.s390x | questing-server-cloudimg-s390x.img | platform |
ubuntu-cloud-26.04.s390x | resolute-server-cloudimg-s390x.img | platform |
ubuntu-cloud-26.10.s390x | stonking-server-cloudimg-s390x.img | platform |
fedora-cloud-42.s390x | Fedora-Cloud-Base-Generic-42-1.1.s390x.qcow2 | platform |
fedora-cloud-43.s390x | Fedora-Cloud-Base-Generic-43-1.6.s390x.qcow2 | platform |
fedora-cloud-44.s390x | Fedora-Cloud-Base-Generic-44-1.7.s390x.qcow2 | platform |
fedora-cloud-45.s390x | Fedora-Cloud-Base-Generic-45-1.4.s390x.qcow2 | platform |
Ubuntu's come from cloud-images.ubuntu.com with the release's SHA256SUMS; Fedora's from Fedora's secondary architectures tree (42 from its archive) with the image's CHECKSUM file. Sections: data/ubuntu.ini, data/fedora.ini:87-172. See the support matrix.
The .run command line
What ubuntu-cloud-24.04.s390x.run runs with every default, outside the snap, on an x86\_64 host:
qemu-system-s390x -cpu qemu -machine s390-ccw-virtio,accel=tcg \ -m 2048 -smp 1 -nographic \ -drive file=ubuntu-cloud-24.04.s390x.qcow2,if=none,format=qcow2,id=drive0,media=disk,cache=writeback,discard=unmap \ -device virtio-blk,drive=drive0,bootindex=0 \ -device virtio-rng-pci \ -netdev user,id=netdev0 -device virtio-net-pci,netdev=netdev0,id=net0
-netdev user also takes QEMU_NETDEV_USER_EXTRA, which allocate sets to forward SSH (image-garden:1107), and the pkgproxy bridge when one is in use; see the .run script. Arguments to the script go to QEMU after these.
for contributors
In image-garden's CI
| Job | Systems | Timeout | Recorded time |
|---|---|---|---|
s390x: [fedora] | fedora-cloud-42 to 45 | 45m | 12.9 minutes; up to 8.2 for one |
s390x: [ubuntu 1/2] | ubuntu-cloud 18.04, 20.04, 22.04, 24.04 | 105m | 35.2 minutes; up to 16.2 for one |
s390x: [ubuntu 2/2] | ubuntu-cloud 25.04, 25.10, 26.04, 26.10 | 115m | 39.9 minutes; up to 18.7 for one |
Each runs on an x86\_64 runner tagged qemu-emulated, boots each image once, with -smp 2 and -m 1024, 40 minutes per system, allow_failure: true; on version tags it runs, elsewhere by hand (.gitlab-ci.yml:663-690, .gitlab-ci.yml:950-981).
Byte order checklist (derived)
- Decode on-disk and on-wire integers byte by byte, or with explicit little- or big-endian helpers, never by copying bytes into an integer.
- Hash or sign a serialised form, not the in-memory bytes of a struct.
- Use
htonl,ntohland friends rather than an unconditional byte swap; on s390x they do nothing, which is correct. - Bit fields and unions that overlay integers on byte arrays lay out differently.
- Plain
charis unsigned on s390x; usesigned charorint8_twhere the sign matters.
Roads from here
SYSTEMS · distributions
- The support matrix — the twelve s390x systems among all the others
ARCHITECTURES · machines and firmware
- Six architectures, six QEMU machines — the other machines, and why emulation is slow
- Boot types — what platform boot means beside efi and bios
- ppc64 — the other platform-boot architecture, and a little-endian one
RUNTIME · make rules and the CLI
- The .run script — more CPUs or memory for an emulated guest
SNAP · snap-only features
- Snap components — how the snap's per-architecture QEMU components install
CONTAINER · OCI image
- Running the container in CI — the container in CI, whose QEMU has s390x