loongarch64 and OpenCloudOS

OpenCloudOS 9 for users for contributors

opencloudos-cloud-9, a pinned OpenCloudOS 9.6 build for x86_64, aarch64 and loongarch64, is the only loongarch64 system; it boots efi on QEMU's virt board with CPU max and LoongArch EDK2, and in the snap the qemu-loongarch64 component carries the emulator, the firmware and the virtio card's efi-virtio.rom.

On the map: architectures

▶ Watch this deck — 8 scenes, ~5 min

Worth seeing first

01 A sixth architecture, and its first system

LOONGARCH64 LoongArch, which QEMU calls loongarch64 a QEMU machine: virt, max and, for a while, nothing to boot opencloudos-cloud-9.x86_64 opencloudos-cloud-9.aarch64 opencloudos-cloud-9.loongarch64 $ image-garden make opencloudos-cloud-9.loongarch64.run on a PC: emulated by TCG, so give it time its image machine, firmware one small file every install
LoongArch is loongarch64 to QEMU. image-garden had a virt machine for it before any system; opencloudos-cloud-9 is the first, built for x86_64, aarch64 and loongarch64. image-garden make opencloudos-cloud-9.loongarch64.run builds it; on a PC it is emulated, so give it time

opencloudos-cloud-9 is the only loongarch64 system, also built for x86_64 and aarch64: image-garden make opencloudos-cloud-9.loongarch64.run.

Say your software has to run on LoongArch, the 64-bit architecture QEMU calls loongarch64. image-garden had a QEMU machine for it before it had anything to boot there. OpenCloudOS 9 changed that: opencloudos-cloud-9 is the first and so far the only loongarch64 system, and it comes for x86_64 and aarch64 too. You build it like ubuntu-cloud-24.04.x86_64, with one make command for its .run script. On a PC it's emulated, so give it time. This deck shows where its image comes from, the machine and its firmware, one small file the network card needs, and which installs bring it all.

Details and sources

Details

  • Loongarch64 is one of rulegen.py's six architectures (rulegen.py:23-29). The older release notes added the machine "No distribution cloud images are available for loongarch64 yet" (NEWS:346-351); this release adds opencloudos-cloud-9, "image-garden's first loongarch64 system" (NEWS:52-53).
  • The README: "OpenCloudOS 9 is the only loongarch64 system", for x86\_64, aarch64 and loongarch64 (README.md:598-606, README.md:658-662); the sections are in data/opencloudos.ini:13-32.
  • On an x86_64 host QEMU has no KVM for loongarch64, so it runs under TCG (derived; see emulation is slow).

02 A pinned build general version

A PINNED BUILD one directory per build, no alias for the latest the same build on all three newer: a new image-garden OpenCloudOS-GenericCloud-9.6-20260922.0.loongarch64.qcow2.sha256 its own checksum, next to it x86_64 aarch64 loongarch64 UEFI boot on all three opencloudos-cloud-9.loongarch64 the 9 is the release https://mirrors.opencloudos.tech/opencloudos/9.6/images/qcow2/ loongarch64/20260922.0/ OpenCloudOS-GenericCloud-9.6-20260922.0.loongarch64.qcow2
opencloudos-cloud-9.loongarch64 downloads build 20260922.0 of 9.6 from a directory of its own on the OpenCloudOS mirror, as OpenCloudOS has no alias for the latest build; the same build for x86_64, aarch64 and loongarch64, and a newer one comes with a new image-garden. Each image is checked against the .sha256 file next to it. All three boot with UEFI, and the 9 in the name is the release

The download names build 20260922.0 of 9.6, the same on x86_64, aarch64 and loongarch64, checked against the .sha256 file next to the image. All three boot with UEFI.

So where does its image come from? OpenCloudOS publishes each build of its cloud images in a directory named after the build, with no alias for the latest one. So image-garden downloads one fixed build of 9.6, the same for all three architectures, and moving to a newer build takes a new image-garden. And instead of one checksum list for a whole release, each image has its own checksum file right next to it: the image's address with .sha256 on the end. All three boot with UEFI, and the 9 in the name is the release.

Details and sources

Details

  • The data file's comment: each build sits in a directory named after it, "with the build in the file name, and no alias for the latest one: pin a build, and move to a newer one by hand. Builds of 9.6 for the three architectures appear together, on the project's own mirror" (data/opencloudos.ini:4-7).
  • All three systems download build 20260922.0 of 9.6 and its .sha256 file over https from the project's own mirror, and boot with UEFI (data/opencloudos.ini:13-32).

for contributors

In the data

03 A pinned build, in its section for contributors in place of the general version

A PINNED BUILD one directory per build, no alias for the latest moving on: an edit by hand the checksum file sits next to the image: @URL@ is the image's resolved URL, so this is URL + .sha256 x86_64, aarch64 and loongarch64: the same build, Boot=efi, Release=9 [opencloudos-cloud-9.loongarch64] URL=https://mirrors.opencloudos.tech/opencloudos/9.6/images/qcow2/ loongarch64/20260922.0/ OpenCloudOS-GenericCloud-9.6-20260922.0.loongarch64.qcow2 SHA256SUMS=@URL@.sha256 Arch=loongarch64 Boot=efi Release=9
The opencloudos-cloud-9.loongarch64 section: the URL names the build directory 20260922.0 of 9.6, as OpenCloudOS has no alias for the latest build, so moving on is an edit by hand; SHA256SUMS=@URL@.sha256 takes the checksum file next to the image; Boot=efi and Release=9 on all three architectures

The URL names build 20260922.0 of 9.6; SHA256SUMS=@URL@.sha256 takes the checksum file next to the image. Boot=efi, Release=9.

Its section in the OpenCloudOS INI file looks much like Ubuntu's, with two differences. OpenCloudOS publishes each build of its cloud images in a directory named after the build, with no alias for the latest one. So the URL pins one build, and moving to a newer one is an edit by hand. And instead of one checksum list for a whole release, each image has its own checksum file right next to it, so SHA256SUMS names the image's own URL with a suffix, through a placeholder. Boot is efi on all three architectures, and Release is 9.

Details and sources

Details

  • The file's comment: each build sits in a directory named after it, "with the build in the file name, and no alias for the latest one: pin a build, and move to a newer one by hand. Builds of 9.6 for the three architectures appear together, on the project's own mirror" (data/opencloudos.ini:4-7).
  • All three sections use build 20260922.0 of 9.6, SHA256SUMS=@URL@.sha256, Boot=efi and Release=9 (data/opencloudos.ini:13-32).
  • @URL@ expands to the resolved image URL and is allowed only in SHA256SUMS and SHA512SUMS (rulegen.py:51-58, data/README.md:62-67).
  • The images and their .sha256 files are fetched over https from the project's own mirror, like every image (data/opencloudos.ini:4-7, data/opencloudos.ini:13-32).

04 The loongarch64 machine

THE MACHINE qemu-system-loongarch64 -machine virt,accel=… -cpu max -smp 1 4 on a loongarch64 host -m 2048 -drive if=pflash,unit=0,…efi-code.qcow2,readonly=on -drive if=pflash,unit=1,…efi-vars.qcow2 its own firmware copies -drive …,id=drive0 -device virtio-blk,drive=drive0 -netdev user,… -device virtio-net-pci,netdev=netdev0 like aarch64: no BIOS, a loongarch64 system always boots through UEFI
opencloudos-cloud-9.loongarch64.run runs qemu-system-loongarch64 with -machine virt and -cpu max, -smp 1 (4 on a loongarch64 host) and -m 2048, two pflash drives for its own firmware copies, a virtio-blk disk and a virtio-net-pci card. like aarch64 it has no BIOS way in and always boots through UEFI

qemu-system-loongarch64 -cpu max -machine virt, -smp 1 (4 on a loongarch64 host), -m 2048, two pflash drives, virtio-blk and virtio-net-pci.

The machine itself is plain. QEMU's loongarch64 emulator runs the virt board with the CPU model called max, and one CPU, unless your host is a loongarch64 machine itself; then it's four. Memory is the usual two gigabytes. It boots through UEFI, so the system gets its own copies of the firmware code and variables, like every efi system. The disk is a virtio block device and the network a virtio network card. And like aarch64, it has no BIOS way in: a loongarch64 system always boots through UEFI.

Details and sources

Details

  • QEMU_SYSTEM_LOONGARCH64_MACHINE = virt, QEMU_CPU_LOONGARCH64 = max, QEMU_SMP_LOONGARCH64 = 1, the network -netdev user with virtio-net-pci, and the EFI command line with two pflash drives (mk/010-qemu-loongarch64.mk:3-23). Unlike x86_64 and aarch64, the network option has no -smbios type=41 entry.
  • The host's own architecture gets 4 CPUs and memory defaults to 2048 MiB (mk/010-qemu.mk:5-12); see four CPUs for your own architecture.

for contributors

In rulegen.py

  • ruleset_loongarch64_efi (rulegen.py:669-686) is printed for Boot=efi (rulegen.py:815-817); a loongarch64 section without it, or with another value, stops rulegen.py with has no Boot=, use efi for loongarch64 or which loongarch64 does not support, use efi (rulegen.py:300-333).

05 Its firmware

ITS FIRMWARE QEMU_EDK2_CODE_LOONGARCH64 ?= first that exists /usr/share/qemu-efi-loongarch64/QEMU_EFI.fd Debian, Ubuntu /usr/share/edk2/loongarch64/QEMU_EFI.fd Fedora 16 MiB, the size of the virt board's flash: no truncate, unlike riscv64's 32 MiB …/qemu-loongarch64/share/qemu/edk2-loongarch64-code.fd in the snap $GARDEN_LOONGARCH64_PREFIX/share/qemu/edk2-loongarch64-code.fd your own QEMU ENV GARDEN_LOONGARCH64_PREFIX=/usr/local the container
QEMU_EDK2_CODE_LOONGARCH64 lists /usr/share/qemu-efi-loongarch64/QEMU_EFI.fd from Debian and Ubuntu's qemu-efi-loongarch64 package and /usr/share/edk2/loongarch64/QEMU_EFI.fd from Fedora's edk2-loongarch64, then the snap component's edk2-loongarch64-code.fd and the one under GARDEN_LOONGARCH64_PREFIX, which the container sets to /usr/local. Both fill the virt board's 16 MiB flash, so nothing is truncated

/usr/share/qemu-efi-loongarch64/QEMU_EFI.fd (Debian, Ubuntu) or /usr/share/edk2/loongarch64/QEMU_EFI.fd (Fedora), then the snap component's or $GARDEN_LOONGARCH64_PREFIX's edk2-loongarch64-code.fd.

Like the other efi architectures, loongarch64 copies its firmware from the host, the first file of a list that exists. Debian and Ubuntu package LoongArch EDK2 under one name and Fedora under another, and the list has both packages' paths. Either fills the sixteen megabytes of flash that QEMU's virt board has, so unlike riscv64 there's nothing to stretch. In the snap, the loongarch64 component brings QEMU's own build. Outside it, GARDEN_LOONGARCH64_PREFIX points at the firmware of a QEMU you built, as the container does.

Details and sources

Details

  • "Debian and Ubuntu package the firmware as qemu-efi-loongarch64, Fedora as edk2-loongarch64. Both fill the 16 MiB flash of QEMU's virt machine, as do the copies QEMU itself installs." The list, the snap component's edk2-loongarch64-code.fd and -vars.fd, and GARDEN_LOONGARCH64_PREFIX (mk/010-qemu-loongarch64.mk:76-94); the copies and their qcow2 conversion (mk/010-qemu-loongarch64.mk:102-114).
  • riscv64 truncates its copies to 32 MiB (mk/010-qemu-riscv64.mk:102-110); loongarch64 has no such step.
  • The container sets GARDEN_LOONGARCH64_PREFIX=/usr/local (Dockerfile:102).

06 The network card's option ROM

ONE SMALL FILE virtio-net-pci card efi-virtio.rom its UEFI option ROM, loaded from QEMU's data the snap builds QEMU once; each component gets only what its machines load components/qemu-loongarch64/ bin/qemu-system-loongarch64 share/qemu/edk2-loongarch64-code.fd share/qemu/edk2-loongarch64-vars.fd share/qemu/efi-virtio.rom share/qemu/keymaps/ finds its data next to the binary it runs from a distribution's QEMU, or the container's: the ROM is in their usual share/qemu
QEMU's virtio-net-pci card has a UEFI option ROM, efi-virtio.rom, which QEMU loads from its data directory. The snap builds QEMU once and gives each component only the files its machines load; components/qemu-loongarch64 has bin/qemu-system-loongarch64 and share/qemu with the EDK2 code and variables and efi-virtio.rom, which QEMU finds next to its binary. A distribution's or the container's QEMU has the ROM in its usual share/qemu

The snap's qemu-loongarch64 component carries share/qemu/efi-virtio.rom, the option ROM of the virtio-net-pci card, next to edk2-loongarch64-code.fd and -vars.fd.

One small file matters here. QEMU's virtio network card comes with an option ROM, a little UEFI driver that QEMU loads from its data directory when it creates the card, and QEMU needs to find it. The snap builds QEMU once and gives each architecture's component only the files its machines load. The loongarch64 component now carries that ROM, efi-virtio, next to its firmware. QEMU in a component finds its data next to the binary it runs from, so the card comes up. A distribution's QEMU and the container's keep the ROM in their usual data directory.

Details and sources

Details

  • "The qemu-loongarch64 component carries efi-virtio.rom, which a virtio network card needs" (NEWS.snappy:43-44).
  • The snap's QEMU part gives each component its emulator, the keymaps and "the firmware and option ROMs that machines of that system load"; qemu-loongarch64 gets edk2-loongarch64-code.fd, edk2-loongarch64-vars.fd and efi-virtio.rom (snap/snapcraft.yaml:380-413).
  • The stub's comment: "QEMU is relocatable: it finds its firmware and other data next to the binary it runs from" (qemu-stubs/qemu-system-loongarch64:33-36).
  • The card is virtio-net-pci (mk/010-qemu-loongarch64.mk:7-9). That QEMU loads the card's ROM by default and fails to create the card without it, and that the container's make install of QEMU installs the ROMs, are QEMU's behaviour (derived).

07 Snap, container or packages

EVERY INSTALL the snap $ snap install image-garden+qemu-loongarch64 without it: It seems that the component with QEMU loongarch64 is not installed. the container QEMU_TARGET_LIST=…,loongarch64-softmmu ENV GARDEN_LOONGARCH64_PREFIX=/usr/local a distribution Ubuntu: qemu-system-misc qemu-efi-loongarch64 emulated on a PC, whichever road you take in CI: a generous timeout, or expect a boot more than a test run
The snap: snap install image-garden+qemu-loongarch64, and without it the stub's notice that the component with QEMU loongarch64 is not installed. The container: QEMU built with loongarch64-softmmu and GARDEN_LOONGARCH64_PREFIX=/usr/local. Ubuntu: qemu-system-misc and qemu-efi-loongarch64; whichever road, the guest is emulated on a PC, so in CI give it a generous timeout

Snap: snap install image-garden+qemu-loongarch64. Container: loongarch64-softmmu and GARDEN_LOONGARCH64_PREFIX. Ubuntu: qemu-system-misc and qemu-efi-loongarch64.

Whichever way you installed image-garden, there's a road to loongarch64. The snap has a loongarch64 QEMU component with the emulator, the firmware and the ROM. Without it, the snap's stand-in for QEMU shows a message with the snap install command. The container builds QEMU with loongarch64 among its targets and points image-garden at that build's firmware. On a distribution, install its loongarch64 QEMU and firmware: on Ubuntu, that's two packages. Whichever road you take, the guest is emulated on a PC, so in CI give it a generous timeout, or expect a boot more than a test run.

Details and sources

Details

  • The snap's stub for qemu-system-loongarch64 prints a notice box, "It seems that the component with QEMU loongarch64 is not installed", and the command snap install image-garden+qemu-loongarch64 (qemu-stubs/qemu-system-loongarch64:9-31). The component for the host's architecture is installed on refresh; others by hand (README.md:309-320).
  • The container's QEMU target list includes loongarch64-softmmu (Dockerfile:33), and its prefix variable points at that build's firmware (Dockerfile:102).
  • Distribution packages may be older than the upstream release (the maintainer's statement), so a packaged image-garden may not have opencloudos-cloud-9 yet.

for contributors

In image-garden's CI

  • image-garden's CI job loongarch64: [el] installs qemu-efi-loongarch64 qemu-system-misc on Ubuntu and tests opencloudos-cloud-9 with a 30 minute timeout (.gitlab-ci.yml:1004-1015); like every emulated job it only boots each image once (GARDEN_TEST_BOOT_ONLY) and has allow_failure: true, because the CI server is slow (.gitlab-ci.yml:663-690).

08 Where to go from here

ROADS loongarch64 Six architectures and why emulation is slow UEFI firmware the shared search lists The support matrix OpenCloudOS among the rest The container in CI its own QEMU The snap per-architecture components The .run script more CPUs for a slow guest
Roads from loongarch64: six architectures, UEFI firmware per system, the support matrix, the container in CI, the snap and the .run script

Next: six architectures, UEFI firmware per system, the support matrix, the container in CI, the snap and the .run script.

So loongarch64 is one machine, one firmware list, one ROM and, for now, one system. From here, the architectures deck sets it beside the other five machines and explains why emulation is slow. The firmware deck shows the search lists every efi architecture shares. The support matrix shows where OpenCloudOS sits among the other families. The container and the snap decks cover the two installs that bring their own QEMU, and the run script deck how to give an emulated guest more CPUs.

Details and sources

Read more

Basis of the statements on this page

Read in data/opencloudos.ini, mk/010-qemu-loongarch64.mk, rulegen.py, snap/snapcraft.yaml, qemu-stubs/qemu-system-loongarch64, the Dockerfile and .gitlab-ci.yml of image-garden at the tag in garden.commit ("code"). What QEMU does with an option ROM is derived from QEMU's behaviour. Nothing was run for this page.

The three systems

SystemArchitectureBootImage
opencloudos-cloud-9.x86_64x86_64efiOpenCloudOS-GenericCloud-9.6-20260922.0.x86_64.qcow2
opencloudos-cloud-9.aarch64aarch64efiOpenCloudOS-GenericCloud-9.6-20260922.0.aarch64.qcow2
opencloudos-cloud-9.loongarch64loongarch64efiOpenCloudOS-GenericCloud-9.6-20260922.0.loongarch64.qcow2

Each from https://mirrors.opencloudos.tech/opencloudos/9.6/images/qcow2/ARCH/20260922.0/, checked against the .sha256 file next to it.

The loongarch64 machine

OptionValueVariable
programqemu-system-loongarch64QEMU_SYSTEM_LOONGARCH64
-machinevirtQEMU_SYSTEM_LOONGARCH64_MACHINE
-cpumaxQEMU_CPU_LOONGARCH64
-smp1, or 4 on a loongarch64 hostQEMU_SMP_LOONGARCH64, QEMU_SMP_OPTION
-m2048QEMU_MEM_OPTION
firmwaretwo pflash drivesQEMU_BOOT_FIRMWARE_OPTION
network-netdev user, virtio-net-pciQEMU_NET_OPTION

Firmware search list

  • /usr/share/qemu-efi-loongarch64/QEMU_EFI.fd and QEMU_VARS.fd (Debian, Ubuntu: qemu-efi-loongarch64)
  • /usr/share/edk2/loongarch64/QEMU_EFI.fd and QEMU_VARS.fd (Fedora: edk2-loongarch64)
  • In the snap: qemu-loongarch64/share/qemu/edk2-loongarch64-code.fd and -vars.fd
  • With GARDEN_LOONGARCH64_PREFIX: PREFIX/share/qemu/edk2-loongarch64-code.fd and -vars.fd

What each install brings

InstallEmulatorFirmwareefi-virtio.rom
Snapimage-garden+qemu-loongarch64 componentin the componentin the component
Containerbuilt with loongarch64-softmmuQEMU's own, via the prefixQEMU's own
Ubuntuqemu-system-miscqemu-efi-loongarch64with QEMU (derived)

Roads from here

SYSTEMS · distributions

ARCHITECTURES · machines and firmware

RUNTIME · make rules and the CLI

SNAP · snap-only features

CONTAINER · OCI image