rusty_rtos_port_xtensa/lib.rs
1#![no_std]
2// Xtensa inline asm is nightly-only, and the gate is by TARGET rather than
3// by toolchain: an Xtensa build is always the `esp` fork, since there is no
4// upstream rustc target, while the host build -- which exists so callers
5// keep type-checking on stable -- never sees the attribute.
6#![cfg_attr(target_arch = "xtensa", feature(asm_experimental_arch))]
7//! `rusty_rtos_port-xtensa` — the Kairos Xtensa port.
8//!
9//! The Cortex-M port's docs say this family keeps its assembly in the port
10//! crates, "the only crates in the family with a fenced `unsafe` block".
11//! This is that crate for Xtensa LX6/LX7 — ESP32 and ESP32-S3.
12//!
13//! # Why this crate exists at all, given the corpus does not need it
14//!
15//! `rusty_rtos_demo/firmware/xiao-s3-corpus` runs the whole conformance
16//! corpus on an ESP32-S3, byte-identical to C FreeRTOS, **with no port**. A
17//! Kairos task keeps its locals in the TCB, so it owns no stack and needs no
18//! context switch. That result is real, and it is not what this crate is for.
19//!
20//! What needs a context switch is hosting tasks that are **not** ours. The
21//! `esp-radio-rtos-driver` interface (0.4.1) that K5b joins is explicit:
22//!
23//! ```text
24//! /// This function is used to create threads.
25//! /// It should allocate the stack.
26//! fn task_create(&self, name: &str, task: extern "C" fn(*mut c_void), ...,
27//! task_stack_size: usize) -> ThreadPtr;
28//! ```
29//!
30//! A C function pointer, a stack size, and blocking semaphore waits the
31//! radio blob performs from deep inside its own call frames. No stackless
32//! kernel can satisfy that, so the port is required by the radio joint and
33//! by nothing else the family has met so far.
34//!
35//! # The switch happens in an INTERRUPT, and that is the whole design
36//!
37//! An ARM switch saves eight callee-saved registers and swaps `SP`. The
38//! equivalent on Xtensa is far worse than it looks: a 64-entry physical
39//! register file behind a rotating 16-register window, and a task several
40//! calls deep has several live windows sitting in that file. Switch stacks
41//! with them live and the hardware later writes them onto whichever stack is
42//! current — the *incoming* one — and the corruption surfaces far from its
43//! cause.
44//!
45//! A first version of this crate tried to switch from task context, spilling
46//! the windows by hand with `xtensa-lx-rt`'s `SPILL_REGISTERS` sequence. It
47//! started a task, ran it, printed from it — and hung the moment that task
48//! nested calls deeply enough to need the register file back. That is
49//! recorded because the failure is instructive and the fix is not "try
50//! harder at the spill":
51//!
52//! **The switch belongs in an exception handler, where the context is
53//! already saved.** `xtensa-lx-rt`'s interrupt entry spills every window and
54//! writes the whole machine — `A0`–`A15`, `PC`, `PS`, `SAR`, the loop and
55//! MAC registers — into a [`Context`]. A handler holding `&mut Context` can
56//! therefore switch tasks by *copying structs*: save the trap frame into the
57//! outgoing task's slot, copy the incoming task's slot over the trap frame,
58//! and return. The exception exit restores it, windows and all.
59//!
60//! So a yield here raises a software interrupt rather than calling a
61//! switcher — which is what FreeRTOS's Xtensa port and Espressif's own
62//! `esp-rtos` both do, and for this reason.
63//!
64//! # Unsafe
65//!
66//! Every use is fenced with `#[expect(unsafe_code)]` and a justification.
67//! See `UNSAFE.md`.
68
69/// Crate version, for manifests and logs.
70pub const VERSION: &str = env!("CARGO_PKG_VERSION");
71
72#[cfg(target_arch = "xtensa")]
73pub use xtensa_lx_rt::exception::Context;
74
75/// Kani proofs of the stack builder (hardening gate H-30).
76#[cfg(kani)]
77mod proofs;
78
79/// The saved machine state of one task.
80///
81/// On Xtensa this is the interrupt trap frame, because the switch happens
82/// inside an interrupt; off Xtensa it is a stand-in carrying the fields this
83/// crate sets, so that callers keep type-checking on the host.
84#[cfg(not(target_arch = "xtensa"))]
85#[derive(Debug, Clone, Copy, Default)]
86#[allow(non_snake_case)]
87pub struct Context {
88 /// Program counter.
89 pub PC: u32,
90 /// Processor state.
91 pub PS: u32,
92 /// Return address.
93 pub A0: u32,
94 /// Stack pointer.
95 pub A1: u32,
96 /// First windowed argument register used by [`new_task_context`].
97 pub A6: u32,
98 /// Second windowed argument register used by [`new_task_context`].
99 pub A7: u32,
100 /// The shift-amount register.
101 ///
102 /// Not set by this crate, and present for exactly that reason: the real
103 /// trap frame carries a dozen registers a fresh task simply wants zeroed,
104 /// so [`new_task_context`] finishes with `..Default::default()`. Without
105 /// one such field here the host stub would be exhaustively initialised
106 /// and that tail would read as dead code on the host build alone.
107 pub SAR: u32,
108}
109
110/// `PS.WOE` — window overflow enabled.
111///
112/// A task started without it would run, and the first interrupt taken in it
113/// would spill nothing, quietly corrupting whichever stack came next.
114const PS_WOE: u32 = 0x0004_0000;
115
116/// `PS.CALLINC` = 1: the task is entered as though it had been `call4`-ed.
117///
118/// This is what puts the entry point's two arguments in `A6`/`A7`: on
119/// `entry` the window rotates by four, so the callee sees them as its own
120/// `a2`/`a3`.
121const PS_CALLINC_CALL4: u32 = 1 << 16;
122
123/// How many bytes below the stack top the initial frame occupies.
124pub const INITIAL_FRAME_BYTES: usize = 16;
125
126/// Build the saved context of a task that has never run.
127///
128/// `stack_top` is one past the highest usable byte of the task's stack; it is
129/// rounded down to the 16-byte alignment the ABI requires of `SP`. When the
130/// task is first switched to, `wrapper` runs with `task_fn` and `param` as
131/// its two arguments.
132///
133/// The wrapper exists because a task body must not simply `return`: there is
134/// no frame beneath it to return into. A caller supplies one that ends the
135/// task instead.
136///
137/// # Safety
138///
139/// `stack_top` must be one past a writable stack that stays mapped for as
140/// long as the task can run, with at least [`INITIAL_FRAME_BYTES`] plus
141/// whatever the task body needs below it.
142#[expect(unsafe_code, reason = "writing the initial frame")]
143#[must_use]
144pub unsafe fn new_task_context(
145 wrapper: extern "C" fn(task_fn: usize, param: usize),
146 task_fn: usize,
147 param: usize,
148 stack_top: *mut u8,
149) -> Context {
150 // The address arithmetic is done at POINTER width and narrowed only on
151 // the way into the register fields. Doing it in `u32` throughout costs
152 // nothing on a 32-bit target and writes through a TRUNCATED address on
153 // any other — which on the 64-bit host build is an access violation the
154 // first time a test calls this. Found exactly that way.
155 let top = (stack_top as usize) & !0xf;
156
157 // The four words the ABI expects below a frame's stack pointer. The one
158 // at `top - 12` is the frame's own stack pointer, which is what a window
159 // underflow follows when the task's first `entry` unwinds.
160 // SAFETY: the caller guarantees `[top - 16, top)` is writable.
161 unsafe {
162 (top.wrapping_sub(4) as *mut u32).write_volatile(0);
163 (top.wrapping_sub(8) as *mut u32).write_volatile(0);
164 (top.wrapping_sub(12) as *mut u32).write_volatile(top as u32);
165 (top.wrapping_sub(16) as *mut u32).write_volatile(0);
166 }
167
168 // `..Default::default()` and not a full literal: the Xtensa `Context` is
169 // the whole trap frame -- SAR, the loop registers, the MAC accumulators --
170 // and a fresh task wants zero in every one of them.
171 Context {
172 PC: (wrapper as *const ()) as usize as u32,
173 A0: 0,
174 A1: top as u32,
175 A6: task_fn as u32,
176 A7: param as u32,
177 PS: PS_WOE | PS_CALLINC_CALL4,
178 ..Default::default()
179 }
180}
181
182/// Swap the running task.
183///
184/// Called from inside the switching interrupt, with the trap frame the
185/// handler was given. `current` is where the outgoing task's state is kept —
186/// `None` when the outgoing task is being discarded rather than paused — and
187/// `next` is the task to resume.
188///
189/// # Safety
190///
191/// `trap_frame` must be the frame the interrupt handler was handed, and the
192/// two contexts must be valid for writing and reading respectively.
193#[expect(unsafe_code, reason = "the context switch itself")]
194pub unsafe fn switch_context(
195 current: Option<*mut Context>,
196 next: *const Context,
197 trap_frame: &mut Context,
198) {
199 // `copy_nonoverlapping`, which LLVM lowers to a call to `memcpy` -- on the
200 // ESP32-S3 the routine in mask ROM. Hand-written in-line copies were
201 // tried against it on the XIAO S3 (`xiao-s3-realtime`, `--features
202 // decompose`, 2026-10-01) and every one LOST:
203 // - eight words per step, loads before stores: 278 cycles for both
204 // copies against the ROM's 247 without FP save, 484 against 347 with;
205 // - two words per step stays a loop at `opt-level = "s"`, ten
206 // instructions and a taken branch per two words;
207 // - volatile word accesses get a `memw` each on Xtensa.
208 // The ROM routine is the fast one; leave it.
209 //
210 // SAFETY: the contract above. These are plain `Copy` structs, and the
211 // exception exit restores whatever is left in `trap_frame`.
212 unsafe {
213 if let Some(current) = current {
214 core::ptr::copy_nonoverlapping(core::ptr::from_mut(trap_frame), current, 1);
215 }
216 core::ptr::copy_nonoverlapping(next, core::ptr::from_mut(trap_frame), 1);
217 }
218}
219
220/// The software interrupt the switch runs in.
221///
222/// Software0 everywhere except the original ESP32, which reserves it for the
223/// Bluetooth stack and uses Software1 — the same choice `esp-rtos` makes. It
224/// has to agree with the handler a firmware exports.
225pub const SW_INTERRUPT_MASK: u32 = if cfg!(feature = "esp32") {
226 1 << 29
227} else {
228 1 << 7
229};
230
231/// Enable the switching interrupt. Call once, before the first switch.
232#[cfg(target_arch = "xtensa")]
233#[expect(unsafe_code, reason = "enabling an interrupt is a register write")]
234pub fn enable_switching() {
235 // SAFETY: enables one software interrupt, whose handler the firmware
236 // supplies; it can do nothing until `yield_now` raises it.
237 unsafe {
238 xtensa_lx::interrupt::enable_mask(SW_INTERRUPT_MASK);
239 }
240}
241
242/// `portYIELD()`: raise the switching interrupt.
243///
244/// It does not switch, it *asks*. The switch happens when the interrupt is
245/// taken, which is the only context in which the machine state is saved.
246#[cfg(target_arch = "xtensa")]
247#[expect(unsafe_code, reason = "raising an interrupt is a register write")]
248#[inline]
249pub fn yield_now() {
250 // SAFETY: sets the software interrupt this port owns.
251 unsafe {
252 xtensa_lx::interrupt::set(SW_INTERRUPT_MASK);
253 }
254}
255
256/// Clear the switching interrupt. The handler must do this first.
257#[cfg(target_arch = "xtensa")]
258#[expect(unsafe_code, reason = "clearing an interrupt is a register write")]
259#[inline]
260pub fn clear_switch_request() {
261 // SAFETY: clears the software interrupt this port owns.
262 unsafe {
263 xtensa_lx::interrupt::clear(SW_INTERRUPT_MASK);
264 }
265}
266
267/// Off Xtensa this is a stub, so every caller keeps type-checking on the
268/// host build. That is what stops this crate rotting between board runs.
269#[cfg(not(target_arch = "xtensa"))]
270pub fn enable_switching() {}
271
272/// As [`enable_switching`].
273#[cfg(not(target_arch = "xtensa"))]
274#[inline]
275pub fn yield_now() {}
276
277/// As [`enable_switching`].
278#[cfg(not(target_arch = "xtensa"))]
279#[inline]
280pub fn clear_switch_request() {}
281
282// ------------------------------------------------------------- the port --
283
284use core::sync::atomic::{AtomicU32, Ordering};
285
286use rusty_rtos_core::isr::Woken;
287use rusty_rtos_core::port::Port;
288
289/// `PS.INTLEVEL` a critical section masks to.
290///
291/// Three, not fifteen: level 4 and above on this ISA are non-maskable and
292/// debug-level interrupts that a critical section has no business holding
293/// off, and the radio blob's own handlers live below it. It is also the
294/// level `esp-hal`'s `critical-section` implementation uses, which matters
295/// because the two will nest inside one another in a radio firmware.
296#[cfg(target_arch = "xtensa")]
297const CRITICAL_INTLEVEL: u32 = 3;
298
299/// The Kairos Xtensa port.
300///
301/// Critical sections mask interrupts by raising `PS.INTLEVEL`; the yield
302/// raises the software interrupt the switch runs in; the tick arrives from
303/// whatever timer the firmware wires up, through [`XtensaPort::note_tick`].
304#[derive(Debug, Default)]
305pub struct XtensaPort {
306 nesting: AtomicU32,
307 /// The `PS` saved by the OUTERMOST `enter_critical`, restored by the
308 /// matching exit. Only the outermost value is kept, because only the
309 /// outermost exit unmasks.
310 saved_ps: AtomicU32,
311 yields: AtomicU32,
312 ticks: AtomicU32,
313 exits: AtomicU32,
314}
315
316impl XtensaPort {
317 /// A port with nothing counted yet.
318 #[must_use]
319 pub const fn new() -> Self {
320 Self {
321 nesting: AtomicU32::new(0),
322 saved_ps: AtomicU32::new(0),
323 yields: AtomicU32::new(0),
324 ticks: AtomicU32::new(0),
325 exits: AtomicU32::new(0),
326 }
327 }
328
329 /// Ticks delivered so far.
330 #[must_use]
331 pub fn tick_count(&self) -> u64 {
332 u64::from(self.ticks.load(Ordering::Relaxed))
333 }
334
335 /// Count one tick. A firmware calls this from its timer interrupt,
336 /// beside `Kernel::increment_tick`.
337 pub fn note_tick(&self) {
338 self.ticks.fetch_add(1, Ordering::Relaxed);
339 }
340
341 /// `portYIELD()` calls made.
342 #[must_use]
343 pub fn yield_count(&self) -> u64 {
344 u64::from(self.yields.load(Ordering::Relaxed))
345 }
346}
347
348/// Raise `PS.INTLEVEL` and answer the old `PS`.
349#[cfg(target_arch = "xtensa")]
350#[expect(unsafe_code, reason = "the critical section is a PS write")]
351#[inline(always)]
352fn mask_interrupts() -> u32 {
353 let ps: u32;
354 // SAFETY: `rsil` reads PS and raises INTLEVEL in one instruction. It
355 // touches no memory and cannot fault.
356 unsafe {
357 core::arch::asm!(
358 "rsil {0}, {1}",
359 out(reg) ps,
360 const CRITICAL_INTLEVEL,
361 options(nostack),
362 );
363 }
364 ps
365}
366
367/// Restore a `PS` saved by [`mask_interrupts`].
368#[cfg(target_arch = "xtensa")]
369#[expect(unsafe_code, reason = "the critical section is a PS write")]
370#[inline(always)]
371fn restore_interrupts(ps: u32) {
372 // SAFETY: `ps` came from `rsil` on this core, so it is a state this
373 // core was already in. `rsync` is required before the new PS is
374 // guaranteed visible to the instructions that follow.
375 unsafe {
376 core::arch::asm!(
377 "wsr.ps {0}",
378 "rsync",
379 in(reg) ps,
380 options(nostack),
381 );
382 }
383}
384
385#[cfg(not(target_arch = "xtensa"))]
386#[inline(always)]
387fn mask_interrupts() -> u32 {
388 0
389}
390
391#[cfg(not(target_arch = "xtensa"))]
392#[inline(always)]
393fn restore_interrupts(_ps: u32) {}
394
395impl Port for XtensaPort {
396 /// This port SWITCHES STACKS, so the kernel must not commit a switch at
397 /// the point of the yield — only the switching exception can move the
398 /// registers, and anything running between a commit and that exception
399 /// would be running as a task the kernel had already moved on from.
400 const COMMITS_SWITCH: bool = true;
401
402 fn yield_now(&self) {
403 // No counter here: `Kernel::port_yield` calls `count_yield` just
404 // before this, and counting in both places would double every yield
405 // the kernel asks for.
406 yield_now();
407 }
408
409 fn yield_from_isr(&self, woken: Woken) {
410 if woken == Woken::YES {
411 self.yields.fetch_add(1, Ordering::Relaxed);
412 yield_now();
413 }
414 }
415
416 fn enter_critical(&self) {
417 let ps = mask_interrupts();
418 // Only the OUTERMOST section's PS is kept: an inner `rsil` returns
419 // a PS that is already masked, and restoring that on the way out
420 // would leave interrupts off for good.
421 if self.nesting.fetch_add(1, Ordering::Relaxed) == 0 {
422 self.saved_ps.store(ps, Ordering::Relaxed);
423 }
424 }
425
426 fn exit_critical(&self) {
427 // Interrupts are masked here, so this read-modify-write needs no
428 // atomicity of its own.
429 let n = self.nesting.load(Ordering::Relaxed).saturating_sub(1);
430 self.nesting.store(n, Ordering::Relaxed);
431 if n == 0 {
432 self.exits.fetch_add(1, Ordering::Relaxed);
433 restore_interrupts(self.saved_ps.load(Ordering::Relaxed));
434 }
435 }
436
437 fn set_interrupt_mask_from_isr(&self) -> u32 {
438 mask_interrupts()
439 }
440
441 fn clear_interrupt_mask_from_isr(&self, saved: u32) {
442 restore_interrupts(saved);
443 }
444
445 fn in_isr(&self) -> bool {
446 // `PS.INTLEVEL` above zero means an interrupt is being serviced.
447 // This is weaker than ARM's `IPSR`: a task inside a critical
448 // section also reads non-zero. Callers in this family use it to
449 // decide which API half to take, and a task in a critical section
450 // taking the from-ISR half is safe -- the reverse would not be.
451 mask_intlevel() != 0
452 }
453
454 fn count_tick(&self) {
455 self.note_tick();
456 }
457
458 fn count_yield(&self) {
459 self.yields.fetch_add(1, Ordering::Relaxed);
460 }
461
462 fn exits(&self) -> u64 {
463 u64::from(self.exits.load(Ordering::Relaxed))
464 }
465
466 fn idle(&self) {
467 idle_wait();
468 }
469}
470
471/// The current `PS.INTLEVEL`.
472#[cfg(target_arch = "xtensa")]
473#[expect(unsafe_code, reason = "reading PS")]
474#[inline]
475fn mask_intlevel() -> u32 {
476 let ps: u32;
477 // SAFETY: reads a register, touches no memory.
478 unsafe {
479 core::arch::asm!("rsr.ps {0}", out(reg) ps, options(nomem, nostack));
480 }
481 ps & 0xf
482}
483
484#[cfg(not(target_arch = "xtensa"))]
485#[inline]
486fn mask_intlevel() -> u32 {
487 0
488}
489
490/// `waiti 0`: sleep until the next interrupt. The C port's idle.
491#[cfg(target_arch = "xtensa")]
492#[expect(unsafe_code, reason = "the idle instruction")]
493#[inline]
494fn idle_wait() {
495 // SAFETY: `waiti` is a hint; it cannot fault. It returns on any
496 // interrupt at level 0 or above, which includes the tick.
497 unsafe {
498 core::arch::asm!("waiti 0", options(nomem, nostack));
499 }
500}
501
502#[cfg(not(target_arch = "xtensa"))]
503#[inline]
504fn idle_wait() {}