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.
| Need | MCP tool | CLI |
|---|---|---|
| Decode panic (Xtensa + RISC-V; runs addr2line if the toolchain is on PATH) | crash_decode | esp32wb crash panic.txt --elf build/<app>.elf [--target T] (- reads stdin) |
| Arch + toolchain prefix for the chip | chip_info | esp32wb chip <target> |
| Surrounding log context | log_summary | esp32wb logs monitor.log |
| Stack sizes after a stack overflow | stack_check | esp32wb 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 contains | Architecture | Chips |
|---|---|---|
PC, PS, A0..A15, EXCCAUSE, EXCVADDR, Backtrace: 0x..:0x.. | Xtensa | ESP32, ESP32-S2, ESP32-S3 |
MEPC, RA, SP, MCAUSE, MTVAL, MSTATUS, stack memory dump | RISC-V | ESP32-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 name | RISC-V equivalent | Typical cause |
|---|---|---|
LoadProhibited | Load access fault | Read through NULL / dangling / uninitialised pointer |
StoreProhibited | Store access fault | Write through bad pointer, write to flash/ROM |
InstrFetchProhibited | Instruction access fault | Bad function pointer, corrupted return address |
IllegalInstruction | Illegal instruction | Corrupted stack/code, bad function pointer, abort paths |
LoadStoreAlignment | Load/Store address misaligned | Misaligned 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/1 | same | ISR too long / interrupts disabled too long |
Cache error / cache-disabled access | Cache error | Code/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
esp32wb crash <file> --elf build/<app>.elf(preferred), oridf.py monitorwith the matching ELF (decodes automatically; on RISC-V it unwinds the stack dump), or- 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
0x00000000or 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_CHECKerror 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
阅读完整来源 ↗