Skip to main content

Crate rusty_rtos_demo_core

Crate rusty_rtos_demo_core 

Source
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

scenarioC filewhat it tortures
dynamicdynamic.csuspend, resume, priority set, suspend-all
abortdelayAbortDelay.cxTaskAbortDelay against every way a task can block
pollqPollQ.ca queue polled from both ends, never blocking
blockqBlockQ.cblocking sends and receives, three task pairs
semtestsemtest.ctwo binary semaphores guarding a shared variable
countsemcountsem.ccounting semaphores, driven to both ends
recmutexrecmutex.ca recursive mutex and its priority inheritance
blocktimblocktim.cblock times and xTaskDelayUntil, to the tick
qpeekQPeek.cpeeking, and the order four priorities wake in
genqtestGenQTest.cboth queue ends, and priority inheritance
qoverwriteQueueOverwrite.ca queue of one, and the first interrupt half
qsetpollQueueSetPolling.ca queue set polled by a task, written by an interrupt
intsemIntSemTest.csemaphores and a mutex given from an interrupt
sbintStreamBufferInterrupt.ca string streamed from the tick, byte by byte
streambufferStreamBufferDemo.cthe whole stream-buffer face: two echo pairs, the head-and-tail tests, trigger levels
tasknotifyTaskNotify.cevery notification method, and a notify to a suspended task
timerdemoTimerDemo.csoftware 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::Shared;
pub use runner::SimKernel;
pub use runner::Step;
pub use runner::Verdict;
pub use trace::LineTrace;

Modules§

abortdelay
AbortDelay — xTaskAbortDelay against 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
PollQ a third time, with the task bodies as async 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.