hardfault-triage
Use when triaging processor exception crashes — HardFault, MemManage, BusFault, UsageFault, data/prefetch abort, illegal instruction, or watchdog timeout. Covers fault-register interpretation, stack-frame extraction, PC-to-source resolution, and root-cause classification.
AmethystLuna · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add AmethystLuna/embedded-workbench --skill hardfault-triage技能说明
name: hardfault-triage description: "Use when triaging processor exception crashes — HardFault, MemManage, BusFault, UsageFault, data/prefetch abort, illegal instruction, or watchdog timeout. Covers fault-register interpretation, stack-frame extraction, PC-to-source resolution, and root-cause classification."
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
.lstfile or debugger to find the exact instruction atPC − function_start
Step 4 — Root-Cause
Classify the defect behind the fault signature:
| Fault Class | Code Defect |
|---|---|
| Bus error at valid SRAM address | Null pointer, use-after-free, buffer overflow into heap metadata |
| Bus error at peripheral address | Unclocked or powered-down peripheral — RCC/PM init ordering |
| Undefined instruction / invalid state | Corrupted function pointer, jumped to freed memory, stack smash overwrote LR |
| Stack overflow (exception entry) | Task stack too small, deep call chain, large local variables, recursion |
| Imprecise bus error (no valid address) | DMA to freed buffer, write-buffer coherency, cache maintenance |
| MPU / memory protection violation | Region misconfiguration, attempted write to read-only region |
Cortex-M Fault Architecture
Fault Register Quick Reference
All at System Control Block (SCB) base 0xE000ED00:
| Register | Address | Key Bits |
|---|---|---|
| CFSR | 0xE000ED28 | Composite: UFSR[25:16] + BFSR[15:8] + MMFSR[7:0] |
| HFSR | 0xE000ED2C | Bit 30 FORCED=1 means escalated from other fault handler |
| MMFAR | 0xE000ED34 | Fault address (valid when MMFSR.MMARVALID=1) |
| BFAR | 0xE000ED38 | Fault address (valid when BFSR.BFARVALID=1) |
CFSR sub-registers:
| Sub-register | Bits | Covers |
|---|---|---|
| MMFSR (MemManage) | CFSR[7:0] | MPU violation, XN violation, access violation |
| BFSR (BusFault) | CFSR[15:8] | Precise/imprecise bus error, stack push/pop fault |
| UFSR (UsageFault) | CFSR[25:16] | Undefined instruction, invalid state, unaligned, divide-by-0 |
Common Fault Signatures (Cortex-M)
| CFSR Value | Decomposition | Typical Root Cause |
|---|---|---|
0x00008200 | BFSR.PRECISERR (BFAR valid) | Null pointer dereference, access to unclocked peripheral |
0x00000400 | BFSR.IMPRECISERR (BFAR not valid) | Write-buffer async fault; DMA target freed; cache coherency |
0x00020000 | UFSR.INVSTATE | Tried to execute ARM code in Thumb mode; corrupted function pointer |
0x00010000 | UFSR.UNDEFINSTR | Jumped to data region; function pointer to freed or zeroed memory |
0x01000000 | UFSR.UNALIGNED | Unaligned load/store (CCR.UNALIGN_TRP must be enabled) |
0x00000001 | MMFSR.IACCVIOL | Executing from XN (execute-never) region — MPU config |
0x00000002 | MMFSR.DACCVIOL | Writing to read-only memory — MPU config |
0x00000800 | BFSR.STKERR | Stack overflow on exception entry (push to full stack) |
0x00001000 | BFSR.UNSTKERR | Stack corruption on exception return (pop from corrupted stack) |
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 in
阅读完整来源 ↗