Skip to main content

sel4/
lib.rs

1//
2// Copyright 2023, Colias Group, LLC
3//
4// SPDX-License-Identifier: MIT
5//
6
7//! This crate provides straightforward, pure-Rust bindings to the [seL4
8//! API](https://sel4.systems/Info/Docs/seL4-manual-latest.pdf).
9//!
10//! Most items in this crate correspond to types, constants, and functions in `libsel4`. See the
11//! [seL4 manual](https://sel4.systems/Info/Docs/seL4-manual-latest.pdf) for more information about
12//! the seL4 concepts and `libsel4` items references in this crate's documentation.
13//!
14//! This crate's implementation is based on the lower-level [`sel4-sys`](::sel4_sys) crate, which is
15//! generated from the libsel4 headers and interface definition files.
16//!
17//! ### Features
18//!
19//! #### `"state"`
20//!
21//! Functions in the C libsel4 use the thread-local variable `__sel4_ipc_buffer` to obtain a pointer
22//! to the current thread's IPC buffer:
23//!
24//! ```C
25//! extern __thread seL4_IPCBuffer *__sel4_ipc_buffer;
26//! ```
27//!
28//! [libmicrokit](https://github.com/seL4/microkit/tree/main/libmicrokit), which does not support
29//! thread-local storage uses the following snippet to force `__sel4_ipc_buffer` to global rather
30//! than thread-local:
31//!
32//! ```C
33//! #define __thread
34//! #include <sel4/sel4.h>
35//! ```
36//!
37//! For the sake of flexibility and applicability, this crate can be configured to use no state at
38//! all. Users can opt out of state and explicitly pass around references to the active IPC buffer
39//! instead of relying on the implementation to obtain such a reference using thread-local or global
40//! state. Such a paradigm is useful in certain uncommon circumstances, but most users will benefit
41//! from the convenience of an implicit IPC buffer. The `"state"` feature, enabled by default, uses
42//! state to allow one to make seL4 API calls without having to explicitly specify an IPC buffer.
43//!
44//! For the sake of interoperability with C, the state looks something like: `static mut
45//! __sel4_ipc_buffer: *mut IpcBuffer`. If the `"state-exposed"` feature is enabled, it is exposed
46//! with `#![no_mangle]`. If the `"state-extern"` feature is enabled, it is wrapped in an `extern
47//! "C"` block. Whether it is thread-local is determined by the following pseudocode:
48//!
49//! ```rust
50//! cfg_select! {
51//!     all(any(target_thread_local, feature = "tls"), not(feature = "non-thread-local-state")) => {
52//!         // thread-local
53//!     }
54//!     not(feature = "thread-local-state") => {
55//!         // not thread-local
56//!     }
57//!     _ => {
58//!         compile_error!(r#"invalid configuration"#);
59//!     }
60//! }
61//! ```
62//!
63//! The non-thread-local configuration should only be used in cases where the language runtime does
64//! not support thread-local storage. In those cases without thread-local storage where this crate
65//! will only ever run in a single thread, use the `"single-threaded"` feature to enable a more
66//! efficient implementation. Note that enabling the `"single-threaded"` feature in a case where
67//! this crate runs in more than one thread is unsafe.
68//!
69//! At the API level, the `"state"` feature causes [`NoExplicitInvocationContext`] to be an alias
70//! for [`ImplicitInvocationContext`], which implements [`InvocationContext`] by accessing the
71//! thread-local pointer to an IPC buffer. When the `"state"` feature is not enabled,
72//! [`NoExplicitInvocationContext`] is an alias for [`NoInvocationContext`], which does not
73//! implement [`InvocationContext`]. The thread-local IPC buffer pointer is modified and accessed by
74//! [`set_ipc_buffer`], [`with_ipc_buffer`], and [`with_ipc_buffer_mut`]. The lower-level
75//! [`try_with_ipc_buffer_slot`] and [`try_with_ipc_buffer_slot_mut`] are provided as well.
76//!
77//! ### Building
78//!
79//! This crate and its dependencies depend, at build time, on the libsel4 headers. The location of
80//! these headers is provided to this crate at build time by environment variables. If
81//! `SEL4_INCLUDE_DIRS` is set, then its value is interpreted as a colon-separated list of include
82//! paths for the libsel4 headers. Otherwise, if `SEL4_PREFIX` is set, then
83//! `$SEL4_PREFIX/libsel4/include` is used.
84
85#![no_std]
86#![feature(cfg_target_thread_local)]
87#![feature(thread_local)]
88#![allow(unused_features)]
89#![allow(clippy::unit_arg)]
90
91pub use sel4_config::{
92    self as config, sel4_cfg, sel4_cfg_attr, sel4_cfg_bool, sel4_cfg_enum, sel4_cfg_if,
93    sel4_cfg_match, sel4_cfg_str, sel4_cfg_struct, sel4_cfg_usize, sel4_cfg_word,
94    sel4_cfg_wrap_match,
95};
96
97pub use sel4_sys as sys;
98
99mod arch;
100mod bootinfo;
101mod cap_rights;
102mod cnode_cap_data;
103mod const_helpers;
104mod cptr;
105mod error;
106mod fault;
107mod helper_macros;
108mod invocation_context;
109mod invocations;
110mod ipc_buffer;
111mod message_info;
112mod object;
113mod reply_authority;
114mod syscalls;
115mod vspace;
116
117pub mod init_thread;
118
119pub use bootinfo::{
120    BootInfo, BootInfoExtra, BootInfoExtraId, BootInfoExtraIter, BootInfoPtr, UntypedDesc,
121};
122pub use cap_rights::{CapRights, CapRightsBuilder};
123pub use cnode_cap_data::CNodeCapData;
124pub use cptr::{
125    AbsoluteCPtr, CPtr, CPtrBits, CPtrWithDepth, Cap, CapType, HasCPtrWithDepth, cap, cap_type,
126};
127pub use error::{Error, Result};
128pub use fault::*;
129pub use invocation_context::{InvocationContext, NoExplicitInvocationContext, NoInvocationContext};
130pub use invocations::{TcbFlagsBuilder, Time};
131pub use ipc_buffer::IpcBuffer;
132pub use message_info::{MessageInfo, MessageInfoBuilder};
133pub use object::{
134    CapTypeForObject, CapTypeForObjectOfFixedSize, CapTypeForObjectOfVariableSize, ObjectBlueprint,
135    ObjectType,
136};
137pub use reply_authority::{ConveysReplyAuthority, ReplyAuthority};
138pub use syscalls::{Badge, CallWithMRs, FastMessages, NUM_MESSAGE_REGISTERS, RecvWithMRs, r#yield};
139pub use vspace::{
140    CapTypeForFrameObject, CapTypeForFrameObjectOfFixedSize, CapTypeForTranslationTableObject,
141    vspace_levels,
142};
143
144#[sel4_cfg(not(KERNEL_MCS))]
145pub use reply_authority::ImplicitReplyAuthority;
146#[sel4_cfg(not(KERNEL_MCS))]
147pub use syscalls::reply;
148
149#[sel4_cfg(SET_TLS_BASE_SELF)]
150pub use syscalls::set_tls_base;
151
152pub use arch::top_level::*;
153
154pub(crate) use helper_macros::{
155    declare_cap_alias, declare_cap_type, declare_cap_type_for_object,
156    declare_cap_type_for_object_of_fixed_size, declare_cap_type_for_object_of_variable_size,
157    declare_fault_newtype, newtype_methods,
158};
159
160sel4_cfg_if! {
161    if #[sel4_cfg(PRINTING)] {
162        mod printing;
163
164        pub use printing::{DebugWrite, debug_put_char};
165    }
166}
167
168sel4_cfg_if! {
169    if #[sel4_cfg(DEBUG_BUILD)] {
170        mod debug;
171
172        pub use debug::{debug_snapshot, debug_halt};
173    }
174}
175
176sel4_cfg_if! {
177    if #[sel4_cfg(ENABLE_BENCHMARKS)] {
178        mod benchmark;
179
180        pub use benchmark::{
181            benchmark_reset_log,
182            benchmark_finalize_log,
183            benchmark_set_log_buffer,
184        };
185
186        sel4_cfg_if! {
187            if #[sel4_cfg(BENCHMARK_TRACK_UTILISATION)] {
188                pub use benchmark::{
189                    benchmark_get_thread_utilisation,
190                    benchmark_reset_thread_utilisation,
191                };
192
193                #[sel4_cfg(DEBUG_BUILD)]
194                pub use benchmark::{
195                    benchmark_dump_all_thread_utilisation,
196                    benchmark_reset_all_thread_utilisation,
197                };
198            }
199        }
200    }
201}
202
203#[cfg(feature = "state")]
204mod state;
205
206#[cfg(feature = "state")]
207pub use state::{
208    ImplicitInvocationContext, ipc_buffer_is_thread_local, set_ipc_buffer,
209    try_with_ipc_buffer_slot, try_with_ipc_buffer_slot_mut, with_ipc_buffer, with_ipc_buffer_mut,
210};
211
212/// Corresponds to `seL4_Word`.
213pub type Word = sys::seL4_Word;
214
215/// The size of [`Word`] in bits.
216pub const WORD_SIZE: usize = sel4_cfg_usize!(WORD_SIZE);
217
218#[doc(hidden)]
219pub mod _private {
220    #[sel4_config::sel4_cfg(PRINTING)]
221    pub use super::printing::_private as printing;
222}