ESP Core Dump Utility

Warnings

• gotcha Standalone usage outside of ESP-IDF requires manual installation of the correct GDB toolchain (e.g., `xtensa-esp-elf-gdb` or `riscv-esp-elf-gdb`) and ensuring it's in your system's PATH. The GDB version must be compatible with the ESP-IDF version used to compile your firmware.
  Fix: Install the ESP-IDF framework, or download the appropriate `esp-gdb` toolchain (matching your chip and ESP-IDF version) and add its executable directory to your system's PATH. Consult ESP-IDF documentation for specific toolchain versions.
• gotcha Insufficient partition size allocated for the core dump on flash can lead to 'Not enough space to save core dump!' errors during a crash. This prevents the core dump from being saved.
  Fix: Ensure your `partitions.csv` file defines a `coredump` partition of type 'data' and subtype 'coredump' with adequate size. The required size depends on the number of tasks and stack sizes in your application.
• gotcha When Flash Encryption is enabled on the ESP device, core dumps saved to an encrypted flash partition cannot be directly read using `idf.py coredump-info` or `idf.py coredump-debug` from the host. Reading must happen from the ESP, which handles decryption.
  Fix: To analyze core dumps from encrypted flash, read them directly from the ESP device using `idf.py coredump-info -c <path-to-core-dump>` after the device decrypts and sends it. Alternatively, disable flash encryption for debugging purposes if feasible for development builds.
• breaking Python 3.12 removed the `distutils` module. Older versions of `esp-coredump` might fail if they still rely on `distutils` for setup or internal operations.
  Fix: Upgrade `esp-coredump` to version 1.12.0 or newer (e.g., `pip install --upgrade esp-coredump`). Version 1.12.0 includes a fix to replace `distutils` with `shutil` for Python 3.12 compatibility.
• gotcha GDB may fail to parse call stacks that involve ROM functions due to missing debug information for the ROM. This can lead to incomplete backtraces.
  Fix: The ESP-IDF monitor typically handles this by automatically loading the appropriate ROM ELF files based on the target and its revision. When debugging manually, ensure that ROM ELF files are available and loaded if needed.

Install

• pip install esp-coredump==1.16.0 Latest stable release

Imports

• CoreDump

  from esp_coredump import CoreDump

  This is the primary class for interacting with core dump functionality programmatically.

Quickstart

This quickstart demonstrates how to programmatically use `esp-coredump` to analyze a core dump file. It sets up a `CoreDump` object with dummy files for illustration and attempts to retrieve core dump information. For actual usage, replace the dummy paths with your device's core dump and application ELF files.

import os
from esp_coredump import CoreDump

# --- This is a demonstration with dummy files. ---
# In a real scenario, 'coredump.b64' would come from an ESP device
# and 'program.elf' would be your firmware's ELF file with debug symbols.

# Create dummy core dump and ELF files for the example to run
dummy_coredump_b64_content = "hDEAAAEAAAAOAAAAbAEAAA==" # Minimal valid-looking base64
dummy_elf_content = b"\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00" # Minimal ELF header

with open("dummy_coredump.b64", "w") as f:
    f.write(dummy_coredump_b64_content)
with open("dummy_program.elf", "wb") as f:
    f.write(dummy_elf_content)

try:
    # Instantiate the CoreDump object.
    # 'chip' must match your target Espressif chip (e.g., 'esp32', 'esp32s3', 'esp32c3').
    # 'core' is the path to your core dump file, and 'core_format' specifies its type.
    # 'prog' is the path to your application's ELF file containing debug symbols.
    coredump = CoreDump(
        chip='esp32',
        core='./dummy_coredump.b64',
        core_format='b64',
        prog='./dummy_program.elf',
        # If GDB is not in your system's PATH, specify its location:
        # gdb=os.environ.get('ESP_GDB_PATH', None)
    )

    print("--- Attempting to retrieve Core Dump Info ---")
    # This will print information about the core dump, including task states and call stacks.
    # With dummy files, this will likely raise an error but demonstrates API usage.
    coredump.info_corefile()

    # To start an interactive GDB debugging session:
    # print("\n--- Starting GDB session (interactive, will block) ---")
    # coredump.dbg_corefile()

except Exception as e:
    print(f"An error occurred (expected with dummy files for full analysis): {e}")

finally:
    # Clean up dummy files
    if os.path.exists("dummy_coredump.b64"):
        os.remove("dummy_coredump.b64")
    if os.path.exists("dummy_program.elf"):
        os.remove("dummy_program.elf")