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

esp32-crash-review

Decodes and analyses ESP32-family panics — Guru Meditation errors, register dumps, backtraces, aborts, stack overflows and watchdog timeouts on both Xtensa (ESP32, S2, S3) and RISC-V (C2, C3, C5, C6, H2, P4) chips — to find the root cause and recommend a fix plus diagnostic config. Use when the user pastes a crash or says "Guru Meditation", "LoadProhibited", "StoreProhibited", "InstrFetchProhibited", "IllegalInstruction", "Load access fault", "Store access fault", "MEPC", "MTVAL", "EXCVADDR", "Backtrace:", "abort() was called", "Stack canary watchpoint triggered", "Interrupt wdt timeout", "Task watchdog got triggered", "crash loop", "/review-crash", or "decode this backtrace".

agodianel · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add agodianel/esp32-claude-workbench --skill esp32-crash-review

技能说明


name: esp32-crash-review description: Decodes and analyses ESP32-family panics — Guru Meditation errors, register dumps, backtraces, aborts, stack overflows and watchdog timeouts on both Xtensa (ESP32, S2, S3) and RISC-V (C2, C3, C5, C6, H2, P4) chips — to find the root cause and recommend a fix plus diagnostic config. Use when the user pastes a crash or says "Guru Meditation", "LoadProhibited", "StoreProhibited", "InstrFetchProhibited", "IllegalInstruction", "Load access fault", "Store access fault", "MEPC", "MTVAL", "EXCVADDR", "Backtrace:", "abort() was called", "Stack canary watchpoint triggered", "Interrupt wdt timeout", "Task watchdog got triggered", "crash loop", "/review-crash", or "decode this backtrace". license: MIT metadata: source: esp32-workbench version: "0.2.0"

ESP32 Crash Review

Crash analysis is architecture-specific. Identify the chip first.

Tools

If the esp32-workbench MCP server is connected, call its tools; otherwise run the CLI. If esp32wb is not on PATH, use uvx --from git+https://github.com/agodianel/esp32-claude-workbench esp32wb <args>. Add --json for machine-readable output.

NeedMCP toolCLI
Decode panic (Xtensa + RISC-V; runs addr2line if the toolchain is on PATH)crash_decodeesp32wb crash panic.txt --elf build/<app>.elf [--target T] (- reads stdin)
Arch + toolchain prefix for the chipchip_infoesp32wb chip <target>
Surrounding log contextlog_summaryesp32wb logs monitor.log
Stack sizes after a stack overflowstack_checkesp32wb stacks .

The ELF must be the exact build that produced the crash; a rebuilt ELF gives wrong lines. If --elf is missing, ask for it or say decoding is unavailable.

Steps

1. Identify target and architecture

From CONFIG_IDF_TARGET, the boot banner, or the dump itself:

Dump containsArchitectureChips
PC, PS, A0..A15, EXCCAUSE, EXCVADDR, Backtrace: 0x..:0x..XtensaESP32, ESP32-S2, ESP32-S3
MEPC, RA, SP, MCAUSE, MTVAL, MSTATUS, stack memory dumpRISC-VESP32-C2, C3, C5, C6, H2, P4

Toolchains: Xtensa uses a per-chip prefix (xtensa-esp32-elf-, xtensa-esp32s2-elf-, xtensa-esp32s3-elf-); RISC-V chips use riscv32-esp-elf-. Confirm with esp32wb chip <target>.

2. Exception type

Xtensa nameRISC-V equivalentTypical cause
LoadProhibitedLoad access faultRead through NULL / dangling / uninitialised pointer
StoreProhibitedStore access faultWrite through bad pointer, write to flash/ROM
InstrFetchProhibitedInstruction access faultBad function pointer, corrupted return address
IllegalInstructionIllegal instructionCorrupted stack/code, bad function pointer, abort paths
LoadStoreAlignmentLoad/Store address misalignedMisaligned access via cast or packed struct
IntegerDivideByZero(no trap — RISC-V returns a defined result)Unchecked divisor
Unhandled debug exception + "Stack canary watchpoint triggered"Breakpoint (end-of-stack watchpoint) or Stack protection fault (HW stack guard)Stack overflow
Interrupt wdt timeout on CPU0/1sameISR too long / interrupts disabled too long
Cache error / cache-disabled accessCache errorCode/data in flash accessed while cache disabled (ISR not in IRAM)

The fault address is EXCVADDR on Xtensa and MTVAL on RISC-V; the faulting instruction is PC (Xtensa) / MEPC (RISC-V).

3. Decode the call chain

  1. esp32wb crash <file> --elf build/<app>.elf (preferred), or
  2. idf.py monitor with the matching ELF (decodes automatically; on RISC-V it unwinds the stack dump), or
  3. Manual: <prefix>addr2line -pfiaC -e build/<app>.elf <PC> <addr...>.

RISC-V panics normally lack a Backtrace: line unless the firmware was built with CONFIG_ESP_SYSTEM_USE_EH_FRAME or CONFIG_ESP_SYSTEM_USE_FRAME_POINTER; without the monitor or the ELF you may only get the faulting function from MEPC and RA.

4. Interpret

  • Fault address 0x00000000 or a small offset → NULL pointer / NULL struct member (offset ≈ member offset).
  • Fault address that is garbage (not in any RAM/flash region of the chip) → uninitialised or corrupted pointer. Memory maps differ per chip; check the TRM rather than reusing classic-ESP32 ranges.
  • Crash inside a FreeRTOS/driver call from an ISR → non-ISR-safe API in ISR.
  • Different crash sites every time → memory corruption (overflow, use-after-free).
  • abort() → read the preceding line (assert text, ESP_ERROR_CHECK error name and file:line).

Detailed patterns: Guru Meditation playbook, watchdog playbook.

5. Diagnostic configuration (debug builds only)

CONFIG_HEAP_POISONING_COMPREHENSIVE=y
CONFIG_HEAP_TASK_TRACKING=y
CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK=y
CONFIG_FREERTOS_CHECK_STACKOVERFLOW_CANARY=y
CONFIG_COMPILER_STACK_CHECK_MODE_STRONG=y   # option name varies by IDF version
CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT=y        # keep the dump on screen instead of rebooting
CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH=y       # capture field crashes; read with idf.py coredump-info

Verify each option exists for your ESP-IDF version in menuconfig before adding it, and remove debug options before release (esp32wb sdkconfig flags them).

6. Report

# Crash Analysis — <project> (target: <chip>, arch: Xtensa|RISC-V, IDF <ver>)
## Exception
- Type / core / task:
- PC|MEPC → function (file:line):
- Fault address (EXCVADDR|MTVAL):
## Call chain
| # | Address | Function | File:Line |
## Root cause (confidence: high/medium/low, with evidence)
## Classification: NULL pointer | stack overflow | ISR violation | memory corruption | watchdog | cache/IRAM | other
## Recommended fix (goes through an implementation co
阅读完整来源 ↗