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
