axiomOS Overview

Relevant source files

• README.md 
• docs/architecture/system-overview.md 
• docs/decisions/0003-supported-targets.md 
• docs/reference/generated/components.md 
• kernel/src/main.rs 
• kernel/src/lib.rs 
• Cargo.toml 

axiomos is a bare-metal, no_std Rust kernel whose behavior can be changed at runtime by loading verified eBPF programs onto kernel hooks (scheduler switch, syscalls, timers, GPIO, PWM, IIO). It targets robotics and embedded control, where reflashing firmware to change a control policy is slow and risky. This wiki documents the main branch.

Why it exists

Field-deployed robots need behavioral updates (new sensor fusion, modified control loops, updated safety policy). Linux has the eBPF mechanism but not hard real-time latency or a small footprint; an RTOS has the footprint but no safe runtime extension. axiomos combines a small monolithic Rust kernel with a load-time verifier so that untrusted, hot-swappable logic is a first-class kernel object with static safety and timing admission (README , threat model ).

The three defining design choices:

1. Bare metal, monolithic. No host OS or RTOS. Limine boots x86_64; AArch64 boots from firmware with a device tree.
2. Rust core, no_std, panic=abort. Assembly is limited to boot stubs and exception vectors; every unsafe site is inventoried in an unsafe ledger.
3. eBPF for runtime extension. Programs are authenticated (Ed25519), verified (CFG, bounds, tnum, pruning, liveness, static WCET), admitted against a utilization budget, then executed by an interpreter when a hook fires.

System at a glance

See System Overview for the full ownership model.

Supported targets

What works and what does not

The implemented surface (per the README and confirmed in code): boot on x86_64 and AArch64, paging and per-process address spaces, APIC and GIC interrupts, preemptive scheduling with per-CPU run queues, a syscall ABI (31 dispatched syscalls), kernel heap, VFS with ext2 root and devfs, pipes, fork/exec/waitpid, the BPF verifier gating the load path, WCET admission, Ed25519 BPF signing, RP1 GPIO/UART/PWM on Pi 5, and VirtIO on x86_64/virt.

Honest limitations

Discrepancies between README limitations and current code:

• Signed BPF loading. The README says unsigned loads are accepted by default. In code, a build without the bpf-unsigned-development feature embeds a production Ed25519 key and sets allow_unsigned = false (kernel/src/bpf/trust.rs ); unsigned loading is an explicit development feature.
• Run queues. The README mentions a single global run queue; the code uses per-CPU queues with bounded stealing (kernel/crates/kernel_run_queue ).
• sys_nanosleep. The README says it busy-spins; the code parks the task with a deadline and reschedules (kernel/src/syscall/mod.rs ).
• User page faults. The README says they panic the kernel; the x86_64 handler calls terminate_current_task_on_user_exception first and only panics for kernel-mode faults.
• Missing /bin/init. Boot does not panic; it prints BOOT_FATAL code=init-executable-missing and halts (kernel/src/main.rs ).

Repository map

Where to go next