Exceptions

Exceptions, and interrupts, are a hardware mechanism by which the processorhandles asynchronous events and fatal errors (e.g. executing an invalidinstruction). Exceptions imply preemption and involve exception handlers,subroutines executed in response to the signal that triggered the event.

The cortex-m-rt crate provides an exception attribute to declare exceptionhandlers.

  1. // Exception handler for the SysTick (System Timer) exception
  2. #[exception]
  3. fn SysTick() {
  4.     // ..
  5. }

Other than the exception attribute exception handlers look like plainfunctions but there's one more difference: exception handlers can not becalled by software. Following the previous example, the statement SysTick();would result in a compilation error.

This behavior is pretty much intended and it's required to provide a feature:static mut variables declared inside exception handlers are safe to use.

  1. #[exception]
  2. fn SysTick() {
  3.     static mut COUNT: u32 = 0;
  5.     // `COUNT` has type `&mut u32` and it's safe to use
  6.     *COUNT += 1;
  7. }

As you may know, using static mut variables in a function makes itnon-reentrant). It's undefined behavior to call a non-reentrant function,directly or indirectly, from more than one exception / interrupt handler or frommain and one or more exception / interrupt handlers.

Safe Rust must never result in undefined behavior so non-reentrant functionsmust be marked as unsafe. Yet I just told that exception handlers can safelyuse static mut variables. How is this possible? This is possible becauseexception handlers can not be called by software thus reentrancy is notpossible.

A complete example

Here's an example that uses the system timer to raise a SysTick exceptionroughly every second. The SysTick exception handler keeps track of how manytimes it has been called in the COUNT variable and then prints the value ofCOUNT to the host console using semihosting.

NOTE: You can run this example on any Cortex-M device; you can also run iton QEMU

  1. #![deny(unsafe_code)]
  2. #![no_main]
  3. #![no_std]
  5. extern crate panic_halt;
  7. use core::fmt::Write;
  9. use cortex_m::peripheral::syst::SystClkSource;
  10. use cortex_m_rt::{entry, exception};
  11. use cortex_m_semihosting::{
  12.     debug,
  13.     hio::{self, HStdout},
  14. };
  16. #[entry]
  17. fn main() -> ! {
  18.     let p = cortex_m::Peripherals::take().unwrap();
  19.     let mut syst = p.SYST;
  21.     // configures the system timer to trigger a SysTick exception every second
  22.     syst.set_clock_source(SystClkSource::Core);
  23.     // this is configured for the LM3S6965 which has a default CPU clock of 12 MHz
  24.     syst.set_reload(12_000_000);
  25.     syst.clear_current();
  26.     syst.enable_counter();
  27.     syst.enable_interrupt();
  29.     loop {}
  30. }
  32. #[exception]
  33. fn SysTick() {
  34.     static mut COUNT: u32 = 0;
  35.     static mut STDOUT: Option<HStdout> = None;
  37.     *COUNT += 1;
  39.     // Lazy initialization
  40.     if STDOUT.is_none() {
  41.         *STDOUT = hio::hstdout().ok();
  42.     }
  44.     if let Some(hstdout) = STDOUT.as_mut() {
  45.         write!(hstdout, "{}", *COUNT).ok();
  46.     }
  48.     // IMPORTANT omit this `if` block if running on real hardware or your
  49.     // debugger will end in an inconsistent state
  50.     if *COUNT == 9 {
  51.         // This will terminate the QEMU process
  52.         debug::exit(debug::EXIT_SUCCESS);
  53.     }
  54. }
  1. $ tail -n5 Cargo.toml
  1. [dependencies]
  2. cortex-m = "0.5.7"
  3. cortex-m-rt = "0.6.3"
  4. panic-halt = "0.2.0"
  5. cortex-m-semihosting = "0.3.1"
  1. $ cargo run --release
  2.      Running `qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb (..)
  3. 123456789

If you run this on the Discovery board you'll see the output on the OpenOCDconsole. Also, the program will not stop when the count reaches 9.

The default exception handler

What the exception attribute actually does is override the default exceptionhandler for a specific exception. If you don't override the handler for aparticular exception it will be handled by the DefaultHandler function, whichdefaults to:

  1. fn DefaultHandler() {
  2.     loop {}
  3. }

This function is provided by the cortex-m-rt crate and marked as#[nomangle] so you can put a breakpoint on "DefaultHandler" and catch_unhandled exceptions.

It's possible to override this DefaultHandler using the exception attribute:

  1. #[exception]
  2. fn DefaultHandler(irqn: i16) {
  3.     // custom default handler
  4. }

The irqn argument indicates which exception is being serviced. A negativevalue indicates that a Cortex-M exception is being serviced; and zero or apositive value indicate that a device specific exception, AKA interrupt, isbeing serviced.

The hard fault handler

The HardFault exception is a bit special. This exception is fired when theprogram enters an invalid state so its handler can not return as that couldresult in undefined behavior. Also, the runtime crate does a bit of work beforethe user defined HardFault handler is invoked to improve debuggability.

The result is that the HardFault handler must have the following signature:fn(&ExceptionFrame) -> !. The argument of the handler is a pointer toregisters that were pushed into the stack by the exception. These registers area snapshot of the processor state at the moment the exception was triggered andare useful to diagnose a hard fault.

Here's an example that performs an illegal operation: a read to a nonexistentmemory location.

NOTE: This program won't work, i.e. it won't crash, on QEMU becauseqemu-system-arm -machine lm3s6965evb doesn't check memory loads and willhappily return 0 on reads to invalid memory.

  1. #![no_main]
  2. #![no_std]
  4. extern crate panic_halt;
  6. use core::fmt::Write;
  7. use core::ptr;
  9. use cortex_m_rt::{entry, exception, ExceptionFrame};
  10. use cortex_m_semihosting::hio;
  12. #[entry]
  13. fn main() -> ! {
  14.     // read a nonexistent memory location
  15.     unsafe {
  16.         ptr::read_volatile(0x3FFF_FFFE as *const u32);
  17.     }
  19.     loop {}
  20. }
  22. #[exception]
  23. fn HardFault(ef: &ExceptionFrame) -> ! {
  24.     if let Ok(mut hstdout) = hio::hstdout() {
  25.         writeln!(hstdout, "{:#?}", ef).ok();
  26.     }
  28.     loop {}
  29. }

The HardFault handler prints the ExceptionFrame value. If you run thisyou'll see something like this on the OpenOCD console.

  1. $ openocd
  2. (..)
  3. ExceptionFrame {
  4.     r0: 0x3ffffffe,
  5.     r1: 0x00f00000,
  6.     r2: 0x20000000,
  7.     r3: 0x00000000,
  8.     r12: 0x00000000,
  9.     lr: 0x080008f7,
  10.     pc: 0x0800094a,
  11.     xpsr: 0x61000000
  12. }

The pc value is the value of the Program Counter at the time of the exceptionand it points to the instruction that triggered the exception.

If you look at the disassembly of the program:

  1. $ cargo objdump --bin app --release -- -d -no-show-raw-insn -print-imm-hex
  2. (..)
  3. ResetTrampoline:
  4.  8000942:       movw    r0, #0xfffe
  5.  8000946:       movt    r0, #0x3fff
  6.  800094a:       ldr     r0, [r0]
  7.  800094c:       b       #-0x4 <ResetTrampoline+0xa>

You can lookup the value of the program counter 0x0800094a in the dissassembly.You'll see that a load operation (ldr r0, [r0] ) caused the exception.The r0 field of ExceptionFrame will tell you the value of register r0was 0x3fff_fffe at that time.