embedded-fault-debug

Embedded Fault Debug

Overview

Use this skill to preserve crash evidence and find the first failing instruction. The agent should read architecture-specific fault state before reset, map addresses to symbols, and separate root cause from secondary symptoms.

When To Use

Use this skill when:

• Firmware hits HardFault, BusFault, UsageFault, trap, illegal instruction, default handler, watchdog reset, assert, or panic.
• The board resets unexpectedly or hangs after a repeatable action.
• The user has a register dump, fault log, crash PC, stack dump, watchdog event, or GDB backtrace.

Do not use this skill when the target cannot yet connect or flash; use mcu-flashing-debug first.

First Questions

Ask for:

• Architecture/chip family and toolchain.
• Exact symptom and whether it is reproducible.
• Register dump, backtrace, fault/trap registers, assert log, or reset reason.
• ELF/MAP file that matches the running image.
• Whether the target has been reset since the fault.

Workflow

1. Preserve state. Do not reset or reflash until fault registers, PC, LR/RA, SP, and stack frame are captured.

2. Confirm image-symbol match. Ensure the ELF/MAP file matches the firmware currently running on target.

3. Identify the faulting address. Map PC, exception return address, mepc, stacked PC, or return address to a symbol and source line.

4. Classify the cause. Separate invalid memory access, illegal instruction, stack overflow, alignment, bus/peripheral access, watchdog, assert, and default handler cases.

5. Walk backward to the first bad state. Inspect caller, input pointers, stack bounds, interrupt context, DMA/cache interactions, and recent initialization.

6. Add a focused verification. Use a watchpoint, assertion, guard pattern, stack watermark, or minimal repro to prove the suspected cause.

Architecture Notes

Cortex-M

Read SCB fault registers before reset:

CFSR  = 0xE000ED28
HFSR  = 0xE000ED2C
MMFAR = 0xE000ED34
BFAR  = 0xE000ED38