</>EmbeddedInterview

How do you analyse a HardFault on a Cortex-M?

HardDebugging, Testing & Tools

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 0xFFFFFFFx or 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.