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_init!($init);
86    };
87    {
88        init = $init:expr,
89        heap_size = $heap_size:expr $(,)?
90    } => {
91        $crate::_private::declare_init!($init);
92        $crate::_private::declare_heap!($heap_size);
93    };
94}
95
96// For macros
97#[doc(hidden)]
98pub mod _private {
99    pub use crate::heap::_private as heap;
100
101    pub use crate::{declare_heap, declare_init, declare_protection_domain, entry::run_main};
102}
sel4_microkit/lib.rs

sel4_microkit/
lib.rs
