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

01 RISC-V, mostly emulated

RISCV64 on a PC riscv64 guest TCG translates the usual case: slow on a riscv64 host riscv64 guest KVM, if any README: tier 3, experimental $ image-garden make ubuntu-cloud-24.04.riscv64.run ~/.cache/image-garden/dl/ubuntu/noble-server-cloudimg-riscv64.img checked against the same SHA256SUMS list as the x86_64 example the virt board OpenSBI, EDK2 nine systems snap, container give it time
On a PC a riscv64 guest is translated by TCG, slowly; on a riscv64 host it runs natively only where KVM is available, which the README ranks tier 3, experimental. image-garden make ubuntu-cloud-24.04.riscv64.run downloads noble-server-cloudimg-riscv64.img, checked against the same SHA256SUMS as the x86_64 example. The deck covers the virt board, OpenSBI and EDK2, nine systems, the snap and container, and giving it time

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.riscv64 downloads noble-server-cloudimg-riscv64.img, checked against https://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

02 The virt board, with ACPI off

THE VIRT BOARD, ACPI OFF qemu-system-riscv64 -machine virt,acpi=off,accel=… -m 2048 no ACPI: the kernel reads a device tree -cpu max every extension QEMU emulates -device virtio-net-pci,… no -smbios type=41 entry on a PC: the usual case accel=tcg -smp 1 emulated, many times slower on a riscv64 host with KVM accel=kvm:tcg -smp 4 native
ubuntu-cloud-24.04.riscv64.run, in short: qemu-system-riscv64 -machine virt,acpi=off, so the kernel reads a device tree; -cpu max; -m 2048; a virtio-net-pci card without the -smbios entry. On a PC accel=tcg and -smp 1, emulated; only a riscv64 host with KVM gets accel=kvm:tcg and -smp 4

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, CPU max, 1 vCPU unless the host is riscv64, then 4; memory 2048 MiB; network -netdev user with virtio-net-pci and 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; max enables 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" and QEMU_SMP_OPTION change one run; see the .run script.

for contributors

In the code

03 OpenSBI, then EDK2

OPENSBI, THEN EDK2 QEMU virt OpenSBI comes with QEMU EDK2, from flash the system's disk EDK2 must be on your host qemu-efi-riscv64 Fedora's EDK2 snap: qemu-riscv64 your own QEMU efi-code.riscv64.img, efi-vars.riscv64.img sized to 32 MiB ubuntu-cloud-24.04.riscv64.efi-code.qcow2, .efi-vars.qcow2 every riscv64 system boots efi
QEMU's virt board runs OpenSBI, which QEMU loads by itself, then EDK2 from the flash, which boots the system from its disk. EDK2 comes from qemu-efi-riscv64, Fedora's EDK2, the snap's qemu-riscv64 component or a self-built QEMU; make sizes the code and variable copies to the board's 32 MiB flash before each system gets its own. Every riscv64 system boots efi

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.rom and opensbi-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's qemu-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"; truncate pads 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.

for contributors

In the code

04 Nine systems, Ubuntu and Fedora

NINE SYSTEMS Ubuntu 24.04 25.04 25.10 26.04 26.10 Fedora 42 43 44 45 Fedora's alternative architectures tree, one dated build pinned each 9 systems all efi no other family no Debian, no EL, no Ubuntu Core $ image-garden make fedora-cloud-45.riscv64.run
Nine riscv64 systems: Ubuntu 24.04, 25.04, 25.10, 26.04 and 26.10, and Fedora 42, 43, 44 and 45, pinned dated builds from Fedora's alternative architectures tree; all efi. No other family and no Ubuntu Core. Each builds like the x86_64 example, such as image-garden make fedora-cloud-45.riscv64.run

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 as Fedora-Cloud-Base-Generic-45-20261022.0.riscv64.qcow2, checked against the .sha256 file beside it.
  • Ubuntu Core has no riscv64 systems, and make all on a riscv64 host leaves it out.

for contributors

In the code

05 The snap, the container or your distribution

WHERE QEMU COMES FROM the snap component qemu-riscv64: QEMU, EDK2, OpenSBI $ snap install image-garden+qemu-riscv64 without it: It seems that the component with QEMU riscv64 … the container QEMU_TARGET_LIST=…,riscv64-softmmu,… ENV GARDEN_RISCV64_PREFIX=/usr/local images for x86_64 and aarch64 hosts only a distribution Ubuntu: qemu-system-riscv qemu-efi-riscv64 image-garden make all builds your host's architecture only: on a PC, not these
The snap: the qemu-riscv64 component with QEMU, EDK2 and OpenSBI, added on a PC with snap install image-garden+qemu-riscv64, else the stub says the component with QEMU riscv64 is not installed. The container: riscv64-softmmu and GARDEN_RISCV64_PREFIX, images only for x86_64 and aarch64 hosts. Ubuntu: qemu-system-riscv and qemu-efi-riscv64. make all builds the host's architecture only

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-riscv64 holds "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 sets GARDEN_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-riscv and qemu-efi-riscv64. Distribution packages may be older than the upstream release (the maintainer's statement).
  • make all builds the systems of GARDEN_ARCH, your host's architecture unless you set it, as in image-garden make GARDEN_ARCH=riscv64 all (mk/000-garden.mk:16-18, rulegen.py:456-459).

for contributors

In the code

06 Inside: the makefile and its CI for contributors

INSIDE QEMU_SYSTEM_RISCV64_MACHINE = virt,acpi=off QEMU_CPU_RISCV64 = max QEMU_DEFAULT_NET_OPTION_RISCV64 ?= -netdev user,… -device virtio-net-pci,… efi-code.riscv64.img: $(firstword …) cp --preserve=timestamps $< $@ truncate --size 32MiB $@ .DELETE_ON_ERROR: a half-made copy is removed, not kept rulegen.py: Boot=efi only, ruleset_riscv64_efi CI: the riscv64 stage, emulated on x86_64 runners GARDEN_TEST_BOOT_ONLY: "1" allow_failure: true runs on version tags, by hand elsewhere
mk/010-qemu-riscv64.mk sets virt,acpi=off and max with plain assignments and a network option without -smbios; its firmware rules copy the first EDK2 found and truncate it to 32 MiB, and .DELETE_ON_ERROR removes a half-made copy; rulegen.py allows Boot=efi only and prints ruleset_riscv64_efi; in CI the riscv64 stage is emulated on x86_64 runners, boot only, on version tags or by hand, with allow_failure

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_ERROR exists 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_ARCH and ruleset_riscv64_efi (rulegen.py:302-309, rulegen.py:650-667).
  • CI: .systems-emulated (runners tagged qemu-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

GIVE IT TIME a quarter of an hour, or more, per boot spread one minute for SSH image-garden allocate waits for the guest's SSH first GARDEN_SSH_WAIT_TIMEOUT=600 kill-timeout: 60m in the spread task QEMU_SMP_OPTION="-smp 4" a thread per emulated CPU Little-endian, like x86_64 and aarch64: for byte order bugs, test on s390x
On a PC one riscv64 boot can take a quarter of an hour or more. spread allows one minute for SSH after allocation, so image-garden allocate waits for the SSH banner for up to GARDEN_SSH_WAIT_TIMEOUT, 600 seconds by default; raise it for slower guests. Give spread tasks a generous kill-timeout, and more CPUs with QEMU_SMP_OPTION. riscv64 is little-endian; test byte order on s390x

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 to GARDEN_SSH_WAIT_TIMEOUT seconds (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-timeout is 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).

08 Where to go from here

ROADS riscv64 Six architectures why emulation costs The adhoc backend waiting for SSH The .run script more CPUs and memory UEFI firmware the search lists Snap components qemu-riscv64 The container in CI its runners The support matrix
Roads from riscv64: six architectures, the adhoc backend, the .run script, UEFI firmware, snap components, the container in CI and the support matrix

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

FactValue
QEMU programqemu-system-riscv64; in the snap the image-garden.qemu-system-riscv64 app
Machinevirt,acpi=off
CPUmax
Acceleratortcg on any other host; kvm:tcg only where QEMU lists KVM (a riscv64 host with KVM)
vCPUs1, or 4 on a riscv64 host
Memory-m 2048
Boot typesefi only
FirmwareOpenSBI (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 componentqemu-riscv64: snap install image-garden+qemu-riscv64
ContainerQEMU with riscv64-softmmu, GARDEN_RISCV64_PREFIX=/usr/local; images for x86\_64 and aarch64 hosts only
Ubuntu packagesqemu-system-riscv, qemu-efi-riscv64
Host tier3: experimental, native where KVM is available
Byte orderlittle-endian (derived)

The nine systems

SystemImage
ubuntu-cloud-24.04.riscv64, 25.04, 25.10, 26.04, 26.10cloud-images.ubuntu.com, …-server-cloudimg-riscv64.img, current build
fedora-cloud-42.riscv64 to 45dl.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

WhatHow
allocate's wait for SSHGARDEN_SSH_WAIT_TIMEOUT, seconds, 600 by default, with --spread
Spread's limit per taskkill-timeout in the task (spread, derived)
More vCPUs for one runQEMU_SMP_OPTION="-smp 4"
More memory for one runQEMU_MEM_OPTION="-m 4096"
Build all riscv64 systems on a PCimage-garden make GARDEN_ARCH=riscv64 all

for contributors

Where it is set

FactSource
Program, machine, CPU, SMP, networkmk/010-qemu-riscv64.mk:3-9
Firmware lists, copies, truncatemk/010-qemu-riscv64.mk:75-116
Native vCPU count, memorymk/010-qemu.mk:5-12
Efi onlyrulegen.py:302-309
Snap componentsnap/snapcraft.yaml:74-80, :404-406
SSH waitimage-garden:1167-1203
CI stage and timings.gitlab-ci.yml:663-690, :919-948
Make variableEffect
QEMU_CPU_RISCV64 (=)the -cpu model; set on the make command line, not from the environment
QEMU_SMP_RISCV64the 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

ARCHITECTURES · machines and firmware

RUNTIME · make rules and the CLI

SPREAD · tests

SNAP · snap-only features

CONTAINER · OCI image