rrkernel
A preemptive round-robin RTOS kernel in Rust. One API, from a Cortex-M0 to your desktop — timing you state in cycles, size measured in kilobytes.
The short version. Every task gets the same slice, chosen once at startup, and hardware guarantees it is honoured — even when a task never yields. You write
thread::spawn(|| …)with closures, exactly like desktop Rust.
use ;
use rrkernel;
No priorities. No unsafe in application code. No allocator. Two files: your main.rs and a
memory.x your chip crate usually ships anyway.
Why another RTOS?
The problem. On a microcontroller, "it usually keeps up" is not a specification. Control loops, sampling and protocol timing need a bounded worst case: a guaranteed slice, a guaranteed switch cost, and a guarantee that no single task can hold the CPU hostage.
The gap in the obvious choices.
| Option | What it gives you | Where precise timing suffers |
|---|---|---|
Superloop + delay() |
nothing to learn | one blocking call delays everything; each job's timing depends on the slowest other job |
| FreeRTOS / Zephyr (C) | everything, configurable | priorities and priority inheritance turn the worst case into an analysis problem rather than a fact, and the scheduler is a black box from Rust |
| RTIC | compile-time, zero-cost, superb for interrupt logic | it is an interrupt/resource framework, not a time-sliced scheduler: CPU-bound tasks are not preempted against each other |
| Embassy | beautiful async I/O on one stack | cooperative: a future that does not yield stalls everything, and there is no preemption between independent workloads |
std::thread (desktop) |
familiar, preemptive | needs an OS, an allocator and megabytes; the slices you get are the OS's guess |
How rrkernel answers it.
- A slice you can state in cycles.
Slice::Millis(1)on an 8 MHz part is exactly 8000SysTickcycles — measured, not approximated, and validated at init rather than silently clamped. - Preemption is the guarantee, not a feature. A task that never yields is throttled by hardware:
every other task's worst case is
(N-1)slices whether the offender cooperates or not. - The switch is engineered and measured. 38 cycles typical, 80 worst on an STM32F103 at 8 MHz, because the timer counter restarts on every switch and error cannot accumulate.
- Rust all the way down, without giving up the desktop. The same ring, counters and API run on Windows and Linux, so timing-sensitive logic is developed and tested on a laptop and flashed unchanged.
- Nothing in your way. Task bodies are ordinary closures;
unsafestays in the kernel, the ports and the macro.
What "precise" means here
Measured on an STM32F103C8 at 8 MHz with 1 ms slices (cargo run --release --bin fidelity in
examples/cortex-m-bluepill — reproducible on your board).
| Metric | Measured | How |
|---|---|---|
| Slice length | 1 000 000 ns exactly (8000 cycles) | SysTick->LOAD, chosen so the request is whole cycles |
| Slice accuracy | 2 674 ns worst error under full load | DWT->CYCCNT sampled in the tick handler |
| Switch cost | 38 cycles typical / 80 worst | DWT around the Rust half of PendSV |
| Sleep precision | 601 sleeps: 0 early, 0 late | every sleep checked against its own request |
| Idle behaviour | 1 wfi per tick, core parked between ticks |
idle_waits counter + a verified sleep window |
| Fairness | equal slices per task, no starvation | pure round robin by construction |
How it works
flowchart LR
SYSTICK["SysTick<br/>8000 cycles = 1 ms"] -->|expires| PENDSV["PendSV<br/>the switch"]
PENDSV -->|"save R4-R11, restart the counter"| RING
subgraph RING["the ring — pure round robin, one priority level"]
direction LR
A(["Task A<br/>Running"]) --> B(["Task B<br/>Ready"]) --> C(["Task C<br/>Ready"]) --> A
end
PENDSV -.->|"wake at deadline"| W(["tick sweep<br/>wake_expired"])
The slice is the whole contract
The only scheduling knob is the slice, fixed before the first task runs:
configure;
- The request becomes whole timer cycles and is reported back —
scheduler::slice_ns()prints what you actually got. A slice the hardware cannot honour is rejected at init, never clamped. - Every switch restarts the counter, so the successor always gets a complete slice: an early exit, a spawn or a block cannot shorten anyone else's turn.
- Sleeping is an absolute deadline on the global tick, not a per-task countdown, so a late wake-up is corrected on the next period instead of accumulating.
What happens on a switch
| Step | Where | Cost |
|---|---|---|
SysTick expires |
hardware | — |
on_tick(): count the tick, wake expired deadlines |
Rust, in the ISR | a few dozen cycles |
PendSV is pended (lowest priority, so it never preempts another ISR) |
SysTick_Handler |
1 store |
| Save R4–R11, publish SP, walk the ring, restore the successor | asm + schedule_next |
38–80 cycles |
Restart the slice counter (SysTick->VAL = 0) |
asm | 1 store |
Guarantees
| Guarantee | Bound | Why it holds |
|---|---|---|
| A runnable task runs within | (N-1) × (slice + switch) |
one lap of a pure round-robin ring |
| A task blocked on a lock or I/O runs within | its deadline, plus that same bound after the wake | keyed blocking; waking is O(1) |
| Worst-case switch time | (N-1) ring steps + the measured switch |
sleepers stay in the ring, so the walk grows with N |
| No task can starve a peer by not yielding | hardware-enforced | the tick is a hardware interrupt |
| Switching is allocation-free and O(1) | always | O(1) unlink, bump arena, deferred free |
The
(N-1)bound covers tasks that are runnable. A task waiting on a lock is bounded by the holder's progress instead: the static lock-order rule keeps that chain finite, but it is not(N-1)slices, and the documentation says so rather than pretending otherwise.
Sleeping, blocking, yielding — one mechanism
Everything funnels through a single blocking primitive: the deadline is read, the state becomes
Blocked, and the switch is pended inside one critical section, so a tick can never observe a
half-formed waiter.
| You write | What happens | Cost while waiting |
|---|---|---|
rrkernel::sleep(d) |
parks until an absolute tick | 0 CPU |
signal.wait(deadline) |
parks until an ISR sets it |
0 CPU, woken in O(1) |
scheduler::yield_now() |
gives up the slice, stays Ready |
1 switch |
fut.await under exec::block_on |
parks on Pending, re-polled on wake |
0 CPU |
embedded_io::Read on a Pipe |
parks the reader, the ISR wakes it | 0 CPU — measured: 0 slices |
wait_until(ready, deadline) |
yields once per poll (no interrupt to wait on) | 1 switch per poll, never starves |
An nb::WouldBlock, a Pending future, a Signal that has not fired, and a task with nothing to do
are all "give the slice back now": the round robin continues instead of spinning.
How it shapes your application
| Instead of | You write |
|---|---|
| priorities to stop one job hogging the CPU | nothing — the slice does it |
while flag {} polling or a hand-tuned delay |
signal.wait(timeout) / fut.await |
a state machine split across switch cases just so it can yield |
an ordinary function, or an async fn that awaits |
static mut with unsafe accessors |
closures that capture their own state (Send + 'static) |
| a hand-written "idle task" | none — the kernel parks the core when nothing is runnable |
| two copies of a driver for blocking and async callers | one async driver + hal::Blocking |
Key features
- Preemptive round robin, one priority level. No priorities, no priority inheritance, no work stealing, no preempt-on-wake: a woken task waits its turn.
- Cycle-exact slices chosen at init, validated against the hardware, restarted on every switch.
#[rrkernel]installs the entry point, the configuration, the vector wiring, the panic and fault handlers, an optional RTT log sink and task 0 — yourmainstays short.- Familiar API.
thread::spawntakesFnOnce() + Send + 'static, exactly likestd::thread;sleep(Duration),now(),deadline_after,spawn_async. - Events and waiting:
Signal(ISR-safe and race-free),WaitQueue(single-wakeup hand-off),park/wake/TaskId,yield_now, and a poll-yield fallback with a mandatory deadline. - Async without an executor dependency:
exec::block_on, a taskWaker,Sleep,spawn_async—core::futureonly, no allocator, futures live on their task's own stack. - The standard embedded traits, always available (no feature flags to discover):
embedded-hal+embedded-hal-asyncfor delays, a blocking facade over an async driver and a kernel-mutex shared-bus device;embedded-io+embedded-io-asyncfor the ISR-drivenPipe. core-only kernel. Noalloc, no libc; TCBs, closure blobs and stacks come from a bump arena with deferred reclamation.- Six ports, one API: Cortex-M0/M0+/M3/M4/M33, RISC-V 32, ARM A/R, Xtensa, plus Windows and Linux backends so you can develop and test on a laptop.
- Measured, not claimed. Every number in this README comes from a counter in the kernel
(
scheduler::stats()), reproducible on real hardware.
Where it has actually been run
| Target | Real hardware | QEMU | Host tests | Builds |
|---|---|---|---|---|
| Cortex-M3 — STM32F103C8 ("Blue Pill") | ✅ VERDICT : PASS — 601 sleeps, 0 early, 1 wfi/tick, switch 38/80 cycles |
runs, no faults | — | ✅ |
| Cortex-M4 — STM32F401 ("Black Pill") | LED + threads run; RTT blocked by a probe-rs flashing quirk | — | — | ✅ |
Cortex-M0 / M0+ (thumbv6m) |
not yet on a board | — | — | ✅ |
Cortex-M33 (thumbv8m.main) |
no | — | — | ✅ |
RISC-V 32 (riscv32imac) |
no | ✅ VERDICT : PASS, exits 0 |
— | ✅ |
ARM A/R (armv7a, armv7r) |
no | ✅ VERDICT : PASS (guest never exits) |
— | ✅ |
| Xtensa LX6 (ESP32) | no | boots, switch runs, resume wrong → no verdict (docs/ESP32.md) |
— | nightly only |
Windows (win32) |
n/a | — | ✅ 23 tests | ✅ |
Linux (posix) |
n/a | — | ✅ 23 tests (WSL) | ✅ |
| macOS | no | — | — | compile_error! — work list in docs/PORTING.md |
Testing & CI
&&
CI runs four jobs: posix-core (fmt, clippy, tests, examples), windows, bare-metal (build dev
and release for six targets + clippy), and qemu (verdicts for RISC-V 32 and ARM A/R). The dev
build matters: lto = "fat" defers codegen, and a release-only build once hid a real compile error.
Honest limits
- Host tick source in some task sets. On Windows and Linux,
tick_count()has been observed to stay0from init in theio_layersscenario, which stalls deadline-based paths (timeouts, async timers). The blocking-I/O paths are unaffected, and the metal port ticks normally (3254 ticks measured).examples/io_layers.rsexits 3 with that diagnosis instead of hanging. - Asymmetric parking on the host backends. On every bare-metal port a blocking call has taken the
caller off the CPU before it returns. On Win32 the tick thread parks the task a moment later; on
POSIX the
SIGALRMhandler has no idle context to switch to when nothing is runnable. Each port reports this througharch::parks_synchronously(), andsleep_fidelitygates its strict form on it. - The
layersfirmware flashes but prints nothing (park/async/pipe demo).fidelityon the same probe prints and passes, so it is the new binary or the async path, not the toolchain. Under investigation. sync::Mutexand multi-core are not hardware-verified. The lock layer compiles everywhere with 32-bit atomics and its lost-wakeup path is fixed and reasoned about; the shared-bus device built on it has not been exercised on a real bus. Multi-core validates and refusesactive_cores > 1rather than pretending: no port starts a secondary core, and-smp 2has never been run.- The Xtensa port does not pass (
docs/ESP32.md), and macOS is acompile_error!until itssigaction/sigeventlayouts are adapted. - The crate has dependencies. The kernel core is
core-only with no allocator, but the crate always pullsembedded-hal,embedded-hal-async,embedded-ioandembedded-io-async(allno_std). That is the deliberate cost of making the standard traits available without feature flags. - 1-hour soak tests and physically unplugged peripherals are not automated anywhere yet.
Quickstart
Cargo.toml
[]
= "0.3"
= { = "0.7", = ["critical-section-single-core"] }
= "0.7"
= "0.6" # only if you want `log = rtt`
.cargo/config.toml
[]
= "probe-rs run --chip STM32F103C8"
= ["-C", "link-arg=-Tlink.x"]
[]
= "thumbv7m-none-eabi"
src/main.rs
use ;
use rrkernel;
use rprintln;
// entry point, vectors, panic + fault handlers, task 0
Then cargo run --release flashes and streams RTT. Complete, working copies live in
examples/cortex-m-bluepill (F103) and
examples/cortex-m-blackpill (F401).
The ring, counters and API are identical; only the backend differs (a waitable timer plus thread
suspend/resume on Windows, SIGALRM plus fibre switching on Linux). Timing limits are the host's,
and the examples report exactly what they measured — on one Windows machine a 1 ms slice is at the
edge of what the OS timer can honour, and the example says so.
Waiting on hardware without burning the slice
use Signal;
use Pipe;
static RX: Pipe = new;
spawn;
The reader is Blocked between bytes: measured 0 slices consumed while 71 bytes arrived.
Async, when a state machine is easier to write
spawn;
A .await that returns Pending hands the CPU over immediately — same guarantee as a blocking
sleep, so an async task cannot starve anyone either.
One bus, many tasks
use MutexDevice;
// Acquired with a timeout, held across a whole transaction, released on drop. The loser is parked,
// not spun — and never `CriticalSectionDevice`, which would mask interrupts for the transfer.
static I2C: = with_timeout;
An async driver can also be offered to blocking code without a second implementation:
rrkernel::hal::Blocking::new(async_driver).
The API in one screen
| Area | Items |
|---|---|
| Start | configure(clock, slice, stack), #[rrkernel(log = rtt)], scheduler::init_with(cfg) |
| Tasks | thread::spawn, spawn_with_stack, try_spawn, scheduler::main_body, SchedulerConfig |
| Time | now(), sleep(Duration), sleep_ms/us/secs/minutes/hours, deadline_after, deadline_add, sleep_until, ticks_for, tick_ns() |
| Events | Signal (ISR-safe set/wait), WaitQueue (wake_one/wake_all), park/wake/TaskId, yield_now, wait_until |
| Async | exec::block_on, exec::sleep, exec::spawn_async, exec::current_waker, SignalWait |
| Locks | sync::Mutex (sleeping, static lock order, try_lock_for), hal::MutexDevice (shared bus) |
| HAL/IO | hal::KernelDelay, hal::Blocking, io::Pipe (Read/Write, blocking and async) |
| Inspection | scheduler::stats() (ticks, switches, worst period error, worst switch, arena, blocks_without_current), for_each_task, platform_limits(), arch::idle_waits() |
Repository layout
src/
lib.rs the public surface, in one file
scheduler.rs policy: init/config, schedule_next, blocking, wake, stats, spawn, reclaim
event.rs Signal, WaitQueue, park/wake, yield_now, wait_until
exec.rs block_on, Waker, Sleep, spawn_async
hal.rs KernelDelay, Blocking facade, MutexDevice (embedded-hal / -async)
io.rs Pipe: ISR-driven byte ring, embedded-io / -async Read+Write
ring.rs tcb.rs arena.rs closure.rs trampoline.rs thread.rs time.rs config.rs
arch/ one file per port: cortex_m, riscv, arm_ar, xtensa, win32, posix
app_support.rs what #[rrkernel] expands into, plus the RAM black-box log
examples/
roundrobin_demo.rs sleep_fidelity.rs io_layers.rs smoke.rs jitter_bench.rs
cortex-m-bluepill/ (F103: main + `fidelity` + `layers` binaries)
cortex-m-blackpill/ (F401)
firmware-*/ the shared demo, cross-compiled per architecture (QEMU verdicts)
docs/ DESIGN.md (engineering record) · PORTING.md (port checklist) · ESP32.md
tests/ ring invariants · ring property tests · event state machines
Roadmap
Core kernel
- Preemptive round robin, one priority level, pure by construction
- Slice planned in cycles at init, validated, restarted on every switch
- Bump arena + deferred reclamation: spawn/exit at steady state
-
(N-1)worst-case bound instrumented instats() - Sleep precision verified on hardware (601 sleeps, 0 early)
- Idle path that genuinely parks the core (1
wfiper tick, measured) -
max_taskscap and a published switch-cost-vs-N benchmark - Stack canary / high-water marks in
stats() -
plan_timerfloor raised to 10× the measured switch cost (~800 cycles)
Concurrency
-
park/wake/TaskId,Signal,WaitQueue,yield_now,wait_until - Race-free waits: condition checked inside the blocking critical section
-
sync::Mutexwith static lock order and timeouts -
sync::Mutexand the shared bus exercised on real hardware - Interleaving tests over a mock arch layer
Async & I/O
-
block_on,Waker,Sleep,spawn_async(core-only, no executor dependency) -
embedded-hal+embedded-hal-async: delays, blocking facade, shared-bus device -
embedded-io+embedded-io-async: ISR-drivenPipe, 0 slices while blocked -
SpiDeviceshared-bus impl (I2C is done; SPI follows the same shape) - CAN / SD / ethernet / USB adapters
- 1-hour shared-bus soak test on hardware
Ports
- Cortex-M (M0/M0+/M3/M4/M33) — verified on an STM32F103C8
- RISC-V 32 (
riscv32imac) — QEMU verdict - ARM A/R (
armv7a,armv7r) — QEMU verdict - Windows and Linux host backends — 23 tests each
- Xtensa LX6 (ESP32): boot, switch and UART work; the resume is wrong
- macOS/BSD (POSIX layout adaptation), AVR (ATmega328P)
- Multi-core bring-up:
active_cores > 1,-smp 2, per-core current state
Time base
-
arch::cycle_counter()on Cortex-M (DWT) and RISC-V (rdcycle) -
DWT->CYCCNTmeasured across a verified sleep — it keeps counting, so DWT is usable -
Instant+ 64-bit counter extension, so deadlines stop being tick counts
Tooling & docs
- CI: fmt, clippy, tests, six-target builds (dev and release), QEMU verdicts
- Property tests for the ring, model-checked against a
Vecreference -
docs/DESIGN.md§8: the measured engineering record, bugs included -
docs/GUARANTEES.md(bounds, how each was measured, on which chip) -
docs/ASYNC_AND_IO.md(the three layers, the wake protocol, timeout rules) - Host tick source in the
io_layersscenario;layersfirmware RTT output
Contributing
The most useful contributions, roughly in order:
- A board. Port it to what you own —
docs/PORTING.mdis a checklist of about eleven functions, and a Cortex-M port is two files. A port that runs the shared demo toVERDICT : PASSis done. - A failing test. "This is broken, here is the trace" is as welcome as a feature; that is how
most of the bugs in
docs/DESIGN.md§8 were found. - A measurement. Hardware numbers with the chip and clock attached.
House rules, learned the hard way: never make a status table prettier than the truth; a silent failure
is a bug, not a hang; and a port must not skip the contract (on_tick, the critical_enter token
polarity, the full-slice restart).
License
MIT — see LICENSE. Use it on any board, including commercially. If you port it somewhere,
the only thing asked in return is that docs/PORTING.md gets the quirks you discovered.