kernel/platform/

chip.rs

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

//! Interfaces for implementing microcontrollers in Tock.

use crate::platform::mpu;
use crate::syscall;
use core::fmt::Write;

/// Interface for individual MCUs.
///
/// The trait defines chip-specific properties of Tock's operation. These
/// include whether and which memory protection mechanism and scheduler_timer to
/// use, how to switch between the kernel and userland applications, and how to
/// handle hardware events.
///
/// Each microcontroller should define a struct and implement this trait.
pub trait Chip {
    /// The particular Memory Protection Unit (MPU) for this chip.
    type MPU: mpu::MPU;

    /// Provider to query the currently running thread ID.
    type ThreadIdProvider: ThreadIdProvider;

    /// The implementation of the interface between userspace and the kernel for
    /// this specific chip. Likely this is architecture specific, but individual
    /// chips may have various custom requirements.
    type UserspaceKernelBoundary: syscall::UserspaceKernelBoundary;

    /// The kernel calls this function to tell the chip to check for all pending
    /// interrupts and to correctly dispatch them to the peripheral drivers for
    /// the chip.
    ///
    /// This function should loop internally until all interrupts have been
    /// handled. It is ok, however, if an interrupt occurs after the last check
    /// but before this function returns. The kernel will handle this edge case.
    fn service_pending_interrupts(&self);

    /// Ask the chip to check if there are any pending interrupts.
    fn has_pending_interrupts(&self) -> bool;

    /// Returns a reference to the implementation for the MPU on this chip.
    fn mpu(&self) -> &Self::MPU;

    /// Returns a reference to the implementation for the interface between
    /// userspace and kernelspace.
    fn userspace_kernel_boundary(&self) -> &Self::UserspaceKernelBoundary;

    /// Called when there is nothing left for the chip to do and it should enter
    /// a low power sleep state. This low power sleep state should allow
    /// interrupts to still be active so that the next interrupt event wakes the
    /// chip and resumes the scheduler.
    fn sleep(&self);

    /// Run a function in an atomic state w.r.t. to the current core. This
    /// means that interrupts are disabled so that an interrupt will not fire
    /// during the passed in function's execution, but *does not* make any
    /// guarantees about memory consistency on a multi-core system.
    unsafe fn with_interrupts_disabled<F, R>(&self, f: F) -> R
    where
        F: FnOnce() -> R;

    /// Print out chip state (system registers) to a supplied
    /// writer. This does not print out the execution context
    /// (data registers), as this depends on how they are stored;
    /// that is implemented by
    /// `syscall::UserspaceKernelBoundary::print_context`.
    /// This also does not print out a process memory state,
    /// that is implemented by `process::Process::print_memory_map`.
    /// The MPU state is printed by the MPU's implementation of
    /// the Display trait.
    /// Used by panic.
    unsafe fn print_state(&self, writer: &mut dyn Write);
}

/// Interface for retrieving the currently executing thread.
///
/// This is used to enforce correctness with shared state that has access
/// restrictions (e.g., only a single thread can access a specific value).
///
/// Many embedded platforms are single-core and only permit a single execution
/// thread at a time. However, interrupts can typically occur at any time, and
/// the execution of an interrupt service routine (ISR) constitutes a second
/// thread. Implementations of this trait must be able to differentiate between
/// at minimum the main thread of execution and an ISR execution, but may also
/// consider multiple execution threads if available on a particular device.
///
/// # Safety
///
/// This thread is marked as `unsafe` as implementation must guarantee its
/// correctness. Users of this trait are allowed to make soundness guarantees
/// based on the implementation being correct. Failing to provide a correct
/// implementation can lead to unsound behavior. By implementing this trait,
/// providers are guaranteeing the implementations are always correct for the
/// given hardware platform.
pub unsafe trait ThreadIdProvider {
    /// Return a unique ID for the currently executing thread.
    ///
    /// The unique ID must fit in a `usize` and must be unique and consistent
    /// for the currently running thread. The actual value is opaque and there
    /// is no assumption about the meaning of the assigned IDs. Implementations
    /// are allowed to arbitrarily assign IDs to threads as long as the IDs are
    /// unique and consistent.
    fn running_thread_id() -> usize;
}

/// Interface for handling interrupts on a hardware chip.
///
/// Each board must construct an implementation of this trait to handle specific
/// interrupts. When an interrupt (identified by number) has triggered and
/// should be handled, the implementation of this trait will be called with the
/// interrupt number. The implementation can then handle the interrupt, or
/// return `false` to signify that it does not know how to handle the interrupt.
///
/// This functionality is given this `InterruptService` interface so that
/// multiple objects can be chained together to handle interrupts for a chip.
/// This is useful for code organization and removing the need for duplication
/// when multiple variations of a specific microcontroller exist. Then a shared,
/// base object can handle most interrupts, and variation-specific objects can
/// handle the variation-specific interrupts.
///
/// To simplify structuring the Rust code when using `InterruptService`, the
/// interrupt number should be passed "top-down". That is, an interrupt to be
/// handled will first be passed to the `InterruptService` object that is most
/// specific. If that object cannot handle the interrupt, then it should
/// maintain a reference to the second most specific object, and return by
/// calling to that object to handle the interrupt. This continues until the
/// base object handles the interrupt or decides that the chip does not know how
/// to handle the interrupt. For example, consider a `nRF52840` chip that
/// depends on the `nRF52` crate. If both have specific interrupts they know how
/// to handle, the flow would look like:
///
/// ```ignore
///           +---->nrf52840_peripherals
///           |        |
///           |        |
///           |        v
/// kernel-->nrf52     nrf52_peripherals
/// ```
/// where the kernel instructs the `nrf52` crate to handle interrupts, and if
/// there is an interrupt ready then that interrupt is passed through the
/// InterruptService objects until something can service it.
pub trait InterruptService {
    /// Service an interrupt, if supported by this chip. If this interrupt
    /// number is not supported, return false.
    unsafe fn service_interrupt(&self, interrupt: u32) -> bool;
}

/// A default implementation of `InterruptService` that handles nothing and returns `false`.
impl InterruptService for () {
    unsafe fn service_interrupt(&self, _interrupt: u32) -> bool {
        false
    }
}

/// Generic operations that clock-like things are expected to support.
pub trait ClockInterface {
    fn is_enabled(&self) -> bool;
    fn enable(&self);
    fn disable(&self);
}

/// Helper struct for interfaces that expect clocks, but have no clock control.
pub struct NoClockControl {}
impl ClockInterface for NoClockControl {
    fn is_enabled(&self) -> bool {
        true
    }
    fn enable(&self) {}
    fn disable(&self) {}
}

/// Instance of NoClockControl for things that need references to
/// `ClockInterface` objects.
pub const NO_CLOCK_CONTROL: NoClockControl = NoClockControl {};