Skip to main content

Crate rusty_rtos_port_xtensa

Crate rusty_rtos_port_xtensa 

Source
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.
XtensaPort
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.