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.

1. Confirm image-symbol match.

Ensure the ELF/MAP file matches the firmware currently running on target.

1. Identify the faulting address.

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

1. Classify the cause.

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

1. Walk backward to the first bad state.

Inspect caller, input pointers, stack bounds, interrupt context, DMA/cache interactions, and recent initialization.

1. 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

Decode stacked r0-r3, r12, lr, pc, and xpsr from MSP or PSP.

RISC-V

Read:

mcause, mepc, mtval, mtvec, mstatus, sp

Check whether mcause is interrupt or exception, and map mepc to source/disassembly.

8051

Use available evidence:

• Reset reason register if the derivative provides one.
• Stack pointer and internal RAM pressure.
• ISR vector selection and default handler loops.
• Watchdog configuration.
• GPIO heartbeat or serial breadcrumbs around suspected code.

Common Root Causes

• Stack overflow or ISR stack pressure.
• Null/corrupt function pointer.
• Wrong vector table, trap vector, or interrupt number.
• Accessing peripheral before clock/reset release.
• DMA writing outside buffers.
• Cache coherency issue on cache-enabled MCUs.
• Compiler target flags not matching core features.
• Watchdog not serviced during long init.
• Bootloader/app offset mismatch.

Verification

Before claiming a fault is understood:

• State the matched ELF/MAP and running firmware identity if known.
• Report faulting PC/address and mapped symbol/source.
• Report architecture-specific fault registers or explain why unavailable.
• State the suspected root cause and the evidence linking it to the fault.
• State the next minimal verification step, such as watchpoint, stack watermark, or assertion.

Common Failures

• Resetting immediately and losing the only useful fault state.
• Trusting a backtrace when the ELF does not match flashed firmware.
• Fixing the line where the fault occurred instead of the earlier corruption.
• Ignoring interrupt context, stack selection, or DMA/cache side effects.
• Treating watchdog reset as a generic crash without reading reset reason.

Example

User:

程序跑一会儿就进 HardFault。

Agent:

1. Asks for chip, ELF, register dump, CFSR/HFSR, stacked PC, and whether reset happened.
2. Maps stacked PC to source.
3. Checks stack bounds, caller, interrupt context, and invalid memory access evidence.
4. Suggests a focused watchpoint or stack watermark before changing code.