[wasm] Compute CoreCLR P/Invoke struct sizes with crossgen2's type system

[radekdoulik]

Replaces the hardcoded struct-size table in the CoreCLR wasm P/Invoke generator with crossgen2's real field-layout engine.

The problem

ManagedToNativeGenerator computed wasm ABI signature strings from System.Reflection.MetadataLoadContext, which has no field-layout engine. Struct sizes came from a 7-entry hardcoded table, and anything outside it was a hard build error:

error WASM0067: SignatureMapper: unknown multi-field struct 'X' (fields: N)
- add its size to s_knownStructSizes in SignatureMapper.cs

Size matters because the CoreCLR interpreter lays struct arguments out inline across 8-byte slots — TokenToSlotCount returns max((size + 7) / 8, 1) for an S<N> token. A wrong N misaligns the interpreter frame.

Mono's generator needs none of this: its alphabet has no S, and it encodes every struct as a pointer.

The change

crossgen2 gains --generate-portable-callhelpers <dir>, which writes the three C++ call-helper files directly. It sets up its type system as for a real wasm compilation, scans the input assemblies and emits — no JIT, no R2R image. The option requires --targetarch wasm with --targetos browser|wasi.

The CoreCLR half of the MSBuild task is deleted rather than adapted: ManagedToNativeGenerator, PInvokeCollector, PInvokeTableGenerator, SignatureMapper, InternalCallSignatureCollector, InterpToNativeGenerator. _CoreCLRGenerateManagedToNative keeps its name and position in the target graph; its final step changes from <UsingTask> to <Exec>. The regeneration scripts move next to their output under src/coreclr/vm/wasm/ and drive generate-coreclr-helpers.proj. Mono's generator is untouched.

−2269 lines under src/tasks, +1541 under ILCompiler.ReadyToRun/PortableCallHelpers. A move, not an addition: the second implementation of wasm ABI lowering is gone, and the one that remains is the one the JIT interface itself calls. Sizes are computed, not enumerated. The only change to WasmLowering is widening WasmValueTypeToSigChar from private to internal.

Naming

Portable entry points exist for any platform that cannot generate code at run time; wasm is the only one today. Per review feedback nothing in this functionality is named after wasm. Symbols shared by the runtime and the generated tables were renamed on both sides at once:

before	after
StringToWasmSigThunk	StringToPortableSigThunk
g_wasmThunks[Count]	g_portableCallHelperThunks[Count]
wasm_ret_S<n>	portable_callhelper_ret_S<n>

What keeps wasm in its name is what is genuinely about wasm: the ABI in WasmLowering, the --targetos browser|wasi requirement, and the wasm-specific corerun the runtime tests link.

Finding crossgen2

Three paths, tried in order:

• Override — $(PortableCallHelpersGeneratorPath), which must name a crossgen2 executable.
• In repo — $(Crossgen2InBuildDir); crossgen2 is built unconditionally by the clr subset.
• Out of repo — the wasm-tools workload declares the existing Microsoft.NETCore.App.Crossgen2.<host-rid> pack, whose Sdk/Sdk.props defines $(Crossgen2ToolPath). ~12.5 MB.

The SDK resolves this pack only when PublishReadyToRun is set, which wasm CoreCLR apps never set — hence the workload. dotnet/sdk#56119 proposes acquiring it directly instead, which would let the workload entry go. If none of the three resolve, the targets error rather than passing an empty path down.

The pack is named for the machine that runs crossgen2, not the target: generation never loads the JIT, so a host-targeting crossgen2 answers wasm ABI questions correctly.

The workload-testing legs do not set $(BuildHostTools), so nothing produced a crossgen2 pack for their local package feed. (The perf browser-wasm leg does produce one, but only because it opts in — #133143.) Microsoft.NETCore.App.Crossgen2.Host.sfxproj pins the RID to the build host, and is now built by the CoreCLR browser-wasm leg behind $(BuildCrossgen2HostPackForWorkloadTesting), guarded on $(BuildHostTools) being unset so the two paths can never emit the same package id twice. The official build is untouched — it already publishes this pack from the host platform legs.

Behaviour changes

WASM0066 is removed. The old task warned for every DllImport whose module did not resolve to a linked-in native library — a CoreCLR-only divergence that fires on ordinary cross-platform code never executed on wasm (#131874 reports ten from SkiaSharp alone on a shipped Preview 7 SDK). In-tree it had already accumulated two NoWarn suppressions and a WarnOnUnresolvedPInvokeModules=false; all three go, along with the --no-warn-unresolved-directpinvoke opt-out that existed only to silence it. An unresolved module is not knowably wrong at build time: callhelpers_pinvoke_override returns nullptr on a miss, so a call that actually happens throws DllNotFoundException naming the module, as on every other platform. Dropping a warning is strictly loosening.

WASM0065 is added, as a message. Per module, when it declares P/Invokes without [assembly: DisableRuntimeMarshalling], since the generated helpers assume signatures cross unmarshalled. A message rather than a warning: it reports something the app author often cannot fix, and as a warning it would fail -warnaserror builds. Four fire across the 181 framework assemblies.

Exported callbacks with an ambiguous name are rejected. An export wrapper resolves its MethodDesc through LookupUnmanagedCallersOnlyMethodByName, which takes the first [UnmanagedCallersOnly] method of matching name and compares no signature — so two exported overloads resolve to the same method and one wrapper calls it with the wrong arguments. Everything the generator controls carries the arity, so the existing duplicate-key and duplicate-symbol checks both pass. Generation now fails instead, naming both signatures. Only exports: a non-exported callback is found by the arity-aware key and never reaches the name lookup.

Known limitations

• wasi has no out-of-repo acquisition path. wasi-experimental extends microsoft-net-runtime-mono-tooling, not wasm-tools, so it picks up no crossgen2 pack; the targets error explicitly there. Browser is the shipping wasm/CoreCLR target.
• Reverse thunks allocate one int64_t slot per managed parameter, while a by-value struct argument occupies ceil(size/8) interpreter slots. No [UnmanagedCallersOnly] callback in CoreLib or the libraries takes a by-value struct, so nothing exercises this. The old generator rejected such callbacks with WASM0067; this one accepts them, so user code would get a bad thunk rather than a diagnostic.
• 'V' (v128) has no case in the C++ emission helpers. Pre-existing; fails loudly.
• Multi-slot types (Int128, Vector256, …) are rejected at the thunk emitter rather than at the interop boundary, so the diagnostic differs from the old WASM0068. Still a clean crossgen2 : error : with exit 1. No such P/Invoke exists today.
• Does not re-enable the tests disabled in [browser-wasm] CoreCLR runtime tests blocked on interop gaps after test-specific corerun enablement #131811 ([wasm][coreCLR] Enable runtime tests that need relinking, and cover the call-helpers generator end to end #133187), and does not address gaps Define a root README.md #3–[master] Update dependencies from dotnet/coreclr #7 there.

Verification

• Regeneration reproduces the committed helpers byte for byte, apart from the rename above, with zero WASM0001/WASM0060/WASM0061/WASM0062 warnings across a full CoreLib+libraries scan. (The checked-in P/Invoke table is already slightly stale against main independently of this PR; that drift is left alone.)
• WasmArgumentLayoutTests goes from 17 to 22 test methods. The two covering the rejection above were checked against a disabled check, so they test it rather than agree with it.
• clr+libs builds clean for browser and wasi; WasmAppBuilder still builds for both net11.0 and net472.
• Both flavors build end to end from the in-tree samples, with per-architecture native payloads, a non-PE file and duplicate-culture satellites injected into the bundle.
• The renamed runtime contract was checked by building: libcoreclr_static.a exports g_portableCallHelperThunks and no g_wasmThunks, and the browser sample links its generated tables against it.

Contributes to #131811, closing blocking gap #1 and the struct half of gap #2: a 3-int and a 5-double struct in [UnmanagedFunctionPointer] signatures now resolve to vS12 / S12i / vS40i, where all three previously threw NotSupportedException.

Note

This pull request description was drafted with the help of GitHub Copilot.

[azure-pipelines]

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

[radekdoulik]

This should resolve #131874

[Copilot]

Pull request overview

This PR updates the CoreCLR WebAssembly P/Invoke helper generation pipeline to compute wasm ABI struct sizing and signature lowering via crossgen2’s type system (hosted in a new out-of-process tool), replacing the previous hardcoded/reflective size logic that couldn’t reliably handle field layout or constructed generics.

Changes:

• Add ILCompiler.Wasm.Lowering as an out-of-proc “signature resolver” tool and wire ManagedToNativeGenerator to query it for ABI tokens and full method signatures.
• Refactor wasm lowering/shared helpers in the compiler toolchain (type-cache interface, moved wasm type encoding, split MethodDesc-facing lowering).
• Add parity tests to ensure the standalone resolver produces the same signatures as crossgen2.

Reviewed changes

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

Show a summary per file

File	Description
src/tasks/WasmAppBuilder/WasmAppBuilder.csproj	Builds the resolver tool in RunGenerator and passes its path into ManagedToNativeGenerator.
src/tasks/WasmAppBuilder/IcallTableGenerator.cs	Requires an injected CoreCLR SignatureMapper when generating CoreCLR icall signatures.
src/tasks/WasmAppBuilder/coreclr/WasmLoweringFlags.cs	Task-local copy of lowering flags (mirrors compiler enum values).
src/tasks/WasmAppBuilder/coreclr/WasmAbiTypeResolver.cs	New resolver client that runs ILCompiler.Wasm.Lowering once and queries over stdin/stdout.
src/tasks/WasmAppBuilder/coreclr/SignatureMapper.cs	Converts from static helper + hardcoded struct sizes to instance-based mapper backed by resolver.
src/tasks/WasmAppBuilder/coreclr/PInvokeTableGenerator.cs	Routes signature/name token decisions through the new SignatureMapper instance.
src/tasks/WasmAppBuilder/coreclr/PInvokeCollector.cs	Uses resolver-backed signature computation; skips open generic callback delegates.
src/tasks/WasmAppBuilder/coreclr/ManagedToNativeGenerator.cs	Adds SignatureResolverPath/DotNetHostPath and initializes resolver + mapper for generation.
src/tasks/WasmAppBuilder/coreclr/IWasmAbiTypeResolver.cs	New abstraction for “type token” and “method signature” ABI queries.
src/tasks/WasmAppBuilder/coreclr/InternalCallSignatureCollector.cs	Uses resolver-based lowering for InternalCall signatures; skips generic InternalCalls.
src/mono/nuget/Microsoft.NET.Runtime.WebAssembly.Wasi.Sdk/Microsoft.NET.Runtime.WebAssembly.Wasi.Sdk.pkgproj	Ships the resolver tool in the SDK pack output layout.
src/mono/nuget/Microsoft.NET.Runtime.WebAssembly.Sdk/Microsoft.NET.Runtime.WebAssembly.Sdk.pkgproj	Ships the resolver tool in the SDK pack output layout.
src/coreclr/tools/Common/JitInterface/WasmLowering.MethodDesc.cs	New split file for MethodDesc-based lowering + flag computation.
src/coreclr/tools/Common/JitInterface/WasmLowering.cs	Refactors to use IWasmTypeCacheContext and narrows API surface in this file.
src/coreclr/tools/Common/Compiler/IWasmTypeCacheContext.cs	New interface for caching/round-tripping wasm-lowered struct/v128 types.
src/coreclr/tools/Common/Compiler/DependencyAnalysis/Target_Wasm/WasmTypes.Encoding.cs	Splits encoding/mangling/JIT interface conversions out of WasmTypes.cs.
src/coreclr/tools/Common/Compiler/DependencyAnalysis/Target_Wasm/WasmTypes.cs	Keeps the wasm type model “type-system only” and makes types partial to split helpers.
src/coreclr/tools/Common/Compiler/CompilerTypeSystemContext.Wasm.cs	Implements IWasmTypeCacheContext on the compiler context.
src/coreclr/tools/aot/ILCompiler.Wasm.Lowering/WasmTypeSystemContext.cs	New minimal wasm-configured type system context used by the resolver tool.
src/coreclr/tools/aot/ILCompiler.Wasm.Lowering/WasmMetadataFieldLayoutAlgorithm.cs	New wasm field-layout algorithm mirroring crossgen2 instance layout logic.
src/coreclr/tools/aot/ILCompiler.Wasm.Lowering/WasmAbiTypeResolver.cs	Resolver API implementation: per-type token and per-method signature queries.
src/coreclr/tools/aot/ILCompiler.Wasm.Lowering/Program.cs	Implements the stdin/stdout query server protocol (“ready”, t ..., m ...).
src/coreclr/tools/aot/ILCompiler.Wasm.Lowering/ILCompiler.Wasm.Lowering.csproj	New tool project, links shared lowering/type sources and pins output path.
src/coreclr/tools/aot/ILCompiler.TypeSystem/ILCompiler.TypeSystem.csproj	Grants internals visibility to the resolver tool.
src/coreclr/tools/aot/ILCompiler.RyuJit/ILCompiler.RyuJit.csproj	Includes the new WasmLowering.MethodDesc.cs split file.
src/coreclr/tools/aot/ILCompiler.ReadyToRun/ILCompiler.ReadyToRun.csproj	Includes split wasm encoding + cache interface + MethodDesc lowering file.
src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/VectorOfTFieldLayoutAlgorithm.cs	Extracted Vector<T> layout algorithm into a standalone file.
src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/ReadyToRunCompilerContext.cs	Removes the now-extracted nested VectorOfTFieldLayoutAlgorithm type.
src/coreclr/tools/aot/ILCompiler.ReadyToRun.Tests/WasmLoweringParityTests.cs	New parity tests comparing crossgen2 vs resolver lowering across CoreLib.
src/coreclr/tools/aot/ILCompiler.ReadyToRun.Tests/ILCompiler.ReadyToRun.Tests.csproj	Adds aliased reference to the resolver tool for side-by-side parity testing.
src/coreclr/tools/aot/ILCompiler.Compiler/ILCompiler.Compiler.csproj	Includes split wasm encoding + cache interface file.
Directory.Build.props	Adds WasmSignatureResolverDir for pinned resolver output placement.

[jkotas]

Would it be better to expose this as crossgen command line option instead of repackaging large part of crossgen in a new tool?

[radekdoulik]

Would it be better to expose this as crossgen command line option instead of repackaging large part of crossgen in a new tool?

That could work too. We don't include crossgen in the packages yet IIRC, I can add it in this PR though. I will try it.

For the record, the new tool is 632K, crossgen pack is 36M (measured on mac). We will ship the crossgen anyway, so it indeed makes sense to add the new option instead of the new tool.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/coreclr/tools/aot/ILCompiler.ReadyToRun/JitInterface/WasmAbiQuery.cs:49

• This type doesn’t appear to need to be public. ILCompiler.ReadyToRun already declares InternalsVisibleTo for ILCompiler.ReadyToRun.Tests, so making this internal would reduce accidental surface area without impacting the crossgen2 entrypoint or tests.

    public static class WasmAbiQuery
    {

[Copilot]

🟡 Changes recommended

There are merge-blocking nullable/treat-warnings-as-errors issues in newly added managed code that will fail the build as-is.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

src/tasks/WasmAppBuilder/FilterManagedAssemblies.cs:25

• Assemblies is declared nullable (ITaskItem[]?) but is dereferenced unconditionally (Assemblies.Length / foreach). With nullable enabled and TreatWarningsAsErrors=true, this will produce CS8602 (and can NRE if MSBuild ever invokes the task without setting it). Make the property non-nullable and initialize with null! so [Required] validation remains meaningful.

• Files reviewed: 52/52 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The test corerun relink target wires crossgen2 discovery through a private property rather than the shared PortableCallHelpersGeneratorPath, making tool-path overrides inconsistent with the rest of the PR.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

src/tests/Common/CLRTest.WasmCorerun.targets:334

• The generator path is wired through the private property $(_WasmCorerunGeneratorPath), which is inconsistent with the app-side targets (BrowserWasmApp.CoreCLR.targets / WasiApp.CoreCLR.targets) that use $(PortableCallHelpersGeneratorPath) and $(Crossgen2ToolPath). This makes it harder to override the tool path consistently across build + tests and prevents reuse of the pack-provided Crossgen2ToolPath when available.

This issue also appears on line 348 of the same file.

src/tests/Common/CLRTest.WasmCorerun.targets:348

• This Exec still invokes $(_WasmCorerunGeneratorPath). If the tool-path wiring is unified on $(PortableCallHelpersGeneratorPath), this should use that property so the generator actually runs from the resolved/overridden location.

• Files reviewed: 52/52 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It changes critical wasm build/generation plumbing across crossgen2, MSBuild targets, and runtime symbol contracts, and needs a human to validate cross-platform build behavior end-to-end.

Review details

Suppressed comments (2)

src/coreclr/tools/aot/ILCompiler.ReadyToRun/PortableCallHelpers/PortableCallHelpersGenerator.cs:23

• PortableCallHelpersGeneratorOptions leaves OutputDirectory and TargetOS as null unless the caller sets them, but the generator later assumes these are usable strings. Initializing them to non-null defaults avoids accidental NullReferenceExceptions and makes the required/optional contract clearer (the existing validation can still enforce non-empty).

    public sealed class PortableCallHelpersGeneratorOptions
    {
        public string OutputDirectory { get; init; }
        public IReadOnlyList<string> PInvokeModules { get; init; } = [];
        public string TargetOS { get; init; }
    }

src/coreclr/tools/aot/ILCompiler.ReadyToRun/PortableCallHelpers/PInvokeCollector.cs:101

• PInvokeCallback.EntryPoint and EntrySymbol can remain null for non-exported callbacks / before EmitNativeToInterp assigns them, but they are typed as non-nullable string. Give them non-null defaults (or make them nullable) to prevent future accidental null dereferences and to better reflect the lifecycle of these values.

        public MethodSignature Parameters => Method.Signature;
        public string EntryPoint { get; }
        public EcmaMethod Method { get; }
        public string EntrySymbol { get; set; }
        public string AssemblyName { get; }

• Files reviewed: 52/52 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It rewires a broad build+interop generation pipeline across crossgen2/MSBuild/runtime codepaths, and the remaining concern around generator-path override consistency warrants human validation before merge.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/tests/Common/CLRTest.WasmCorerun.targets:334

• The crossgen2 path override here is wired to the private property $(_WasmCorerunGeneratorPath) and only defaults from $(Crossgen2InBuildDir). This is inconsistent with the rest of the build (which uses $(PortableCallHelpersGeneratorPath) / $(Crossgen2ToolPath)) and makes the error message point users at an internal underscore property.

Consider accepting $(PortableCallHelpersGeneratorPath) (and optionally $(Crossgen2ToolPath)) as the override/fallback source, while still allowing $(_WasmCorerunGeneratorPath) to win when explicitly set.

• Files reviewed: 52/52 changed files
• Comments generated: 0 new
• Review effort level: Lite

[jkotas]

Please edit the PR description to only keep what's relevant for the final delta.

[jkotas]

cc @dotnet/crossgen-contrib FYI

[Copilot]

🔵 Needs a closer look

It makes broad build/toolchain/runtime-contract changes across crossgen2, VM wasm helpers, workloads, and CI that need careful human validation and full CI signal.

Review details

Suppressed comments (1)

src/coreclr/tools/aot/ILCompiler.ReadyToRun/PortableCallHelpers/PInvokeCollector.cs:101

• PInvokeCallback.EntryPoint and EntrySymbol can be left uninitialized for non-export callbacks, but are declared as non-nullable strings. Initializing them avoids null values leaking into later formatting/logging if code changes, and makes the type’s invariants explicit.

        public MethodSignature Parameters => Method.Signature;
        public string EntryPoint { get; }
        public EcmaMethod Method { get; }
        public string EntrySymbol { get; set; }
        public string AssemblyName { get; }

• Files reviewed: 52/52 changed files
• Comments generated: 1
• Review effort level: Lite

[pavelsavara]

@maraf it would be good if you can have look later. We can address your feedback in followup

[radekdoulik]

/ba-g the runtime-diagnostics (SOSTests cDAC_windows_x64_release) is unrelated and is failing on main and other PRs