HeliOS is a small educational operating-system kernel for RISC-V 64. It boots on QEMU, opens an interactive UART shell, schedules tasks, handles timer interrupts, and implements basic synchronization and heap allocation.
The project is intentionally compact: the goal is to make core OS mechanisms visible without hiding them behind a large codebase.
- RISC-V 64
rv64gckernel running on QEMUvirtwith OpenSBI. - Interactive UART shell with process, scheduler, memory, and timer commands.
- Cooperative and preemptive Round-Robin scheduling.
- Shortest Job First scheduling with burst estimates.
- Task creation, context switching, and simple process inspection.
- SBI timer interrupts at 100 Hz.
- Semaphores, mutexes, and a producer-consumer demo.
- Free-list heap allocator with block coalescing.
- Automated QEMU smoke test for CI.
HeliOS is not a toy shell wrapped around QEMU output. It exercises the pieces that make an operating-system kernel interesting: boot code, traps, task state, scheduling policy, synchronization, memory management, and repeatable runtime checks. The code is small enough to inspect, but complete enough to demonstrate real systems behavior.
If you are reading this from an OSDev, RISC-V, embedded Linux, or xv6 background, start with the runtime path rather than the shell:
linker.ldfixes the kernel load address at0x80200000.boot/start.Ssets the initial stack and implements the low-level context switch.kernel/kmain.cinitializes tasks, scheduling, traps, the timer, and the shell task.kernel/trap.chandles supervisor timer interrupts and requests reschedule points.kernel/sched.candkernel/task.cimplement the runnable task model, Round-Robin/SJF selection, and context-switch handoff.kernel/kmem.candkernel/sync.ckeep the demo honest by adding dynamic stack allocation, free-list reuse, semaphores, and mutexes.
For a deeper map of the kernel, see Architecture Notes.
Install the required toolchain:
# macOS
brew install qemu riscv-gnu-toolchain
# Ubuntu/Debian
sudo apt-get install qemu-system-misc gcc-riscv64-unknown-elfBuild and run:
make clean && make -j
make runTry these commands at the HeliOS> prompt:
about
help
ps
run cpu
run io
ps
sched preempt on
uptime
meminfo
intstats
Exit QEMU with Ctrl+C.
./scripts/demo.shThe demo sends a short command sequence to the shell: about, help, ps,
run cpu, run io, ps, sched rr, and meminfo.
| Command | Purpose |
|---|---|
about |
Show kernel capabilities |
help |
List shell commands |
ps |
List active tasks |
run cpu |
Create a CPU-bound task |
run io |
Create an I/O-bound task |
kill <pid> |
Terminate a task |
sched rr |
Switch to Round-Robin scheduling |
sched sjf |
Switch to Shortest Job First scheduling |
| `sched preempt on | off` |
sleep <ticks> |
Sleep for a number of timer ticks |
pcdemo |
Run the producer-consumer synchronization demo |
bench |
Run a scheduler benchmark |
uptime |
Show runtime in ticks and seconds |
meminfo |
Show heap usage |
intstats |
Show timer and interrupt state |
boot/start.S Boot entry and context switch
kernel/ Kernel entrypoint, shell, scheduler, tasks, traps, heap
drivers/ UART and SBI timer drivers
lib/printf.c Minimal formatted output
include/helios.h Shared kernel declarations
scripts/ QEMU, demo, and smoke-test helpers
docs/ Technical notes and visualization
make # Build the kernel
make run # Run in QEMU
make run-gdb # Run QEMU with a GDB server
make gdb # Connect GDB
make smoke # Build and run the QEMU smoke test
make clean # Remove build artifacts
make dtb # Extract the QEMU device treemake smokeThe smoke test boots the kernel, drives the shell, and checks for expected
output from about, help, ps, uptime, meminfo, and intstats.
- No MMU: memory is physical and direct.
- No filesystem: runtime state lives in memory.
- Single supervisor-mode environment: no strict user/kernel separation.
MIT. See LICENSE.