embedded-debug

name	embedded-debug
description	Firmware crash analysis, stack trace decoder, and register dump interpreter for ESP32/ARM/AVR platforms. Use when debugging device crashes, panics, guru meditation errors, hard faults, or analyzing core dumps.
argument-hint	<crash output or description of the issue>
context	fork
agent	embedded-debug-agent

Analyze firmware crash output, decode stack traces, and diagnose embedded system failures.

$ARGUMENTS

What This Skill Does

1. Crash Analysis: Parse panic handlers, guru meditation errors, hard faults, watchdog resets
2. Stack Trace Decoding: Decode raw addresses to function names using ELF binaries
3. Register Dump Interpretation: Analyze CPU register state at crash time
4. Root Cause Identification: Correlate crash data with source code to find the bug
5. Fix Recommendations: Suggest specific code changes to prevent the crash

Supported Platforms

Platform	Crash Types
ESP32 (all variants)	Guru Meditation, LoadProhibited, StoreProhibited, InstrFetchProhibited, watchdog reset, brownout, cache errors
ARM Cortex-M (STM32, Teensy, nRF)	HardFault, MemManage, BusFault, UsageFault, watchdog reset
AVR (Arduino Uno/Mega)	Stack overflow (silent corruption), watchdog reset, undefined opcode
RISC-V (ESP32-C3/C6/H2)	Illegal instruction, load/store fault, breakpoint

How To Use

With crash output

/embedded-debug
Guru Meditation Error: Core  0 panic'ed (LoadProhibited). Exception was unhandled.
Core 0 register dump:
PC      : 0x400d1234  PS      : 0x00060030  A0      : 0x800d5678
...

With a description

/embedded-debug Device reboots every 30 seconds, serial shows "rst:0x3 (SW_RESET)"

With a core dump

/embedded-debug Analyze the core dump from the last crash

What You'll Get

• Decoded stack trace with source file and line numbers
• Explanation of the crash type and what triggered it
• Identification of the faulty code path
• Specific fix recommendations with code examples
• Prevention strategies (stack size tuning, watchdog config, null checks)

ESP32 Crash Quick Reference

Exception Type → Root Cause

Exception	EXCVADDR hint	Likely Root Cause
LoadProhibited	~0x00000000	NULL pointer dereference (uninitialized LED strip?)
LoadProhibited	Other	Read from freed or out-of-bounds memory
StoreProhibited	Any	Write to read-only or invalid memory address
InstrFetchProhibited	Any	Jump to invalid/NULL function pointer or corrupt vtable
IllegalInstruction	Any	Stack overflow corrupting code, or corrupt heap
IntegerDivideByZero	N/A	Division by zero in LED index math
Unaligned	Any	Misaligned memory access (DMA buffer not 4-byte aligned)
Cache disabled but cache memory range accessed	Any	ISR accessing flash — add IRAM_ATTR to ISR function

Key Register Meanings (ESP32 Xtensa)

Register	Meaning
PC	Program Counter — where the crash happened
EXCVADDR	Address that caused the fault (NULL pointer, invalid write target)
A1	Stack pointer — compare to task stack base to detect overflow
A0	Return address — calling function

ISR Violation Pattern

Symptoms: Cache disabled but cache memory range accessed or crash inside FreeRTOS API

Cause: FastLED ISR handler calling blocking or flash-accessing code.

Diagnosis: Look for crash inside xSemaphoreTake, vTaskDelay, printf, or any non-ISR-safe function.

Fix:

1. Add IRAM_ATTR to all ISR-related functions
2. Replace blocking calls with ISR-safe variants (xSemaphoreGiveFromISR, xQueueSendFromISR)
3. Move logging out of ISR to a deferred task

Watchdog Reset Pattern

Symptoms: rst:0x7 (TG0WDT_SYS_RESET) or rst:0x8 (TG1WDT_SYS_RESET)

Cause: Task or interrupt handler not yielding — common with:

• FastLED show() blocking on DMA in a task with watchdog enabled
• High LED counts causing long encoding loops without yield
• Spinning in a loop without vTaskDelay(0) or taskYIELD()

Fix:

1. Call esp_task_wdt_reset() in long loops, or
2. Move FastLED show() to a dedicated task exempt from watchdog, or
3. Reduce LED count to bring encoding time under watchdog timeout

Stack Overflow Pattern

Symptoms: StackOverflow + task name, or IllegalInstruction with A1 near stack limit

Diagnosis: Check task stack size in xTaskCreate or xTaskCreatePinnedToCore. FastLED show() with large LED arrays can use significant stack.

Fix: Increase task stack size (minimum 4096 bytes for tasks calling FastLED show with encoding)

Memory Corruption Pattern

Symptoms: IllegalInstruction at random address, corrupted register values, intermittent crashes

Diagnosis: Enable diagnostics:

// In sdkconfig or menuconfig:
CONFIG_HEAP_POISONING_COMPREHENSIVE=y
CONFIG_HEAP_TASK_TRACKING=y
CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK=y

Common FastLED Cause: Writing past end of CRGB array (index out of bounds in user sketch)

Backtrace Decoding Commands

# ESP32 (Xtensa)
xtensa-esp32-elf-addr2line -pfiaC -e build/firmware.elf 0xADDR1 0xADDR2

# ESP32-S3
xtensa-esp32s3-elf-addr2line -pfiaC -e build/firmware.elf 0xADDR1

# ESP32-C3/C6 (RISC-V)
riscv32-esp-elf-addr2line -pfiaC -e build/firmware.elf 0xADDR1

# Live decode via idf.py
idf.py -p /dev/ttyUSB0 monitor