Skip to main content

sel4_root_task/
lib.rs

1//
2// Copyright 2023, Colias Group, LLC
3//
4// SPDX-License-Identifier: BSD-2-Clause
5//
6
7//! A runtime for root tasks.
8//!
9//! This crate defines an entrypoint at `_start` that performs the following Rust language runtime
10//! and [`libsel4`](sel4) initialization:
11//! - Set up the stack
12//! - Initialize thread-local storage (using stack memory)
13//! - Set up exception handling
14//! - Set the seL4 IPC buffer for `libsel4` (using [`sel4::set_ipc_buffer`])
15//! - Run C-style constructors (from `__init_array_start`/`__init_array_end`)
16//!
17//! After initialization, the entrypoint calls the root task main function, which must be declared
18//! with [`#[root_task]`](root_task). For example:
19//!
20//! ```rust
21//! #[root_task]
22//! fn main(bootinfo: &sel4::BootInfo) -> ! {
23//!     todo!()
24//! }
25//! ```
26//!
27//! Building root tasks using this crate does not require a custom linker script when using `LLD`.
28//! In particular, this crate is tested with the `LLD` binary that ships with `rustc` (`rust-lld`).
29//! Using a GNU linker will likely require a custom linker script.
30
31#![no_std]
32#![feature(linkage)]
33
34pub use sel4_panicking_env::abort;
35
36#[doc(inline)]
37pub use sel4_panicking as panicking;
38
39mod entry;
40mod heap;
41mod printing;
42mod termination;
43
44pub use heap::set_global_allocator_mutex_notification;
45pub use termination::{Never, Termination};
46
47#[sel4::sel4_cfg(PRINTING)]
48pub use printing::{debug_print, debug_println};
49
50/// Declares a function to be the root task's main function.
51///
52/// For example:
53///
54/// ```rust
55/// #[root_task]
56/// fn main(bootinfo: &sel4::BootInfo) -> ! {
57///     todo!()
58/// }
59/// ```
60///
61/// The main function have a signature of the form:
62///
63/// ```rust
64/// fn<T: Termination>(&sel4::BootInfoPtr) -> T
65/// ```
66///
67/// (See [`Termination`])
68///
69/// This macro takes two optional parameters, whose values can be any expression of type `usize`:
70///
71/// ```rust
72/// #[root_task(
73///     stack_size = <stack_size_expr: usize>,
74///     heap_size = <heap_size_expr: usize>,
75/// )]
76/// ```
77///
78/// - `stack_size`: Declares the size of the initial thread's stack, in bytes. Note that this
79///   includes space for thread-local storage. If absent, [`DEFAULT_STACK_SIZE`] will be used.
80/// - `heap_size`: Creates a `#[global_allocator]`, backed by a static heap of the specified size.
81///   If this parameter is not specified, no `#[global_allocator]` will be automatically declared,
82///   and, unless one is manually declared, heap allocations will result in a link-time error.
83///
84/// Note that, if both parameters are provided, they must appear in the order above.
85pub use sel4_root_task_macros::root_task;
86
87#[doc(hidden)]
88#[macro_export]
89macro_rules! declare_root_task {
90    {
91        main = $main:expr $(,)?
92    } => {
93        $crate::_private::declare_root_task! {
94            main = $main,
95            stack_size = $crate::_private::DEFAULT_STACK_SIZE,
96        }
97    };
98    {
99        main = $main:expr,
100        stack_size = $stack_size:expr $(,)?
101    } => {
102        $crate::_private::declare_main!($main);
103        $crate::_private::declare_stack!($stack_size);
104    };
105    {
106        main = $main:expr,
107        $(stack_size = $stack_size:expr,)?
108        heap_size = $heap_size:expr $(,)?
109    } => {
110        $crate::_private::declare_heap!($heap_size);
111        $crate::_private::declare_root_task! {
112            main = $main,
113            $(stack_size = $stack_size,)?
114        }
115    };
116}
117
118/// The default stack size used by [`#[root_task]`](crate::root_task).
119pub const DEFAULT_STACK_SIZE: usize = 1024
120    * if cfg!(panic = "unwind") && cfg!(debug_assertions) {
121        128
122    } else {
123        64
124    };
125
126// For macros
127#[doc(hidden)]
128pub mod _private {
129    pub use sel4::BootInfoPtr;
130    pub use sel4_runtime_common::declare_stack;
131
132    pub use crate::heap::_private as heap;
133
134    pub use crate::{
135        DEFAULT_STACK_SIZE, declare_heap, declare_main, declare_root_task, entry::run_main,
136    };
137}