[RyuJIT Wasm] WasmObjectWriter Webcil Envelope Support by adamperlin · Pull Request #125468 · dotnet/runtime

adamperlin · 2026-03-12T00:08:36Z

This PR implements WebCIL envelope support for the WasmObjectWriter. It builds up the data segment and assigns RVAs/Raw data addresses to each Webcil section as a first pass. As a second pass, it emits the proper headers and sections, and and also implements relocation resolution for IMAGE_BASE* type relocs that may appear in Webcil data sections using the pre-assigned section addresses.

The WebcilDataSegment is emitted as two Wasm data segments according to the Webcil spec like so:

  (data "\0f\00\00\00") ;; data segment 0: payload size as a 4 byte LE uint32, 
                        ;; may have extra padding so that the next segment is properly aligned
  (data "payload\cc")  ;; data segment 1: webcil payload (start is 4 byte aligned)
      | webcil header
      __________________________
      | section header (1)
      | ...
      | section header (n)
      ___________________________
      | section 1 (align 16-byte)
      ___________________________
      | ...
      ___________________________
      | section n (align 16-byte)
      ___________________________

The PR also adds a simple validator program which uses Microsoft.NET.Webcil.Validator. I am fine if we don't want to include this or want this refactored, I just included it in case it would be useful to have as I used it for testing purposes.

…-object-writer-webcil

Stemming from incorrect start address calculation for first data section, and passing in wrong section start pointer Enable emitting AssemblyStubNode's and SymbolRangeNodes on Wasm into data section (contents still not correct)

… header

…gs and add associated asserts

Move WasmFunction type definition to a more suitable spot (and fix ilc compilation)

…ersion global

…-object-writer-webcil

Copilot

Pull request overview

Adds initial WebCIL “envelope” emission support to the CoreCLR AOT Wasm object writer so the runtime can locate PE/CLI header data and debug directory data inside a WebAssembly binary.

Changes:

Introduces WebcilHeader / WebcilSectionHeader encoders and wires Webcil.cs into ILCompiler projects.
Extends WasmObjectWriter to build a flat WebCIL segment, resolve PE-style relocations into it, and emit it as passive Wasm data segments (with DataCount + exported helpers/globals).
Adjusts dependency tracking so Wasm methods get explicit signature nodes, and updates some Wasm-specific section placement logic.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
src/coreclr/tools/aot/ILCompiler.ReadyToRun/ILCompiler.ReadyToRun.csproj	Adds `Webcil.cs` to the ReadyToRun tool build.
src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/MethodWithGCInfo.cs	Adds a Wasm32-only dependency on `WasmTypeNode` for explicit signatures.
src/coreclr/tools/aot/ILCompiler.Compiler/ILCompiler.Compiler.csproj	Adds `Webcil.cs` to the compiler tool build.
src/coreclr/tools/Common/Compiler/ObjectWriter/Webcil.cs	New: encodes WebCIL header + section headers.
src/coreclr/tools/Common/Compiler/ObjectWriter/WasmObjectWriter.cs	Major: builds/emits WebCIL payload as Wasm data segments; adds DataCount/Global handling and relocation resolution changes.
src/coreclr/tools/Common/Compiler/ObjectWriter/WasmNative.cs	Adds `WasmGlobal` encoding support.
src/coreclr/tools/Common/Compiler/ObjectWriter/WasmInstructions.cs	Adds instruction helpers needed for emitted Wasm stubs (locals + memory.init).
src/coreclr/tools/Common/Compiler/ObjectWriter/ObjectWriter.cs	Adds Wasm-related adjustments and several debug `Console.WriteLine` statements during emission/relocation.
src/coreclr/tools/Common/Compiler/DependencyAnalysis/Target_Wasm/WasmTypes.cs	Formatting tweak in `WasmValueType`.
src/coreclr/tools/Common/Compiler/DependencyAnalysis/Relocation.cs	Exposes `WASM_PADDED_RELOC_SIZE_32` publicly for reuse.
src/coreclr/tools/Common/Compiler/DependencyAnalysis/AssemblyStubNode.cs	Places `AssemblyStubNode` into read-only data for Wasm targets.

You can also share your feedback on Copilot code review. Take the survey.

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

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

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

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

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

…or webcil sections and check alignment constraints in BuildWebcilDataSegment()

…omments

Copilot

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 5 comments.

You can also share your feedback on Copilot code review. Take the survey.

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

...Microsoft.NET.WebAssembly.Webcil.Validator/Microsoft.NET.WebAssembly.Webcil.Validator.csproj

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

…CInfo

Copilot

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

src/coreclr/tools/Common/Compiler/ObjectWriter/ObjectWriter.cs:389

This change makes all ISymbolRangeNode handling unconditional (previously gated by LayoutMode == CodeDataLayout.Unified). If the original condition was important for non-Wasm backends or for separate-layout scenarios, this risks changing behavior beyond Wasm. Consider restricting this to the Wasm path (or otherwise documenting why it is now correct for all targets/layout modes).

                // TODO-WASM: emit symbol ranges properly when code and data are separated
                // Right now we still need to determine placements for some traditionally text-placed nodes,
                // such as DebugDirectoryEntryNode and AssemblyStubNode
                if (depNode is ISymbolRangeNode symbolRange)
                {
                    symbolRangeNodes.Add(symbolRange);
                    continue;
                }

You can also share your feedback on Copilot code review. Take the survey.

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

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

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…m/Webcil.cs and unify type definition with WasmObjectWriter

…-object-writer-webcil

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

src/coreclr/tools/Common/Compiler/ObjectWriter/ObjectWriter.cs:456

AssemblyStubNode is no longer skipped for Wasm during object emission, but the Wasm implementations of several AssemblyStubNode derivatives still throw NotImplementedException (e.g. Target_Wasm/WasmReadyToRunHelperNode.cs). If any of these nodes are present (they’re created by NodeFactory.CreateReadyToRunHelperNode), this change will cause the Wasm/R2R build to fail at emit time. Consider restoring the Wasm AssemblyStubNode skip until the Wasm stub emitters are implemented, or implement the required Wasm emitters before allowing these nodes to be emitted.

                if (node is INodeWithTypeSignature codeNode && _nodeFactory.Target.IsWasm)
                {
                    Debug.Assert(codeNode.Signature != null, $"Wasm code node {codeNode.GetType()} has null signature");

                    // TODO: eventually this should check IMethodCodeNodeWithTypeSignature
                    // Once we have signatures implemented for all code-carrying nodes
                    if (node is IMethodBodyNode methodNode)
                    {
                        // Record only information we can get from the MethodDesc here. The actual
                        // body will be emitted by the call to EmitData() at the end
                        // of this loop iteration.
                        RecordMethodDeclaration(codeNode, methodNode.Method);
                    }
                }

You can also share your feedback on Copilot code review. Take the survey.

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

src/coreclr/tools/aot/ILCompiler.ReadyToRun/ILCompiler.ReadyToRun.csproj

src/tasks/Microsoft.NET.WebAssembly.Webcil.Validator/Program.cs

...Microsoft.NET.WebAssembly.Webcil.Validator/Microsoft.NET.WebAssembly.Webcil.Validator.csproj

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

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

You can also share your feedback on Copilot code review. Take the survey.

src/coreclr/tools/aot/ILCompiler.ReadyToRun/ILCompiler.ReadyToRun.csproj

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

+                            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);
+                            break;


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

        // TODO-WASM: Consider alignment needs for data sections
        public static readonly ObjectNodeSection DataSection = new ObjectNodeSection("wasm.data", SectionType.Writeable, needsAlign: false);
+        public static readonly ObjectNodeSection DataCountSection = new ObjectNodeSection("wasm.datacount", SectionType.ReadOnly, needsAlign: false);
        public static readonly ObjectNodeSection CombinedDataSection = new ObjectNodeSection("wasm.alldata", SectionType.Writeable, needsAlign: false);


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

You can also share your feedback on Copilot code review. Take the survey.

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

        protected internal override void UpdateSectionAlignment(int sectionIndex, int alignment)
        {
-            // This is a no-op for now under Wasm
+            WebcilSection section = _sections[sectionIndex] as WebcilSection;
+            // We should only be updating the alignment of Webcil sections; Wasm-native sections should
+            // not have alignment constraints.
+            Debug.Assert(section != null, $"Section: {sectionIndex} is not a WebcilSection");
+            if (section == null)
+            {
+                return;
+            }
+
+            section.MinAlignment = Math.Max(section.MinAlignment, alignment);
        }


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

@@ -468,19 +842,22 @@ private void WriteImports()
                if (import.Index.HasValue)
                {
                    int assigned = assignedImportIndices[(int)import.Kind];


pavelsavara

LGTM.

I wonder if we can add smoke test.
Produce trivial IL-only webcil with the object writer and test it with coreCLR loader.
Even manual/unmerged test doing this would be nice.

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

adamperlin · 2026-03-18T18:11:29Z

LGTM.

I wonder if we can add smoke test. Produce trivial IL-only webcil with the object writer and test it with coreCLR loader. Even manual/unmerged test doing this would be nice.

I have validated that the basic structure is correct for a simple example using the existing Microsoft.NET.WebAssembly.WebcilReader (and a simple driver program that calls the reader), but I'd definitely like to have a smoke test! What would it take to use the CoreCLR loader at the moment?

davidwrighton

LGTM modulo comments.

davidwrighton · 2026-03-18T18:40:15Z

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

-            foreach (var symbolicRelocation in relocationList)
-            {
-                if (!_definedSymbols.ContainsKey(symbolicRelocation.SymbolName))
+                foreach (var symbolicRelocation in relocationList)


Add another set of curly braces here for clarity.

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

davidwrighton · 2026-03-18T18:59:16Z

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

+
+                uint rawSectionSize = (uint)webcilSection.Stream.Length;
+                uint alignedSectionSize = (uint)AlignmentHelper.AlignUp((int)rawSectionSize, (int)WebcilSectionAlignment);
+                uint virtualSize = alignedSectionSize;


Needs a comment that virtualSize needs to be the same as alignedSectionSize so that RVA's can be constant, and that loading the Webcil image doesn't require interesting layout in memory.

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

pavelsavara · 2026-03-18T19:17:47Z

What would it take to use the CoreCLR loader at the moment?

Just produce valid WebCIL 1 IL-only assembly (no R2R). I think you are close to it, right ?

…mperlin/runtime into adamperlin/wasm-object-writer-webcil

adamperlin added 11 commits February 27, 2026 12:34

WIP: build webcil data segment

42a21db

Merge branch 'main' of github.com:dotnet/runtime into adamperlin/wasm…

0481359

…-object-writer-webcil

WIP resolve relocs + emit webcil data segment

d0519e6

First pass at building up Webcil data segment and resolving relocations

0e0f4e9

Resolve Cor header/debug directory symbols + size and place in webcil…

4ad2dc8

… header

Add some instructions to support Webcil header/size getters

81ee517

Add webcil payload/size getters to output module; fix some padding bu…

95f991f

…gs and add associated asserts

Add inter data segment padding support (needed for Webcil)

509c5f6

Move WasmFunction type definition to a more suitable spot (and fix ilc compilation)

Add WasmGlobal class and use to write globals section; export webcilV…

f9ed9eb

…ersion global

Merge branch 'main' of github.com:dotnet/runtime into adamperlin/wasm…

ea3845c

…-object-writer-webcil

Copilot AI review requested due to automatic review settings March 12, 2026 00:08

github-actions bot added the area-crossgen2-coreclr label Mar 12, 2026

dotnet-policy-service bot assigned adamperlin Mar 12, 2026

Copilot started reviewing on behalf of adamperlin March 12, 2026 00:11 View session

Copilot AI reviewed Mar 12, 2026

View reviewed changes

build-analysis bot mentioned this pull request Mar 12, 2026

Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host. dotnet/dnceng#5922

Open

3 tasks

adamperlin added 3 commits March 13, 2026 10:37

Add Microsoft.NET.WebAssembly.Webcil.Validator program; various fixes

d4ed00b

Properly override UpdateSectionAlignment() to set minimal alignment f…

76b21d9

…or webcil sections and check alignment constraints in BuildWebcilDataSegment()

Remove Console.WriteLine's; Remove a bit of dead code; Clarify some c…

e1fe575

…omments

Copilot AI review requested due to automatic review settings March 13, 2026 18:46

Copilot started reviewing on behalf of adamperlin March 13, 2026 18:47 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

adamperlin added 2 commits March 13, 2026 12:14

Remove old fix for adding type signatures as dependencies MethodWithG…

277ed87

…CInfo

Feedback

cd0696d

Copilot AI review requested due to automatic review settings March 13, 2026 19:34

Copilot started reviewing on behalf of adamperlin March 13, 2026 19:41 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

adamperlin commented Mar 13, 2026

View reviewed changes

src/coreclr/tools/Common/Compiler/ObjectWriter/Webcil.cs Outdated Show resolved Hide resolved

Apply suggestions from code review

ccb8e4f

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

build-analysis bot mentioned this pull request Mar 17, 2026

Android arm32 device not found (armeabi-v7a architecture unavailable) #125440

Open

Refactor: Move webcil header/constant definitions to tools/Common/Was…

ec88c5b

…m/Webcil.cs and unify type definition with WasmObjectWriter

Merge branch 'main' of github.com:dotnet/runtime into adamperlin/wasm…

d743659

…-object-writer-webcil

Copilot AI review requested due to automatic review settings March 17, 2026 18:54

Copilot started reviewing on behalf of adamperlin March 17, 2026 18:55 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

adamperlin added 2 commits March 17, 2026 12:51

Switch some exceptions for asserts in WasmObjectWriter

95d2704

More feedback

f2e4520

Copilot AI review requested due to automatic review settings March 17, 2026 19:56

Copilot started reviewing on behalf of adamperlin March 17, 2026 19:57 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

adamperlin and others added 2 commits March 17, 2026 15:25

Remove validator program

f212f8e

Potential fix for pull request finding

d796ca2

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 17, 2026 22:27

Copilot started reviewing on behalf of adamperlin March 17, 2026 22:29 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

build-analysis bot mentioned this pull request Mar 18, 2026

[android] Android.Device_Emulator.JIT.Test failing on emulators with CoreCLR #112633

Open

pavelsavara reviewed Mar 18, 2026

View reviewed changes

src/coreclr/tools/Common/Compiler/ObjectWriter/WebcilEncoder.cs Show resolved Hide resolved

src/coreclr/tools/Common/Compiler/ObjectWriter/WebcilEncoder.cs Show resolved Hide resolved

davidwrighton approved these changes Mar 18, 2026

View reviewed changes

adamperlin added 2 commits March 18, 2026 14:46

Review feedback

5518a27

Merge branch 'adamperlin/wasm-object-writer-webcil' of github.com:ada…

379f7e9

…mperlin/runtime into adamperlin/wasm-object-writer-webcil

build-analysis bot mentioned this pull request Mar 19, 2026

osx builds failing with CMake error #125757

Closed

Copilot AI mentioned this pull request Mar 20, 2026

Fix OleTxTests.Recovery CI timeout by bounding remote process wall-clock time #125813

Open

Conversation

adamperlin commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

pavelsavara left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

adamperlin commented Mar 18, 2026

Uh oh!

davidwrighton left a comment

Choose a reason for hiding this comment

Uh oh!

davidwrighton Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

davidwrighton Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adamperlin commented Mar 12, 2026 •

edited

Loading