sel4_microkit/
lib.rs

Help
1//
2// Copyright 2023, Colias Group, LLC
3//
4// SPDX-License-Identifier: BSD-2-Clause
5//
6
7#![no_std]
8
9//! A foundation for pure-Rust [seL4 Microkit](https://github.com/seL4/microkit) protection domains.
10//!
11//! See the [seL4 Microkit manual](https://github.com/seL4/microkit/blob/main/docs/manual.md) for
12//! non-Rust-specific documentation about the seL4 Microkit.
13//!
14//! See [the demo](https://github.com/seL4/rust-microkit-demo) for a concrete example of
15//! this crate in action.
16//!
17//! This crate depends, at build time, on the libsel4 headers. It requires that either
18//! `$SEL4_INCLUDE_DIRS` contains a colon-separated list of include paths for the libsel4 headers,
19//! or that `$SEL4_PREFIX` is set, in which case `$SEL4_PREFIX/libsel4/include` is used.
20//!
21//! The `microkit` tool expects protection domain binaries to expose a few symbols. All protection
22//! domains must contain the symbol `__sel4_ipc_buffer_obj`. Furthermore, for protection domains
23//! with memory regions, the `microkit` tool injects the addresses of these memory regions at build
24//! time by patching designated symbols. The
25//! [`*-sel4-microkit{,-minimal}.json`](https://github.com/seL4/rust-sel4/tree/main/support/targets)
26//! `rustc` target specs distributed as part of the [rust-sel4
27//! project](https://github.com/seL4/rust-sel4) provide `__sel4_ipc_buffer_obj`, and the
28//! [`memory_region_symbol`] macro provides a conveneint way to declare memory region address
29//! symbols.
30//!
31//! Use the [`protection_domain`] macro to declare the initialization function, stack size, and,
32//! optionally, heap and heap size.
33
34#[cfg(feature = "alloc")]
35extern crate alloc;
36
37pub use sel4_microkit_base::*;
38
39mod entry;
40mod heap;
41mod printing;
42
43pub mod panicking;
44
45#[sel4::sel4_cfg(PRINTING)]
46pub use printing::{debug_print, debug_println};
47
48/// Declares a function to be the the protection domain's initialization function.
49///
50/// For example:
51///
52/// ```rust
53/// #[protection_domain]
54/// fn init() -> impl Handler {
55///     todo!()
56/// }
57/// ```
58///
59/// The initialization function have a signature of the form:
60///
61/// ```rust
62/// fn<T: Handler>() -> T
63/// ```
64///
65/// (See [`Handler`])
66///
67/// This macro takes two optional parameters, whose values can be any expression of type `usize`:
68///
69/// ```rust
70/// #[protection_domain(
71///     stack_size = <stack_size_expr: usize>,
72///     heap_size = <heap_size_expr: usize>,
73/// )]
74/// ```
75///
76/// - `stack_size`: Declares the size of the protection domain's stack, in bytes. Note that this
77///   includes space for thread-local storage. If absent, [`DEFAULT_STACK_SIZE`] will be used.
78/// - `heap_size`: Creates a `#[global_allocator]`, backed by a static heap of the specified size.
79///   If this parameter is not specified, no `#[global_allocator]` will be automatically declared,
80///   and, unless one is manually declared, heap allocations will result in a link-time error.
81///
82/// Note that, if both parameters are provided, they must appear in the order above.
83pub use sel4_microkit_macros::protection_domain;
84
85#[doc(hidden)]
86#[macro_export]
87macro_rules! declare_protection_domain {
88    {
89        init = $init:expr $(,)?
90    } => {
91        $crate::_private::declare_protection_domain! {
92            init = $init,
93            stack_size = $crate::_private::DEFAULT_STACK_SIZE,
94        }
95    };
96    {
97        init = $init:expr,
98        stack_size = $stack_size:expr $(,)?
99    } => {
100        $crate::_private::declare_init!($init);
101        $crate::_private::declare_stack!($stack_size);
102    };
103    {
104        init = $init:expr,
105        $(stack_size = $stack_size:expr,)?
106        heap_size = $heap_size:expr $(,)?
107    } => {
108        $crate::_private::declare_heap!($heap_size);
109        $crate::_private::declare_protection_domain! {
110            init = $init,
111            $(stack_size = $stack_size,)?
112        }
113    };
114}
115
116/// The default stack size used by [`#[protection_domain]`](crate::protection_domain).
117pub const DEFAULT_STACK_SIZE: usize = 1024
118    * if cfg!(panic = "unwind") && cfg!(debug_assertions) {
119        128
120    } else {
121        64
122    };
123
124// For macros
125#[doc(hidden)]
126pub mod _private {
127    pub use sel4_runtime_common::declare_stack;
128
129    pub use crate::heap::_private as heap;
130
131    pub use crate::{
132        declare_heap, declare_init, declare_protection_domain, entry::run_main, DEFAULT_STACK_SIZE,
133    };
134}
sel4_microkit/lib.rs

sel4_microkit/
lib.rs
