mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 13:12:26 +00:00
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>
67 lines
3.8 KiB
Markdown
67 lines
3.8 KiB
Markdown
# 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_name` or `DW_AT_GNU_dwo_name`), `stmt_list` and whether
|
|
`DW_AT_low_pc` is present.
|
|
- Each attribute carries an explicit `present`, `absent`, `unresolved` or
|
|
`unknown` state. A value that cannot be trusted is never returned as a fact.
|
|
- Locate `.debug_info`, `.debug_abbrev`, `.debug_str`, `.debug_line_str` and
|
|
`.debug_str_offsets` by container. Mach-O sections are read only from the
|
|
`__DWARF` segment, by file range rather than VM mapping. Decompress ELF
|
|
`SHF_COMPRESSED` zlib and zstd, and GNU `.zdebug_*` and Mach-O `__zdebug_*`
|
|
zlib, within a fixed `256 MiB` decompressed allowance; a larger declared
|
|
size fails the call.
|
|
- Bound DWARF 5 `strx` indexes to their `.debug_str_offsets` contribution and
|
|
apply `DW_AT_str_offsets_base` regardless of attribute order. Decode chained
|
|
`DW_FORM_indirect` within the unit. An unknown form becomes a unit issue that
|
|
names the form code.
|
|
- Identify ELF relocation sections by type and `sh_info` target. In an ET_REL
|
|
image with unapplied debug relocations, relocated fields stay `unresolved`;
|
|
when `.debug_abbrev` holds more than one table, `abbrev_offset` is null, the
|
|
unit reports `unapplied_relocation` and its DIE is not read.
|
|
- Page units with `offset` and `limit` (default `32`, maximum `256`). Bound the
|
|
walk (`100,000` units), 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 and `DW_FORM_indirect` hops share a
|
|
`1,048,576`-step allowance per walk; exhaustion is a `decode_budget` unit
|
|
issue with `partial` coverage.
|
|
- Report `coverage.status` from the shared coverage vocabulary (`complete`,
|
|
or `partial` with a reason) and `debug_info` as `present` or `absent`.
|
|
`absent` does not establish that a separate debug file is absent; ELF and PE limitations name whether `.gnu_debuglink` was
|
|
observed. A `.dwo` object is `partial` because `.debug_info.dwo` is 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](../../../verification/dwarf-units-2026-10-31.md)
|
|
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.
|