Skip to main content

rusty_rtos_demo_core/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2#![forbid(unsafe_code)]
3//! `rusty_rtos_demo-core` — the FreeRTOS standard demo tasks, remade.
4//!
5//! `FreeRTOS/Demo/Common/Minimal` is the corpus every FreeRTOS port has
6//! been judged against for twenty years: each file starts a handful of
7//! tasks that torture one part of the kernel and then answers one question,
8//! `xAre...StillRunning()`. Kairos remakes them because they are the
9//! conformance suite, and runs them on the deterministic sim port so that
10//! every scheduling decision the Rust kernel makes can be diffed, line for
11//! line, against the C kernel making the same decisions
12//! (umbrella `ORACLES.md`).
13//!
14//! # What a scenario is here
15//!
16//! A C demo task is a function with an infinite loop that blocks. This
17//! crate cannot block — the kernel is `forbid(unsafe)` and has no stacks to
18//! switch — so each task is a state machine whose `step` runs one C
19//! statement. [`runner::Runner`] steps whichever task the kernel says is
20//! current, which makes the sequence of kernel calls, and therefore the
21//! trace, identical to the C's.
22//!
23//! # The corpus
24//!
25//! | scenario | C file | what it tortures |
26//! |---|---|---|
27//! | [`dynamic`] | `dynamic.c` | suspend, resume, priority set, suspend-all |
28//! | [`abortdelay`] | `AbortDelay.c` | `xTaskAbortDelay` against every way a task can block |
29//! | [`pollq`] | `PollQ.c` | a queue polled from both ends, never blocking |
30//! | [`blockq`] | `BlockQ.c` | blocking sends and receives, three task pairs |
31//! | [`semtest`] | `semtest.c` | two binary semaphores guarding a shared variable |
32//! | [`countsem`] | `countsem.c` | counting semaphores, driven to both ends |
33//! | [`recmutex`] | `recmutex.c` | a recursive mutex and its priority inheritance |
34//! | [`blocktim`] | `blocktim.c` | block times and `xTaskDelayUntil`, to the tick |
35//! | [`qpeek`] | `QPeek.c` | peeking, and the order four priorities wake in |
36//! | [`genqtest`] | `GenQTest.c` | both queue ends, and priority inheritance |
37//! | [`qoverwrite`] | `QueueOverwrite.c` | a queue of one, and the first interrupt half |
38//! | [`qsetpoll`] | `QueueSetPolling.c` | a queue set polled by a task, written by an interrupt |
39//! | [`intsem`] | `IntSemTest.c` | semaphores and a mutex given from an interrupt |
40//! | [`sbint`] | `StreamBufferInterrupt.c` | a string streamed from the tick, byte by byte |
41//! | [`streambuffer`] | `StreamBufferDemo.c` | the whole stream-buffer face: two echo pairs, the head-and-tail tests, trigger levels |
42//! | [`tasknotify`] | `TaskNotify.c` | every notification method, and a notify to a suspended task |
43//! | [`timerdemo`] | `TimerDemo.c` | software timers, checked against the tick they fire on |
44//!
45//! | [`eventgroups`] | `EventGroupsDemo.c` | event bits, a rendezvous, and the deferred-interrupt path |
46//! | [`mbamp`] | `MessageBufferAMP.c` | message buffers across a replaced send-completed seam |
47//! | [`death`] | `death.c` | tasks created and deleted while the scheduler runs |
48//!
49//! Plus [`pollq_typed`] and [`pollq_async`], which are `PollQ` rewritten
50//! against the Rust face and as `async fn` bodies, and diffed against
51//! `PollQ`'s own C oracle trace -- because the point is that the *same*
52//! trace comes out, so the face is proved to cost nothing rather than
53//! asserted to.
54//!
55//! Every one of them is in `kairos conform --all`, and nothing is excluded
56//! from it.
57
58pub mod abortdelay;
59pub mod apisweep;
60pub mod blockq;
61pub mod blocktim;
62pub mod countsem;
63pub mod death;
64pub mod dynamic;
65pub mod eventgroups;
66pub mod genqtest;
67pub mod intqueue;
68pub mod intsem;
69pub mod mbamp;
70pub mod messagebuffer;
71pub mod pins;
72pub mod pollq;
73pub mod pollq_async;
74pub mod pollq_typed;
75pub mod qoverwrite;
76pub mod qpeek;
77pub mod qset;
78pub mod qsetpoll;
79pub mod recmutex;
80pub mod runner;
81pub mod sbint;
82pub mod semtest;
83#[cfg(feature = "smp")]
84pub mod smp;
85pub mod streambuffer;
86pub mod tasknotify;
87pub mod timerdemo;
88pub mod trace;
89
90pub use pins::{Digest, PIN_TICKS, Pin, pins};
91pub use runner::{Body, Runner, Shared, SimKernel, Step, Verdict};
92pub use trace::LineTrace;
93
94/// Crate version, for manifests and logs.
95pub const VERSION: &str = env!("CARGO_PKG_VERSION");
96
97/// The runner's safety net: the most steps a scenario may take before the
98/// run is called a runaway.
99///
100/// The first C oracle run taught us to want one — an unbounded scenario
101/// wrote an 8 GB trace before anybody noticed — so the Rust side refuses
102/// to be the second lesson.
103///
104/// It has to scale with the run, because a step is a C statement and some
105/// scenarios spend thousands of them per tick without making a kernel call
106/// at all: `semtest`'s guarded loop counts to 0xfff between one semaphore
107/// take and the next, which is about four thousand steps a tick. A fixed
108/// limit stopped it at tick 12,429 of a 100,000-tick run and called the
109/// result a failure, which is exactly the kind of lie a guard is supposed
110/// to prevent.
111#[must_use]
112pub const fn step_limit_for(max_ticks: u64) -> u64 {
113    max_ticks.saturating_mul(100_000).saturating_add(10_000_000)
114}
115
116/// The limit for the C harness's default run length.
117pub const DEFAULT_STEP_LIMIT: u64 = step_limit_for(2000);
118
119/// The scenarios this crate can run.
120// Deliberately exhaustive: adding a scenario should fail to compile
121// everywhere it has to be wired, starting with the binary's `match`.
122#[derive(Debug, Clone, Copy, PartialEq, Eq)]
123pub enum Scenario {
124    /// `dynamic.c`.
125    Dynamic,
126    /// `PollQ.c`.
127    PollQ,
128    /// `BlockQ.c`.
129    BlockQ,
130    /// `semtest.c`.
131    SemTest,
132    /// `countsem.c`.
133    CountSem,
134    /// `recmutex.c`.
135    RecMutex,
136    /// `blocktim.c`.
137    BlockTim,
138    /// `AbortDelay.c`.
139    AbortDelay,
140    /// `death.c`.
141    Death,
142    /// `QPeek.c`.
143    QPeek,
144    /// `GenQTest.c`.
145    GenQTest,
146    /// `QueueOverwrite.c`.
147    QOverwrite,
148    /// `QueueSetPolling.c`.
149    QSetPoll,
150    /// `IntSemTest.c`.
151    IntSem,
152    /// `StreamBufferInterrupt.c`.
153    SbInt,
154    /// `StreamBufferDemo.c`.
155    StreamBuffer,
156    /// `TaskNotify.c`.
157    TaskNotify,
158    /// `TimerDemo.c`.
159    TimerDemo,
160    /// `EventGroupsDemo.c`.
161    EventGroups,
162    /// `MessageBufferAMP.c`.
163    MbAmp,
164    /// `MessageBufferDemo.c`.
165    MessageBuffer,
166    /// `IntQueue.c`.
167    IntQueue,
168    /// `QueueSet.c`.
169    QueueSet,
170    /// `ApiSweep`, which is ours rather than a port.
171    ApiSweep,
172    /// `PollQ.c` against the Rust face — diffed against `PollQ`'s own
173    /// C oracle trace, because the face is supposed to cost nothing.
174    PollQTyped,
175    /// `PollQ.c` with `async fn` task bodies (K2.2), diffed against the
176    /// same trace for the same reason.
177    PollQAsync,
178}
179
180impl Scenario {
181    /// The scenario's name, as the trace's verdict line prints it.
182    #[must_use]
183    pub const fn name(self) -> &'static str {
184        match self {
185            Self::Dynamic => "dynamic",
186            Self::PollQ => "PollQ",
187            Self::BlockQ => "BlockQ",
188            Self::SemTest => "semtest",
189            Self::CountSem => "countsem",
190            Self::RecMutex => "recmutex",
191            Self::BlockTim => "blocktim",
192            Self::AbortDelay => "AbortDelay",
193            Self::Death => "death",
194            Self::QPeek => "QPeek",
195            Self::GenQTest => "GenQTest",
196            Self::QOverwrite => "QueueOverwrite",
197            Self::QSetPoll => "QueueSetPolling",
198            Self::IntSem => "IntSemTest",
199            Self::SbInt => "StreamBufferInterrupt",
200            Self::StreamBuffer => "StreamBufferDemo",
201            Self::TaskNotify => "TaskNotify",
202            Self::TimerDemo => "TimerDemo",
203            Self::EventGroups => "EventGroupsDemo",
204            Self::MbAmp => "MessageBufferAMP",
205            Self::MessageBuffer => "MessageBufferDemo",
206            Self::IntQueue => "IntQueue",
207            Self::QueueSet => "QueueSet",
208            Self::ApiSweep => "ApiSweep",
209            Self::PollQTyped => "PollQ-typed",
210            Self::PollQAsync => "PollQ-async",
211        }
212    }
213
214    /// Look a scenario up by name.
215    #[must_use]
216    pub fn from_name(name: &str) -> Option<Self> {
217        match name {
218            "dynamic" => Some(Self::Dynamic),
219            "PollQ" => Some(Self::PollQ),
220            "BlockQ" => Some(Self::BlockQ),
221            "semtest" => Some(Self::SemTest),
222            "countsem" => Some(Self::CountSem),
223            "recmutex" => Some(Self::RecMutex),
224            "blocktim" => Some(Self::BlockTim),
225            "AbortDelay" => Some(Self::AbortDelay),
226            "death" => Some(Self::Death),
227            "QPeek" => Some(Self::QPeek),
228            "GenQTest" => Some(Self::GenQTest),
229            "QueueOverwrite" => Some(Self::QOverwrite),
230            "QueueSetPolling" => Some(Self::QSetPoll),
231            "IntSemTest" => Some(Self::IntSem),
232            "StreamBufferInterrupt" => Some(Self::SbInt),
233            "StreamBufferDemo" => Some(Self::StreamBuffer),
234            "TaskNotify" => Some(Self::TaskNotify),
235            "TimerDemo" => Some(Self::TimerDemo),
236            "EventGroupsDemo" => Some(Self::EventGroups),
237            "MessageBufferAMP" => Some(Self::MbAmp),
238            "MessageBufferDemo" => Some(Self::MessageBuffer),
239            "IntQueue" => Some(Self::IntQueue),
240            "QueueSet" => Some(Self::QueueSet),
241            "ApiSweep" => Some(Self::ApiSweep),
242            "PollQ-typed" => Some(Self::PollQTyped),
243            "PollQ-async" => Some(Self::PollQAsync),
244            _ => None,
245        }
246    }
247
248    /// Every scenario, for a runner that wants to sweep the corpus.
249    #[must_use]
250    pub const fn all() -> &'static [Self] {
251        &[
252            Self::Dynamic,
253            Self::AbortDelay,
254            Self::PollQ,
255            Self::BlockQ,
256            Self::SemTest,
257            Self::CountSem,
258            Self::RecMutex,
259            Self::BlockTim,
260            Self::QPeek,
261            Self::GenQTest,
262            Self::QOverwrite,
263            Self::QSetPoll,
264            Self::IntSem,
265            Self::SbInt,
266            Self::StreamBuffer,
267            Self::TaskNotify,
268            Self::TimerDemo,
269            Self::EventGroups,
270            Self::MbAmp,
271            Self::PollQTyped,
272            Self::PollQAsync,
273        ]
274    }
275}
276
277/// The names a scenario or a firmware wants in scope.
278pub mod prelude {
279    pub use crate::runner::{Body, Runner, Shared, SimKernel, Step, Verdict};
280    pub use crate::trace::LineTrace;
281    pub use crate::{DEFAULT_STEP_LIMIT, Scenario};
282    // Every scenario's `start` answers this, so a firmware that holds them
283    // in a table has to be able to name it without depending on
284    // `rusty_rtos_core` itself.
285    pub use rusty_rtos_core::error::{Error, Result};
286}