Expand description
rusty_rtos_demo-core — the FreeRTOS standard demo tasks, remade.
FreeRTOS/Demo/Common/Minimal is the corpus every FreeRTOS port has
been judged against for twenty years: each file starts a handful of
tasks that torture one part of the kernel and then answers one question,
xAre...StillRunning(). Kairos remakes them because they are the
conformance suite, and runs them on the deterministic sim port so that
every scheduling decision the Rust kernel makes can be diffed, line for
line, against the C kernel making the same decisions
(umbrella ORACLES.md).
§What a scenario is here
A C demo task is a function with an infinite loop that blocks. This
crate cannot block — the kernel is forbid(unsafe) and has no stacks to
switch — so each task is a state machine whose step runs one C
statement. runner::Runner steps whichever task the kernel says is
current, which makes the sequence of kernel calls, and therefore the
trace, identical to the C’s.
§The corpus
| scenario | C file | what it tortures |
|---|---|---|
dynamic | dynamic.c | suspend, resume, priority set, suspend-all |
abortdelay | AbortDelay.c | xTaskAbortDelay against every way a task can block |
pollq | PollQ.c | a queue polled from both ends, never blocking |
blockq | BlockQ.c | blocking sends and receives, three task pairs |
semtest | semtest.c | two binary semaphores guarding a shared variable |
countsem | countsem.c | counting semaphores, driven to both ends |
recmutex | recmutex.c | a recursive mutex and its priority inheritance |
blocktim | blocktim.c | block times and xTaskDelayUntil, to the tick |
qpeek | QPeek.c | peeking, and the order four priorities wake in |
genqtest | GenQTest.c | both queue ends, and priority inheritance |
qoverwrite | QueueOverwrite.c | a queue of one, and the first interrupt half |
qsetpoll | QueueSetPolling.c | a queue set polled by a task, written by an interrupt |
intsem | IntSemTest.c | semaphores and a mutex given from an interrupt |
sbint | StreamBufferInterrupt.c | a string streamed from the tick, byte by byte |
streambuffer | StreamBufferDemo.c | the whole stream-buffer face: two echo pairs, the head-and-tail tests, trigger levels |
tasknotify | TaskNotify.c | every notification method, and a notify to a suspended task |
timerdemo | TimerDemo.c | software timers, checked against the tick they fire on |
| eventgroups | EventGroupsDemo.c | event bits, a rendezvous, and the deferred-interrupt path |
| mbamp | MessageBufferAMP.c | message buffers across a replaced send-completed seam |
| death | death.c | tasks created and deleted while the scheduler runs |
Plus pollq_typed and pollq_async, which are PollQ rewritten
against the Rust face and as async fn bodies, and diffed against
PollQ’s own C oracle trace – because the point is that the same
trace comes out, so the face is proved to cost nothing rather than
asserted to.
Every one of them is in kairos conform --all, and nothing is excluded
from it.
Re-exports§
pub use pins::Digest;pub use pins::PIN_TICKS;pub use pins::Pin;pub use pins::pins;pub use runner::Body;pub use runner::Runner;pub use runner::SimKernel;pub use runner::Step;pub use runner::Verdict;pub use trace::LineTrace;
Modules§
- abortdelay
AbortDelay—xTaskAbortDelayagainst every blocking surface.- apisweep
ApiSweep— six public APIs that no upstream demo reaches.- blockq
BlockQ— blocking sends and receives, three task pairs.- blocktim
blocktim— block times, honoured to the tick.- countsem
countsem— counting semaphores, driven to both ends of their range.- death
death— the scenario that deletes tasks.- dynamic
dynamic— the first scenario of the conformance corpus.- eventgroups
EventGroupsDemo— four tasks around one event group, and an interrupt around another.- genqtest
GenQTest— send-to-front, send-to-back, peek, and priority inheritance.- intqueue
IntQueue— two queues, six tasks and two interrupt handlers.- intsem
IntSemTest— semaphores given from an interrupt, mutexes shared with one.- mbamp
MessageBufferAMP— one message buffer per “core”, and a send that wakes the reader the long way round.- messagebuffer
MessageBufferDemo— the message buffer, which is a stream buffer that keeps its lengths.- pins
- The pinned corpus: what the C kernel printed, in one place.
- pollq
PollQ— a queue polled from both ends, never blocking.- pollq_
async PollQa third time, with the task bodies asasync fn(K2.2).- pollq_
typed PollQ, written against the Rust face instead of the C-shaped one.- prelude
- The names a scenario or a firmware wants in scope.
- qoverwrite
QueueOverwrite— a queue of one, written to whether or not it is full.- qpeek
QPeek— four priorities peeking at one queue, and the order they wake in.- qset
QueueSet— three queues in one set, written by a task and an interrupt.- qsetpoll
QueueSetPolling— a queue set polled by a task, written by an interrupt.- recmutex
recmutex— a recursive mutex, and the priority inheritance around it.- runner
- The sim runner: what plays the part the pthreads play in the C harness.
- sbint
StreamBufferInterrupt— a string sent from the tick, read a byte at a time.- semtest
semtest— two binary semaphores, four tasks, one shared variable each.- streambuffer
StreamBufferDemo— the stream buffer tortured from every side.- tasknotify
TaskNotify— every notification method, checked against itself.- timerdemo
TimerDemo— software timers, checked against the tick they fire on.- trace
- The trace sink: one line per kernel event, in the contract’s format.
Enums§
- Scenario
- The scenarios this crate can run.
Constants§
- DEFAULT_
STEP_ LIMIT - The limit for the C harness’s default run length.
- VERSION
- Crate version, for manifests and logs.
Functions§
- step_
limit_ for - The runner’s safety net: the most steps a scenario may take before the run is called a runaway.