The Problem

Embedded developers need a lightweight, safe‑to‑run RISC‑V operating system that can be compiled from source and used in a QEMU test harness. Existing hobby kernels are either C‑heavy or lack a clear Rust‑only build path. octox offers a fully Rust implementation with a simple build pipeline and an extensible userland.

What This Does

octox implements a Unix‑like kernel, file system, device drivers, and a minimal shell in pure Rust. Entry points live in src/kernel/main.rs (kernel bootstrap) and src/mkfs/main.rs (file‑system image builder). Userland binaries are built from src/user/bin/* and linked into the image by src/user/build.rs. System calls are declared in src/kernel/syscall.rs; a macro in build.rs generates the matching user API in src/user/lib.

How It Is Wired

Entry Point cargo run --target riscv64gc-unknown-none-elf invokes the kernel binary. The ELF loader first jumps into src/kernel/start.rs, which sets up the trap vector table and calls src/kernel/entry.rs to initialize memory, console, and the first process.

Kernel Control Flow src/kernel/entry.rs calls src/kernel/main.rs::main. main.rs creates the init process by invoking src/kernel/exec.rs::exec with the init binary from the root file system. Each new process runs the scheduler in src/kernel/proc.rs, which dispatches to src/kernel/syscall.rs when a trap occurs. The trap handling in src/kernel/trap.rs translates the RISC‑V exception into a syscall number, looks up the handler in the TABLE array of SysCalls, and executes the corresponding method (e.g., SysCalls::dup2).

Userland Interaction User programs call the generated API (e.g., ulib::fs::remove_file) which, via the syscall mechanism, ends up in the same trap path. The mkfs tool src/mkfs/main.rs writes binaries from src/user/bin into the root file system image, which the kernel mounts at boot.

External Effects

  • Console I/O → src/kernel/uart.rs and src/kernel/console.rs.
  • File I/O → src/kernel/file.rs, src/kernel/fs.rs, src/kernel/virtio_disk.rs.
  • Process management → src/kernel/proc.rs, src/kernel/sleep, src/kernel/semaphore.rs.

The largest blast radius is the trap handler in src/kernel/trap.rs; any change here affects all syscalls and device interrupts.

How To Use It

Setup

git clone https://github.com/moses-y/octox
cd octox
cargo build --target riscv64gc-unknown-none-elf

Run

cargo run --target riscv64gc-unknown-none-elf

QEMU will start; press Ctrl‑a x to exit.

Add a user command Create src/user/bin/_foo.rs, add a [bin] entry in src/user/Cargo.toml, then rebuild. The command binary is automatically added to the file system image by src/user/build.rs.

Real‑World Use

A teaching lab can use octox to demonstrate RISC‑V boot, process scheduling, and file system logging. For example, a student writes a custom cat program in src/user/bin/_cat.rs; the build system injects it into the image, and the student runs it in QEMU to see how the kernel handles file descriptors and console output.

Code Health & Issues

  • Medium/SDLC – No test files detected (tests/** missing).
  • Medium/SDLC – No CI/CD configuration (.github/ folder absent).
  • Low/Risk – No Cargo lockfile, so builds are non‑reproducible.

No other static issues were found.

The Bottom Line

octox delivers a fully Rust‑based RISC‑V operating system with a clear build path and minimal dependencies, suitable for educational or prototyping purposes. Its lack of tests and CI limits confidence for production use; however, the codebase is clean, well‑structured, and easy to extend for new syscalls or device drivers.