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 Crash Analysis : Parse panic handlers, guru meditation errors, hard faults, watchdog resets Stack Trace Decoding : Decode raw addresses to function names using ELF binaries Register Dump Interpretation : Analyze CPU register state at crash time Root Cause Identification : Correlate crash data with source code to find the bug 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 : Add IRAM_ATTR to all ISR-related functions Replace blocking calls with ISR-safe variants ( xSemaphoreGiveFromISR , xQueueSendFromISR ) 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 : Call esp_task_wdt_reset() in long loops, or Move FastLED show() to a dedicated task exempt from watchdog, or 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