Topics / Debugging, Testing & Tools / Q2
How do you analyse a HardFault on a Cortex-M?
Short answer: On a fault, the CPU stacks R0–R3, R12, LR, PC and xPSR on the active stack. A HardFault handler written in assembly picks the correct stack pointer (MSP or PSP, from bit 2 of the EXC_RETURN value in LR) and passes it to a C function that reads the stacked PC (the faulting instruction, or the one after it for imprecise faults) and LR (the caller), together with the fault status registers: CFSR (UsageFault/BusFault/MemManage bits), HFSR (FORCED = an escalated configurable fault), MMFAR and BFAR (faulting data address when the valid bits are set). Then look up the PC in the map file or with addr2line.
#include <stdint.h>
typedef struct { uint32_t r0, r1, r2, r3, r12, lr, pc, xpsr; } stack_frame_t;
/* kept in a .noinit section so it survives a reset; inspect after reboot */
__attribute__((section(".noinit"))) volatile struct {
uint32_t magic, pc, lr, cfsr, hfsr, mmfar, bfar, sp;
} crash;
__attribute__((naked)) void HardFault_Handler(void)
{
__asm volatile(
"tst lr, #4 \n" /* EXC_RETURN bit 2: 0 = MSP, 1 = PSP */
"ite eq \n"
"mrseq r0, msp \n"
"mrsne r0, psp \n"
"b hardfault_c \n");
}
void hardfault_c(stack_frame_t *f)
{
crash.magic = 0xDEADFA17;
crash.pc = f->pc;
crash.lr = f->lr;
crash.sp = (uint32_t)f;
crash.cfsr = *(volatile uint32_t *)0xE000ED28; /* SCB->CFSR */
crash.hfsr = *(volatile uint32_t *)0xE000ED2C; /* SCB->HFSR */
crash.mmfar = *(volatile uint32_t *)0xE000ED34; /* SCB->MMFAR */
crash.bfar = *(volatile uint32_t *)0xE000ED38; /* SCB->BFAR */
for (;;) { } /* or: __BKPT(0) when debugging; NVIC_SystemReset() in production */
}
arm-none-eabi-addr2line -e app.elf -f -i 0x08001a3c # function and source line of the stacked PC
Decoding CFSR (common bits)
| Bit (CFSR) | Meaning | Typical cause |
|---|---|---|
| IACCVIOL / DACCVIOL (MemManage) | MPU violation on instruction/data access | stack overflow into a guard region, NULL page protection |
| PRECISERR + BFARVALID (BusFault) | bus error at the address in BFAR | access to a non-existent address, peripheral clock not enabled |
| IMPRECISERR (BusFault) | bus error on a buffered write; PC is after the real fault | write to an invalid address; set DISDEFWBUF (ACTLR) while debugging to make it precise |
| STKERR / UNSTKERR | fault while stacking/unstacking | stack overflow, corrupted SP |
| UNDEFINSTR (UsageFault) | undefined instruction | executing data, corrupted function pointer, wrong instruction set |
| INVSTATE | Thumb bit not set | function pointer without the low bit set, jumping to an ARM-state address |
| INVPC | invalid EXC_RETURN | corrupted LR in an exception handler |
| UNALIGNED / DIVBYZERO | only if trapping enabled (CCR) |
unaligned access, integer divide by zero |
Tips
- Enable the separate MemManage, BusFault and UsageFault handlers (
SCB->SHCSR) for more precise reporting. - A PC of
0xFFFFFFFxor similar garbage usually means the stack was corrupted and a return address was overwritten. - If the stacked PC is in the middle of a function that "cannot" fault, check the LR and the stack contents for what called it, and suspect memory corruption.
- Debuggers and IDEs (STM32CubeIDE fault analyser, Ozone, SEGGER's HardFault handler, Memfault) automate this decoding.