Attribute Macro cortex_m_rt::exception

#[exception]

Attribute to declare an exception handler

IMPORTANT: If you are using Rust 1.30 this attribute must be used on reachable items (i.e. there must be no private modules between the item and the root of the crate); if the item is in the root of the crate you’ll be fine. This reachability restriction doesn’t apply to Rust 1.31 and newer releases.

Syntax

#[exception]
fn SysTick() {
    // ..
}

where the name of the function must be one of:

• DefaultHandler
• 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] unsafe fn HardFault(.. sets the hard fault handler. The handler must have signature unsafe fn(&ExceptionFrame) -> !. This handler is not allowed to return as that can cause undefined behavior.

#[exception] unsafe fn DefaultHandler(.. sets the default handler. All exceptions which have not been assigned a handler will be serviced by this handler. This handler must have signature unsafe fn(irqn: i16) [-> !]. irqn is the IRQ number (See 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).

#[exception] fn Name(.. overrides the default handler for the exception with the given Name. These handlers must have signature [unsafe] fn() [-> !]. When overriding these other exception it’s possible to add state to them by declaring static mut variables at the beginning of the body of the function. These variables will be safe to access from the function body.

Properties

Exception handlers can only be called by the hardware. Other parts of the program can’t refer to the exception handlers, much less invoke them as if they were functions.

static mut variables declared within an exception handler are safe to access and can be used to preserve state across invocations of the handler. The compiler can’t prove this is safe so the attribute will help by making a transformation to the source code: for this reason a variable like static mut FOO: u32 will become let FOO: &mut u32;.

Safety

It is not generally safe to register handlers for non-maskable interrupts. On Cortex-M, HardFault is non-maskable (at least in general), and there is an explicitly non-maskable interrupt NonMaskableInt.

The reason for that is that non-maskable interrupts will preempt any currently running function, even if that function executes within a critical section. Thus, if it was safe to define NMI handlers, critical sections wouldn’t work safely anymore.

This also means that defining a DefaultHandler must be unsafe, as that will catch NonMaskableInt and HardFault if no handlers for those are defined.

The safety requirements on those handlers is as follows: The handler must not access any data that is protected via a critical section and shared with other interrupts that may be preempted by the NMI while holding the critical section. As long as this requirement is fulfilled, it is safe to handle NMIs.

Examples

• Setting the default handler

use cortex_m_rt::exception;

#[exception]
unsafe fn DefaultHandler(irqn: i16) {
    println!("IRQn = {}", irqn);
}

• Overriding the SysTick handler

use cortex_m_rt::exception;

#[exception]
fn SysTick() {
    static mut COUNT: i32 = 0;

    // `COUNT` is safe to access and has type `&mut i32`
    *COUNT += 1;

    println!("{}", COUNT);
}