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.8 KiB
DWARF compile-unit inspection
Problem and outcome
Learning what a native binary was built from currently needs a deep provider or
GNU objdump through inspect_with_objdump, which returns -W text the caller
has to parse. Add inspect_dwarf_units / inspect-dwarf-units, a built-in
reader of DWARF 2 through 5 compile units in one selected local ELF, Mach-O or
PE image. It returns structured unit facts with no provider installed and never
executes the target.
Requirements
- Read compile-unit headers and the unit-level DIE only. Each unit reports
version, unit type when the header has one, address size,
name,comp_dir,producer, language code and DWARF 5 language name,dwo_name(DW_AT_dwo_nameorDW_AT_GNU_dwo_name),stmt_listand whetherDW_AT_low_pcis present. - Each attribute carries an explicit
present,absent,unresolvedorunknownstate. A value that cannot be trusted is never returned as a fact. - Locate
.debug_info,.debug_abbrev,.debug_str,.debug_line_strand.debug_str_offsetsby container. Mach-O sections are read only from the__DWARFsegment, by file range rather than VM mapping. Decompress ELFSHF_COMPRESSEDzlib and zstd, and GNU.zdebug_*and Mach-O__zdebug_*zlib, within a fixed256 MiBdecompressed allowance; a larger declared size fails the call. - Bound DWARF 5
strxindexes to their.debug_str_offsetscontribution and applyDW_AT_str_offsets_baseregardless of attribute order. Decode chainedDW_FORM_indirectwithin the unit. An unknown form becomes a unit issue that names the form code. - Identify ELF relocation sections by type and
sh_infotarget. In an ET_REL image with unapplied debug relocations, relocated fields stayunresolved; when.debug_abbrevholds more than one table,abbrev_offsetis null, the unit reportsunapplied_relocationand its DIE is not read. - Page units with
offsetandlimit(default32, maximum256). Bound the walk (100,000units), abbreviation entries (8,192) and attributes (256), retained string bytes (64 KiB), unit issues (32) and the input read (512 MiB). Decompression attempts and abbreviation parsing share aggregate work allowances. Form reads andDW_FORM_indirecthops share a1,048,576-step allowance per walk; exhaustion is adecode_budgetunit issue withpartialcoverage. - Report
coverage.statusfrom the shared coverage vocabulary (complete, orpartialwith a reason) anddebug_infoaspresentorabsent.absentdoes not establish that a separate debug file is absent; ELF and PE limitations name whether.gnu_debuglinkwas observed. A.dwoobject ispartialbecause.debug_info.dwois not read. - A universal Mach-O requires
architecture; the value is rejected for every other image. MCP requires an absolute path.
Acceptance
Unit, provider, boundary, MCP and CLI acceptance tests cover DWARF 2 through 5,
64-bit offsets, compressed sections, split skeletons, unknown forms, truncated
units, abbreviation budgets, relocatable objects and the decompressed-size
allowance. npm run verify:dwarf-units builds owned C fixtures and compares
every unit's version, name, comp_dir, producer and dwo_name with
llvm-dwarfdump across Mach-O objects and linked ELF and PE images, and checks
fixed expectations for an ELF relocatable object, an ld.lld -r merge and a
.dwo object. The verification record
lists the variants run and those skipped.
Out of scope
Line tables, types, functions, child DIEs and location expressions; following
.dwo files, .gnu_debuglink or build-id links; decoding .gnu_debuglink
contents or GNU build-id notes; applying relocations; opening .dSYM bundles;
and target execution.