Expand description
rusty_rtos_port-xtensa — the Kairos Xtensa port.
The Cortex-M port’s docs say this family keeps its assembly in the port
crates, “the only crates in the family with a fenced unsafe block”.
This is that crate for Xtensa LX6/LX7 — ESP32 and ESP32-S3.
§Why this crate exists at all, given the corpus does not need it
rusty_rtos_demo/firmware/xiao-s3-corpus runs the whole conformance
corpus on an ESP32-S3, byte-identical to C FreeRTOS, with no port. A
Kairos task keeps its locals in the TCB, so it owns no stack and needs no
context switch. That result is real, and it is not what this crate is for.
What needs a context switch is hosting tasks that are not ours. The
esp-radio-rtos-driver interface (0.4.1) that K5b joins is explicit:
/// This function is used to create threads.
/// It should allocate the stack.
fn task_create(&self, name: &str, task: extern "C" fn(*mut c_void), ...,
task_stack_size: usize) -> ThreadPtr;A C function pointer, a stack size, and blocking semaphore waits the radio blob performs from deep inside its own call frames. No stackless kernel can satisfy that, so the port is required by the radio joint and by nothing else the family has met so far.
§The switch happens in an INTERRUPT, and that is the whole design
An ARM switch saves eight callee-saved registers and swaps SP. The
equivalent on Xtensa is far worse than it looks: a 64-entry physical
register file behind a rotating 16-register window, and a task several
calls deep has several live windows sitting in that file. Switch stacks
with them live and the hardware later writes them onto whichever stack is
current — the incoming one — and the corruption surfaces far from its
cause.
A first version of this crate tried to switch from task context, spilling
the windows by hand with xtensa-lx-rt’s SPILL_REGISTERS sequence. It
started a task, ran it, printed from it — and hung the moment that task
nested calls deeply enough to need the register file back. That is
recorded because the failure is instructive and the fix is not “try
harder at the spill”:
The switch belongs in an exception handler, where the context is
already saved. xtensa-lx-rt’s interrupt entry spills every window and
writes the whole machine — A0–A15, PC, PS, SAR, the loop and
MAC registers — into a Context. A handler holding &mut Context can
therefore switch tasks by copying structs: save the trap frame into the
outgoing task’s slot, copy the incoming task’s slot over the trap frame,
and return. The exception exit restores it, windows and all.
So a yield here raises a software interrupt rather than calling a
switcher — which is what FreeRTOS’s Xtensa port and Espressif’s own
esp-rtos both do, and for this reason.
§Unsafe
Every use is fenced with #[expect(unsafe_code)] and a justification.
See UNSAFE.md.
Structs§
- Context
- The saved machine state of one task.
- Xtensa
Port - The Kairos Xtensa port.
Constants§
- INITIAL_
FRAME_ BYTES - How many bytes below the stack top the initial frame occupies.
- SW_
INTERRUPT_ MASK - The software interrupt the switch runs in.
- VERSION
- Crate version, for manifests and logs.
Functions§
- clear_
switch_ request - As
enable_switching. - enable_
switching - Off Xtensa this is a stub, so every caller keeps type-checking on the host build. That is what stops this crate rotting between board runs.
- new_
task_ ⚠context - Build the saved context of a task that has never run.
- switch_
context ⚠ - Swap the running task.
- yield_
now - As
enable_switching.