Macro cortex_m_rt::exception

macro_rules! exception {
    (* , $handler:expr) => { ... };
    (HardFault, $handler:expr) => { ... };
    ($Name:ident, $handler:expr,state: $State:ty = $initial_state:expr) => { ... };
    ($Name:ident, $handler:expr) => { ... };
}

Macro to set or override a processor core exception handler

NOTE This macro must be invoked from an accessible module, ideally from the root of the crate.

Syntax

exception!(
    // Name of the exception
    $Name:ident,

    // Path to the exception handler (a function)
    $handler:expr,

    // Optional, state preserved across invocations of the handler
    state: $State:ty = $initial_state:expr,
);

where $Name can be one of:

• *
• NonMaskableInt
• HardFault
• MemoryManagement (a)
• BusFault (a)
• UsageFault (a)
• SecureFault (b)
• SVCall
• DebugMonitor (a)
• PendSV
• SysTick

(a) Not available on Cortex-M0 variants (thumbv6m-none-eabi)

(b) Only available on ARMv8-M

Usage

exception!(HardFault, ..) sets the hard fault handler. The handler must have signature fn(&ExceptionFrame) -> !. This handler is not allowed to return as that can cause undefined behavior. It's mandatory to set the HardFault handler somewhere in the dependency graph of an application.

exception!(*, ..) sets the default handler. All exceptions which have not been assigned a handler will be serviced by this handler. This handler must have signature fn(irqn: i16). irqn is the IRQ number (cf. CMSIS); irqn will be a negative number when the handler is servicing a core exception; irqn will be a positive number when the handler is servicing a device specific exception (interrupt). It's mandatory to set the default handler somewhere in the dependency graph of an application.

exception!($Exception, ..) overrides the default handler for $Exception. All exceptions, except for HardFault, can be assigned some $State.

Examples

• Setting the HardFault handler

#[macro_use(exception)]
extern crate cortex_m_rt as rt;

use rt::ExceptionFrame;

exception!(HardFault, hard_fault);

fn hard_fault(ef: &ExceptionFrame) -> ! {
    // prints the exception frame as a panic message
    panic!("{:#?}", ef);
}

• Setting the default handler

#[macro_use(exception)]
extern crate cortex_m_rt as rt;

exception!(*, default_handler);

fn default_handler(irqn: i16) {
    println!("IRQn = {}", irqn);
}

• Overriding the SysTick handler

#[macro_use(exception)]
extern crate cortex_m_rt as rt;

exception!(SysTick, sys_tick, state: u32 = 0);

fn sys_tick(count: &mut u32) {
    println!("count = {}", *count);

    *count += 1;
}