Introduce variable location representation and tracking

[djolertrk]

Feature description

Currently, the compiler infrastructure (from generated DWARF) parses source locations only (line:column/.debug_line section). The idea is to parse variables locations (DW_AT_location) as well.

DWARF standard was extended with DW_OP_WASM_location that can represent locals, globals and stack operands.

HIR can be extended with a new builtin/debug instruction - builtin.debug_value, that contains several operands, like pointer to an attribute representing variable (DIlocalVariableAttr), function (DISubprogramAttr) and expression (DIExpression) that represents the value.

Why is this feature needed?

No response

[djolertrk]

Here is a proposal for HIR part: https://github.com/walnuthq/compiler/tree/feature/debug-variable-locations. The design doc is at: https://github.com/walnuthq/compiler/blob/feature/debug-variable-locations/docs/DebugInfoMetadata.md.

[djolertrk]

PRs: compiler (#820) and miden-vm (0xMiden/miden-vm#2471), miden-debug (0xMiden/miden-debug#17)

[djolertrk]

In order to test compiler and miden-debug implementation for debug variables, end-to-end, I back ported the content from 0xMiden/miden-vm#2471 and added more fixes/improvements into branch that is based on miden-vm v0.19.1 at https://github.com/walnuthq/miden-vm/tree/feature/debug-variable-locations-v0.19.1.

I will add these additions from the https://github.com/walnuthq/miden-vm/tree/feature/debug-variable-locations-v0.19.1 to the 0xMiden/miden-vm#2471, since by using it that way we are able to print real values during debugging session!

[djolertrk]

cc @greenhat @bitwalker

[djolertrk]

Here is a summary of how two MLIR-based compilers (Flang and Mojo) approaches to handle debug info and debug variable tracking through transformations.

Flang/FIR — the "intrinsics" approach (similar to what we do today)

Flang uses the same pattern as LLVM's dbg.value/dbg.declare intrinsics, but in MLIR form. Debug info is attached as metadata/attributes (via FusedLoc piggybacking on MLIR locations). Variable-to-value mappings live as declare-like operations (fir.declare) that reference the storage address. More info at: https://github.com/llvm/llvm-project/blob/main/flang/docs/DebugGeneration.md

The problem with this approach is that transforms are free to silently drop or stale-out debug info. There's no verifier that catches it, no mechanism that forces transform authors to update it. It works okay for a pipeline with few transforms, but degrades as the optimizer gets more aggressive, so it inherited the problems with llvm's dimetadata mechanism.

Mojo — first-class DebugInfo dialect

Mojo took a fundamentally different approach by creating a dedicated debuginfo dialect where variable tracking is a first-class SSA operation:

  debuginfo.value #var = %0                                

Three key design pillars:

1. SSA use-def chains for debug values: Since debuginfo.value is a real op that uses SSA values, if a transform deletes a value without updating its debug uses, that's a hard error — not a silent drop. Standard MLIR use-def tracking enforces this automatically.
2. Typed expression trees for DIExpressions: When a transform changes a value's representation (e.g., promotes to alloca), the transform author describes the inverse operation as a typed expression node (e.g., "deref this pointer to recover the source value"). The verifier checks type consistency through the expression tree, so type mismatches between the debug expression and the IR value are caught at compile time. So authors of new transformations need to fill the debug info transformation hooks that perform the opposite of the transformation in terms of diexpression operands.
3. Explicit lifetime tracking: debuginfo.kill #var marks a variable as dead, giving the debugger precise lifetime boundaries instead of relying on scope heuristics.

All in all, flang hopes transforms preserve debug info. Mojo requires it via the type system and SSA semantics, while keeping the burden minimal — transform authors only describe the inverse of what they did.

Reference: https://llvm.org/devmtg/2024-04/slides/TechnicalTalks/MojoDebugging.pdf

Proposal: evolve our current approach toward Mojo's model

Our compiler on the experimental branch, currently uses DbgValue/DbgDeclare ops in the builtin dialect with DILocalVariableAttr/DIExpressionAttr metadata — essentially the Flang/intrinsics approach.

I'd propose we introduce a dedicated debuginfo dialect, following Mojo's model. Moving debug operations out of the builtin dialect and into their own first-class dialect would let us:

• Enforce correctness via SSA semantics — debuginfo.value as a real op using SSA values means deleting or replacing a value without updating its debug uses is a hard error, not a silent drop.
• Add typed expression trees — DIExpressions with type information flowing through the tree, verified for consistency. Transforms that change a value's representation without updating the debug expression get caught by the verifier.
• Provide transform-author utilities — simple helpers where a transform author only needs to describe the inverse of their transformation (e.g., "I wrapped this in a pointer, the inverse is a deref"). Minimal friction, one extra line per transform.
• Track variable lifetimes explicitly — debuginfo.kill to mark variables as dead, giving the debugger precise boundaries instead of scope-based heuristics.
• Own its own verifier rules — a dialect-level verifier that checks type consistency, use-def validity, and lifetime correctness in one place.

cc @bitwalker @greenhat

[djolertrk]

current PRs:

miden-vm: 0xMiden/miden-vm#2471
compiler: #820
debugger: 0xMiden/miden-debug#17

see: 0xMiden/miden-debug#17 (comment)

$ ./target/release/miden-debug /tmp/source_location_test.masp \                                                                                                                                              
    --entrypoint "root_ns:root@1.0.0::source_location_test::entrypoint" -- 150
...
# step several times
# type :vars
x=150