QSOE Systems

QSOE can be built from source or installed from pre-built binaries. Ready-made images for each release are published at github.com/qsoe-dev/dl (current release: 0.1). The files are:

• skimmer.bin — the Skimmer microkernel: the kernel of the QSOE/N variant. A raw binary image, loaded by the bootloader (or QEMU) together with the userspace package below.
• modpkg.cpio — the module package: the shared QSOE userspace (taskman, init, the C library, the shell, drivers and utilities) as a CPIO archive. QSOE/N boots it as an initrd alongside skimmer.bin.
• qsoe-l-qemu.elf — the QSOE/L variant (on the seL4 kernel) as a single, self-contained ELF for the QEMU virt machine. It bundles the elfloader, the seL4 kernel, taskman and the userspace together — nothing else is needed to boot.
• qsoe-l-sifive.elf — the same QSOE/L image, built for the SiFive HiFive Unmatched (FU740) board.
• mrbml-riscv64.efi — mr-bml, QSOE's own bootloader (an EFI application for RISC-V). It can load either variant and drives the boot menu on real hardware.
• nvme.img.gz — a ready-to-run, self-booting QEMU disk image (GPT). Its EFI partition holds mr-bml, and an on-disk root holds both kernels — so QEMU boots straight to the mr-bml menu, no -kernel needed. The fastest way to see QSOE run; see Running under QEMU below.
• virtio.img.gz — a companion root disk used only when running QSOE/L under QEMU (stock seL4 predates the interrupt controller QEMU's NVMe needs, so it mounts its root from a virtio disk instead). Not needed for QSOE/N or for real hardware.

In short: to run it in QEMU, grab nvme.img.gz (plus virtio.img.gz for QSOE/L) and see Running under QEMU. To put it on real hardware, you need mrbml-riscv64.efi plus the kernels — QSOE/N uses skimmer.bin + modpkg.cpio, QSOE/L uses one of the qsoe-l-*.elf images — and see Installation.

The quickest way to see QSOE run — no hardware, no -kernel juggling. The nvme.img download is a self-booting UEFI disk: QEMU's firmware runs mr-bml from it, and mr-bml's menu starts either variant straight off the disk.

You need

• qemu-system-riscv64 — version 11.0.1 or newer for QSOE/N (its NVMe needs the AIA interrupt controller).
• edk2 RISC-V UEFI firmware — on Debian/Ubuntu, the qemu-efi-riscv64 package.
• The launcher run-nvme.sh from the os repository — it wraps the right QEMU machine, firmware and disks for each variant, so you don't have to.

Run it

# unpack the image(s) — add virtio.img.gz only if you want QSOE/L
gunzip nvme.img.gz virtio.img.gz

# point the launcher at them and pick a variant from its menu
NVME_IMG=./nvme.img VIRTIO_IMG=./virtio.img ./run-nvme.sh

Pass n or l to skip the menu (./run-nvme.sh n). The script selects the matching QEMU machine automatically — QSOE/N on the AIA machine with an NVMe root, QSOE/L on the PLIC machine with the virtio root disk. The mr-bml menu and the system console both appear on your terminal; choose a variant and it boots to a login: prompt. Log in as root with password QSOE.

Real hardware, real disk. QSOE 0.1 boots on the SiFive HiFive Unmatched (FU740); the SpaceMiT K3 is a future target. This assumes a board already running Linux — you'll be placing files on its existing EFI and boot partitions, so familiarity with the board's firmware is expected.

The boot model is simple: mr-bml lives in the EFI System Partition; it reads its menu and the kernels from an ext2/3/4 partition; the chosen variant then mounts its own root from a fs-qrv partition.

Steps

1. Copy mrbml-riscv64.efi into your ESP as EFI/BOOT/BOOTRISCV64.EFI (the UEFI removable-media path), or register it with efibootmgr as a boot entry.
2. On your boot/root filesystem, create /boot/qsoe/ and copy the kernels there: skimmer.bin + modpkg.cpio for QSOE/N, qsoe-l-sifive.elf for QSOE/L.
3. Create /boot/mr-bml/mr-bml.cfg with one entry per variant — for example:

# /boot/mr-bml/mr-bml.cfg  — adjust the mainfs= partition to your disk
menuentry 'QSOE/N (Skimmer)' {
    kernel /boot/qsoe/skimmer.bin mainfs=/dev/nvme0n1p8
    modpkg /boot/qsoe/modpkg.cpio
}
menuentry 'QSOE/L (seL4)' {
    kernel /boot/qsoe/qsoe-l-sifive.elf mainfs=/dev/nvme0n1p8
}

The mainfs= device names the partition holding the QSOE root filesystem (fs-qrv) — set it to whichever partition you've devoted to QSOE on your board. On real hardware there is no QEMU virtio split: both variants drive the NVMe disk directly.

QSOE is built with a riscv64-linux-gnu- cross toolchain (rv64gc) and a stock make; QEMU is handy for testing. The umbrella repository orchestrates the build and pulls in the component repositories that match its release tag.

git clone https://gitlab.com/qsoe/os
cd os
make prepare   # fetch the components for this tag (see component.list)
make           # build both variants: QSOE/N, then QSOE/L
make dist      # optional: the QEMU disk images (nvme.img.gz, virtio.img.gz)

QSOE/L additionally shallow-clones the seL4 kernel during make prepare. The build produces exactly the files on the Downloads list. The whole tree is Apache-2.0; the source lives under gitlab.com/qsoe.

The QSOE manuals, published as PDF alongside the releases:

• Design.pdf — the architecture: the two-kernel model, taskman, the IPC and resource-manager design.
• UserGuide.pdf — installation, the shell, the basic commands, the text editor and the utilities.
• ProgrammingBook.pdf — programming for QSOE, including the Resource Server Framework chapter.
• AppPortingGuide.pdf — porting Unix (and QNX) software to QSOE: what to account for — no fork(), no brk(), select() via poll(), and the rest.

It is often said that the Linux kernel has no roadmap. QSOE does — the ten releases that carry it from today's 0.1 to the unified 1.0 are mapped out. A working plan, not a contract: milestones may shift as the work reveals what's really next.

• 0.1 — First public release. Two-kernel foundation, shared userspace, read-only fs-qrv at /usr, interactive getty + login, sources opened. (current)
• 0.2 — Text-mode console on the GK208 ("Kepler"): a watchable on-device display, so the real-time audio work can be seen on hardware, not just over serial.
• 0.3 — First writable filesystem: qrvfs gains file create/unlink, O_CREAT/O_TRUNC, realpath and symlink resolution.
• 0.4 — The canonical dual-panel file manager: QSOE's flagship application, exercising the writable filesystem and the userspace end to end.
• 0.5 — First deva-hdmi audio device, with the priority / interrupt / scheduling groundwork the hard-real-time path needs.
• 0.6 — Comprehensive conformance suites, and the audio real-time package (up to N hard-real-time tasks on an N-CPU system).
• 0.7 — to be defined nearer the time.
• 0.8 — Second hardware target (SpaceMiT K3, RVA23-class) and the AIA interrupt architecture (IMSIC/APLIC), so MSI/MSI-X works uniformly across boards.
• 0.9 — QNX-libc compatibility push: recompile and run a target set of QNX-source utilities, closing the remaining libc gaps.
• 1.0 — First stable release: API comparable to QNX 6.x; intended for porting QNX userland software (fork → posix_spawn).