bern-arch 0.4.0

Bern RTOS hardware specific implementation.
Documentation 
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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

//! Memory Protection.

use bern_units::memory_size::Byte;

/// Memory Protection.
///
/// # Implementation
/// In addition to the trait the following features have to be implemented:
///
/// ## Memory Protection Exception
/// A violation of a memory rule will trigger an exception. The exception must
/// call `memory_protection_exception()` to notify the kernel, i.e.:
/// ```ignore
/// extern "Rust" {
///     pub fn memory_protection_exception();
/// }
///
/// #[allow(non_snake_case)]
/// #[exception]
/// fn MemoryManagement() -> () {
///     unsafe {
///         memory_protection_exception();
///     }
/// }
/// ```
///
/// ## Size and Alignment
/// Different memory protection implementation have different requirements in
/// terms of sizes and alignment.
/// A hardware implementation must provide
/// - Alignment structs for all available alignments with naming convention
///   `A<size number><unit prefix (_,K,M,G)>`, i.e.
///   ```ignore
///   #[repr(align(4_096))]
///   pub struct A4K;
///   ```
/// - A macro `alignment_from_size!()` that returns valid alignment for given
///   memory size, i.e.
///   ```ignore
///   #[macro_export]
///   macro_rules! alignment_from_size {
///       (4_096) => { $crate::arch::memory_protection::A4K };
///       ($x:expr) => {
///           compile_error!("Size does not meet alignment requirements from the MPU. \
///           Compatible sizes are: 4KB");
///        };
///   }
///   ```
///
/// - A macro `size_from_raw!()` that returns a valid size type from raw number,
///   i.e.
///   ```ignore
///   #[macro_export]
///   macro_rules! size_from_raw {
///       (4_096) => { $crate::arch::memory_protection::Size::S4K };
///       ($x:expr) => {
///           compile_error!("Size cannot be protected by MPU. \
///           Compatible sizes are: 4KB");
///        };
///   }
///   ```
pub trait IMemoryProtection {
    /// Precalculated memory region configuration.
    type MemoryRegion;

    /// Enable memory protection hardware.
    fn enable_memory_protection();
    /// Disable memory protection hardware.
    fn disable_memory_protection();
    /// Setup and enable one memory region.
    ///
    /// # Example
    /// Protect all flash memory from write access, instruction fetch allowed.
    /// ```ignore
    /// Arch::enable_memory_region(
    ///    0,
    ///    Config {
    ///         addr: 0x0800_0000 as *const _,
    ///         memory: Type::Flash,
    ///         size: Size::S512K,
    ///         access: Access { user: Permission::ReadOnly, system: Permission::ReadOnly },
    ///         executable: true
    /// });
    /// ```
    fn enable_memory_region(region: u8, config: Config);
    /// Disable one memory region.
    fn disable_memory_region(region: u8);
    /// Compile register values from configuration and store in `MemoryRegion`.
    ///
    /// Same as [`Self::enable_memory_region()`] but return the register configuration
    /// instead of applying it to the actual registers.
    fn prepare_memory_region(region: u8, config: Config) -> Self::MemoryRegion;
    /// Compile register values for an unused memory region.
    fn prepare_unused_region(region: u8) -> Self::MemoryRegion;
    /// Apply 3 precompiled memory regions.
    fn apply_regions(memory_regions: &[Self::MemoryRegion; 3]);
    /// Minimal region size that can be protected.
    fn min_region_size() -> Byte;
    /// Returns the number of memory regions.
    fn n_memory_regions() -> u8;
}

/// Access Permission
pub enum Permission {
    /// Access not permitted
    NoAccess,
    /// Can only be read
    ReadOnly,
    /// Full access, can be read and written
    ReadWrite,
}

/// Access configuration
pub struct Access {
    /// Permission in user mode (i.e. tasks)
    pub user: Permission,
    /// Permission in system mode (i.e. ISR, kernel)
    pub system: Permission,
}

/// Type of memory
pub enum Type {
    /// SRAM in the microcontroller
    SramInternal,
    /// SRAM attach to the microcontroller externally
    SramExternal,
    /// Internal flash memory
    Flash,
    /// Microcontroller peripherals
    Peripheral,
}

/// Memory region configurations
pub struct Config {
    /// Region base address
    pub addr: *const usize,
    /// Memory type
    pub memory: Type,
    /// Size of region
    pub size: Byte,
    /// Permissions
    pub access: Access,
    /// Memory region can be used to fetch instructions
    pub executable: bool,
}