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: