Use Virtual IPs in R2R format (#128423)

## Summary

This PR converts the WASM ReadyToRun format to use virtual IPs for
addressing instead of direct function table indices, and updates R2RDump
to correctly handle the new format.

## Changes

### RUNTIME_FUNCTION format changes
- **BeginAddress** now encodes a virtual IP (bits 30:0) and an
**IsFunclet** flag (bit 31)
- A sentinel entry (0xFFFFFFFF) followed by a 4-byte **min function
table index** is appended after the RUNTIME_FUNCTION table entries
- **UnwindInfo** now encodes frame size (ULEB128) and virtual IP count /
2 (ULEB128)

### R2RDump fixes
- Mask bit 31 (funclet flag) when parsing WASM RUNTIME_FUNCTION entries
- WASM-specific display showing VirtualIP, IsFunclet flag, and size in
virtual IPs
- Dump the min function table index after the RuntimeFunctions table
sentinel
- Fix WASM disassembly function resolution: virtual IP → table index
(via minFunctionTableIndex + runtimeFunctionId) → global function index
(via elem section) → code section index (subtract imported function
count)
- Handle both active (flags==0) and passive (flags==1) WASM elem
segments

### ReadyToRun format documentation
- Added WASM-specific RUNTIME_FUNCTION section to readytorun-format.md
- Documented UnwindInfo encoding, sentinel entry, and min function table
index trailer

## Known Issues

- **GCDecoder** is not yet handled correctly for the new WASM format.
This will be addressed in a follow-up PR.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: davidwrighton

docs/design/coreclr/botr/readytorun-format.md

@@ -413,6 +413,36 @@ which encodes an extra 4-byte representing the end RVA of the unwind info blob.
 |      4 |    4 | Unwind info end RVA (1 plus RVA of last byte)
 |      8 |    4 | GC info start RVA
 
+### RUNTIME_FUNCTION (wasm, size = 8 bytes)
+
+On WebAssembly, the `RUNTIME_FUNCTION` uses a virtual IP as the `BeginAddress` rather than an RVA
+into the image. The high bit of the `BeginAddress` field indicates whether the entry represents a
+funclet (1) or a main method body (0). The remaining 31 bits encode the virtual IP of the start of
+the function or funclet.
+
+| Offset | Size | Value
+|-------:|-----:|:-----
+|      0 |    4 | Virtual IP (bits 30:0) | IsFunclet flag (bit 31)
+|      4 |    4 | UnwindData RVA (GC info follows immediately after the unwind blob)
+
+The table is terminated by a sentinel entry with all bits set (`0xFFFFFFFF`), followed by a 4-byte
+value containing the minimum WebAssembly function table index for the image.
+
+### UnwindInfo (wasm)
+
+On WebAssembly, the unwind info blob associated with each `RUNTIME_FUNCTION` entry is encoded as
+two consecutive ULEB128 values:
+
+| Order | Encoding | Value
+|------:|:---------|:-----
+|     1 | ULEB128  | Frame size in bytes (the number of bytes to unwind from the stack)
+|     2 | ULEB128  | Virtual IP count divided by 2 (the number of virtual IPs logically present in the function, halved)
+
+The virtual IP count (after multiplying by 2) gives the span of virtual IPs covered by this
+function or funclet. All virtual IPs are forced to even numbers so that the runtime can force all virtual
+ips to have odd numbers and fit into the address space in a manner which cannot conflict with either interpreter
+IPs or PortableEntryPoint structures.
+
 ## ReadyToRunSectionType.MethodDefEntryPoints
 
 This section contains a native format sparse array (see 4 Native Format) that maps methoddef rows to

src/coreclr/clrdefinitions.cmake

@@ -163,6 +163,10 @@ add_definitions(-DFEATURE_READYTORUN)
 
 set(FEATURE_READYTORUN 1)
 
+if(NOT CLR_CMAKE_TARGET_ARCH_WASM)
+  add_compile_definitions(FEATURE_COLD_R2R_CODE)
+endif()
+
 if(FEATURE_REJIT)
   add_compile_definitions(FEATURE_REJIT)
 endif()

src/coreclr/inc/clrnt.h

@@ -521,7 +521,7 @@ RtlVirtualUnwind(
 #define UNW_FLAG_EHANDLER               0x1             /* filter handler */
 #define UNW_FLAG_UHANDLER               0x2             /* unwind handler */
 
-inline PEXCEPTION_ROUTINE
+PEXCEPTION_ROUTINE
 RtlVirtualUnwind (
     _In_ DWORD HandlerType,
     _In_ DWORD ImageBase,
@@ -531,24 +531,18 @@ RtlVirtualUnwind (
     _Out_ PVOID *HandlerData,
     _Out_ PDWORD EstablisherFrame,
     __inout_opt PT_KNONVOLATILE_CONTEXT_POINTERS ContextPointers
-    )
-{
-    PORTABILITY_ASSERT("The function RtlVirtualUnwind is not implemented on wasm");
-    return nullptr;
-}
+    );
+
+UINT32 DecodeULEB128AsU32(PTR_BYTE* ppData);
 
-FORCEINLINE
 ULONG
 RtlpGetFunctionEndAddress (
     _In_ PT_RUNTIME_FUNCTION FunctionEntry,
     _In_ TADDR ImageBase
-    )
-{
-    PORTABILITY_ASSERT("The function RtlpGetFunctionEndAddress is not implemented on wasm");
-    return 0;
-}
+    );
 
-#define RUNTIME_FUNCTION__BeginAddress(FunctionEntry)               ((FunctionEntry)->BeginAddress)
+#define RUNTIME_FUNCTION__IsFunclet(FunctionEntry) ((FunctionEntry)->BeginAddress & 0x80000000)
+#define RUNTIME_FUNCTION__BeginAddress(FunctionEntry)               ((FunctionEntry)->BeginAddress & 0x7FFFFFFF)
 #define RUNTIME_FUNCTION__SetBeginAddress(FunctionEntry,address)    ((FunctionEntry)->BeginAddress = (address))
 
 #define RUNTIME_FUNCTION__EndAddress(FunctionEntry, ImageBase)      (RtlpGetFunctionEndAddress(FunctionEntry, (ULONG64)(ImageBase)))

src/coreclr/tools/Common/Compiler/ObjectWriter/Dwarf/DwarfHelper.cs

@@ -103,7 +103,9 @@ public static void WritePaddedSLEB128(Span<byte> bytes, long value)
             }
         }
 
-        public static ulong ReadULEB128(ReadOnlySpan<byte> buffer)
+        public static ulong ReadULEB128(ReadOnlySpan<byte> buffer) => ReadULEB128(buffer, out _);
+
+        public static ulong ReadULEB128(ReadOnlySpan<byte> buffer, out int bytesRead)
         {
             ulong value = 0;
             byte @byte;
@@ -116,10 +118,13 @@ public static ulong ReadULEB128(ReadOnlySpan<byte> buffer)
                 shift += 7;
             } while ((@byte & 0x80) != 0);
 
+            bytesRead = pos;
             return value;
         }
 
-        public static long ReadSLEB128(ReadOnlySpan<byte> buffer)
+        public static long ReadSLEB128(ReadOnlySpan<byte> buffer) => ReadSLEB128(buffer, out _);
+
+        public static long ReadSLEB128(ReadOnlySpan<byte> buffer, out int bytesRead)
         {
             ulong value = 0;
             byte @byte;
@@ -135,6 +140,7 @@ public static long ReadSLEB128(ReadOnlySpan<byte> buffer)
             if (((ulong)shift < (8 * sizeof(ulong))) && ((@byte & 0x40) != 0))
                 value |= unchecked((ulong)(long)-1) << shift;
 
+            bytesRead = pos;
             return unchecked((long)value);
         }
     }

src/coreclr/tools/Common/Compiler/ObjectWriter/WasmObjectWriter.cs

@@ -928,31 +928,27 @@ private unsafe void ResolveRelocations(int sectionIndex, MemoryStream sectionStr
                             break;
                         }
 
-                        // TODO-Wasm: None of the IMAGE_REL type relocs should occur in Wasm
-                        // code, and we should add asserts for this once we've updated the necessary
-                        // dependency nodes to emit the proper reloc type on Wasm.
                         case RelocType.IMAGE_REL_BASED_ABSOLUTE:
                             // No action required
                             break;
 
                         case RelocType.IMAGE_REL_BASED_DIR64:
                         case RelocType.IMAGE_REL_BASED_HIGHLOW:
-                            //       Debug.Assert(betweenWebcilSections);
                             // This is an ImageBase-relative value in PE, but our image base
                             // for Webcil is virtual address 0
+                            Debug.Assert(symbolWebcilSection != null);
                             Relocation.WriteValue(reloc.Type, pData, virtualSymbolImageOffset + 0 + addend);
                             break;
                         case RelocType.IMAGE_REL_BASED_ADDR32NB:
-                            //       Debug.Assert(betweenWebcilSections);
+                            Debug.Assert(symbolWebcilSection != null);
                             Relocation.WriteValue(reloc.Type, pData, virtualSymbolImageOffset + addend);
                             break;
                         case RelocType.IMAGE_REL_BASED_REL32:
                         case RelocType.IMAGE_REL_BASED_RELPTR32:
-                            //      Debug.Assert(betweenWebcilSections);
+                            Debug.Assert(symbolWebcilSection != null);
                             Relocation.WriteValue(reloc.Type, pData, virtualSymbolImageOffset - (virtualRelocOffset + relocLength) + addend);
                             break;
                         case RelocType.IMAGE_REL_FILE_ABSOLUTE:
-                            //       Debug.Assert(betweenWebcilSections && symbolWebcilSection != null);
                             Debug.Assert(symbolWebcilSection != null);
                             long fileOffset = symbolWebcilSection.Header.PointerToRawData + definedSymbol.Value;
                             Relocation.WriteValue(reloc.Type, pData, fileOffset + addend);

src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ExceptionInfoLookupTableNode.cs

@@ -118,10 +118,20 @@ public override ObjectData GetData(NodeFactory factory, bool relocsOnly = false)
             // Add the symbol representing this object node
             exceptionInfoLookupBuilder.AddSymbol(this);
 
+            bool isWasm = factory.Target.Architecture == TargetArchitecture.Wasm32;
+
             // First, emit the actual EH records in sequence and store map from methods to the EH record symbols
             for (int index = 0; index < _methodNodes.Count; index++)
             {
-                exceptionInfoLookupBuilder.EmitReloc(_methodNodes[index], RelocType.IMAGE_REL_BASED_ADDR32NB, -factory.Target.CodeDelta);
+                if (isWasm)
+                {
+                    // For WASM, we use a virtual IP in the table here instead of a method pointer, so that the runtime can perform a binary search based on the virtual IP. The virtual IP is emitted as a plain u32 (not a reloc).
+                    exceptionInfoLookupBuilder.EmitUInt(factory.RuntimeFunctionsTable.GetWasmVirtualIP(_methodNodes[index], 0));
+                }
+                else
+                {
+                    exceptionInfoLookupBuilder.EmitReloc(_methodNodes[index], RelocType.IMAGE_REL_BASED_ADDR32NB, -factory.Target.CodeDelta);
+                }
                 exceptionInfoLookupBuilder.EmitReloc(_ehInfoNode, RelocType.IMAGE_REL_BASED_ADDR32NB, _ehInfoOffsets[index]);
             }
 

src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ReadyToRunHeaderNode.cs

@@ -192,8 +192,8 @@ public override ObjectData GetData(NodeFactory factory, bool relocsOnly = false)
                 builder.EmitReloc(item.StartSymbol, RelocType.IMAGE_REL_BASED_ADDR32NB, rvaDelta);
 
                 // The header entry for the runtime functions table should not include the 4 byte 0xffffffff sentinel
-                // value in the covered range.
-                int delta = item.Id == ReadyToRunSectionType.RuntimeFunctions ? RuntimeFunctionsTableNode.SentinelSizeAdjustment : 0;
+                // value in the covered range. For WASM, also excludes the trailing min table index.
+                int delta = item.Id == ReadyToRunSectionType.RuntimeFunctions ? factory.RuntimeFunctionsTable.SentinelSizeAdjustment : 0;
                 builder.EmitReloc(item.StartSymbol, RelocType.IMAGE_REL_SYMBOL_SIZE, delta);
 
                 count++;

src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/RuntimeFunctionsTableNode.cs

@@ -4,6 +4,7 @@
 using System;
 using System.Collections.Generic;
 
+using ILCompiler.ObjectWriter;
 using Internal.Text;
 using Internal.TypeSystem;
 
@@ -15,6 +16,7 @@ public class RuntimeFunctionsTableNode : HeaderTableNode
     {
         private List<MethodWithGCInfo> _methodNodes;
         private Dictionary<MethodWithGCInfo, int> _insertedMethodNodes;
+        private Dictionary<(MethodWithGCInfo method, int funcletIdx), uint> _methodToVirtualIP;
         private readonly NodeFactory _nodeFactory;
         private int _tableSize = -1;
 
@@ -61,6 +63,58 @@ private void LayoutRuntimeFunctions()
             }
         }
 
+        public uint GetWasmVirtualIP(MethodWithGCInfo lookupMethod, int lookupFrameIndex)
+        {
+            bool isWasm = _nodeFactory.Target.Architecture == TargetArchitecture.Wasm32;
+
+            if (!isWasm)
+            {
+                // For non-WASM targets, virtual IPs are not used, so throw
+                throw new InvalidOperationException("Virtual IPs are not used on non-WASM targets.");
+            }
+
+            if (_methodToVirtualIP != null)
+            {
+                return _methodToVirtualIP[(lookupMethod, lookupFrameIndex)];
+            }
+
+            if (_methodNodes == null)
+            {
+                LayoutRuntimeFunctions();
+            }
+
+            Dictionary<(MethodWithGCInfo method, int funcletIdx), uint> methodToVirtualIP = new ();
+
+            // For WASM, track virtual IP index for each RUNTIME_FUNCTION entry
+            uint currentVirtualIP = 0;
+
+            foreach (MethodWithGCInfo method in _methodNodes)
+            {
+                for (int frameIndex = 0; frameIndex < method.FrameInfos.Length; frameIndex++)
+                {
+                    FrameInfo frameInfo = method.FrameInfos[frameIndex];
+                    methodToVirtualIP.Add((method, frameIndex), currentVirtualIP);
+
+                    // Advance the virtual IP by the number of virtual IPs for this frame
+                    uint virtualIPCount = GetFunctionLocalVirtualIPCountFromUnwindBlob(frameInfo.BlobData);
+                    currentVirtualIP += virtualIPCount;
+                }
+            }
+
+            _methodToVirtualIP = methodToVirtualIP;
+            return _methodToVirtualIP[(lookupMethod, lookupFrameIndex)];
+        }
+
+        /// <summary>
+        /// Read the virtual IP count from a WASM unwind blob.
+        /// The blob format is: ULEB128(frameSize) followed by ULEB128(virtualIPCount).
+        /// </summary>
+        private static uint GetFunctionLocalVirtualIPCountFromUnwindBlob(byte[] blobData)
+        {
+            DwarfHelper.ReadULEB128(blobData.AsSpan(), out int offset); // skip frame size
+            return (uint)DwarfHelper.ReadULEB128(blobData.AsSpan(offset), out _) * 2; // Multiply by 2 to force all virtual IPs to be an even number.
+        }
+
         public override ObjectData GetData(NodeFactory factory, bool relocsOnly = false)
         {
             if (relocsOnly)
@@ -78,6 +132,8 @@ public override ObjectData GetData(NodeFactory factory, bool relocsOnly = false)
             uint runtimeFunctionIndex = 0;
             List<uint> mapping = new List<uint>();
 
+            bool isWasm = _nodeFactory.Target.Architecture == TargetArchitecture.Wasm32;
+
             for (int cold = 0; cold < 2; cold++)
             {
                 foreach (MethodWithGCInfo method in _methodNodes)
@@ -124,9 +180,10 @@ public override ObjectData GetData(NodeFactory factory, bool relocsOnly = false)
                             symbol = method;
                         }
 
-                        if (_nodeFactory.Target.Architecture == TargetArchitecture.Wasm32)
+                        if (isWasm)
                         {
-                            runtimeFunctionsBuilder.EmitReloc(symbol, RelocType.WASM_TABLE_INDEX_I32, frameIndex);
+                            // Set high bit for frame indices greater than 0 to indicate that the RUNTIME_FUNCTION is a funclet
+                            runtimeFunctionsBuilder.EmitUInt(GetWasmVirtualIP(method, frameIndex) | (frameIndex != 0 ? 0x80000000 : 0));
                         }
                         else
                         {
@@ -157,14 +214,29 @@ public override ObjectData GetData(NodeFactory factory, bool relocsOnly = false)
             // Emit sentinel entry
             runtimeFunctionsBuilder.EmitUInt(~0u);
 
+            if (isWasm)
+            {
+                // After sentinel, emit a WASM_TABLE_INDEX_I32 reloc pointing to the first
+                // compiled method. This records the min function table index in the file.
+                if (_methodNodes.Count > 0)
+                {
+                    runtimeFunctionsBuilder.EmitReloc(_methodNodes[0], RelocType.WASM_TABLE_INDEX_I32, delta: 0);
+                }
+                else
+                {
+                    // If there are no compiled methods, emit a 0 for the min table index.
+                    runtimeFunctionsBuilder.EmitUInt(0);
+                }
+            }
+
             _tableSize = runtimeFunctionsBuilder.CountBytes;
             return runtimeFunctionsBuilder.ToObjectData();
         }
 
         /// <summary>
         /// Returns the runtime functions table size and excludes the 4 byte sentinel entry at the end (used by
         /// the runtime in NativeUnwindInfoLookupTable::LookupUnwindInfoForMethod) so that it's not treated as
-        /// part of the table itself.
+        /// part of the table itself. For WASM, also excludes the trailing 4-byte min table index.
         /// </summary>
         public int TableSizeExcludingSentinel
         {
@@ -179,6 +251,7 @@ public int TableSizeExcludingSentinel
 
         public override int ClassCode => (int)ObjectNodeOrder.RuntimeFunctionsTableNode;
 
-        internal const int SentinelSizeAdjustment = -4;
+        internal int SentinelSizeAdjustment =>
+            _nodeFactory.Target.Architecture == TargetArchitecture.Wasm32 ? -8 : -4;
     }
 }

src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRunCodegenNodeFactory.cs

@@ -897,9 +897,12 @@ public void AttachToDependencyGraph(DependencyAnalyzerBase<NodeFactory> graph, I
             RuntimeFunctionsGCInfo = new RuntimeFunctionsGCInfoNode();
             graph.AddRoot(RuntimeFunctionsGCInfo, "GC info is always generated");
 
-            DelayLoadMethodCallThunks = new SymbolNodeRange("DelayLoadMethodCallThunkNodeRange");
-            graph.AddRoot(DelayLoadMethodCallThunks, "DelayLoadMethodCallThunks header entry is always generated");
-            Header.Add(Internal.Runtime.ReadyToRunSectionType.DelayLoadMethodCallThunks, DelayLoadMethodCallThunks);
+            if (!Target.IsWasm)
+            {
+                DelayLoadMethodCallThunks = new SymbolNodeRange("DelayLoadMethodCallThunkNodeRange");
+                graph.AddRoot(DelayLoadMethodCallThunks, "DelayLoadMethodCallThunks header entry is always generated");
+                Header.Add(Internal.Runtime.ReadyToRunSectionType.DelayLoadMethodCallThunks, DelayLoadMethodCallThunks);
+            }
 
             ExceptionInfoLookupTableNode exceptionInfoLookupTableNode = new ExceptionInfoLookupTableNode(this);
             Header.Add(Internal.Runtime.ReadyToRunSectionType.ExceptionInfo, exceptionInfoLookupTableNode);

src/coreclr/tools/aot/ILCompiler.Reflection.ReadyToRun/DebugInfo.cs

@@ -87,7 +87,7 @@ public static string GetPlatformSpecificRegister(Machine machine, int regnum)
                 case Machine.RiscV64:
                     return ((RiscV64.Registers)regnum).ToString();
                 case WasmMachine.Wasm32:
-                    throw new NotImplementedException($"No implementation for machine type {machine}.");
+                    return $"NYI '{regnum}'"; // WASM-TODO Implement this correctly.
                 default:
                     throw new NotImplementedException($"No implementation for machine type {machine}.");
             }