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 decides | how the outgoing task stops | |
|---|---|---|
| voluntary | the task, through pend_switch | it waits on its own permit |
| preemptive | the tick thread | the 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§
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
indexwas handed the run permit. - init_
task - Give task
indexa 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
corefrom now on. - set_
scheduler - Install the function the port calls to pick the next task.
- stale_
grants - How many slots
init_taskfound 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).