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//! { list_slots_for(8, 0, LISTS) }, // items + markers, rounded
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
56#[cfg(test)]
57#[allow(
58 clippy::unwrap_used,
59 clippy::expect_used,
60 clippy::panic,
61 clippy::indexing_slicing,
62 clippy::arithmetic_side_effects
63)]
64mod smp_tests;
65
66pub use kernel::{Kernel, MAX_CORES, Stall, StartHandles, TaskState};
67// The macro-generated `build` names this bound, so it has to be
68// reachable from `$crate` at the call site.
69pub use name::{NAME_CAPACITY, Name};
70pub use queue::{Blocked, Kind as QueueKind, Position, Ready, Wait};
71pub use rusty_rtos_core::hooks::TickHook;
72
73/// Crate version, for manifests and logs.
74pub const VERSION: &str = env!("CARGO_PKG_VERSION");
75
76/// List items a kernel needs for `tasks` tasks: a state item and an event
77/// item each, exactly the two `ListItem_t`s in a C `TCB_t`.
78#[must_use]
79#[inline]
80pub const fn items_for(tasks: usize, timers: usize) -> usize {
81 tasks.saturating_mul(2).saturating_add(timers)
82}
83
84/// Slots the kernel's list arena needs.
85///
86/// `ListsOf`'s first const parameter is the SLOT count, not the item count:
87/// each list's end marker is a node in the same array — which is what C
88/// FreeRTOS does, `xListEnd` being a `ListItem_t` inside `List_t` — and the
89/// total is rounded up to a power of two so every link can be followed with
90/// a mask instead of a bounds check.
91///
92/// Measured on `bench/list-cost`, that shape took the list from **35.84 to
93/// 18.80 instructions per operation**, against C `list.c`'s 22.32 at `-O2`
94/// -- and, at the 32-bit width every Kairos target actually has, **23.75
95/// against 33.42**, which is the ratio that matters.
96///
97/// [`items_for`] keeps its own meaning — two list items per task plus one
98/// per timer — because that is a true number and worth being able to say.
99/// This wraps it.
100#[must_use]
101#[inline]
102pub const fn list_slots_for(tasks: usize, timers: usize, lists: usize) -> usize {
103 rusty_rtos_core::list::slots_for(items_for(tasks, timers), lists)
104}
105
106/// Lists a kernel needs: one ready list per priority, the two delayed
107/// lists, the pending-ready list and the suspended list, plus the two
108/// event lists (`xTasksWaitingToSend`, `xTasksWaitingToReceive`) of every
109/// queue and the one (`xTasksWaitingForBits`) of every event group.
110#[must_use]
111#[inline]
112pub const fn lists_for(max_priorities: u8, queues: usize, groups: usize) -> usize {
113 (max_priorities as usize)
114 .saturating_add(OVERHEAD_LISTS)
115 .saturating_add(queues.saturating_mul(2))
116 .saturating_add(groups)
117}
118
119/// The number of fixed lists that are not a ready list: the two delayed
120/// lists, pending-ready and suspended, and the two timer lists.
121pub const OVERHEAD_LISTS: usize = 6;
122
123/// The tasks a kernel creates for itself whatever the application asks
124/// for: `prvIdleTask` and the timer daemon. A system that declares `n`
125/// tasks needs room for `n + OVERHEAD_TASKS`.
126pub const OVERHEAD_TASKS: usize = 2;
127
128/// The names a scenario or a port wants in scope.
129pub mod prelude {
130 pub use crate::kernel::{Kernel, StartHandles, TaskState};
131 pub use crate::name::Name;
132 pub use crate::queue::{Blocked, Position, Ready, Wait};
133 pub use crate::{items_for, list_slots_for, lists_for};
134 pub use rusty_rtos_core::prelude::*;
135}