1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

// Licensed under the Apache License, Version 2.0 or the MIT License.
// SPDX-License-Identifier: Apache-2.0 OR MIT
// Copyright Tock Contributors 2022.

//! Components extend the functionality of the Tock kernel through a simple
//! factory method interface.

/// A component encapsulates peripheral-specific and capsule-specific
/// initialization for the Tock OS kernel in a factory method, which reduces
/// repeated code and simplifies the boot sequence.
///
/// The `Component` trait encapsulates all of the initialization and
/// configuration of a kernel extension inside the `finalize()` function call.
/// The `Output` type defines what type this component generates. Note that
/// instantiating a component does not instantiate the underlying `Output` type;
/// instead, the memory is statically allocated and provided as an argument to
/// the `finalize()` method, which correctly initializes the memory to
/// instantiate the `Output` object. If instantiating and initializing the
/// `Output` type requires parameters, these should be passed in the component's
/// `new()` function.
///
/// Using a component is as follows:
///
/// ```rust,ignore
/// let obj = CapsuleComponent::new(configuration, required_hw)
///     .finalize(capsule_component_static!());
/// ```
///
/// All required resources and configuration is passed via the constructor, and
/// all required static memory is defined by the `[name]_component_static!()`
/// macro and passed to the `finalize()` method.
pub trait Component {
    /// An optional type to specify the chip or board specific static memory
    /// that a component needs to setup the output object(s). This is the memory
    /// that `static_buf!()` would normally setup, but generic components cannot
    /// setup static buffers for types which are chip-dependent, so those
    /// buffers have to be passed in manually, and the `StaticInput` type makes
    /// this possible.
    type StaticInput;

    /// The type (e.g., capsule, peripheral) that this implementation of
    /// Component produces via `finalize()`. This is typically a static
    /// reference (`&'static`).
    type Output;

    /// A factory method that returns an instance of the Output type of this
    /// Component implementation. This is used in the boot sequence to
    /// instantiate and initialize part of the Tock kernel. This factory method
    /// may only be called once per Component instance.
    ///
    /// To enable reusable (i.e. can be used on multiple boards with different
    /// microcontrollers) and repeatable (i.e. can be instantiated multiple
    /// times on the same board) components, all components must follow this
    /// convention:
    ///
    /// - All statically allocated memory MUST be passed to `finalize()` via the
    ///   `static_memory` argument. The `finalize()` method MUST NOT use
    ///   `static_init!()` or `static_buf!()` directly. This restriction ensures
    ///   that memory is not aliased if the component is used multiple times.
    fn finalize(self, static_memory: Self::StaticInput) -> Self::Output;
}