kernel/platform/chip.rs
1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! Interfaces for implementing microcontrollers in Tock.
6
7use crate::platform::mpu;
8use crate::syscall;
9use core::fmt::Write;
10
11/// Interface for individual MCUs.
12///
13/// The trait defines chip-specific properties of Tock's operation. These
14/// include whether and which memory protection mechanism and scheduler_timer to
15/// use, how to switch between the kernel and userland applications, and how to
16/// handle hardware events.
17///
18/// Each microcontroller should define a struct and implement this trait.
19pub trait Chip {
20 /// The particular Memory Protection Unit (MPU) for this chip.
21 type MPU: mpu::MPU;
22
23 /// The implementation of the interface between userspace and the kernel for
24 /// this specific chip. Likely this is architecture specific, but individual
25 /// chips may have various custom requirements.
26 type UserspaceKernelBoundary: syscall::UserspaceKernelBoundary;
27
28 /// The kernel calls this function to tell the chip to check for all pending
29 /// interrupts and to correctly dispatch them to the peripheral drivers for
30 /// the chip.
31 ///
32 /// This function should loop internally until all interrupts have been
33 /// handled. It is ok, however, if an interrupt occurs after the last check
34 /// but before this function returns. The kernel will handle this edge case.
35 fn service_pending_interrupts(&self);
36
37 /// Ask the chip to check if there are any pending interrupts.
38 fn has_pending_interrupts(&self) -> bool;
39
40 /// Returns a reference to the implementation for the MPU on this chip.
41 fn mpu(&self) -> &Self::MPU;
42
43 /// Returns a reference to the implementation for the interface between
44 /// userspace and kernelspace.
45 fn userspace_kernel_boundary(&self) -> &Self::UserspaceKernelBoundary;
46
47 /// Called when there is nothing left for the chip to do and it should enter
48 /// a low power sleep state. This low power sleep state should allow
49 /// interrupts to still be active so that the next interrupt event wakes the
50 /// chip and resumes the scheduler.
51 fn sleep(&self);
52
53 /// Run a function in an atomic state, which means that interrupts are
54 /// disabled so that an interrupt will not fire during the passed in
55 /// function's execution.
56 unsafe fn atomic<F, R>(&self, f: F) -> R
57 where
58 F: FnOnce() -> R;
59
60 /// Print out chip state (system registers) to a supplied
61 /// writer. This does not print out the execution context
62 /// (data registers), as this depends on how they are stored;
63 /// that is implemented by
64 /// `syscall::UserspaceKernelBoundary::print_context`.
65 /// This also does not print out a process memory state,
66 /// that is implemented by `process::Process::print_memory_map`.
67 /// The MPU state is printed by the MPU's implementation of
68 /// the Display trait.
69 /// Used by panic.
70 unsafe fn print_state(&self, writer: &mut dyn Write);
71}
72
73/// Interface for handling interrupts on a hardware chip.
74///
75/// Each board must construct an implementation of this trait to handle specific
76/// interrupts. When an interrupt (identified by number) has triggered and
77/// should be handled, the implementation of this trait will be called with the
78/// interrupt number. The implementation can then handle the interrupt, or
79/// return `false` to signify that it does not know how to handle the interrupt.
80///
81/// This functionality is given this `InterruptService` interface so that
82/// multiple objects can be chained together to handle interrupts for a chip.
83/// This is useful for code organization and removing the need for duplication
84/// when multiple variations of a specific microcontroller exist. Then a shared,
85/// base object can handle most interrupts, and variation-specific objects can
86/// handle the variation-specific interrupts.
87///
88/// To simplify structuring the Rust code when using `InterruptService`, the
89/// interrupt number should be passed "top-down". That is, an interrupt to be
90/// handled will first be passed to the `InterruptService` object that is most
91/// specific. If that object cannot handle the interrupt, then it should
92/// maintain a reference to the second most specific object, and return by
93/// calling to that object to handle the interrupt. This continues until the
94/// base object handles the interrupt or decides that the chip does not know how
95/// to handle the interrupt. For example, consider a `nRF52840` chip that
96/// depends on the `nRF52` crate. If both have specific interrupts they know how
97/// to handle, the flow would look like:
98///
99/// ```ignore
100/// +---->nrf52840_peripherals
101/// | |
102/// | |
103/// | v
104/// kernel-->nrf52 nrf52_peripherals
105/// ```
106/// where the kernel instructs the `nrf52` crate to handle interrupts, and if
107/// there is an interrupt ready then that interrupt is passed through the
108/// InterruptService objects until something can service it.
109pub trait InterruptService {
110 /// Service an interrupt, if supported by this chip. If this interrupt
111 /// number is not supported, return false.
112 unsafe fn service_interrupt(&self, interrupt: u32) -> bool;
113}
114
115/// Generic operations that clock-like things are expected to support.
116pub trait ClockInterface {
117 fn is_enabled(&self) -> bool;
118 fn enable(&self);
119 fn disable(&self);
120}
121
122/// Helper struct for interfaces that expect clocks, but have no clock control.
123pub struct NoClockControl {}
124impl ClockInterface for NoClockControl {
125 fn is_enabled(&self) -> bool {
126 true
127 }
128 fn enable(&self) {}
129 fn disable(&self) {}
130}
131
132/// Instance of NoClockControl for things that need references to
133/// `ClockInterface` objects.
134pub const NO_CLOCK_CONTROL: NoClockControl = NoClockControl {};