Hardfault Triage

HardFault & Exception Triage

When a processor exception fires, the register file and stack frame are a black-box recording of the crash. This skill covers how to read that recording.

The methodology is architecture-agnostic. Cortex-M (ARMv7-M/v8-M) fault registers and handlers are the primary reference; the same principles apply to Cortex-A aborts, RISC-V exceptions, Xtensa exception vectors, and other MCU fault paths.

REQUIRED BACKGROUND: Load Skill("debug-methodology") for structured root-cause analysis. If the crash involves RTOS tasks or ISR context, also load Skill("embedded-firmware-dev").

Triage Methodology

Every processor exception triage follows the same four-step flow:

Step 1 — Capture

Read the architecture's fault-status and fault-address registers before any other code runs. The first instructions after exception entry are the only guaranteed-clean snapshot.

• Cortex-M: CFSR, HFSR, MMFAR, BFAR at SCB base 0xE000ED00
• Cortex-A: DFSR, DFAR, IFSR, IFAR (data/prefetch abort)
• RISC-V: mcause, mtval, mepc
• Xtensa (ESP32): EXCCAUSE, EXCVADDR, EPC1

Step 2 — Classify

Match the fault-status bit pattern against known signatures. The tables in the architecture-specific sections below cover the most frequent Cortex-M patterns. For other architectures:

• Look up the exception cause code in the architecture reference manual
• Determine the fault class: memory access, instruction fetch, undefined opcode, alignment, privilege violation, bus error

Step 3 — Locate

Extract the program counter (PC) at the moment of the fault and resolve it to source:

• .map file Global Symbols: search for the function whose address range contains the PC
• addr2line: arm-none-eabi-addr2line -e firmware.axf <pc_address> (Cortex-M), equivalent for other toolchains
• Disassembly listing: use the .lst file or debugger to find the exact instruction at PC − function_start

Step 4 — Root-Cause

Classify the defect behind the fault signature:

Cortex-M Fault Architecture

Fault Register Quick Reference

All at System Control Block (SCB) base 0xE000ED00:

CFSR sub-registers:

Common Fault Signatures (Cortex-M)

Cortex-M Stack Frame Capture

The exception handler must be __attribute__((naked)) — no compiler prologue — so SP points directly at the exception stack frame. The processor automatically pushes R0-R3, R12, LR, PC, PSR on exception entry.

Minimal Fault Dump

static void fault_dump_basic(const char *name) {
    printf("FAULT: %s\n", name);
    printf("CFSR: 0x%08lX  HFSR: 0x%08lX\n", SCB->CFSR, SCB->HFSR);
    printf("MMFAR: 0x%08lX  BFAR: 0x%08lX\n", SCB->MMFAR, SCB->BFAR);
}

static __attribute__((used)) void HardFault_HandlerC(uint32_t *stacked) {
    fault_dump_basic("HardFault");
    printf("R0: 0x%08lX  R1: 0x%08lX  R2: 0x%08lX  R3: 0x%08lX\n",
           stacked[0], stacked[1], stacked[2], stacked[3]);
    printf("R12: 0x%08lX  LR: 0x%08lX  PC: 0x%08lX  PSR: 0x%08lX\n",
           stacked[4], stacked[5], stacked[6], stacked[7]);
    while (1) { /* halt for debugger attachment */ }
}

Naked Handler With Nested-Fault Guard

// Prevent infinite recursion if the fault handler itself faults (e.g., UART not init'd)
static volatile uint8_t in_fault = 0;

__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"       // Thread used MSP → stack pointer in R0
        "mrsne r0, psp\n"       // Thread used PSP (RTOS tasks) → stack pointer in R0
        "b HardFault_HandlerC\n"
    );
}

Key points:

• naked attribute is mandatory — without it, the compiler prologue overwrites SP before you can read the stacked frame
• Check LR bit 2 to determine MSP vs PSP (RTOS tasks use PSP for thread stack; handlers and bare-metal threads use MSP)
• The nested-fault guard (in_fault) prevents infinite HardFault recursion when the handler itself triggers a fault
• Dump all fault registers AND stacked registers before halting — these are the only evidence

Stacked Register Layout

Exception frame on stack (Cortex-M, from low to high address):
Offset 0: R0          Offset 16: R12
Offset 4: R1          Offset 20: LR  (exception return address)
Offset 8: R2          Offset 24: PC  (faulting instruction)
Offset 12: R3         Offset 28: PSR (program status register)

PC-to-Source Resolution

Given the stacked PC from the exception handler:

Method 1: addr2line (fastest, one command)

arm-none-eabi-addr2line -e firmware.axf 0x08001234

Output: src/module/file.c:158. Works for any toolchain with an ELF-aware addr2line.

Method 2: .map File Global Symbols

1. Open the .map file (at <listings>/<target>.map)
2. Go to the Global Symbols section
3. Find the function whose start address is the highest value ≤ PC
4. Offset = PC − function_start. Cross-reference with the .lst listing file to find the exact instruction.

Method 3: Debugger Disassembly

In a debugger (Keil, Ozone, gdb), jump to the PC address in the disassembly window. The exact instruction and surrounding call context are visible.

Root-Cause Decision Tree

Fault type?
├── Precise bus error (BFAR valid)
│   ├── BFAR in SRAM region    → null pointer, use-after-free, buffer overflow
│   ├── BFAR in peripheral map → unclocked peripheral; check RCC/clock-gating init order
│   └── BFAR in flash/ROM      → alignment fault or const-data access violation
├── Imprecise bus error (BFAR not valid)
│   └── Suspect: DMA to freed buffer, cache-coherency after peripheral write, write-buffer
├── INVSTATE or UNDEFINSTR
│   ├── PC is a function pointer → freed object, overwritten vtable, buffer overflow on heap
│   └── PC is a return address   → stack corruption (local array overflow overwrote LR)
├── Stack overflow (STKERR)
│   ├── RTOS task → check uxTaskGetStackHighWaterMark() history, worst-case call chain
│   └── ISR/MSP  → check for large local variables in handlers, deep interrupt nesting
└── MPU violation (IACCVIOL / DACCVIOL)
    └── Compare MMFAR/BFAR against MPU region descriptors; check XN/read-only bits

Common Root Causes (Cross-Architecture)

MAP File for Crash Debugging

The .map file is essential for crash analysis. Key sections:

For build-optimization .map analysis (size optimization, memory budget, linker garbage collection), see Skill("keil-mdk-build").

Cross-References