riscv64
virt, no ACPI, EDK2 for users for contributors
riscv64 guests run on QEMU's virt board with ACPI off and -cpu max, almost always emulated with one vCPU; OpenSBI hands over to EDK2 sized to the board's 32 MiB flash, and only Ubuntu 24.04 and later and Fedora 42 to 45 have riscv64 builds, which need generous timeouts.
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 RISC-V, mostly emulated
riscv64 guests are emulated on a PC; a riscv64 host is tier 3, native only with KVM. image-garden make ubuntu-cloud-24.04.riscv64.run uses the riscv64 image from the same SHA256SUMS as the x86_64 example.
Say your software has to run on RISC-V boards, but you don't have one, or yours can't run virtual machines. That's the usual case, and image-garden handles it by emulation: QEMU translates every RISC-V instruction on your PC. It works, but slowly, and the README ranks a riscv64 host tier three, experimental, native only where KVM is available. Take ubuntu-cloud-24.04.riscv64: the same release as the running example, checked against the same list, with the riscv64 image. This deck covers the virt board, how the firmware boots, the nine systems, where QEMU comes from, and how to live with the slowness.
Details and sources
Details
- The README's host tiers: riscv64 (with s390x and ppc64le) is tier 3, "Experimental", "Native where KVM is available", "May timeout in CI, non-fatal failures"; guests of another architecture are emulated with 1 vCPU (README.md:384-396).
ubuntu-cloud-24.04.riscv64downloadsnoble-server-cloudimg-riscv64.img, checked againsthttps://cloud-images.ubuntu.com/noble/current/SHA256SUMS, the list of the x86\_64 example.- That few RISC-V boards offer KVM is general knowledge (derived); image-garden itself only asks QEMU whether it has KVM.
for contributors
In the code
- The section
[ubuntu-cloud-24.04.riscv64](data/ubuntu.ini:251-256), beside the x86\_64 one (:237-242).
Read more
02 The virt board, with ACPI off
qemu-system-riscv64 -machine virt,acpi=off -cpu max, accel=tcg and -smp 1 on a PC, -m 2048, virtio-net-pci without -smbios type=41.
Like Arm, RISC-V gets QEMU's virt board, but with ACPI turned off, so the guest's kernel learns about the hardware from a device tree instead. The CPU model is max: every extension QEMU can emulate. The network card is plain virtio, without the SMBIOS entry that names the card on x86_64 and aarch64. On a PC, the .run script finds no KVM for riscv64, picks TCG, and gives the guest one CPU. Only on a riscv64 host with KVM would it run natively, with four. Memory is the usual two gigabytes, and QEMU_MEM_OPTION raises it for one run.
Details and sources
Details
- Machine
virt,acpi=off, CPUmax, 1 vCPU unless the host is riscv64, then 4; memory 2048 MiB; network-netdev userwithvirtio-net-pciand no-smbios type=41, which x86\_64 and aarch64 have. - Without ACPI the guest kernel describes the hardware from the device tree QEMU's virt board provides;
maxenables every extension QEMU implements; a QEMU for riscv64 on another host has no KVM to offer (all derived from QEMU's documentation). QEMU_MEM_OPTION="-m 4096"andQEMU_SMP_OPTIONchange one run; see the .run script.
for contributors
In the code
- mk/010-qemu-riscv64.mk:3-23; the network option was split per architecture "with the smbios option excluded from riscv64" when riscv64 was added (commit 3dcb00d). The native count and memory: mk/010-qemu.mk:5-12.
Read more
03 OpenSBI, then EDK2
QEMU loads OpenSBI; EDK2 comes from /usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd, Fedora's /usr/share/edk2/riscv/, the snap's component or a prefix, sized to 32 MiB.
Booting RISC-V takes two firmwares. QEMU's virt board first runs OpenSBI, the layer beneath the operating system, which QEMU loads by itself. OpenSBI then starts EDK2 from the board's flash, and EDK2 boots the system from its disk. OpenSBI comes with QEMU. EDK2 must be on your host: Debian and Ubuntu's qemu-efi-riscv64 package, Fedora's EDK2, the snap's riscv64 component, or a QEMU you built. The board's flash is thirty-two megabytes, so make sizes both copies, code and variables, to exactly that before each system gets its own. Every riscv64 system boots efi.
Details and sources
Details
- The snap's riscv64 component carries
edk2-riscv-code.fd,edk2-riscv-vars.fd,efi-virtio.romandopensbi-riscv64-generic-fw_dynamic.bin, "the firmware QEMU loads by default" for the machine (snap/snapcraft.yaml:404-406, tests/snap/qemu-components/task.yaml:54-75). That OpenSBI runs in machine mode and starts EDK2 from pflash is QEMU's behaviour (derived). - EDK2 is looked for at
/usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd(Debian and Ubuntu'sqemu-efi-riscv64),/usr/share/edk2/riscv/RISCV_VIRT_CODE.fd(Fedora) and/usr/share/qemu/ovmf-riscv64-code.bin(openSUSE, commit ef5bc3c), then in the snap's component, then under$GARDEN_RISCV64_PREFIX/share/qemu/; the variables likewise. Which distribution installs which path is derived. - Both copies are truncated to 32 MiB, as "RISCV64 virtual machine requires 32MiB flash size";
truncatepads a shorter file and cuts a longer one (derived). - Missing firmware warns "please install riscv64 edk2 firmware - not in …" on every make; see UEFI firmware per system.
Read more
04 Nine systems, Ubuntu and Fedora
ubuntu-cloud-24.04, 25.04, 25.10, 26.04, 26.10 and fedora-cloud-42 to 45, each .riscv64. No Ubuntu Core.
The choice is short. Ubuntu has riscv64 cloud images from 24.04 on: 24.04, 25.04, 25.10, 26.04 and 26.10. Fedora has them from 42 to 45, from its tree for alternative architectures, and each pins one dated build, so a newer build waits for a new image-garden. That's nine systems, all booting efi. No other family has a riscv64 build, and neither has Ubuntu Core. If you need Debian or an enterprise distribution on RISC-V, it isn't here. On any of the nine, though, you work exactly as with the x86_64 example: one make command, one .run script.
Details and sources
Details
- Ubuntu on riscv64: 24.04, 25.04, 25.10, 26.04, 26.10; Fedora: "riscv64: Version 42+" (README.md:643-649, README.md:692-697).
- Fedora's riscv64 images come from
https://dl.fedoraproject.org/pub/alt/risc-v/release/RELEASE/Cloud/riscv64/images/, each a dated build such asFedora-Cloud-Base-Generic-45-20261022.0.riscv64.qcow2, checked against the.sha256file beside it. - Ubuntu Core has no riscv64 systems, and
make allon a riscv64 host leaves it out.
for contributors
In the code
- data/fedora.ini:80-166 (the four riscv64 sections); the Ubuntu sections in
data/ubuntu.ini; Ubuntu Core's systems exist for x86\_64 and aarch64 only (mk/050-ubuntu-core.mk:4-7), and joinall::only there (commit 073886d).
Read more
05 The snap, the container or your distribution
Snap: snap install image-garden+qemu-riscv64. Container: riscv64-softmmu and GARDEN_RISCV64_PREFIX, on x86_64 and aarch64 hosts. Ubuntu: qemu-system-riscv and qemu-efi-riscv64.
In the snap, riscv64 is the component qemu-riscv64, with QEMU, EDK2 and OpenSBI. On a PC it isn't installed for you: add it with snap install image-garden+qemu-riscv64, or the stand-in for QEMU stops with a message saying so. The container builds QEMU with riscv64 among its targets and points image-garden at that build's firmware, but it's published only for x86_64 and aarch64 hosts. On Ubuntu, install the packages qemu-system-riscv and qemu-efi-riscv64. And note that make all builds your host's architecture only, so on a PC it skips these nine.
Details and sources
Details
- The snap installs only the component of the host's architecture by itself (snap/hooks/install:6-13);
qemu-riscv64holds "the RISC-V 64-bit system emulator (QEMU) as well as the corresponding EFI firmware (EDK2)" (snap/snapcraft.yaml:74-80) and OpenSBI (:404-406). - Without it, QEMU's stand-in shows "It seems that the component with QEMU riscv64 is not installed" and
snap install image-garden+qemu-riscv64(qemu-stubs/qemu-system-riscv64:9-31). - The container builds
riscv64-softmmu(Dockerfile:33) and setsGARDEN_RISCV64_PREFIX=/usr/local(Dockerfile:98-102); its images are built for x86\_64 and aarch64 only (.gitlab-ci.yml:1238-1276). - On Ubuntu:
qemu-system-riscvandqemu-efi-riscv64. Distribution packages may be older than the upstream release (the maintainer's statement). make allbuilds the systems ofGARDEN_ARCH, your host's architecture unless you set it, as inimage-garden make GARDEN_ARCH=riscv64 all(mk/000-garden.mk:16-18, rulegen.py:456-459).
for contributors
In the code
- image-garden's CI installs those Ubuntu packages (.gitlab-ci.yml:292-311).
Read more
06 Inside: the makefile and its CI for contributors
mk/010-qemu-riscv64.mk: virt,acpi=off, max, no -smbios, truncate --size 32MiB. CI: the riscv64 stage, GARDEN_TEST_BOOT_ONLY, allow_failure: true.
For maintainers, riscv64 is a small makefile. It sets virt with ACPI off and CPU max, both plain assignments, and a network option of its own, without the SMBIOS entry. Its firmware rules copy the first EDK2 found, then truncate each copy to thirty-two megabytes; delete on error removes a copy that failed half-way, so a short file never looks finished. rulegen.py allows efi only and prints the riscv64 rule set. In CI, riscv64 is a stage of its own, emulated on x86_64 runners: each system only boots once, the jobs run on version tags or by hand, and they may fail without failing the pipeline.
Details and sources
Details
- The makefile's head:
QEMU_SYSTEM_RISCV64_MACHINE = virt,acpi=off,QEMU_CPU_RISCV64 = max,QEMU_SMP_RISCV64 = 1, the network option without-smbios(mk/010-qemu-riscv64.mk:3-9). - The firmware copies and
truncate --size 32MiB(mk/010-qemu-riscv64.mk:100-116);.DELETE_ON_ERRORexists so that "firmware that was copied but not resized, is not considered up to date" (mk/000-garden.mk:4-7). The snap bundles GNU truncate, as the base's uutils truncate was blocked by the sandbox and "broke building EFI variable storage for riscv64 systems" (NEWS.snappy:167-170). BOOT_BY_ARCHandruleset_riscv64_efi(rulegen.py:302-309, rulegen.py:650-667).- CI:
.systems-emulated(runners taggedqemu-emulated,GARDEN_TEST_BOOT_ONLY,allow_failure, version tags or manual) (.gitlab-ci.yml:663-690); the riscv64 jobs, with 65 to 90 minute timeouts, "20.4 minutes on novigrad" for the four Fedora systems, "31 minutes on novigrad; calvin took up to 19.2 for one" for three Ubuntu ones (.gitlab-ci.yml:919-948).
07 Give it time
Allocate waits up to GARDEN_SSH_WAIT_TIMEOUT (600 s) for SSH before it reports the address. More vCPUs: QEMU_SMP_OPTION="-smp 4". For a big-endian guest use s390x.
Emulation is the gotcha. On a PC, a single boot of a riscv64 system can take a quarter of an hour or more, and every task you run is slow too. Plan for it. spread gives a new machine one minute to answer SSH, so image-garden allocate waits for the guest's SSH server first, for up to GARDEN_SSH_WAIT_TIMEOUT, six hundred seconds by default; raise it for a slower guest. Give each spread task a generous kill timeout too. More CPUs, with QEMU_SMP_OPTION, can help, as QEMU runs each emulated CPU in a thread of its own. And RISC-V is little-endian: for byte order, test on s390x.
Details and sources
Details
- The quarter of an hour comes from image-garden's own test runs: booting each riscv64 system once took up to 19.2 minutes on one x86\_64 server, and the nine took about 76 minutes together on another (.gitlab-ci.yml:919-948). Your PC may be faster or slower.
- With
--spread, allocate waits for the SSH banner before it prints the address, up toGARDEN_SSH_WAIT_TIMEOUTseconds (600 by default), then reports the address anyway (image-garden:1167-1203, image-garden.1:542-549). Spread allows one minute after allocation (the comment at image-garden:1168-1171); see waiting for SSH. kill-timeoutis spread's per-task limit (spread's documentation, derived). QEMU runs each vCPU of a TCG guest in a thread of its own on hosts that support it (multi-threaded TCG, derived), so more vCPUs can help when the host has idle cores.- riscv64 Linux is little-endian, s390x big-endian (derived, general knowledge).
Read more
08 Where to go from here
Next: six architectures, the adhoc backend, the .run script, UEFI firmware, snap components, the container in CI and the support matrix.
So riscv64 is QEMU's virt board without ACPI, OpenSBI and EDK2, nine systems, and a lot of patience. From here, the architectures deck shows why emulation costs so much. The adhoc backend deck explains how allocate waits for a slow guest, and the run script deck how to give it more CPUs and memory. The firmware deck has the search lists, the snap components deck the riscv64 component, the container in CI deck its runners, and the support matrix sets riscv64 beside the rest.
Details and sources
Read more
Basis of the statements on this page
Read in the README, mk/010-qemu-riscv64.mk, mk/010-qemu.mk, mk/000-garden.mk, rulegen.py, data/ubuntu.ini, data/fedora.ini, snap/snapcraft.yaml, qemu-stubs/qemu-system-riscv64, tests/snap/qemu-components/task.yaml, the Dockerfile, .gitlab-ci.yml, NEWS.snappy and the man page of image-garden at the commit in garden.commit ("code"). The timings are the CI comments' figures, not measured for this page. What OpenSBI, ACPI, the device tree, max and multi-threaded TCG do, distribution package paths, and byte order are derived. Nothing was run for this page.
riscv64 at a glance
| Fact | Value |
|---|---|
| QEMU program | qemu-system-riscv64; in the snap the image-garden.qemu-system-riscv64 app |
| Machine | virt,acpi=off |
| CPU | max |
| Accelerator | tcg on any other host; kvm:tcg only where QEMU lists KVM (a riscv64 host with KVM) |
| vCPUs | 1, or 4 on a riscv64 host |
| Memory | -m 2048 |
| Boot types | efi only |
| Firmware | OpenSBI (loaded by QEMU), then EDK2 RISCV_VIRT_CODE.fd and RISCV_VIRT_VARS.fd, copied to efi-code.riscv64.img and efi-vars.riscv64.img and truncated to 32 MiB |
| Network | -netdev user, virtio-net-pci, no -smbios |
| Snap component | qemu-riscv64: snap install image-garden+qemu-riscv64 |
| Container | QEMU with riscv64-softmmu, GARDEN_RISCV64_PREFIX=/usr/local; images for x86\_64 and aarch64 hosts only |
| Ubuntu packages | qemu-system-riscv, qemu-efi-riscv64 |
| Host tier | 3: experimental, native where KVM is available |
| Byte order | little-endian (derived) |
The nine systems
| System | Image |
|---|---|
ubuntu-cloud-24.04.riscv64, 25.04, 25.10, 26.04, 26.10 | cloud-images.ubuntu.com, …-server-cloudimg-riscv64.img, current build |
fedora-cloud-42.riscv64 to 45 | dl.fedoraproject.org/pub/alt/risc-v/release/, one dated build each, with its .sha256 file |
No Ubuntu Core, and no other family.
Living with emulation
| What | How |
|---|---|
| allocate's wait for SSH | GARDEN_SSH_WAIT_TIMEOUT, seconds, 600 by default, with --spread |
| Spread's limit per task | kill-timeout in the task (spread, derived) |
| More vCPUs for one run | QEMU_SMP_OPTION="-smp 4" |
| More memory for one run | QEMU_MEM_OPTION="-m 4096" |
| Build all riscv64 systems on a PC | image-garden make GARDEN_ARCH=riscv64 all |
for contributors
Where it is set
| Fact | Source |
|---|---|
| Program, machine, CPU, SMP, network | mk/010-qemu-riscv64.mk:3-9 |
| Firmware lists, copies, truncate | mk/010-qemu-riscv64.mk:75-116 |
| Native vCPU count, memory | mk/010-qemu.mk:5-12 |
| Efi only | rulegen.py:302-309 |
| Snap component | snap/snapcraft.yaml:74-80, :404-406 |
| SSH wait | image-garden:1167-1203 |
| CI stage and timings | .gitlab-ci.yml:663-690, :919-948 |
| Make variable | Effect |
|---|---|
QEMU_CPU_RISCV64 (=) | the -cpu model; set on the make command line, not from the environment |
QEMU_SMP_RISCV64 | the default -smp |
QEMU_EDK2_CODE_RISCV64, QEMU_EDK2_VARS_RISCV64 (?=) | the EDK2 search lists |
GARDEN_RISCV64_PREFIX (environment) | appends a self-built QEMU's share/qemu firmware |
Roads from here
SYSTEMS · distributions
- The support matrix — riscv64 beside the other five architectures
ARCHITECTURES · machines and firmware
- Six architectures, six QEMU machines — why emulation is slow, and the vCPU count
- UEFI firmware per system — the EDK2 search lists every efi architecture shares
RUNTIME · make rules and the CLI
- The .run script — more CPUs and memory for one boot
SPREAD · tests
- The adhoc backend: allocate and discard — how allocate waits for a slow guest's SSH
SNAP · snap-only features
- Snap components — installing qemu-riscv64 in the snap
CONTAINER · OCI image
- Running the container in CI — the container on CI runners