1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
//! # 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.
//!
//! ```no_run
//! 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.
// Xtensa inline assembly is still an unstable feature in rustc — the esp-rs fork is
// nightly-only for exactly this reason, so the gate is enabled only for that target
// and the host backends keep building on stable.
/// `#[rrkernel]` — the attribute macro that declares a program: `main` becomes task 0, the
/// kernel gets configured by your call, and the fault/panic handlers come with it.
///
/// Import it to use the bare name: `use rrkernel::rrkernel;`
pub use ;
pub use rrkernel;
/// Sleeping with units: [`sleep`], [`sleep_ms`], [`sleep_secs`], … built on absolute
/// deadlines against the kernel's global tick.
pub use ;
/// `core`'s `Duration`, re-exported so an application needs one import for timekeeping:
/// `rrkernel::Duration::from_millis(250)`.
pub use Duration;
/// 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.
/// 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.
/// `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-io` / `embedded-io-async` byte streams on top of an ISR-driven [`event::Signal`].
/// 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.
pub use ;
pub use ;
pub use ;
pub use CpuArch;
pub use ;
pub use ;
pub use ;
/// The global kernel control block (ring, counters, tick statistics).
pub use KERNEL;
/// Start the scheduler with the default 1 ms slice — the convenient form of
/// [`scheduler::init_with`].
///
/// Returns after the tick source is live. The calling context becomes task 0
/// and is linked into the ring.
/// Start the scheduler with an explicit time slice (and other port knobs).