[wasm] Preserve R2R variable debug information

[lewing]

Summary

Preserve variable debug information produced by RyuJIT for ReadyToRun WebAssembly code and define the producer-owned encoding and stack-base contracts used by downstream diagnostic readers.

• Preserve optimized tracked-variable ranges as well as unoptimized/relooper scopes.
• Preserve packed wasm local register values and exact frame-resident stack locations.
• Centralize the register encoding in ICorDebugInfo and advertise its shift/count through target data descriptors.
• Exclude the hidden portable-entry-pointer argument from source variables.
• Pin the current wasm stack VarLoc base encoding to 2.
• Validate optimized locals, GC roots, same-type slot identity, legitimate null, leaf/calling/localloc/funclet frame shapes, and complete exact tuples.

This remains a draft. The producer changes are here; cDAC decoding and live consumer validation remain in dependent draft #133890.

Producer-owned encoding contract

WASM register locations pack a JIT-local index and WasmValueType into the 32-bit ICorDebugInfo::RegNum payload:

packedRegister = localIndex | ((uint)valueType << registerTypeShift)

Current values:

WASM_REG_TYPE_BITS    = 3
WASM_REG_TYPE_SHIFT   = 29
WASM_VALUE_TYPE_COUNT = 7

The JIT derives its masks from these constants and statically asserts the register-width and WasmValueType::Count relationships. The wasm target descriptor publishes WasmDebugRegisterTypeShift=29 and WasmDebugValueTypeCount=7 as uint8 globals. Readers must reject missing or unsupported values rather than plausibly misdecode another local/type.

The static ReadyToRun image reader has no live target descriptor, so a future width/count change requires a format-aware, versioned R2R debug-info update.

Stack base versus engine locals

Three distinct concepts must not be conflated:

1. DebugVarInfo stack base literal 2.
2. The absolute logical frame address reconstructed by runtime/cDAC from shadow-stack linear memory and unwind state.
3. The per-function engine local currently holding SP/FP.

The producer now statically asserts:

REG_FPBASE == REG_SPBASE == REG_NA == REGNUM_AMBIENT_SP == 2

Therefore current VLT_STK/VLT_STK2 records are logical-frame-relative and do not encode a V8 $varN local. If the producer changes away from base 2, the reader needs a coordinated fail-loud update.

Measured WasmRegAlloc rule:

• An FP value is allocated when there are frame locals, localloc, or funclets.
• Root without localloc: FP aliases SP, including methods that make calls.
• Root with localloc: FP is distinct so later SP movement does not move frame homes.
• Funclet: SP and parent establishing FP are distinct; with localloc, the funclet receives the root's pre-adjustment frame base.
• Numeric engine-local indices vary with parameters/allocation and are observation, not format. This PR does not advertise SP/FP local-index metadata.

Exact current-output matrix:

Shape	Function signature / locals	Observed frame access
Leaf, frame local, no call, no localloc	3 i32 params, no declared wasm locals	root FP aliases SP; frame loads use current local 0
One-arg calling root (SumStaticData)	3 i32 params, 7 declared i32 locals	calls do not split FP; frame loads use current local 0
Two-arg calling optimized root	4 i32 params, 3 declared i32 locals	root FP still aliases SP at current local 0; current parameter 3 is the hidden portable-entry pointer, not FP
localloc, no funclet	3 i32 params; i32 locals 3-5, i64 local 6	SP is current local 0; distinct root FP is current local 3; frame loads use 3
Funclet, no localloc	root: 3 params + 2 i32 locals; funclet: 2 params + i32 local 2	root FP aliases current SP 0; funclet current SP is 0 and parent FP is 1
Funclet + localloc	root: i32 locals 3-5 + i64 local 6; funclet: i32 locals 2-3 + i64 local 4	distinct root FP is current local 3; funclet parent establishing FP is current local 1

No stable case was found where compiler-created locals precede the unique FP: current localloc roots allocate FP as the first declared i32 local after parameters, and funclets receive FP as a parameter before declared locals. Arity can still move the root localloc FP index, so these indices are deliberately not a contract.

C1: optimized tracked-variable gate

OptimizedTrackedVariables(int left, int right) is [NoInlining] only and exercises FullOpts/tracked liveness. Its IL declares sum and difference; difference is optimized away, while sum has two exact control-flow ranges.

Complete output:

var 0 Parameter 0 [0x00,0x3C) VLT_REG $1 i32
var 1 Parameter 1 [0x00,0x3C) VLT_REG $2 i32
var 1 Parameter 1 [0x59,0x74) VLT_REG $2 i32
var 2 Local 0     [0x2F,0x51) VLT_REG $4 i32
var 2 Local 0     [0x59,0x74) VLT_REG $4 i32

There is no record for optimized-away IL local 1. This proves the feature is active on the production optimized path, not only behind OptimizationDisabled().

Mutation proof: suppressing optimized non-parameter live-range starts was confirmed in scopeinfo.cpp; WasmWebcilModule became red and crossgen2 detected invalid optimized debug ranges in OptimizedTrackedVariables. Restoring the path returned the full suite to green.

C2: same-type slot identity and legitimate null

GcSlotIdentity creates two distinct movable GcMarker instances with sentinel values 17 and 29, plus a separately stored legitimate-null GcMarker local. IL opcodes are asserted to bind 17 to local 0, 29 to local 1, and ldnull to local 2.

Complete output:

var 0 Local 0 [0x36,0x2B1) VLT_STK base=2 offset=0x48  (marker 17)
var 1 Local 1 [0x36,0x2B1) VLT_STK base=2 offset=0x44  (marker 29)
var 2 Local 2 [0x36,0x2B1) VLT_STK base=2 offset=0x40  (legitimate null)
var 3 Local 3 [0x36,0x2B1) VLT_STK base=2 offset=0x3C  (result)

The two non-null offsets are distinct. All three reference offsets also exist as GC_FRAMEREG_REL pinned/untracked GC slots. The GC.Collect call at native 0x18C lies inside all three reference ranges.

Mutation proof: swapping only the expected 17/29 offsets (0x48 and 0x44) made the exact named test fail; restoring the identity mapping returned green.

Current limitation: the minopts wasm siWasmOpenedScopes latch opens each synthesized source scope once and closes it at method end. Consequently these distinct IL locals share the exact [0x36,0x2B1) end range. Slot/value identity is covered here; disjoint lexical range ends require a focused producer follow-up rather than a semantic change hidden in this PR.

Existing hard cases

Portable-entry-pointer exclusion

Stacked validation found hidden ABI argument $3 reported as source local 0. The fix records lvaWasmPortableEntryPtrArg, maps it to UNKNOWN_ILNUM, and accounts for it in reverse local-number mapping.

Frame-resident GC local across a funclet

GcLocalAcrossFinally allocates a real GcMarker, enters a finally, calls GC.Collect, and keeps the marker alive afterward. IL proves local 0 is Webcil.WasmWebcilModule+GcMarker; debug info reports VLT_STK base=2 offset=0x24; GC info independently reports GC_FRAMEREG_REL+0x24; and the GC call at native 0x161 is inside its live range.

The root frame currently accesses the slot through its SP/FP alias. The funclet uses its distinct parent-FP parameter to load offset 0x24. This remains a suitable #133890 live specimen, but cDAC stack-variable resolution uses reconstructed absolute FP rather than hardcoding either engine-local index.

Existing exact tuples

AddDoubles retains its exact two-parameter register-to-stack transition oracle, and SumWithFinally retains its exact parameter/local stack tuples and no-funclet-DebugInfo assertion.

Stack status and ownership

#132650 merged as 09b4a18f8a6ce1f8eea9636e497a07bd7c50d887. This branch was rewritten onto main at 608580557f7c32e9787164ad78b889108d04faa5 and contains six producer-side commits only.

No src/native/managed/cdac/** reader or implementation files are included. The cDAC consumer is dependent draft #133890.

Validation

• Native clr+libs+host baseline before this matrix: 0 warnings / 0 errors, 10m06s.
• Checked browser-wasm clr+libs after the stack-base invariants: 0 warnings / 0 errors, 11m21s.
• Final browser wasm R2R suite: 85 passed / 0 failed / 37 skipped / 122 total.
• C1 optimized-path mutation: named test red; restored green.
• C2 17/29 slot-swap mutation: 1 failed, restored green.
• Wrong presumed funclet FP local mutation (1 to 3): 1 failed with missing exact wasm instruction sequence, restored green.
• Previous mutations remain non-vacuous: packed local $1 to $2, GC stack base 2 to 3, and encoding value-count 7 to 6 all fail their respective gates.
• Descriptor scrape remains exactly shift 29, count 7.
• JIT formatting and git diff --check are clean.

Final kept artifacts:

artifacts/bin/ILCompiler.ReadyToRun.Tests/Checked/Checked_CLR/browser-wasm/R2RTestCases/WasmWebcilModule/619d979d/IL/WasmWebcilModule.dll
artifacts/bin/ILCompiler.ReadyToRun.Tests/Checked/Checked_CLR/browser-wasm/R2RTestCases/WasmWebcilModule/619d979d/CG2/WasmWebcilModule.wasm
artifacts/pr133086-final-matrix-objdump.txt
artifacts/pr133086-final-OptimizedTrackedVariables-r2rdump.txt
artifacts/pr133086-final-GcSlotIdentity-r2rdump.txt

Note

This pull request description was updated with the assistance of GitHub Copilot.

[azure-pipelines]

Azure Pipelines:
Successfully started running 5 pipeline(s).
11 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[AndyAyersMS]

Does this handle describing locals that are on the linear stack? Last I looked those SP/FP based encodings were wonky for Wasm.

Note the exact Wasm locals that hold SP/FP can vary and may even vary between main method and its funclets, which I doubt we can encode.

An easy test for this is to look at any GC-typed local, these are always on the linear stack.

[davidwrighton]

@lewing, what value does this debugging data provide? Given my understanding that debugging is likely to only be supported on mostly interpreted scenarios, why should we make this correct for R2R scenarios. (I expect that nativeaot will make good use of this data, so I think overall its goodness, but I don't see why its particularly useful for R2RDump.)

[lewing]

It came out of the DWARF discussion and I'm working on something in the nesm debugger and I'm trying to plumb out more info, it is isn't meant to be user facing currently.

[lewing]

I opened #133890 (which includes these commits) with cDAC consumer side changes

[azure-pipelines]

Azure Pipelines:
Successfully started running 7 pipeline(s).
9 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Copilot review overview

🔵 Needs a closer look

scopeinfo.cpp has unresolved issues with BAD_IL_OFFSET handling and method-wide scope latching that can produce incorrect ranges.

Review tier: Lite
Findings: None

What changed in this PR

Preserves WebAssembly ReadyToRun variable debug information and defines register and stack-location contracts for diagnostic readers.

Changes:

• Emits optimized and unoptimized WASM variable locations while excluding hidden ABI arguments.
• Centralizes packed register encoding and publishes target metadata.
• Adds R2R validation for locals, GC roots, stack frames, funclets, and localloc.

File	Reviewed changes
src/​coreclr/​vm/​datadescriptor/​datadescriptor.inc	Publishes WASM encoding metadata.
src/​coreclr/​tools/​aot/​ILCompiler.Reflection.ReadyToRun/​DebugInfo.cs	Decodes packed WASM registers.
src/​coreclr/​tools/​aot/​ILCompiler.ReadyToRun.Tests/​TestCases/​Webcil/​WasmWebcilModule.cs	Adds WASM debug-information test cases.
src/​coreclr/​tools/​aot/​ILCompiler.ReadyToRun.Tests/​TestCases/​R2RTestSuites.cs	Validates exact debug-information records.
src/​coreclr/​jit/​scopeinfo.cpp	Emits WASM variable ranges and locations; requires offset-sentinel guarding and per-block scope closure.
src/​coreclr/​jit/​registeropswasm.cpp	Uses centralized register encoding constants.
src/​coreclr/​jit/​lclvars.cpp	Excludes hidden portable-entry arguments.
src/​coreclr/​jit/​compiler.h	Tracks the portable-entry argument index.
src/​coreclr/​jit/​compiler.cpp	Enables WASM scope information.
src/​coreclr/​jit/​codegen.h	Adds WASM scope-tracking state.
src/​coreclr/​inc/​cordebuginfo.h	Defines WASM debug-register encoding constants.
docs/​design/​datacontracts/​DebugInfo.md	Documents encoding and stack-base contracts.

[lewing]

#134689 will remove this information by default