[browser][coreclr] WASM-specific GC OS layer; no mmap/decommit by pavelsavara · Pull Request #127328 · dotnet/runtime

pavelsavara · 2026-04-23T16:55:45Z

Fixes #121036
Fixes #117813
Fixes #118943

Summary

This PR adds a dedicated WASM implementation of the GC's OS abstraction layer
(GCToOSInterface) and updates the GC and PAL to handle the fact that on WASM
there is no virtual memory: pages cannot be reserved without committing,
partial unmaps don't return memory to the engine, and MAP_FIXED / madvise
are not supported.

The previous approach reused gcenv.unix.cpp with #ifdef TARGET_WASM patches
and overloaded use_large_pages_p to mean "decommit is a no-op". This change
splits those concerns:

A new gc/wasm/gcenv.cpp replaces gc/unix/gcenv.unix.cpp on WASM and
implements VirtualReserve / VirtualCommit / VirtualDecommit /
VirtualRelease on top of posix_memalign / free. WASM-specific patches
in gcenv.unix.cpp are removed.
A new GC flag never_decommit_p replaces every "is decommit a no-op" check
that was previously expressed as use_large_pages_p. It is set on WASM
unconditionally and on other platforms whenever use_large_pages_p is set.
gc/CMakeLists.txt now selects gc/wasm for WASM targets while still
including unix/configure.cmake to generate config.gc.h.
The PAL's virtual.cpp is similarly cleaned up to use posix_memalign /
free on WASM and to zero memory on MEM_DECOMMIT, so the next
VirtualCommit (a no-op on WASM) sees zeroed memory.
A new minipal_getpagesize abstraction is introduced. On WASM it returns a
compile-time constant of 16 KB (the GC's page granularity, distinct from the
64 KB memory.grow granularity that getpagesize() reports). On Windows it
returns the 4 KB constant inline. On other POSIX systems it caches
getpagesize() once per process. CoreCLR PAL callers are updated to use it.

Why a separate `never_decommit_p`

On large pages, decommit is a no-op because the OS pre-commits the entire
range. On WASM, decommit is a no-op because there is no way to give linear
memory back to the engine. The two cases share the same set of GC code paths
that must be skipped or modified (decommit_ephemeral_segment_pages,
decommit_step, decommit_region, decommit_heap_segment_pages,
decommit_heap_segment, distribute_free_regions tail-decommit,
reset_memory, virtual_commit, virtual_decommit assert), but they have
nothing else in common. Reusing use_large_pages_p on WASM was misleading and
made it easy to forget large-pages-only behavior (e.g., pre-touch). The new
flag captures only the "decommit is a no-op" semantics; non-WASM behavior is
unchanged because never_decommit_p == use_large_pages_p everywhere except
WASM.

Why `minipal_getpagesize`

The GC needs the OS page size to be a compile-time constant on WASM (16 KB)
so that alignment math folds. getpagesize() on emscripten returns 64 KB
(the memory.grow granularity), which is too coarse for GC alignment and
thresholds. Centralizing this in minipal lets PAL and GC agree on a single
value and avoids #ifdefs at every call site.

Notes

VirtualReserveAndCommitLargePages on WASM falls through to the regular
reserve/commit path; the GC does not request large pages on WASM.
posix_memalign may return either freshly grown linear memory (zeroed by
the WASM spec) or a recycled block from emscripten's allocator free list.
We always memset to zero on reserve and on decommit so callers can rely
on the standard "memory starts zeroed" contract.
VirtualReset returns false on WASM, forcing the GC to use the
decommit+commit fallback (memset to zero) rather than relying on
madvise, which is a no-op on emscripten.

dotnet-policy-service · 2026-04-23T16:56:41Z

Tagging subscribers to this area: @JulieLeeMSFT, @dotnet/gc
See info in area-owners.md if you want to be subscribed.

Copilot

Pull request overview

This PR separates WebAssembly-specific GC OS interface behavior from the shared Unix implementation by introducing a dedicated gcenv.wasm.cpp, and adjusts the PAL virtual memory implementation on WASM to avoid relying on Emscripten’s incomplete mmap/munmap support.

Changes:

Added a dedicated WASM GCToOSInterface implementation (gcenv.wasm.cpp) and CMake wiring for building it.
Routed WASM GC builds to the new gc/wasm directory and removed WASM-specific #ifdef paths from gcenv.unix.cpp.
Updated PAL virtual memory reserve/release on WASM to use posix_memalign/free instead of mmap/munmap.

Reviewed changes

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

Show a summary per file

File	Description
src/coreclr/pal/src/map/virtual.cpp	Switches WASM reserve/release behavior to `posix_memalign`/`free` and adjusts related error/cleanup paths.
src/coreclr/gc/wasm/gcenv.wasm.cpp	New WASM-specific GC OS interface implementation (virtual memory, CPU/NUMA stubs, memory stats).
src/coreclr/gc/wasm/CMakeLists.txt	Adds build definition for the WASM GC PAL object library.
src/coreclr/gc/unix/gcenv.unix.cpp	Removes WASM-specific branches and fixes `nanosleep` EINTR retry logic.
src/coreclr/gc/CMakeLists.txt	Routes WASM builds to `gc/wasm` instead of `gc/unix`.

Copilot

Pull request overview

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

Copilot

Pull request overview

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

Copilot

Pull request overview

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

Co-authored-by: Jan Kotas <jkotas@microsoft.com>

Copilot

Pull request overview

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

Copilot

Pull request overview

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

jkotas

LGTM otherwise

@janvorli Could you please signoff as well?

Co-authored-by: Jan Kotas <jkotas@microsoft.com>

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Co-authored-by: Adeel Mujahid <3840695+am11@users.noreply.github.com>

Copilot

Pull request overview

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

+{
+    (void)configAffinityMask;
+    (void)configAffinitySet;
+    return nullptr; // only for multiple heaps


+uint32_t GCToOSInterface::GetTotalProcessorCount()
+{
+    return 1;
+}
+


+#else // TARGET_WASI
+    // WASI doesn't have an API to query max memory.
+    g_totalPhysicalMemSize = 2LL * 1024 * 1024 * 1024; // 2GB


+    // In addition if never-decommit is enabled (which is implied by large pages), we
+    // set commit_succeeded_p to true because memory is already committed (and
+    // VirtualCommit would be a no-op).
+    bool commit_succeeded_p = ((h_number >= 0) ? (never_decommit_p ? true :


+
+    while (nanosleep(&requested, &requested) != 0 && errno == EINTR)
+    {


jkotas · 2026-05-02T14:33:00Z

+//
+// On other platforms the value is queried from the OS once and cached; the
+// definition lives in ospagesize.c so there is exactly one cache per process.
+#if defined(TARGET_WASM)


Suggested change

#if defined(TARGET_WASM)

#if defined(HOST_WASM)

minipal should use HOST_... everywhere. It is not concerned about the target platform. Ifdefs that use TARGET_... in minipal are not quite right.

For example, if you use TARGET_WASM here, RyuJIT running on Windows or Linux that produces code for wasm may pickup the custom wasm page size for its allocators. It can lead to interesting bugs.

jkotas · 2026-05-02T14:35:03Z

+    // The OS page size used by CoreCLR on WASM (16KB).
+    // WASM has no hardware pages; getpagesize() returns the 64KB memory.grow granularity,
+    // which is too coarse for GC alignment and thresholds.


Suggested change

// The OS page size used by CoreCLR on WASM (16KB).

// WASM has no hardware pages; getpagesize() returns the 64KB memory.grow granularity,

// which is too coarse for GC alignment and thresholds.

// WASM has no hardware pages; getpagesize() returns the 64KB memory.grow granularity,

// which is too coarse for GC alignment and thresholds. Reduce the OS page size used

// by the runtime on WASM to 16KB.

pavelsavara added this to the 11.0.0 milestone Apr 23, 2026

pavelsavara self-assigned this Apr 23, 2026

Copilot AI review requested due to automatic review settings April 23, 2026 16:55

pavelsavara added arch-wasm WebAssembly architecture area-GC-coreclr labels Apr 23, 2026

Copilot started reviewing on behalf of pavelsavara April 23, 2026 16:57 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

Comment thread src/coreclr/pal/src/map/virtual.cpp

Comment thread src/coreclr/pal/src/map/virtual.cpp Outdated

Comment thread src/coreclr/gc/wasm/gcenv.wasm.cpp Outdated

Comment thread src/coreclr/gc/wasm/gcenv.wasm.cpp Outdated

pavelsavara changed the title ~~[wasm][coreclr] Extract WASM-specific GC memory management into dedicated file~~ [browser/wasi] Dedicated WASM GC PAL — replace mmap with posix_memalign and optimize memory operations Apr 23, 2026

pavelsavara changed the title ~~[browser/wasi] Dedicated WASM GC PAL — replace mmap with posix_memalign and optimize memory operations~~ [browser/wasi][coreCLR] Dedicated WASM GC PAL — replace mmap with posix_memalign and optimize memory operations Apr 24, 2026

Copilot AI review requested due to automatic review settings April 24, 2026 08:20

Copilot started reviewing on behalf of pavelsavara April 24, 2026 08:21 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings April 24, 2026 11:37

Copilot started reviewing on behalf of pavelsavara April 24, 2026 11:38 View session

pavelsavara marked this pull request as ready for review April 24, 2026 11:43

pavelsavara requested review from SingleAccretion, janvorli and radekdoulik April 24, 2026 11:44

Copilot AI reviewed Apr 24, 2026

View reviewed changes

pavelsavara requested review from Copilot and jkotas April 24, 2026 12:38

Copilot started reviewing on behalf of pavelsavara April 24, 2026 12:39 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

Comment thread src/coreclr/gc/wasm/gcenv.cpp

jkotas reviewed Apr 24, 2026

View reviewed changes

Comment thread src/native/minipal/wasm.h Outdated

Copilot started reviewing on behalf of pavelsavara May 1, 2026 07:01 View session

pavelsavara and others added 3 commits May 1, 2026 09:10

Update src/coreclr/gc/wasm/gcenv.cpp

cb2c789

Co-authored-by: Jan Kotas <jkotas@microsoft.com>

Update src/coreclr/gc/wasm/gcenv.cpp

f716254

Co-authored-by: Jan Kotas <jkotas@microsoft.com>

Update src/coreclr/gc/wasm/gcenv.cpp

07c2288

Co-authored-by: Jan Kotas <jkotas@microsoft.com>

Copilot AI reviewed May 1, 2026

View reviewed changes

Comment thread src/coreclr/pal/src/map/virtual.cpp

pavelsavara added 2 commits May 1, 2026 09:45

feedback

fd1ddd2

fix

e2eb693

Copilot AI review requested due to automatic review settings May 1, 2026 08:06

Copilot started reviewing on behalf of pavelsavara May 1, 2026 08:06 View session

Copilot AI reviewed May 1, 2026

View reviewed changes

Comment thread src/coreclr/gc/wasm/gcenv.cpp Outdated

inline constant fold

d7f4c50

build-analysis Bot mentioned this pull request May 1, 2026

System.Net.NameResolution.Tests DNS failures: Name or service not known #126641

Open

jkotas reviewed May 1, 2026

View reviewed changes

Comment thread src/coreclr/gc/wasm/gcenv.cpp Outdated

jkotas reviewed May 1, 2026

View reviewed changes

Comment thread src/coreclr/gc/wasm/gcenv.cpp Outdated

jkotas approved these changes May 1, 2026

View reviewed changes

Update src/coreclr/gc/wasm/gcenv.cpp

b752041

Co-authored-by: Jan Kotas <jkotas@microsoft.com>

Copilot AI review requested due to automatic review settings May 1, 2026 19:09

Copilot started reviewing on behalf of pavelsavara May 1, 2026 19:09 View session

Update src/coreclr/gc/wasm/gcenv.cpp

4616dcc

Co-authored-by: Jan Kotas <jkotas@microsoft.com>

Copilot AI reviewed May 1, 2026

View reviewed changes

build-analysis Bot mentioned this pull request May 1, 2026

System.Net.Sockets.Tests tests fail with ObjectDisposedException #126183

Open

am11 reviewed May 2, 2026

View reviewed changes

Comment thread src/native/minipal/ospagesize.h Outdated

Update src/native/minipal/ospagesize.h

d60a5bb

Co-authored-by: Adeel Mujahid <3840695+am11@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 2, 2026 07:36

Copilot started reviewing on behalf of pavelsavara May 2, 2026 07:36 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

This was referenced May 2, 2026

XHarness package install failure on iOS due to devicectl NSPOSIXErrorDomain error 49 #123796

Open

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

Open

jkotas reviewed May 2, 2026

View reviewed changes


		while (nanosleep(&requested, &requested) != 0 && errno == EINTR)
		{

Conversation

pavelsavara commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why a separate never_decommit_p

Why minipal_getpagesize

Notes

Uh oh!

dotnet-policy-service Bot commented Apr 23, 2026

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!

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!

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!

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!

jkotas left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

jkotas May 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkotas May 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

pavelsavara commented Apr 23, 2026 •

edited

Loading

Why a separate `never_decommit_p`

Why `minipal_getpagesize`

jkotas May 2, 2026 •

edited

Loading