liveBook · Manning

HardFault

As explained in Embedded Software with Rust

HardFault is a Cortex-M processor exception raised when a fault cannot be handled by a more specific enabled fault handler or escalates to HardFault.

HardFault is a Cortex-M processor exception for serious errors, including invalid memory access, undefined instructions, or corrupt state. It is also the fallback when a more specific fault handler is unavailable or disabled. Only reset and the non-maskable interrupt (NMI) can preempt it. section 4.1.3 section 4.5.6

On Armv7-M and Armv8-M mainline targets, MemoryManagement, BusFault, and UsageFault are disabled at reset. Their faults therefore escalate to HardFault by default; the FORCED bit in the HardFault Status Register (HFSR) indicates escalation. Enabling the configurable exceptions gives each fault type a dedicated handler and more specific diagnostic registers. section 6.4.6

use cortex_m::peripheral::{scb::Exception, Peripherals};

let mut p = Peripherals::take().unwrap();
p.SCB.enable(Exception::MemoryManagement);
p.SCB.enable(Exception::BusFault);
p.SCB.enable(Exception::UsageFault);

Enable the three configurable fault exceptions through the cortex-m System Control Block (SCB) API. Provide corresponding handlers to report them. section 6.4.6

When a fault occurs, the processor saves execution context on the stack before entering its handler. In Rust, cortex-m-rt exposes this context as an ExceptionFrame. A HardFault handler can pass the frame to panic!() so the configured panic output channel reports it; the handler must be unsafe and must not return. section 6.4.6

use cortex_m_rt::{entry, exception, ExceptionFrame};

#[exception]
unsafe fn HardFault(ef: &ExceptionFrame) -> ! {
    panic!("{:#?}", ef);
}

This handler routes the saved frame through the existing panic reporting mechanism. section 6.4.6

Inspect the saved pc for the faulting instruction address and lr for the return address. Resolve pc on the development host with arm-none-eabi-addr2line -e <elf-path> <address>, using the ELF file flashed to the target. A GDB breakpoint on HardFault is useful when the firmware provides its own handler. section 6.4.6 section 6.5.7

Fault status registers can narrow down the cause. For example, bit 0 of the Usage-Fault Status Register (UFSR), within the Configurable Fault Status Register (CFSR), indicates an undefined instruction. The following direct register access uses unsafe Rust; a peripheral access crate is normally the more idiomatic option. section 4.5.6

fn HardFault() {
    use cortex_m::peripheral::SCB;

    let scb = unsafe { &*SCB::PTR };
    let cfsr = scb.cfsr.read();

    if (cfsr & (1 << 16)) != 0 {
        // Bit 0 of UFSR is set: undefined instruction caused the fault
    }
    loop {}
}

Read CFSR through cortex-m and test the UFSR undefined-instruction bit. section 4.5.6

Watch for these practical fault sources:

  • Misaligned stack or data can cause faults. Keep the stack pointer 8-byte aligned and align data sections appropriately; ALIGN(8) can enforce section alignment in a linker script. section 4.1.3
  • Packed Rust structs can place wide fields at unaligned addresses. On Cortex-M0 and M0+, unaligned accesses trigger HardFault; packed structs are unsuitable for memory-mapped register overlays. section 5.4.3
  • On Cortex-M0, M0+, and M23, a semihosting breakpoint with no debugger attached escalates to HardFault. Compile semihosting macros out of standalone release builds using the crate’s no-semihosting feature. section 6.2.1

How Embedded Software with Rust covers it

How deep it goes
Explains escalation and implements frame and status-register inspection, with configurable fault enablement for more specific diagnosis.
Examples
Shows an undefined-instruction status check, an ExceptionFrame dump, and a packed struct with potentially unaligned fields.
What you can do after
Diagnose faults using cortex-m-rt exception frames, fault status registers, and arm-none-eabi-addr2line.
How it connects
Connects HardFault to exception handling, configurable faults, memory alignment, panic handlers, and semihosting.

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.