Trait CortexMVariant

pub trait CortexMVariant {
    const GENERIC_ISR: unsafe extern "C" fn();
    const SYSTICK_HANDLER: unsafe extern "C" fn();
    const SVC_HANDLER: unsafe extern "C" fn();
    const HARD_FAULT_HANDLER: unsafe extern "C" fn();

    // Required methods
    unsafe fn switch_to_user(
        user_stack: *const usize,
        process_regs: &mut [usize; 8],
    ) -> *const usize;
    unsafe fn print_cortexm_state(writer: &mut dyn Write);
}

Trait to encapsulate differences in between Cortex-M variants

This trait contains functions and other associated data (constants) which differs in between different Cortex-M architecture variants (e.g. Cortex-M0, Cortex-M4, etc.). It is not designed to be implemented by an instantiable type and passed around as a runtime-accessible object, but is to be used as a well-defined collection of functions and data to be exposed to architecture-dependent code paths. Hence, implementations can use an enum without variants to implement this trait.

The fact that some functions are proper trait functions, while others are exposed via associated constants is necessitated by the associated const functions being #\[naked\]. To wrap these functions in proper trait functions would require these trait functions to also be #\[naked\] to avoid generating a function prologue and epilogue, and we’d have to call the respective backing function from within an asm! block. The associated constants allow us to simply reference any function in scope and export it through the provided CortexMVariant trait infrastructure.

Required Associated Constants

const GENERIC_ISR: unsafe extern "C" fn()

All ISRs not caught by a more specific handler are caught by this handler. This must ensure the interrupt is disabled (per Tock’s interrupt model) and then as quickly as possible resume the main thread (i.e. leave the interrupt context). The interrupt will be marked as pending and handled when the scheduler checks if there are any pending interrupts.

If the ISR is called while an app is running, this will switch control to the kernel.

const SYSTICK_HANDLER: unsafe extern "C" fn()

The systick_handler is called when the systick interrupt occurs, signaling that an application executed for longer than its timeslice. This interrupt handler is no longer responsible for signaling to the kernel thread that an interrupt has occurred, but is slightly more efficient than the generic_isr handler on account of not needing to mark the interrupt as pending.

const SVC_HANDLER: unsafe extern "C" fn()

This is called after a svc instruction, both when switching to userspace and when userspace makes a system call.

const HARD_FAULT_HANDLER: unsafe extern "C" fn()

Hard fault handler.

Required Methods

unsafe fn switch_to_user( user_stack: *const usize, process_regs: &mut [usize; 8], ) -> *const usize

Assembly function called from UserspaceKernelBoundary to switch to an an application. This handles storing and restoring application state before and after the switch.

unsafe fn print_cortexm_state(writer: &mut dyn Write)

Format and display architecture-specific state useful for debugging.

This is generally used after a panic!() to aid debugging.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors