HeliOS

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.

Context: collaborative educational systems project. Thomas Chisica is a contributor, not the sole author of every component. This repository demonstrates kernel mechanisms and their runtime checks, not a production operating system.

Read in five minutes

Research-software perspective: this repository shows how interfaces between boot, scheduling, interrupts and memory can be made inspectable and exercised with runtime checks. It complements the ML projects with collaborative C systems work. Smoke tests are not formal verification or a production reliability claim.

1. Follow the boot-to-scheduler path in the architecture notes.
2. Inspect the QEMU smoke script and its expected shell output.
3. Use make smoke after installing the toolchain below; review the current limits before reusing the kernel.

What It Implements

• RISC-V 64 rv64gc kernel running on QEMU virt with 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.

Why It Matters

The code connects boot, traps, task state, scheduling, synchronization and memory management in a compact implementation. Its educational value is that these paths can be inspected together and exercised by repeatable runtime checks.

For Systems Readers

If you are reading this from an OSDev, RISC-V, embedded Linux, or xv6 background, start with the runtime path rather than the shell:

1. linker.ld fixes the kernel load address at 0x80200000.
2. boot/start.S sets the initial stack and implements the low-level context switch.
3. kernel/kmain.c initializes tasks, scheduling, traps, the timer, and the shell task.
4. kernel/trap.c handles supervisor timer interrupts and requests reschedule points.
5. kernel/sched.c and kernel/task.c implement the runnable task model, Round-Robin/SJF selection, and context-switch handoff.
6. kernel/kmem.c and kernel/sync.c keep the demo honest by adding dynamic stack allocation, free-list reuse, semaphores, and mutexes.

For a deeper map of the kernel, see Architecture Notes.

Quickstart

Install the required toolchain:

# macOS
brew install qemu riscv-gnu-toolchain

# Ubuntu/Debian
sudo apt-get install qemu-system-misc gcc-riscv64-unknown-elf

Build and run:

make clean && make -j
make run

Try 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.

Automated Demo

./scripts/demo.sh

The demo sends a short command sequence to the shell: about, help, ps, run cpu, run io, ps, sched rr, and meminfo.

Shell Commands

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

Repository Layout

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 Targets

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 tree

Verification

make smoke

The smoke test boots the kernel, drives the shell, and checks for expected output from about, help, ps, uptime, meminfo, and intstats.

Current Limits

• No MMU: memory is physical and direct.
• No filesystem: runtime state lives in memory.
• Single supervisor-mode environment: no strict user/kernel separation.

Documentation

• Architecture notes
• Technical documentation
• Web visualization

License

MIT. See LICENSE.