rrkernel 0.3.0

Preemptive round-robin RTOS kernel: one API for bare-metal Cortex-M (SysTick+PendSV, cycle-exact slices) and std desktops, with an optional #[rrkernel] attribute that makes main() task 0.
Documentation
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
<div align="center">

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

[![Rust](https://img.shields.io/badge/rust-1.88%2B-dea584?logo=rust)](https://www.rust-lang.org)
[![no_std](https://img.shields.io/badge/no__std-yes-2b2b2b)](#)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Deps](https://img.shields.io/badge/kernel%20core-zero%20deps-3fb950)](#)
[![Tests](https://img.shields.io/badge/host%20tests-23%20passing-3fb950)](#testing--ci)
[![Hardware](https://img.shields.io/badge/STM32F103-verified-3fb950)](#where-it-has-actually-been-run)

</div>

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

<details>
<summary><b>What it looks like, in 20 seconds</b></summary>

```rust
use rrkernel::{configure, thread, Duration, Slice};
use rrkernel::rrkernel;

#[rrkernel(log = rtt)]

#[cortex_m_rt::entry]

fn main() {
    configure(8_000_000, Slice::Millis(1), 1024);   // clock, slice, stack — that is the contract

    thread::spawn(|| loop {                          // CPU-bound, never yields:
        core::hint::spin_loop();                     // preempted by hardware every millisecond
    });

    thread::spawn(|| loop {
        led.set_low();
        rrkernel::sleep(Duration::from_millis(500));  // no CPU burnt while waiting
        led.set_high();
        rrkernel::sleep(Duration::from_millis(500));
    });
}
```

No priorities. No `unsafe` in application code. No allocator. Two files: your `main.rs` and a
`memory.x` your chip crate usually ships anyway.

</details>

---

## 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 8000 `SysTick`
  cycles — 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; `unsafe` stays 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


```mermaid
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:

```rust
configure(core_clock_hz, Slice::Millis(1), stack_bytes);
```

- 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 `set`s 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 — your `main` stays short.
- **Familiar API.** `thread::spawn` takes `FnOnce() + Send + 'static`, exactly like `std::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 task `Waker`, `Sleep`, `spawn_async`
  — `core::future` only, 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-async` for delays, a blocking facade over an async driver and a
  kernel-mutex shared-bus device; `embedded-io` + `embedded-io-async` for the ISR-driven `Pipe`.
- **`core`-only kernel.** No `alloc`, 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


```bash
cargo test --features std                                     # 23 tests: ring, arena, closure, ABI, events
cargo clippy --all-targets --features std -- -D warnings       # clean on host + all six bare-metal targets
cargo fmt --all --check
cargo run --example sleep_fidelity --features std              # sleep fidelity + idle window
cargo run --example io_layers --features std                   # I/O layers acceptance
cargo run -p firmware-riscv  --target riscv32imac-unknown-none-elf --release   # QEMU verdict
cargo run -p firmware-arm-a  --target armv7a-none-eabi             --release   # QEMU verdict
cd examples/cortex-m-bluepill && cargo run --release --bin fidelity            # on your board
```

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


<details>
<summary><b>What is known to be incomplete or unproven</b> — click to expand</summary>

- **Host tick source in some task sets.** On Windows *and* Linux, `tick_count()` has been observed to
  stay `0` from init in the `io_layers` scenario, 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.rs` exits 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 `SIGALRM` handler has no idle context to switch to when nothing is runnable. Each port
  reports this through `arch::parks_synchronously()`, and `sleep_fidelity` gates its strict form on it.
- **The `layers` firmware flashes but prints nothing** (park/async/pipe demo). `fidelity` on the same
  probe prints and passes, so it is the new binary or the async path, not the toolchain. Under
  investigation.
- **`sync::Mutex` and 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 refuses `active_cores > 1` rather
  than pretending: no port starts a secondary core, and `-smp 2` has never been run.
- **The Xtensa port does not pass** (`docs/ESP32.md`), and macOS is a `compile_error!` until its
  `sigaction`/`sigevent` layouts are adapted.
- **The crate has dependencies.** The *kernel core* is `core`-only with no allocator, but the crate
  always pulls `embedded-hal`, `embedded-hal-async`, `embedded-io` and `embedded-io-async` (all
  `no_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.

</details>

---

## Quickstart


<details open>
<summary><b>On a board</b> (STM32F103 "Blue Pill")</summary>

`Cargo.toml`

```toml
[dependencies]
rrkernel = "0.3"
cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
cortex-m-rt = "0.7"
rtt-target = "0.6"          # only if you want `log = rtt`
```

`.cargo/config.toml`

```toml
[target.thumbv7m-none-eabi]
runner = "probe-rs run --chip STM32F103C8"
rustflags = ["-C", "link-arg=-Tlink.x"]
[build]
target = "thumbv7m-none-eabi"
```

`src/main.rs`

```rust
#![no_std]

#![no_main]


use rrkernel::{configure, thread, Duration, Slice};
use rrkernel::rrkernel;
use rtt_target::rprintln;

#[rrkernel(log = rtt)]              // entry point, vectors, panic + fault handlers, task 0

#[cortex_m_rt::entry]

fn main() {
    configure(8_000_000, Slice::Millis(1), 1024);

    thread::spawn(|| loop { core::hint::spin_loop() });      // never yields: still throttled
    thread::spawn(|| loop {
        rprintln!("tick at {} ms", rrkernel::now());
        rrkernel::sleep(Duration::from_millis(500));
    });

    // Returning from `main` is a task exit: task 0 is unlinked like any other.
}
```

Then `cargo run --release` flashes and streams RTT. Complete, working copies live in
[`examples/cortex-m-bluepill`](examples/cortex-m-bluepill) (F103) and
[`examples/cortex-m-blackpill`](examples/cortex-m-blackpill) (F401).

</details>

<details>
<summary><b>On a desktop</b> — same API, no hardware</summary>

```bash
cargo run --example roundrobin_demo --features std      # preemption, auto-unlink, report
cargo run --example sleep_fidelity  --features std      # sleep precision + idle windows
cargo run --example io_layers       --features std      # shared bus, ISR-driven pipe, async
```

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.

</details>

### Waiting on hardware without burning the slice


```rust
use rrkernel::event::Signal;
use rrkernel::io::Pipe;

static RX: Pipe = Pipe::new();

#[cortex_m_rt::interrupt]

fn USART1() {
    while let Some(b) = read_hw_byte() {
        RX.push_from_isr(b);            // ISR-safe, allocation-free, wakes the reader
    }
}

thread::spawn(|| {
    let mut buf = [0u8; 64];
    loop {
        let deadline = rrkernel::deadline_after(Duration::from_millis(100));
        match RX.read_blocking(&mut buf, Some(deadline)) {
            Ok(n) => handle(&buf[..n]),
            Err(_) => {}                // Err(Timeout): the device went quiet
        }
    }
});
```

The reader is `Blocked` between bytes: **measured 0 slices consumed** while 71 bytes arrived.

### Async, when a state machine is easier to write


```rust
thread::spawn(|| rrkernel::exec::block_on(async {
    loop {
        rrkernel::exec::sleep(Duration::from_millis(100)).await;   // gives the slice back
        sample_and_filter().await;
    }
}));
```

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


```rust
use rrkernel::hal::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: MutexDevice<MyI2c, 0x4000_0001> = MutexDevice::with_timeout(my_bus, 100);
```

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


```text
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**

- [x] Preemptive round robin, one priority level, pure by construction
- [x] Slice planned in cycles at init, validated, restarted on every switch
- [x] Bump arena + deferred reclamation: spawn/exit at steady state
- [x] `(N-1)` worst-case bound instrumented in `stats()`
- [x] Sleep precision verified on hardware (601 sleeps, 0 early)
- [x] Idle path that genuinely parks the core (1 `wfi` per tick, measured)
- [ ] `max_tasks` cap and a published switch-cost-vs-N benchmark
- [ ] Stack canary / high-water marks in `stats()`
- [ ] `plan_timer` floor raised to 10× the measured switch cost (~800 cycles)

**Concurrency**

- [x] `park`/`wake`/`TaskId`, `Signal`, `WaitQueue`, `yield_now`, `wait_until`
- [x] Race-free waits: condition checked inside the blocking critical section
- [x] `sync::Mutex` with static lock order and timeouts
- [ ] `sync::Mutex` and the shared bus exercised on real hardware
- [ ] Interleaving tests over a mock arch layer

**Async & I/O**

- [x] `block_on`, `Waker`, `Sleep`, `spawn_async` (core-only, no executor dependency)
- [x] `embedded-hal` + `embedded-hal-async`: delays, blocking facade, shared-bus device
- [x] `embedded-io` + `embedded-io-async`: ISR-driven `Pipe`, 0 slices while blocked
- [ ] `SpiDevice` shared-bus impl (I2C is done; SPI follows the same shape)
- [ ] CAN / SD / ethernet / USB adapters
- [ ] 1-hour shared-bus soak test on hardware

**Ports**

- [x] Cortex-M (M0/M0+/M3/M4/M33) — **verified on an STM32F103C8**
- [x] RISC-V 32 (`riscv32imac`) — QEMU verdict
- [x] ARM A/R (`armv7a`, `armv7r`) — QEMU verdict
- [x] 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**

- [x] `arch::cycle_counter()` on Cortex-M (DWT) and RISC-V (`rdcycle`)
- [x] `DWT->CYCCNT` measured across a *verified* sleep — it keeps counting, so DWT is usable
- [ ] `Instant` + 64-bit counter extension, so deadlines stop being tick counts

**Tooling & docs**

- [x] CI: fmt, clippy, tests, six-target builds (dev **and** release), QEMU verdicts
- [x] Property tests for the ring, model-checked against a `Vec` reference
- [x] `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_layers` scenario; `layers` firmware RTT output

## Contributing


The most useful contributions, roughly in order:

1. **A board.** Port it to what you own — `docs/PORTING.md` is a checklist of about eleven functions,
   and a Cortex-M port is two files. A port that runs the shared demo to `VERDICT : PASS` is done.
2. **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.
3. **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](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.