domains / software-engineering / dwarf-debug-info-analysis / dwarf-expert

dwarf-expert

Skill card

combined

The trailofbits copy is the more complete, self-contained procedure: it contains the specific dwarfdump flags, the DIE search escalation strategy, the macOS dSYM caveat, the DWARF version pinning notes, and the library table with parsing pitfalls. The sickn33 copy is a wrapper that delegates the detailed steps to external reference files (readelf.md, dwarfdump.md, coding.md) and adds a decision tree and explicit scope limits (v3-v5 only). Because the sickn33 copy lacks the concrete command-line details and the trailofbits copy lacks the explicit version scope and decision-tree structure, crowning one would hide a real alternative approach (self-contained vs. reference-file-based).

Repositories

Other copies

Combined skill

---
name: dwarf-expert
description: Analyzes DWARF debug information in compiled binaries. Use when inspecting .debug_* sections, DIE trees, or DW_TAG_/DW_AT_ entries with dwarfdump/llvm-dwarfdump or readelf, verifying debug info with llvm-dwarfdump --verify, answering DWARF standard questions, or writing code that parses DWARF (libdwarf, pyelftools, gimli).
effort: medium
allowed-tools: Read Write Edit Bash Grep Glob WebSearch WebFetch
---
# DWARF Expert

Expertise for DWARF debug info: parsing and searching it, verifying its integrity, answering questions about the standard, and writing code that consumes it.

## Scope
- **In Scope**: DWARF v3, v4, and v5 analysis, parsing, verification, and code generation.
- **Out of Scope**: Runtime debugging (use gdb/lldb), reverse engineering beyond DWARF sections (use Ghidra/IDA), compiler-specific DWARF generation bugs, and general ELF parsing without DWARF needs.

# Authoritative Sources
When precision matters, look standard details up instead of answering from memory:
1. **dwarfstd.org** — the official specification. Web-search specific sections, e.g. "DWARF5 DW_TAG_subprogram attributes site:dwarfstd.org".
2. **LLVM** — `llvm/lib/DebugInfo/DWARF/` is a reliable reference implementation: `DWARFDie.cpp`, `DWARFUnit.cpp`, `DWARFDebugLine.cpp`, `DWARFVerifier.cpp`.
3. **libdwarf** — the reference C implementation at github.com/davea42/libdwarf-code.

# Parsing and Searching with dwarfdump
Prefer `dwarfdump` over `readelf` for DWARF-specific work. Check `dwarfdump --version` first to distinguish libdwarf's `dwarfdump` from LLVM's `llvm-dwarfdump`. The options below are LLVM's.

On macOS, linked Mach-O executables do not carry DWARF: it stays in the `.o` files until `dsymutil` collects it into a `.dSYM` bundle. Point `dwarfdump` at the dSYM (or the object files), not the executable. `pyelftools` is ELF-only — for Mach-O scripted work, stay with the LLVM tools.

- `--all`: dump every DWARF section; `--debug-info`, `--debug-line`, etc. dump one
- `--show-children [--recurse-depth=<n>]`: include child DIEs
- `--show-parents [--parent-recurse-depth=<n>]`: include parent DIEs
- `--show-form`: print attribute form types
- `--find=<name>`: exact-name lookup via accelerator tables
- `--name=<pattern> [--ignore-case] [--regex]`: exhaustive DIE-name search
- `--lookup=<address>`: find the DIE covering an address
- `--verbose`: print low-level encoding detail

## Searching DIEs
Escalate through these strategies:
1. **Name or address match**: `--find`, then `--name`; `--lookup` for addresses.
2. **Attribute or type queries**: dump and filter. `grep -B` pulls in the header line carrying each DIE's offset.
3. **Multi-attribute or structural queries**: write a Python script using `pyelftools`.

# Verifying DWARF Integrity
- `llvm-dwarfdump --verify <binary>`: structural checks. `--error-display=<quiet|summary|details|full>` controls detail; `--verify-json=<path>` writes a machine-readable error summary.
- `llvm-dwarfdump --statistics <binary>`: debug-info quality metrics as JSON.

Verify after producing DWARF, when a debugger misbehaves, and when developing DWARF tooling.

# readelf
For general ELF structure, or when `dwarfdump` is unavailable:
- `--debug-dump=<section>`: dump a DWARF section
- `--dwarf-depth=<n>` / `--dwarf-start=<n>`: limit DIE depth / start offset

# Writing Code That Parses DWARF
Prefer an existing library over parsing by hand:

| Library | Language | Notes |
|---------|----------|-------|
| `libdwarf` | C/C++ | Low-level; used to implement `dwarfdump` |
| `pyelftools` | Python | Also parses ELF in general |
| `gimli` | Rust | Pair with `object` to load container files |
| `debug/dwarf` | Go | Standard library |
| `LibObjectFile` | .NET | Also handles ELF/PE object files |

Default to Python with `pyelftools` for one-off scripts.

DWARF-specific pitfalls:
- Attributes are optional.
- Attribute indirection: resolve `DW_AT_abstract_origin` or `DW_AT_specification` chains.
- Type chains: walk `DW_AT_type` links to reach the base type.

# Decision Tree
- Need to verify DWARF data integrity? Use `llvm-dwarfdump --verify`.
- Need to answer questions about the DWARF standard? Search dwarfstd.org or reference LLVM/libdwarf source.
- Need simple section dump or general ELF info? Use `readelf`.
- Need to parse, search, and/or dump DWARF DIE nodes? Use `dwarfdump`.
- Need to write, modify, or review code that interacts with DWARF data? Refer to the coding guidelines above.