kernel/lib.rs
1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! Core Tock Kernel
6//!
7//! The kernel crate implements the core features of Tock as well as shared
8//! code that many chips, capsules, and boards use. It also holds the Hardware
9//! Interface Layer (HIL) definitions.
10//!
11//! Most `unsafe` code is in this kernel crate.
12//!
13//!
14//! ## Core Kernel Visibility
15//!
16//! As the root crate in the Tock operating system, this crate serves multiple
17//! purposes:
18//!
19//! 1. It includes the logic for the core kernel, including process management,
20//! grants, scheduling, etc.
21//!
22//! 2. It includes important interfaces for hardware and other device
23//! abstractions. These are generally in the HIL and platform folders.
24//!
25//! 3. It includes utility functions used elsewhere in the kernel, generally by
26//! multiple different crates such that it makes sense to have shared
27//! implementations in the core kernel crate.
28//!
29//! Because of these different features of the core kernel, managing visibility
30//! of the various objects and functions is a bit tricky. In general, the kernel
31//! crate only exposes what it absolutely needs to. However, there are three
32//! cases where resources in this crate _must_ be exposed.
33//!
34//! 1. The shared utility functions and structs must be exposed. These are
35//! marked `pub` and are used by many other kernel crates.
36//!
37//! Some utility objects and abstractions, however, expose memory unsafe
38//! behavior. These are marked as `unsafe`, and require an `unsafe` block to
39//! use them. One example of this is `StaticRef` which is used for accessing
40//! memory-mapped I/O registers. Since accessing the addresses through just a
41//! memory address is potentially very unsafe, instantiating a `StaticRef`
42//! requires an `unsafe` block.
43//!
44//! 2. The core kernel types generally have to be exposed as other layers of the
45//! OS need to use them. However, generally only a very small interface is
46//! exposed, and using that interface cannot compromise the overall system or
47//! the core kernel. These functions are also marked `pub`. For example, the
48//! `ProcessBuffer` abstraction must be exposed to capsules to use shared memory
49//! between a process and the kernel. However, the constructor is not public,
50//! and the API exposed to capsules is very limited and confined by the Rust
51//! type system. The constructor and other sensitive interfaces are
52//! restricted to use only inside the kernel crate and are marked
53//! `pub(crate)`.
54//!
55//! In some cases, more sensitive core kernel interfaces must be exposed. For
56//! example, the kernel exposes a function for starting the main scheduling
57//! loop in the kernel. Since board crates must be able to start this loop
58//! after all initialization is finished, the kernel loop function must be
59//! exposed and marked `pub`. However, this interface is not generally safe
60//! to use, since starting the loop a second time would compromise the
61//! stability of the overall system. It's also not necessarily memory unsafe
62//! to call the start loop function again, so we do not mark it as `unsafe`.
63//! Instead, we require that the caller hold a `Capability` to call the
64//! public but sensitive functions. More information is in `capabilities.rs`.
65//! This allows the kernel crate to still expose functions as public while
66//! restricting their use. Another example of this is the `Grant`
67//! constructor, which must be called outside of the core kernel, but should
68//! not be called except during the board setup.
69//!
70//! 3. Certain internal core kernel interfaces must also be exposed. These are
71//! needed for extensions of the core kernel that happen to be implemented in
72//! crates outside of the kernel crate. For example, additional
73//! implementations of `Process` may live outside of the kernel crate. To
74//! successfully implement a new `Process` requires access to certain
75//! in-core-kernel APIs, and these must be marked `pub` so that outside
76//! crates can access them.
77//!
78//! These interfaces are highly sensitive, so again we require the caller
79//! hold a Capability to call them. This helps restrict their use and makes
80//! it very clear that calling them requires special permissions.
81//! Additionally, to differentiate these interfaces, which are for external
82//! extensions of core kernel functionality, from the other public but
83//! sensitive interfaces (item 2 above), we append the name `_external` to
84//! the function name.
85//!
86//! One note is that there are currently very few extensions to the core
87//! kernel that live outside of the kernel crate. That means we have not
88//! necessarily created `_extern` functions for all the interfaces needed for
89//! this use case. It is likely we will have to create new interfaces as new
90//! use cases are discovered.
91
92// `clippy::missing_safety_doc`: Our goal is to apply this in all of Tock,
93// but as of September 2026 we are starting with the kernel crate.
94#![deny(clippy::missing_safety_doc)]
95// `clippy::undocumented_unsafe_blocks`: Our goal is to apply this in all of
96// Tock, but as of September 2026 we are starting with the kernel crate.
97#![deny(clippy::undocumented_unsafe_blocks)]
98#![warn(unreachable_pub)]
99#![no_std]
100
101/// Kernel major version.
102///
103/// This is compiled with the crate to enable for checking of compatibility with
104/// loaded apps. Major, minor and patch version constants are updated during a
105/// release.
106pub const KERNEL_MAJOR_VERSION: u16 = 2;
107/// Kernel minor version.
108///
109/// This is compiled with the crate to enable for checking of compatibility with
110/// loaded apps.
111pub const KERNEL_MINOR_VERSION: u16 = 4;
112/// Kernel patch version.
113pub const KERNEL_PATCH_VERSION: u16 = 0;
114/// Kernel in-development version counter.
115///
116/// Use to distinguish development kernels from release kernels, and can be used
117/// to have applications or tools depend on in-development kernel features that
118/// are not yet included in any release.
119///
120/// A value of `0` indicates that this a release, of the version indicated by
121/// [`KERNEL_MAJOR_VERSION`], [`KERNEL_MINOR_VERSION`] and
122/// [`KERNEL_PATCH_VERSION`].
123///
124/// A value other than `0` indicates that this is a development revision, before
125/// (older than) the next release described by [`KERNEL_MAJOR_VERSION`],
126/// [`KERNEL_MINOR_VERSION`] and [`KERNEL_PATCH_VERSION`].
127pub const KERNEL_PRERELEASE_VERSION: u16 = 1;
128
129/// Tock kernel attributes structure for version information.
130#[repr(C)]
131struct TockAttributesKernelVersion {
132 major: u16,
133 minor: u16,
134 patch: u16,
135 prerelease: u16,
136 tlv_type: u16,
137 tlv_len: u16,
138}
139
140/// Create a data structure which follows the Tock Kernel Attributes format
141/// for specifying the version of the Tock kernel.
142///
143/// More information on kernel attributes is
144/// [here](https://book.tockos.org/doc/kernel_attributes.html).
145///
146/// This is inserted into a specific section (`.tock.attr.kernel_version`) that
147/// the linker script includes at the correct location to be included in the
148/// attributes.
149///
150/// This section attribute is only applied when targeting bare-metal
151/// (`target_os = "none"`). Host builds (e.g. tests, clippy, doc) use object
152/// formats (Mach-O, PE, ...) that reject a bare section name like this,
153/// yielding errors such as: `mach-o section specifier requires a segment and
154/// section separated by a comma`.
155#[cfg_attr(target_os = "none", unsafe(link_section = ".tock.attr.kernel_version"))]
156#[used]
157static TOCK_ATTRIBUTES_KERNEL_VERSION: TockAttributesKernelVersion = TockAttributesKernelVersion {
158 major: KERNEL_MAJOR_VERSION,
159 minor: KERNEL_MINOR_VERSION,
160 patch: KERNEL_PATCH_VERSION,
161 prerelease: KERNEL_PRERELEASE_VERSION,
162 tlv_type: 0x0103,
163 tlv_len: 8,
164};
165
166pub mod capabilities;
167pub mod collections;
168pub mod component;
169pub mod debug;
170pub mod deferred_call;
171pub mod dynamic_binary_storage;
172pub mod errorcode;
173pub mod grant;
174pub mod hil;
175pub mod introspection;
176pub mod ipc;
177pub mod platform;
178pub mod process;
179pub mod process_checker;
180pub mod processbuffer;
181pub mod scheduler;
182pub mod storage_permissions;
183pub mod syscall;
184pub mod upcall;
185pub mod utilities;
186
187mod config;
188mod kernel;
189mod memop;
190mod process_array;
191mod process_binary;
192mod process_loading;
193mod process_policies;
194mod process_printer;
195mod process_standard;
196mod syscall_driver;
197
198// Core resources exposed as `kernel::Type`.
199pub use crate::errorcode::ErrorCode;
200pub use crate::kernel::Kernel;
201pub use crate::process::ProcessId;
202pub use crate::scheduler::Scheduler;