Skip to main content

Crate rusty_rtos_port_host

Crate rusty_rtos_port_host 

Source
Expand description

The Kairos host port: a task gets a real stack from the operating system.

§Why this exists

The Kairos kernel is stackless by design. A blocking call keeps its locals in the TCB and answers Wait::Blocked, meaning “call again when this task next runs” — which is what lets one kernel run the conformance corpus on a host, on a simulator and on three different chips without a line of assembly in between.

A task written in C cannot work that way. vTaskDelay has to return later, on the line after, with its locals intact, and locals in C live on a stack. So the C ABI needs a port that supplies one — and until this crate there were only two kinds: three bare-metal ports, which need an emulator or a chip, and the sim port, which is stackless. That is why K6’s kill test ran on QEMU Cortex-M3 before it ran on a host: there was nowhere on a host for a C task to keep its locals.

§The shape is FreeRTOS’s own

portable/ThirdParty/GCC/Posix runs one pthread per task and lets exactly one of them run at a time; the MSVC-MinGW port does the same with Win32 threads. This is that: one OS thread per task, a single run permit, and a tick thread standing in for the timer interrupt. The OS supplies the stacks and switches them; we supply the policy.

§The two ways a switch happens

who decideshow the outgoing task stops
voluntarythe task, through pend_switchit waits on its own permit
preemptivethe tick threadthe OS freezes the thread where it stands

The voluntary path is all a cooperative kernel needs. The preemptive path is not optional: integer.c and flop.c in the standard demos never block and never yield — with configUSE_PREEMPTION set they rely on being taken off the CPU — so a host port without it starves every task below them and their neighbours’ checkers report failure. A cooperative host port would pass the demos that block and quietly fail the ones that do not, which is the worst of both.

§Freezing a thread is safe here, and the reason is narrow

Suspending an arbitrary thread is a famous way to deadlock: freeze it inside malloc and the next thread that allocates waits forever.

It is safe here because of the ORDER in Ticker::interrupt: the tick thread takes the critical-section lock first, and every kernel call and every heap call is inside that lock. A thread that is not holding it is not inside the kernel and not inside our heap, so there is no lock for it to be holding when it freezes.

What that argument does NOT cover is a lock we do not own: the C runtime’s allocator, or stdout. A task that calls printf or the system malloc directly can still be frozen inside one. The demo task files do neither — they allocate through pvPortMalloc, which is the Kairos heap behind our own critical section. A cell that prints from a task must do it inside Port::enter_critical.

§Unsafe

The workspace denies unsafe_code. Every use here is fenced with #[expect(unsafe_code)] and a justification, and they are all of one kind: freezing and thawing an OS thread. See UNSAFE.md.

Structs§

HostPort
The host Port.
Ticker
The tick thread’s own handle on the system.

Constants§

MAX_TASKS
The most tasks a host cell may have.
NO_TASK
Nobody is running.
PREEMPTIVE
Whether this platform can take a task off the CPU that does not cooperate.
VERSION
Crate version, for manifests and logs.

Statics§

CURRENT
Which task index currently holds the run permit.

Functions§

core
The kernel core the run permit currently stands for.
critical_depth
How deep the calling thread is inside critical sections, and whether it is the holder at all.
grants_to
How many times slot index was handed the run permit.
init_task
Give task index a thread, parked until it is granted the permit.
my_index
Which task the CALLING THREAD is, if it is a task thread at all.
orphaned_threads
How many task threads have been orphaned by a slot being reused.
pend_switch
portYIELD(): ask the scheduler who is next and hand the CPU over.
release_task
Hand a task slot’s OS handle back. For a cell that deletes tasks.
set_core
Make the run permit stand for kernel core core from now on.
set_scheduler
Install the function the port calls to pick the next task.
stale_grants
How many slots init_task found holding a stale grant or freeze.
start_first_task
Start the first task and never come back.
switch_pending
Is a context switch outstanding but not yet taken? (ICSR.PENDSVSET.)
thread_of
The OS thread backing task index, or zero if it has none yet.
tick_stats
(ticks, wanted a switch, could not freeze, actually switched).

Type Aliases§

Scheduler
What the port calls to choose the next task.
TickFn
What the tick thread calls once per period.