跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

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 .lst file or debugger to find the exact instruction at PC − function_start

Step 4 — Root-Cause

Classify the defect behind the fault signature:

Fault ClassCode Defect
Bus error at valid SRAM addressNull pointer, use-after-free, buffer overflow into heap metadata
Bus error at peripheral addressUnclocked or powered-down peripheral — RCC/PM init ordering
Undefined instruction / invalid stateCorrupted 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 violationRegion misconfiguration, attempted write to read-only region

Cortex-M Fault Architecture

Fault Register Quick Reference

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

RegisterAddressKey Bits
CFSR0xE000ED28Composite: UFSR[25:16] + BFSR[15:8] + MMFSR[7:0]
HFSR0xE000ED2CBit 30 FORCED=1 means escalated from other fault handler
MMFAR0xE000ED34Fault address (valid when MMFSR.MMARVALID=1)
BFAR0xE000ED38Fault address (valid when BFSR.BFARVALID=1)

CFSR sub-registers:

Sub-registerBitsCovers
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 ValueDecompositionTypical Root Cause
0x00008200BFSR.PRECISERR (BFAR valid)Null pointer dereference, access to unclocked peripheral
0x00000400BFSR.IMPRECISERR (BFAR not valid)Write-buffer async fault; DMA target freed; cache coherency
0x00020000UFSR.INVSTATETried to execute ARM code in Thumb mode; corrupted function pointer
0x00010000UFSR.UNDEFINSTRJumped to data region; function pointer to freed or zeroed memory
0x01000000UFSR.UNALIGNEDUnaligned load/store (CCR.UNALIGN_TRP must be enabled)
0x00000001MMFSR.IACCVIOLExecuting from XN (execute-never) region — MPU config
0x00000002MMFSR.DACCVIOLWriting to read-only memory — MPU config
0x00000800BFSR.STKERRStack overflow on exception entry (push to full stack)
0x00001000BFSR.UNSTKERRStack 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
阅读完整来源 ↗