sel4_root_task/
lib.rs

Help
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#![feature(never_type)]
34
35pub use sel4_panicking_env::abort;
36
37#[doc(inline)]
38pub use sel4_panicking as panicking;
39
40mod entry;
41mod heap;
42mod printing;
43mod termination;
44
45pub use heap::set_global_allocator_mutex_notification;
46pub use termination::{Never, Termination};
47
48#[sel4::sel4_cfg(PRINTING)]
49pub use printing::{debug_print, debug_println};
50
51/// Declares a function to be the root task's main function.
52///
53/// For example:
54///
55/// ```rust
56/// #[root_task]
57/// fn main(bootinfo: &sel4::BootInfo) -> ! {
58///     todo!()
59/// }
60/// ```
61///
62/// The main function have a signature of the form:
63///
64/// ```rust
65/// fn<T: Termination>(&sel4::BootInfoPtr) -> T
66/// ```
67///
68/// (See [`Termination`])
69///
70/// This macro takes two optional parameters, whose values can be any expression of type `usize`:
71///
72/// ```rust
73/// #[root_task(
74///     stack_size = <stack_size_expr: usize>,
75///     heap_size = <heap_size_expr: usize>,
76/// )]
77/// ```
78///
79/// - `stack_size`: Declares the size of the initial thread's stack, in bytes. Note that this
80///   includes space for thread-local storage. If absent, [`DEFAULT_STACK_SIZE`] will be used.
81/// - `heap_size`: Creates a `#[global_allocator]`, backed by a static heap of the specified size.
82///   If this parameter is not specified, no `#[global_allocator]` will be automatically declared,
83///   and, unless one is manually declared, heap allocations will result in a link-time error.
84///
85/// Note that, if both parameters are provided, they must appear in the order above.
86pub use sel4_root_task_macros::root_task;
87
88#[doc(hidden)]
89#[macro_export]
90macro_rules! declare_root_task {
91    {
92        main = $main:expr $(,)?
93    } => {
94        $crate::_private::declare_root_task! {
95            main = $main,
96            stack_size = $crate::_private::DEFAULT_STACK_SIZE,
97        }
98    };
99    {
100        main = $main:expr,
101        stack_size = $stack_size:expr $(,)?
102    } => {
103        $crate::_private::declare_main!($main);
104        $crate::_private::declare_stack!($stack_size);
105    };
106    {
107        main = $main:expr,
108        $(stack_size = $stack_size:expr,)?
109        heap_size = $heap_size:expr $(,)?
110    } => {
111        $crate::_private::declare_heap!($heap_size);
112        $crate::_private::declare_root_task! {
113            main = $main,
114            $(stack_size = $stack_size,)?
115        }
116    };
117}
118
119/// The default stack size used by [`#[root_task]`](crate::root_task).
120pub const DEFAULT_STACK_SIZE: usize = 1024
121    * if cfg!(panic = "unwind") && cfg!(debug_assertions) {
122        128
123    } else {
124        64
125    };
126
127// For macros
128#[doc(hidden)]
129pub mod _private {
130    pub use sel4::BootInfoPtr;
131    pub use sel4_runtime_common::declare_stack;
132
133    pub use crate::heap::_private as heap;
134
135    pub use crate::{
136        declare_heap, declare_main, declare_root_task, entry::run_main, DEFAULT_STACK_SIZE,
137    };
138}
sel4_root_task/lib.rs

sel4_root_task/
lib.rs
