Skip to main content

Crate rusty_rtos_port_riscv

Crate rusty_rtos_port_riscv 

Source
Expand description

rusty_rtos_port-riscv — the Kairos RISC-V port.

RV32, for QEMU virt and for the ESP32-C6/C61/H2/P4 family.

§Simpler than Xtensa, and not for the reason you would guess

Xtensa’s difficulty is the register windows: a task several calls deep has live frames in a 64-entry file that must reach its own stack before anything else runs. RISC-V has no windows, so there is nothing to spill.

But it is NOT simply “Cortex-M with different names”, and the difference is worth stating because it decides the design:

who saves the callee-saved registers
Cortex-Mthe hardware stacks r0-r3, r12, lr, pc, xPSR; the port adds r4-r11
Xtensathe window spill, driven by xtensa-lx-rt’s exception entry
RISC-Vnobody — the port must do all of it

A RISC-V trap saves nothing to the stack. riscv-rt’s entry saves the caller-saved registers into a TrapFrame so a normal Rust handler can run, and the callee-saved ones survive only because that handler is an ordinary function that preserves them. For a context switch they belong to the outgoing task and have to be written down, so this port keeps its own frame: ra, sp and s0–s11.

§The switch still happens in the trap

The lesson from the Xtensa port holds: the decision and the register swap are one step, taken where the context is already captured. A yield raises the machine software interrupt through the CLINT; the handler swaps and returns. Port::COMMITS_SWITCH is true for exactly that reason — the kernel must not move current at the point of the yield, because the registers do not move until the trap is taken.

§Unsafe

Every use is fenced with #[expect(unsafe_code)] and a justification. See UNSAFE.md.

Structs§

Context
The saved machine state of one task.
RiscvPort
The Kairos RISC-V port.

Constants§

CLINT_MSIP
The CLINT’s msip register for hart 0 on QEMU virt.
FRESH_MSTATUS
mstatus for a task that has never run: MPIE set so mret enables interrupts, and MPP = M-mode so it returns to the privilege it left.
SAVED_REGISTERS
How many registers the port itself saves: ra, sp, s0–s11.
VERSION
Crate version, for manifests and logs.

Functions§

clear_switch_request
As raise_switch.
mcycle
Off RISC-V there is no mcycle; the signature is kept so callers type-check on the host.
minstret
As mcycle.
new_task_context⚠
Build the saved context of a task that has never run.
new_task_context_preemptive⚠
Build the saved context of a task that has never run, for the PREEMPTIVE path.
raise_switch
Off RISC-V there is no CLINT and nothing to raise.
switch_context⚠
Off RISC-V this does nothing, so callers keep type-checking on the host.
switch_context_trap⚠
Off RISC-V this does nothing, so callers keep type-checking on the host.