liveBook · Manning

Panic handler

As explained in Embedded Software with Rust

A panic handler is the Rust-defined function that determines how a panic is handled in a target without the hosted panic runtime.

A panic handler defines what happens when a Rust program panics. In bare-metal no_std firmware, the standard library’s panic runtime is unavailable, so the final linked artifact must supply a handler directly or through a dependency. This also applies to a no_std static library linked into a C program. section 6.4 section 8.3.2

Mark a handler with #[panic_handler]. It receives a reference to PanicInfo, which may contain a source location and formatted message. Its return type is !: once called, it must never return. section 6.4.3

use core::panic::PanicInfo;

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {}
}

This minimal handler ignores the panic information and loops forever. A watchdog can be used to reset a device that becomes stuck in such a loop. section 4.4.3 section 6.4.2

A handler can instead log a message, break into a debugger, signal a fault, or reset the device. Embedded Cargo profiles also typically set panic = "abort" to avoid pulling in stack-unwinding support. section 1.3.2 section 6.4 section 6.4.2

Prebuilt handler crates provide different failure behaviors:

  • panic-halt loops silently; it can suit firmware that relies on a watchdog. section 6.4.3 section 6.4.2
  • panic-semihosting prints a message but requires an active debugger, so it is unsuitable for standalone firmware. section 6.4.2
  • panic-itm streams messages over ITM/SWO; panic-probe prints a message and triggers a debugger breakpoint. section 6.4.2
  • panic-abort traps to the HardFault handler on Cortex-M. section 6.4.2

Import a handler crate with use panic_xxx as _; to link its registered handler without directly referencing its items. Cargo features and mutually exclusive cfg attributes can select a diagnostic handler for development and a silent handler otherwise, ensuring exactly one is linked per build. section 6.4.2 section 6.4.5

// main.rs

#[cfg(feature = "debug-panic")]
use panic_semihosting as _;

#[cfg(not(feature = "debug-panic"))]
use panic_halt as _;

This selection uses a declared debug-panic feature to choose semihosting when enabled and panic-halt otherwise. section 6.4.5

How Embedded Software with Rust covers it

How deep it goes
Explains the required signature and non-returning behavior, then compares handler crates and conditional selection.
Examples
Shows an infinite-loop handler, a feature-selected handler pair, and a no_std static library callable from C.
What you can do after
Build it from scratch as a non-returning handler or select a prebuilt handler for diagnostic and silent builds.
How it connects
Connects panics to stack unwinding, watchdog resets, semihosting, and Cargo features.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Embedded Software with Rust. The section links point to the parts of the book it draws on.