Skip to main content

Crate rrkernel

Crate rrkernel 

Source
Expand description

§rrkernel — a preemptive round-robin RTOS kernel with a no_std core

Zero dependencies. One API. Two kinds of machine:

  • Bare metal (no_std, Cortex-M): SysTick as the cycle-exact slice timer, PendSV for the context switch, hand-written Thumb assembly for the register frame, and a user-chosen slice down to ~100 cycles.
  • Desktop (std): identical ring, counters and life cycle on top of OS primitives — a one-shot timer plus real thread suspension on Windows, setitimer/SIGALRM plus hand-written x86-64 fiber switching on POSIX.

§The developer API

There is no scheduler_run(), no explicit yield, and no manual loop/exit handling. Initialising the scheduler starts the timer engine immediately; spawning links a task into the live ring and switches to it; returning from a task’s function unlinks it and switches away.

use rrkernel::{scheduler, thread, Slice, SchedulerConfig};

fn main() {
    // Choose the slice first: this is the timing contract.
    scheduler::init_with(SchedulerConfig::embedded(Slice::Millis(1), 168_000_000)).unwrap();

    // Task 1: CPU-bound, preempted automatically every slice.
    thread::spawn(|| loop {
        core::hint::spin_loop();
    });

    // Task 2: finishes its work, then the trampoline unlinks it, updates the
    // pointers/counters and switches to the next task immediately.
    thread::spawn(|| do_work());
}

fn do_work() {
    // Tasks may spawn tasks at any time; the child is inserted into the
    // running ring and gets the CPU on the next switch.
    thread::spawn(|| { /* child task */ });
}

§Scheduling contract

  • Pure round robin. Every task has identical priority; the only knob is the slice, which is set by the user at init (and can be retuned later with scheduler::set_slice).
  • Fixed, full slices. Every switch re-arms the timer, so a task that exits early or a spawn that kicks the scheduler never shortens the next task’s slice and the period never drifts.
  • O(1) unlink on completion. (*prev).next = next; (*next).prev = prev, active_threads -= 1, then an immediate context switch. Dead tasks never accumulate in the ring, and their stacks are recycled by the deferred-free path on the next switch.

§Honest limits

Cycle-exact slices are a bare-metal property. On a desktop OS the slice is bounded by the OS timer resolution (0.5–1 ms on Windows) and the jitter by the OS scheduler — scheduler::stats and the jitter_bench example measure it instead of pretending otherwise. On bare metal the switch costs roughly 0.5–1 µs at 168 MHz and the jitter is a handful of cycles. There are no priorities (so no priority inheritance) and no blocking primitives by design, which also means a task’s worst-case lateness is (N-1) slices.

Re-exports§

pub use app_support::configure;
pub use app_support::log_with;
pub use time::deadline_add;
pub use time::deadline_after;
pub use time::now;
pub use time::sleep;
pub use time::sleep_hours;
pub use time::sleep_minutes;
pub use time::sleep_ms;
pub use time::sleep_ns;
pub use time::sleep_secs;
pub use time::sleep_until;
pub use time::sleep_us;
pub use time::tick_ns;
pub use time::ticks_for;
pub use config::ConfigError;
pub use config::PlatformLimits;
pub use config::SchedulerConfig;
pub use config::Slice;
pub use event::park;
pub use event::wait_until;
pub use event::wake;
pub use event::Signal;
pub use event::Timeout;
pub use event::WaitQueue;
pub use event::WakeReason;
pub use scheduler::block_for_ticks;
pub use scheduler::block_until_tick;
pub use scheduler::block_until_tick_if;
pub use scheduler::current_id;
pub use scheduler::deadline_after_ticks;
pub use scheduler::main_body;
pub use scheduler::sleep_until_tick;
pub use scheduler::wake_first_blocked_on;
pub use scheduler::wake_task;
pub use scheduler::yield_now;
pub use scheduler::BlockOutcome;
pub use scheduler::SchedulerStats;
pub use scheduler::TaskId;
pub use scheduler::TaskInfo;
pub use smp::CpuArch;
pub use sync::LockError;
pub use sync::LockId;
pub use sync::Mutex;
pub use sync::MutexGuard;
pub use tcb::IdlePolicy;
pub use tcb::KernelConfig;
pub use tcb::Measure;
pub use tcb::TaskControlBlock;
pub use tcb::TaskState;
pub use thread::spawn;
pub use thread::spawn_with_stack;
pub use thread::try_spawn;
pub use thread::SpawnError;
pub use thread::DEFAULT_STACK_SIZE;
pub use tcb::KERNEL;

Modules§

app_support
The app! facade: everything a Cortex-M application should not have to write.
arch
Architecture / platform ports.
arena
Stack / TCB / closure arena with O(1)-ish recycling.
closure
Closure placement without a heap and without alloc.
config
User-facing scheduler configuration: the time slice you choose at init, plus the knobs the port needs.
critical
Critical sections: the one primitive every ring mutation depends on.
event
Events and waiting: event::park, event::Signal, event::WaitQueue, and the event::wait_until poll-yield fallback. Everything an I/O or async layer needs to block a task without burning its slice. Events: park, Signal, WaitQueue, and the poll-yield fallback.
exec
The async layer: exec::block_on, the task Waker, Sleep. A .await that returns Pending gives up the slice exactly like a blocking call does. The async layer: block_on, the task Waker, and async sleeps.
hal
embedded-hal / embedded-hal-async adapters: delays, the blocking facade over an async driver, and a kernel-mutex device for a bus shared between tasks. embedded-hal adapters: delays, the blocking facade over an async driver, and a kernel-mutex device for a bus shared between tasks.
io
embedded-io / embedded-io-async byte streams on top of an ISR-driven event::Signal. embedded-io byte streams driven by an interrupt, without burning a slice while idle.
ring
The automated doubly-linked circular task ring.
scheduler
Scheduler policy: who runs next, what the counters say, and how a finished task’s memory gets reclaimed.
smp
Architecture-agnostic multi-core support: core identity, cross-core interlocks and inter-processor interrupts.
sync
Sleeping locks need at least a word-wide atomic read-modify-write: the id allocator and every lock’s owner word are atomics. Targets without one (Cortex-M0, AVR, riscv32imc) simply do not get this layer — a mutex whose owner field cannot be updated atomically is not a mutex. Sleeping locks, static lock-order enforcement, and timeout/back-off recovery.
tcb
Task Control Block and global kernel control state.
thread
thread::spawn — the entire task-creation surface.
time
Sleeping with units: sleep, sleep_ms, sleep_secs, … built on absolute deadlines against the kernel’s global tick. Sleeping, with units.
trampoline
Task life cycle: run the body, then tear the task down automatically.

Structs§

Duration
core’s Duration, re-exported so an application needs one import for timekeeping: rrkernel::Duration::from_millis(250). A Duration type to represent a span of time, typically used for system timeouts.

Functions§

scheduler_init
Start the scheduler with the default 1 ms slice — the convenient form of scheduler::init_with.
scheduler_init_with
Start the scheduler with an explicit time slice (and other port knobs).

Attribute Macros§

rrkernel
Turn a cortex-m-rt main into the kernel’s task 0.