Files
reverse-engineering-anything/docs/guides/native/dwarf-units.md
T
Matt Van Hornandgensokyo-dev 637e4cb60c feat(native): inspect DWARF compile units offline
Add bounded offline DWARF compilation-unit inspection with source provenance, explicit coverage, caller-selected controls and shared ELF compression framing.

Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-17 10:04:46 +00:00

79 lines
3.9 KiB
Markdown

# DWARF compile units
`inspect_dwarf_units` / `inspect-dwarf-units` reads compile-unit headers and
the unit DIE from one selected local ELF, Mach-O, or PE image. It covers
DWARF 2 through 5, including compressed ELF sections. It does not execute the
image and does not require a disassembler.
```bash
rea inspect-dwarf-units /absolute/path/to/program --json
```
The CLI resolves relative paths against the caller's working directory. MCP
requires an absolute filesystem path:
```json
{
"name": "inspect_dwarf_units",
"arguments": { "path": "/artifacts/program" }
}
```
A universal Mach-O needs `architecture` (`x86`, `x86_64`, `arm`, or `arm64`).
The same value is rejected for every other image. A `.dSYM` bundle is not
opened. Pass the DWARF file inside the bundle.
## Observations
Each call returns the artifact path, SHA-256, and byte length, the container
`format`, and `sections` for `.debug_info`, `.debug_abbrev`, `.debug_str`,
`.debug_line_str`, and `.debug_str_offsets` when those sections are
file-backed. Section rows keep the stored name, file offset, stored size, and
`compression` (`none`, `zlib`, or `zstd`). ELF `SHF_COMPRESSED` zlib and zstd
payloads, and legacy GNU `.zdebug_*` and Mach-O `__zdebug_*` zlib payloads, are
decompressed within a fixed allowance. A declared size above that allowance
fails the call. Mach-O sections are read only from the `__DWARF` segment.
`omissions` gives one row per section name and reason, with a count when
several sections share it.
`units` lists the requested page. `offset` and `limit` select that page.
`total_units` counts framed units in this file, up to the walk cap. Each unit
row gives its offset inside decompressed `.debug_info`, DWARF version, unit
type when the header has one, address size, name, `comp_dir`, producer,
language code and DWARF 5 language name, `dwo_name`, `stmt_list`, and whether
`DW_AT_low_pc` is present. `file_offset` is null when `.debug_info` is
compressed. Per-unit decode problems are `issues`. The walk continues when the
unit length still frames the next unit.
## Coverage and limits
`coverage.status` is `complete` when every framed unit was visited. Gaps inside
a visited unit stay in that unit's `issues`, so `complete` does not mean every
fact resolved. `partial` means a later length could not frame the next unit, the
walk cap was reached, a declared `.debug_info` could not be decoded, a further
`.debug_info` section was not read, or attribute decoding used up its shared
work allowance. Each form read and each `DW_FORM_indirect` hop costs one step
of that allowance; units read after it runs out report `decode_budget`. A `.dwo` object is `partial` because its
`.debug_info.dwo` is not read. `debug_info` is `absent` when this file declares
no `.debug_info`, or declares one that stores no bytes; coverage is then
`complete` with no units. That does not establish that a separate debug file
is absent. For ELF and PE, the limitations then name
whether `.gnu_debuglink` was observed. `.gnu_debuglink` contents and GNU build-id
notes are not decoded here.
Child DIEs, types, functions, line tables, and location expressions are not
read. An unknown DWARF form becomes a unit issue that names the form code.
`DW_AT_str_offsets_base` is applied to `strx` indexes in the same DIE
regardless of attribute order. `dwo_name` reads `DW_AT_dwo_name` and the GNU
`DW_AT_GNU_dwo_name`.
An ET_REL image whose debug relocations are unapplied holds placeholders in its
relocated fields. `DW_AT_stmt_list`, `DW_AT_str_offsets_base`, and `DW_FORM_strp`,
`DW_FORM_line_strp`, `DW_FORM_strx`, and `DW_FORM_GNU_str_index` values stay
unresolved. The abbreviation offset selects a table only when `.debug_abbrev`
holds one table. Otherwise, as in `ld -r` output, `abbrev_offset` is null, the
unit reports `unapplied_relocation`, and its DIE is not read.
The [verification record](../../verification/dwarf-units-2026-10-31.md) lists the
compiled variants compared with a DWARF dumper.