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>
3.9 KiB
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.
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:
{
"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 lists the compiled variants compared with a DWARF dumper.