Skip to content
DivByDiamondPublic

About

OnyxOS - RISC-V operating system (kernel + shell + bootloader + compiler), ultra ~272KB

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

OnyxOS

Build & Test Release

RISC-V Rust C++20 Shell Compiler GPL-3.0

OnyxOS booting in QEMU

OnyxOS is an operating system for RISC-V, written from scratch. It started as a system for the OC2R Minecraft mod (OpenComputers 2, which emulates RISC-V with Sedna), and it also boots in QEMU. A Milk-V Duo S port is a goal, not yet verified.

Everything in the stack is our own: a monolithic kernel in Rust, a bootloader in C++, a Rust shell, and a self-hosting C compiler that builds the userland.

$ bash scripts/bootstrap.sh && bash scripts/build-all.sh && bash scripts/run-qemu.sh

Log in as root and you get a shell, a TCP/IP stack, FAT32 and OnyxFS v2, plus Lua, vim and a few more apps built with our own compiler.

Status

Area State
Boot in QEMU virt (OpenSBI, OnyxBoot, kernel, init, login) Works
Boot inside OC2R (Sedna) Works, verified in-game
TCP/IP, UDP, DHCP, DNS Works; HTTP only, no TLS
FAT32, OnyxFS v2 (journal, snapshots) Works
Self-hosting compiler Works (make selfhost-test)
SMP Experimental, multi-hart boots are not stable yet
Unprivileged user sessions Unfinished: login does not install uid/gid yet
Real single-board hardware (Milk-V Duo S) Not verified
GUI (window manager, compositor), Java runtime Planned

This repository is the meta-project: it vendors the other Onyx repositories as sibling checkouts, builds all of them, and assembles the boot disk image and QEMU launch scripts.


Components

Component Language Description
OnyxBoot C++20 Bootloader: FDT, VirtIO, SDHCI, FAT32/ext4, GPT, boot menu
OnyxKernel Rust Monolithic kernel: SMP, Sv39 MM, VFS, TCP/IP, OnyxFS v2, FAT32, wide syscall ABI
OnyxShell Rust /bin/osh: built-in commands, tab completion, history, pipes/redirects, globbing, job control
OnyxCompiller C99 Self-hosting C compiler: C99 -> RV64 -> .onx, libonyxc
OnyxApps C99 Optional userland applications, built with OnyxCompiller
OnyxOS (this repo) - Build orchestration, docs, disk image assembly

Quick Start

$ # 1. Install build dependencies
$ sudo pacman -S cmake base-devel curl libarchive             # Arch
$ sudo apt install cmake build-essential libcurl4-openssl-dev libarchive-dev  # Debian/Ubuntu

$ # 2. Clone every Onyx repository as a sibling checkout
$ bash scripts/bootstrap.sh

$ # 3. Build every component and assemble the boot disk image
$ bash scripts/build-all.sh

$ # 4. Boot it in QEMU
$ bash scripts/run-qemu.sh

scripts/bootstrap.sh reads repository URLs from Onyx.vent and checks out exact commits from Onyx.lock.json into .vent/repos/. It uses Python 3 and Git directly; Vent is not required. Existing dirty or symlinked repositories are never checked out automatically. scripts/build-all.sh verifies the lock before building and writes artifacts to .build/.

For local sibling checkouts or symlinks, explicitly opt into development inputs:

$ ONYX_DEPS_MODE=workspace bash scripts/build-all.sh
$ ONYX_DEPS_MODE=workspace bash scripts/build-oc2r.sh

This mode reports revisions and dirty status; it does not claim a locked build. See dependency locking for release updates.


Repository Layout

OnyxOS/
├── Onyx.vent               # Component source URLs
├── Onyx.lock.json          # Exact component Git revisions
├── .vent/
│   └── repos/               # Sibling checkouts (after bootstrap.sh)
├── scripts/
│   ├── bootstrap.sh         # Clone exact locked component revisions
│   ├── build-all.sh         # Build every component + assemble the disk image
│   ├── run-qemu.sh          # Boot in QEMU (dev mode or full boot chain)
│   ├── mk-onyxfs-disk.sh    # Build the FAT32 + OnyxFS partitioned disk image
│   ├── qemu-smoke.sh        # Headless boot smoke test
│   └── qemu-interactive-smoke.sh  # Interactive boot smoke test
├── docs/
│   ├── architecture/        # Boot chain, memory layout, privilege rings
│   ├── dev/                 # Building, contributing, roadmap
│   ├── hardware/            # UART, PLIC, CLINT, VirtIO
│   ├── internals/            # Coding style, error handling conventions
│   ├── kernel/               # Process model, memory management, interrupts
│   ├── shell/                 # Shell commands and internals
│   └── lore/                  # Project history and notes
├── Makefile
└── README.md

Running QEMU

scripts/run-qemu.sh supports two modes:

$ bash scripts/run-qemu.sh boot    # default: full chain via OnyxBoot + a disk image
$ bash scripts/run-qemu.sh dev     # fast dev loop: QEMU loads the kernel ELF directly, no disk image

Useful environment variables:

Variable Effect
QEMU_MEM RAM size (default 256M)
QEMU_EXTRA Extra QEMU flags, e.g. -s -S for GDB

SMP is controlled by passing -smp N via QEMU_EXTRA, or by invoking QEMU directly (see the OnyxKernel README for the full manual command line and its multi-hart caveat - the kernel supports up to 8 harts, but multi-hart boots are still experimental).


Building Components Individually

OnyxKernel

$ cd .vent/repos/OnyxKernel
$ cargo kbuild    # alias for: cargo build --release -p onyx_kernel --target riscv64gc-unknown-none-elf

OnyxBoot

$ cd .vent/repos/OnyxBoot
$ make -j$(nproc)

OnyxShell

$ cd .vent/repos/OnyxShell
$ bash build.sh

OnyxCompiller

$ cd .vent/repos/OnyxCompiller
$ make            # native Linux binary
$ make onyxcc-onx # cross-compiled .onx for OnyxOS

Building a Firmware Image for OC2R

OC2R is a Minecraft (NeoForge) mod that adds virtual computers with 64-bit RISC-V emulation. OnyxOS can boot directly inside the game.

OC2R downloads a computer's firmware from a GitHub repository using an oc2r-firmware.json manifest at the repository root. The mod reads it, follows the image link, and flashes that image into the virtual machine.

Manifest format (oc2r-firmware.json)

{
  "name": "OnyxOS",
  "version": "0.3.0",
  "layout": "minux",
  "image": "https://github.com/DivByDiamond/OnyxOS/releases/latest/download/onyx-flash.img"
}
Field Value Description
name OnyxOS Firmware name
version e.g. 0.3.0 Matches the OnyxKernel workspace Cargo.toml version
layout minux Flash layout scheme (below)
image direct link to onyx-flash.img The flat flash image attached to a GitHub Release

minux layout (flash is exactly 15 MB):

Offset Size Contents
0x000000 - fw_jump.bin (OpenSBI, from the OC2R mod's src/main/scripts/firmware_files/)
0x200000 (2 MB) - OnyxKernel image (ELF, built by cargo)
up to 15 MB - zero-filled

Building the image manually

$ # 1. Resolve locked dependencies into .vent/repos/
$ make deps

$ # 2. Build the bootloader and kernel
$ make -C .vent/repos/OnyxBoot
$ cargo build --release -p onyx_kernel --target riscv64gc-unknown-none-elf \
    --manifest-path .vent/repos/OnyxKernel/Cargo.toml

$ # 3. Place a real OpenSBI build at firmware/fw_jump.bin
$ #    (from the OC2R mod: src/main/scripts/firmware_files/fw_jump.bin)

$ # 4. Assemble a 15 MB image using the minux layout
$ dd if=/dev/zero of=onyx-flash.img bs=1M count=15
$ dd if=firmware/fw_jump.bin of=onyx-flash.img conv=notrunc
$ dd if=.vent/repos/OnyxKernel/target/riscv64gc-unknown-none-elf/release/onyx-kernel \
    of=onyx-flash.img bs=1M seek=2 conv=notrunc

Automated builds via GitHub Actions

.github/workflows/release.yml runs on every pushed git tag (e.g. v0.3.0):

  1. Builds every component (make deps resolves exact component commits from Onyx.lock.json).
  2. Assembles onyx-flash.img (15 MB, minux layout).
  3. Creates a GitHub Release and attaches the image.

The manifest's image field points at /releases/latest/download/onyx-flash.img, which GitHub resolves to the newest release's asset automatically.

To produce a working release you need to either:

  1. Commit a real fw_jump.bin (OpenSBI) at firmware/fw_jump.bin, or set the repository variable OC2R_FW_JUMP_URL (without either, CI builds an image with a placeholder that will not boot); and
  2. Push a tag such as v0.3.0 - CI builds and uploads the image.

Every push to main also publishes a preview image as a workflow artifact, without creating a Release.


Userspace Applications

Optional userspace programs live in the OnyxApps monorepo (a text editor, a system monitor, an HTTP client, and more). Each application has its own README.md under apps/<name>/. Build with make in the OnyxApps repository root; CI also publishes build/*.onx artifacts.

All applications run on top of the kernel's ANSI/VT100 framebuffer terminal (fb_term/ansi.rs): SGR colors, cursor positioning, erase sequences, scroll regions, per-process termios via TCGETS/TCSETS, and TIOCGWINSZ reporting the real framebuffer grid.


Roadmap

Planned work and open issues are tracked in docs/dev/roadmap.md (project-wide milestones) and OnyxKernel's todo.md (kernel-level tracking, including in-progress investigations).


License

GPL-3.0-or-later. See LICENSE.

About

OnyxOS - RISC-V operating system (kernel + shell + bootloader + compiler), ultra ~272KB

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages