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}