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
- Six architectures, six QEMU machines — the QEMU machine, CPU and acceleration of each architecture
01 A sixth architecture, and its first system
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
Loongarch64is 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).
Read more
02 A pinned build general version
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.0of 9.6 and its.sha256file over https from the project's own mirror, and boot with UEFI (data/opencloudos.ini:13-32).
for contributors
In the data
- All three sections use
SHA256SUMS=@URL@.sha256,Boot=efiandRelease=9(data/opencloudos.ini:13-32);@URL@expands to the resolved image URL and is allowed only inSHA256SUMSandSHA512SUMS(rulegen.py:51-58, data/README.md:62-67).
Read more
03 A pinned build, in its section for contributors in place of the general version
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.0of 9.6,SHA256SUMS=@URL@.sha256,Boot=efiandRelease=9(data/opencloudos.ini:13-32). @URL@expands to the resolved image URL and is allowed only inSHA256SUMSandSHA512SUMS(rulegen.py:51-58, data/README.md:62-67).- The images and their
.sha256files are fetched over https from the project's own mirror, like every image (data/opencloudos.ini:4-7, data/opencloudos.ini:13-32).
Read more
04 The loongarch64 machine
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 userwithvirtio-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=41entry.- 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 forBoot=efi(rulegen.py:815-817); a loongarch64 section without it, or with another value, stops rulegen.py withhas no Boot=, use efi for loongarch64orwhich loongarch64 does not support, use efi(rulegen.py:300-333).
Read more
05 Its firmware
/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.fdand-vars.fd, andGARDEN_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).
Read more
06 The network card's option ROM
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.fdandefi-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'smake installof QEMU installs the ROMs, are QEMU's behaviour (derived).
Read more
07 Snap, container or packages
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-loongarch64prints a notice box, "It seems that the component with QEMU loongarch64 is not installed", and the commandsnap 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]installsqemu-efi-loongarch64 qemu-system-miscon 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 hasallow_failure: true, because the CI server is slow (.gitlab-ci.yml:663-690).
Read more
08 Where to go from here
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
| System | Architecture | Boot | Image |
|---|---|---|---|
opencloudos-cloud-9.x86_64 | x86_64 | efi | OpenCloudOS-GenericCloud-9.6-20260922.0.x86_64.qcow2 |
opencloudos-cloud-9.aarch64 | aarch64 | efi | OpenCloudOS-GenericCloud-9.6-20260922.0.aarch64.qcow2 |
opencloudos-cloud-9.loongarch64 | loongarch64 | efi | OpenCloudOS-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
| Option | Value | Variable |
|---|---|---|
| program | qemu-system-loongarch64 | QEMU_SYSTEM_LOONGARCH64 |
-machine | virt | QEMU_SYSTEM_LOONGARCH64_MACHINE |
-cpu | max | QEMU_CPU_LOONGARCH64 |
-smp | 1, or 4 on a loongarch64 host | QEMU_SMP_LOONGARCH64, QEMU_SMP_OPTION |
-m | 2048 | QEMU_MEM_OPTION |
| firmware | two pflash drives | QEMU_BOOT_FIRMWARE_OPTION |
| network | -netdev user, virtio-net-pci | QEMU_NET_OPTION |
Firmware search list
/usr/share/qemu-efi-loongarch64/QEMU_EFI.fdandQEMU_VARS.fd(Debian, Ubuntu:qemu-efi-loongarch64)/usr/share/edk2/loongarch64/QEMU_EFI.fdandQEMU_VARS.fd(Fedora:edk2-loongarch64)- In the snap:
qemu-loongarch64/share/qemu/edk2-loongarch64-code.fdand-vars.fd - With
GARDEN_LOONGARCH64_PREFIX:PREFIX/share/qemu/edk2-loongarch64-code.fdand-vars.fd
What each install brings
| Install | Emulator | Firmware | efi-virtio.rom |
|---|---|---|---|
| Snap | image-garden+qemu-loongarch64 component | in the component | in the component |
| Container | built with loongarch64-softmmu | QEMU's own, via the prefix | QEMU's own |
| Ubuntu | qemu-system-misc | qemu-efi-loongarch64 | with QEMU (derived) |
Roads from here
SYSTEMS · distributions
- The support matrix — OpenCloudOS among the other distribution families
ARCHITECTURES · machines and firmware
- Six architectures, six QEMU machines — the other five machines, and why emulation is slow
- UEFI firmware per system — the firmware search lists every efi architecture shares
RUNTIME · make rules and the CLI
- The .run script — more CPUs or memory for an emulated guest
SNAP · snap-only features
- The image-garden snap — the snap and its per-architecture QEMU components
CONTAINER · OCI image
- Running the container in CI — the container, whose own QEMU has loongarch64