rusty_rtos_kernel_core/lib.rs
1#![cfg_attr(not(feature = "std"), no_std)]
2#![forbid(unsafe_code)]
3//! `rusty_rtos_kernel-core` — the FreeRTOS scheduler remade in safe Rust.
4//!
5//! This crate is `tasks.c` and `queue.c` as a state machine over indices:
6//! the ready lists, the two delayed lists, the pending-ready and suspended
7//! lists, the tick, the context switch, and the queue with its two event
8//! lists. It owns no CPU (that is [`rusty_rtos_core::port::Port`]), no
9//! memory (that is `Heap`), and no stack — which is the point.
10//!
11//! # Why there is no context switch here
12//!
13//! A context switch is a stack swap, and a stack swap is `unsafe`. The
14//! family's law is that `unsafe` lives only in `rusty_rtos_port-<arch>`
15//! (mission plan §2.1), so this crate never touches one. What it does
16//! instead is decide *which task should run*: [`Kernel::switch_context`]
17//! moves `current` and fires the same `TASK_SWITCHED_OUT` / `_IN` pair the
18//! C kernel fires. On silicon the port acts on that decision with its
19//! fenced assembly; on the sim the runner acts on it by calling the next
20//! task's step function. Both see the same decisions in the same order,
21//! which is what the conformance diff checks.
22//!
23//! # Geometry is const, not heap
24//!
25//! FreeRTOS allocates TCBs and queue storage from a heap. Kairos puts them
26//! in arenas sized at compile time, so the kernel has no allocator at all
27//! and a firmware's RAM is a number you can read off the type:
28//!
29//! ```ignore
30//! type K = Kernel<PosixDemoConfig, SimPort, SimTrace,
31//! 16, // TASKS
32//! { items_for(16) }, // two list items per task
33//! { lists_for(7, 8) }, // ready + 4 + two per queue
34//! 8, // QUEUES
35//! 64>; // shared queue slots
36//! ```
37//!
38//! The four helpers below compute the derived numbers, and
39//! [`Kernel::new`] refuses a geometry that does not add up rather than
40//! indexing out of bounds later.
41//!
42//! `forbid(unsafe)`. `no_std` (+ `alloc`). Every arithmetic operation is
43//! checked, wrapping or saturating by name; every slice access is a `get`.
44
45pub mod events;
46pub mod kernel;
47pub mod name;
48#[cfg(kani)]
49pub mod proofs;
50pub mod queue;
51pub mod stream;
52pub mod system;
53pub mod timer;
54pub mod typed;
55
56pub use kernel::{Kernel, Stall, StartHandles, TaskState};
57// The macro-generated `build` names this bound, so it has to be
58// reachable from `$crate` at the call site.
59pub use name::{NAME_CAPACITY, Name};
60pub use queue::{Blocked, Kind as QueueKind, Position, Ready, Wait};
61pub use rusty_rtos_core::hooks::TickHook;
62
63/// Crate version, for manifests and logs.
64pub const VERSION: &str = env!("CARGO_PKG_VERSION");
65
66/// List items a kernel needs for `tasks` tasks: a state item and an event
67/// item each, exactly the two `ListItem_t`s in a C `TCB_t`.
68#[must_use]
69pub const fn items_for(tasks: usize, timers: usize) -> usize {
70 tasks.saturating_mul(2).saturating_add(timers)
71}
72
73/// Lists a kernel needs: one ready list per priority, the two delayed
74/// lists, the pending-ready list and the suspended list, plus the two
75/// event lists (`xTasksWaitingToSend`, `xTasksWaitingToReceive`) of every
76/// queue and the one (`xTasksWaitingForBits`) of every event group.
77#[must_use]
78pub const fn lists_for(max_priorities: u8, queues: usize, groups: usize) -> usize {
79 (max_priorities as usize)
80 .saturating_add(OVERHEAD_LISTS)
81 .saturating_add(queues.saturating_mul(2))
82 .saturating_add(groups)
83}
84
85/// The number of fixed lists that are not a ready list: the two delayed
86/// lists, pending-ready and suspended, and the two timer lists.
87pub const OVERHEAD_LISTS: usize = 6;
88
89/// The tasks a kernel creates for itself whatever the application asks
90/// for: `prvIdleTask` and the timer daemon. A system that declares `n`
91/// tasks needs room for `n + OVERHEAD_TASKS`.
92pub const OVERHEAD_TASKS: usize = 2;
93
94/// The names a scenario or a port wants in scope.
95pub mod prelude {
96 pub use crate::kernel::{Kernel, StartHandles, TaskState};
97 pub use crate::name::Name;
98 pub use crate::queue::{Blocked, Position, Ready, Wait};
99 pub use crate::{items_for, lists_for};
100 pub use rusty_rtos_core::prelude::*;
101}