Skip to content

test(dwarf): check DWARF at every instruction; remap locals of DW_AT_ranges entries - #345

Draft
logan-gatlin wants to merge 3 commits into
mainfrom
dwarf-testing
Draft

logan-gatlin wants to merge 3 commits into
mainfrom
dwarf-testing

Conversation

@logan-gatlin

@logan-gatlin logan-gatlin commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

walrus's DWARF tests so far check specific cases by hand. This PR adds a checker that compares what a debugger learns at every instruction before and after walrus. It runs the checker over the existing test modules, over rustc and clang output, and in two fuzz targets. It then fixes what the checker still finds after #340.

Checker (first commit)

walrus_tests_utils::dwarf::check_preserved(input, output) pairs each instruction of the input with the same instruction of the output by walking both modules' function bodies side by side. It doesn't use walrus's own record of where it put each instruction. For each pair it compares:

  • the line table row (file, line, column);
  • the scopes covering it: subprograms, inlined subroutines and lexical blocks;
  • each variable's location.

For locations, DW_OP_WASM_location local indices are translated through the numbering of the function the instruction is in, and global indices through the module's.

It knows what walrus drops on purpose, such as unreachable code after an unconditional branch, return or throw, and unused locals. For those it expects "optimized out" rather than a match.

dwarf::synthesize(wasm, &mut Unstructured) gives any module DWARF chosen by the fuzz input:

  • DWARF 4 or 5;
  • low_pc/high_pc in either form, or DW_AT_ranges;
  • location lists or exprlocs, over arbitrary sub-ranges;
  • lexical blocks per wasm block.

It runs in:

Where Input
dwarf_synthetic every round_trip and valid module, with default DWARF and 32 fixed seeds, with and without gc
dwarf_fixtures rustc (-O0/-O1/-O2/-O3) and clang (-O0/-O2) output, DWARF 4 and 5, in crates/tests/dwarf-fixtures (rebuilt by build.sh); also llvm-dwarfdump --verify when it's on $PATH
fuzz/dwarf wasm-smith modules with synthesized DWARF
fuzz/dwarf-raw mutations of the fixtures; checks for no panic, readable DWARF, code ranges inside functions and deterministic output

Running it against main found several bugs that #340 already fixes. dwarf_mapping.rs keeps a regression test for each of them, and they all pass on #340:

  • ranges and line rows that start in removed code, or at the byte before an instruction;
  • DW_OP_addr;
  • a low_pc/high_pc pair whose code now spans functions;
  • a line row at a function's end;
  • VLIW line tables.

Fixes (second commit)

On #340, 16 of the 127 dwarf_synthetic modules still failed, all for one reason.

Locals of an entry that gives its code as DW_AT_ranges.

  • The bug: an entry's local indices came from the function its DW_AT_low_pc is in, or else from its parent's. A subprogram or lexical block that uses DW_AT_ranges instead got its parent's function and its parent's code. The parent is often the unit, whose low_pc of 0 is a tombstone. So its locals were either copied unchanged, naming locals walrus had removed or renumbered, or remapped through the wrong function and dropped.
  • The fix: an entry's scope is now its own code, split into pieces by the input function each piece came from.
    • An exprloc whose pieces are now in functions that number its locals differently becomes a location list with the right local in each. This is the same thing fix(dwarf): derive DWARF from where each instruction was emitted #340 does for code a pass copied.
    • Location list entries are remapped per piece, rather than with the function their start is in.
    • A DW_LLE_default_location can't be split, so it's dropped where its locals differ between those functions.
    • An expression with no locals, such as a static variable's DW_OP_addr in a unit that covers every function, is remapped only once.

Panics on DWARF that can't be read.

  • DWARF that can't be read or written is now dropped with a warning instead of making emit_wasm panic.
  • Two line-program inputs make gimli itself panic: a DWARF 4 DW_LNE_define_file with an empty name, and a DW_LNS_advance_line of i64::MIN. walrus rejects them before gimli sees them.
  • These are gimli bugs. The fixes are on a local gimli branch and not sent upstream yet. Once they're released, this pre-check can go.

Fuzzing fixes (third commit)

The first hour of fuzzing found 30 crashes in dwarf-raw, the target that mutates real compiler output.

  • 22 crashes, in gimli's line program writer. walrus kept the input's line encoding. Rows at walrus's new addresses don't fit a minimum instruction length above 1, and some line base and range values can't encode an advance; gimli's writer asserts on both.
    • Line programs are now written with one byte per instruction and one operation each, as Wasm has, and rows' operation indices are 0.
  • 5 crashes, from low_pc/high_pc pairs that couldn't be mapped. These were a DW_AT_low_pc that isn't an address, and a tombstone low_pc with a high_pc that's neither a size nor a tombstone. Their attributes were copied unchanged or mapped one at a time, so a discarded function could get a range of 0.. the end of a live one.
    • They're now written as removed code.
  • 3 crashes, false positives in the checker. It rejected a DW_AT_sibling that points at the null entry ending its parent's children. That's what gimli writes for the last child, and llvm-dwarfdump --verify accepts it.

Two more gimli bugs came up while writing the tests. Neither makes walrus panic, so the fuzzers don't catch them:

  • ConvertLineProgram loses a DW_LNE_set_address that comes right before DW_LNE_end_sequence, so the sequence ends at its last row. LLVM ends sequences with DW_LNS_advance_pc instead.
  • It rejects any input header with a positive line_base, even when a different encoding is requested. walrus then drops the DWARF with a warning.

dwarf_mapping.rs and dwarf_malformed.rs have a regression test for each fix, and each fails without it. No public API changes.

Testing

  • cargo test --all: everything passes except 5 walrus-fuzz-utils tests, which need WABT's wasm-interp. It wasn't installed locally.
  • cargo test --features parallel, and the same with --manifest-path crates/tests/Cargo.toml: pass.
  • dwarf_fixtures, including llvm-dwarfdump --verify: passes.
  • Fuzzing, two rounds of one hour per target with 5 workers each:
    • First round: dwarf ran 6.6M inputs with no crashes. dwarf-raw ran 6.3M inputs and found the 30 crashes above.
    • Second round, with the fixes: dwarf ran 6.8M inputs and dwarf-raw 6.2M, with no crashes.

@logan-gatlin logan-gatlin changed the title test(dwarf): check DWARF at every instruction, and fix what it found test(dwarf): check DWARF at every instruction; remap locals of DW_AT_ranges entries Nov 16, 2026
@logan-gatlin
logan-gatlin changed the base branch from main to dwarf-instr-map November 16, 2026 18:52
Base automatically changed from dwarf-instr-map to main November 16, 2026 18:53
Add `walrus_tests_utils::dwarf`, which compares what a debugger learns at
each instruction of the input and of walrus's output: the source line, the
scopes covering it and where each variable is. It pairs instructions by
walking both modules' function bodies side by side, so it doesn't rely on
walrus's own record of where it put each instruction. `synthesize` gives a
module DWARF chosen by an `arbitrary` input, varying forms (DWARF 4 and 5,
low/high pc, ranges, location lists, exprlocs) and ranges.

It runs in:

- `dwarf_synthetic`: every `round_trip` and `valid` module, with default
  DWARF and 32 fixed seeds, with and without gc;
- `dwarf_fixtures`: rustc and clang output at several optimization levels
  and DWARF versions, rebuilt by `dwarf-fixtures/build.sh`, and through
  `llvm-dwarfdump --verify` when it's on `$PATH`;
- the `dwarf` fuzz target, over wasm-smith modules with synthesized DWARF;
- the `dwarf-raw` fuzz target, which mutates the fixtures and checks that
  walrus doesn't panic, emits readable DWARF with code ranges inside
  functions, and emits the same bytes twice.

`dwarf_mapping` has regression tests for what the fuzzers found on main
that #340 already fixes: ranges and line rows starting in
removed code or the byte before an instruction, `DW_OP_addr`, low/high pc
spanning functions, rows at a function's end and VLIW line tables.

Some `dwarf_synthetic` seeds fail until the next commit, which fixes the
locals of entries that give their code as `DW_AT_ranges`.
An entry's local indices came from the function its `DW_AT_low_pc` is in,
or else its parent's. An entry that gives its code as `DW_AT_ranges`
instead, as subprograms and lexical blocks can, got its parent's function
(often none, as a unit's `DW_AT_low_pc` of 0 is a tombstone), and its
parent's code as its scope. Its locals were then left unchanged, naming
locals walrus removed or renumbered, or remapped through another
function and dropped. The fuzzer found this on 16 of the 127
`round_trip` and `valid` modules.

An entry's scope is now its own code, from `DW_AT_ranges` or low/high pc,
split into pieces by the input function each came from, as local indices
are that function's. An expression whose pieces are now in functions that
number its locals differently becomes a location list with the right local
in each, as #340 already did for code a pass copied. A location list entry
is remapped per piece, rather than with the function its start is in. A
`DW_LLE_default_location` can't be split, so it's dropped where its
locals differ. Expressions that name no locals, such as a static
variable's `DW_OP_addr` in a unit covering every function, are remapped
once.

Also, DWARF that can't be read is dropped with a warning instead of
making `emit_wasm` panic, including two line program inputs gimli panics
on instead of returning an error: a DWARF 4 `DW_LNE_define_file` with an
empty name, and a `DW_LNS_advance_line` of `i64::MIN`. They're rejected
before gimli sees them.
An hour of `dwarf-raw` (6.3M runs) found 30 crashes in three groups:

- 22 were gimli's line program writer asserting on the input's line
  encoding, which walrus kept: a minimum instruction length above 1, which
  Wasm's byte addresses aren't multiples of, or a line base and range that
  can't encode an advance. Line programs are now written with one byte per
  instruction and one operation each, as Wasm has, and rows' operation
  indices are 0.
- 5 were entries whose `DW_AT_low_pc` isn't an address-class form, or is
  a tombstone with a `DW_AT_high_pc` that's neither a size nor a
  tombstone. They were left as they were, so their attributes were
  copied unchanged or mapped one at a time: a discarded function could get
  `0..` the end of a live one. They're now written as removed code.
- 3 were the checker rejecting a `DW_AT_sibling` that points at the null
  entry ending its parent's children, which is what gimli writes for the
  last child, and what readers expect.

The `dwarf` target ran 6.6M inputs with no crashes.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant