sel4_microkit/
lib.rs

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 an optional `heap_size` parameter, whose value can be any expression of type `usize`:
68///
69/// ```rust
70/// #[protection_domain(heap_size = <heap_size_expr: usize>)]
71/// ```
72///
73/// If this parameter is provided, the macro creates a `#[global_allocator]`, backed by a static
74/// heap of the specified size. If this parameter is not specified, no `#[global_allocator]` will be
75/// automatically declared, and, unless one is manually declared, heap allocations will result in a
76/// link-time error.
77pub use sel4_microkit_macros::protection_domain;
78
79#[doc(hidden)]
80#[macro_export]
81macro_rules! declare_protection_domain {
82    {
83        init = $init:expr $(,)?
84    } => {
85        $crate::_private::declare_entrypoint!();
86        $crate::_private::declare_init!($init);
87    };
88    {
89        init = $init:expr,
90        stack_size = $stack_size:expr $(,)?
91    } => {
92        $crate::_private::declare_stack!($stack_size);
93        $crate::_private::declare_entrypoint_with_stack_init!();
94        $crate::_private::declare_init!($init);
95    };
96    {
97        init = $init:expr,
98        $(stack_size = $stack_size:expr,)?
99        heap_size = $heap_size:expr $(,)?
100    } => {
101        $crate::_private::declare_heap!($heap_size);
102        $crate::_private::declare_protection_domain! {
103            init = $init,
104            $(stack_size = $stack_size,)?
105        }
106    };
107}
108
109// For macros
110#[doc(hidden)]
111pub mod _private {
112    pub use crate::heap::_private as heap;
113
114    pub use sel4_runtime_common::{
115        declare_entrypoint, declare_entrypoint_with_stack_init, declare_stack,
116    };
117
118    pub use crate::{declare_heap, declare_init, declare_protection_domain, entry::run_main};
119}
sel4_microkit/lib.rs

sel4_microkit/
lib.rs
