Disable server GC and background GC for CoreCLR WebAssembly builds

[Copilot]

Description

Applies two complementary size optimizations for CoreCLR WebAssembly builds, which use the interpreter instead of the traditional JIT:

1. Disable server GC — FEATURE_SVR_GC is suppressed for WebAssembly in clrdefinitions.cmake. WebAssembly is single-threaded and has no use for server GC's multi-heap design.

2. Disable background GC — Background GC (concurrent GC) requires WRITE_WATCH support and background threads, neither of which is available on WebAssembly. BACKGROUND_GC is now suppressed with a #ifndef TARGET_WASM guard in gcpriv.h. The datadescriptor.h and datadescriptor.inc cDAC descriptor files are updated to guard the fields and globals that only exist when BACKGROUND_GC is defined.

3. cDAC support for optional background GC fields — The cDAC contract reader (GCHeapWKS.cs, GCHeapSVR.cs, IGCHeap.cs, GC_1.cs) is updated so that MarkArray, NextSweepObj, BackgroundMinSavedAddr, and BackgroundMaxSavedAddr are treated as optional fields — absent when background GC is disabled, and defaulted to 0. Field presence is determined by whether the fields exist in the data descriptor (no explicit feature flag is emitted). The GC.md contract documentation is updated to describe this optional behavior, following the same pattern as the segment-only fields such as GCHeapSavedSweepEphemeralSeg.

Size measurements (corerun.wasm)

Configuration	Raw (bytes)	Brotli (bytes)
Original baseline	4,497,135	1,340,828
Disable server GC + background GC	4,171,449	1,258,272
Total savings	325,686 (7.2%)	82,556 (6.2%)

[janvorli]

@copilot let's disable the background GC for WASM too.

[janvorli]

cc: @radekdoulik FYI

[Copilot]

@copilot let's disable the background GC for WASM too.

Done in dc7b9f9. Added #ifndef TARGET_WASM guard around #define BACKGROUND_GC in gcpriv.h, and updated datadescriptor.h and datadescriptor.inc to guard the fields that only exist when BACKGROUND_GC is defined.

Additional savings from disabling background GC: 47,527 bytes raw / 15,680 bytes brotli, bringing the total vs baseline to 93,330 bytes raw (2.2%) / 25,599 bytes brotli (2.0%).

[janvorli]

@copilot please undo the changes in the jitinterface.cpp, these are unrelated to the GC changes.

[radekdoulik]

I had similar PR #127222 for it, so closed it and moved the feedback commit here, which disables the server GC on iOS and tvOS. /cc @vitek-karas

[janvorli]

LGTM

[dotnet-policy-service]

Tagging subscribers to 'arch-wasm': @lewing, @pavelsavara
See info in area-owners.md if you want to be subscribed.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

src/coreclr/gc/datadescriptor/datadescriptor.inc:25

• The BACKGROUND_GC guard only wraps MarkArray/NextSweepObj/Background* fields, but the SavedSweepEphemeralSeg/Start fields later in this GCHeap type definition are still only guarded by !USE_REGIONS. In datadescriptor.h those SavedSweepEphemeral* offsets are now only defined when BACKGROUND_GC is enabled, so this can lead to referencing missing cdac_data members (and a build break) when BACKGROUND_GC is disabled. Please guard SavedSweepEphemeralSeg/Start here with the same !USE_REGIONS && BACKGROUND_GC condition used elsewhere in the descriptor.

#endif // BACKGROUND_GC
CDAC_TYPE_FIELD(GCHeap, T_POINTER, AllocAllocated, cdac_data<GC_NAMESPACE::gc_heap>::AllocAllocated)
CDAC_TYPE_FIELD(GCHeap, T_POINTER, EphemeralHeapSegment, cdac_data<GC_NAMESPACE::gc_heap>::EphemeralHeapSegment)
CDAC_TYPE_FIELD(GCHeap, T_POINTER, CardTable, cdac_data<GC_NAMESPACE::gc_heap>::CardTable)
CDAC_TYPE_FIELD(GCHeap, T_POINTER, FinalizeQueue, cdac_data<GC_NAMESPACE::gc_heap>::FinalizeQueue)

docs/design/datacontracts/GC.md:163

• Several table entries still say "sever builds"; this looks like a typo and should be "server builds".

| `GCHeap` | AllocAllocated | GC | Heap's highest address allocated by Alloc (in sever builds) |
| `GCHeap` | EphemeralHeapSegment | GC | Pointer to the heap's ephemeral heap segment (in sever builds) |
| `GCHeap` | CardTable | GC | Pointer to the heap's bookkeeping GC data structure (in sever builds) |
| `GCHeap` | FinalizeQueue | GC | Pointer to the heap's CFinalize data structure (in sever builds) |
| `GCHeap` | GenerationTable | GC | Pointer to the start of an array containing `"TotalGenerationCount"` `Generation` structures (in sever builds) |

[Copilot]

This introduces new behavior where background-GC-related fields can be missing and are defaulted to TargetPointer.Null. There are existing cDAC GC contract unit tests, but they don’t appear to cover the "background GC disabled" shape (globals/fields absent). Please add tests exercising both workstation (missing globals) and server (missing type fields) scenarios to ensure these null-default semantics stay correct.

[Copilot]

The updated availability notes correctly call out background GC for MarkArray/NextSweepObj/Background* fields. For consistency with the descriptor changes, please also update the SavedSweepEphemeralSeg/SavedSweepEphemeralStart entries later in this table to mention they’re absent when BACKGROUND_GC is disabled as well (not just when segment GC is unavailable).

[Copilot]

These globals are now documented as only present with background GC, which matches the code changes. Please also update the GCHeapSavedSweepEphemeralSeg/GCHeapSavedSweepEphemeralStart entries later in this globals table to reflect that they’re also absent when BACKGROUND_GC is disabled.

[Copilot]

This change disables FEATURE_SVR_GC not only for WebAssembly but also for iOS and tvOS. That broadens the behavior change beyond what’s described in the PR title/description; if that’s unintentional, drop the iOS/tvOS conditions, and if it’s intentional, please update the PR description to call out the additional platforms affected (and why).

[github-actions]

🤖 Copilot Code Review — PR #127178

Note

This review was generated by Copilot and should be treated as an AI-generated analysis. Findings were cross-validated across multiple model families (Claude Opus 4.6, Claude Sonnet 4.5, GPT-5.3-Codex).

Holistic Assessment

Motivation: Well-justified. WASM is single-threaded and has no use for server GC or background GC (which requires WRITE_WATCH and threads). The measured ~93KB (2.2%) raw savings are meaningful for a WASM target. Disabling server GC for iOS/tvOS follows the same rationale as the pre-existing Android exclusion.

Approach: Clean and follows established codebase patterns. The cDAC optional-field handling mirrors the existing SavedSweepEphemeralSeg pattern. The FeatureBackgroundGc global was correctly removed per reviewer feedback — field presence alone is sufficient. The PR was iterated through multiple rounds of human review with appropriate corrections.

Summary: ⚠️ Needs Human Review. The code changes look correct for all current platform combinations. One inconsistency between the server GC and workstation GC data descriptor blocks should be evaluated. The new optional-field code paths in the cDAC managed reader lack direct test coverage.

---

Detailed Findings

⚠️ Server GC SavedSweepEphemeral* Guard Inconsistency — datadescriptor.inc

(Flagged by all three models)

In datadescriptor.inc, the workstation block (lines 168–171) and datadescriptor.h (lines 66–69) now guard SavedSweepEphemeralSeg/SavedSweepEphemeralStart with #if !defined(USE_REGIONS) && defined(BACKGROUND_GC). However, the server GC block (lines 27–30) still uses only #ifndef USE_REGIONS:

// datadescriptor.inc, server block (lines 27-30) — missing BACKGROUND_GC guard
#ifndef USE_REGIONS
CDAC_TYPE_FIELD(GCHeap, T_POINTER, SavedSweepEphemeralSeg, ...)
CDAC_TYPE_FIELD(GCHeap, T_POINTER, SavedSweepEphemeralStart, ...)
#endif // !USE_REGIONS

These fields exist in gc_heap only under #ifdef BACKGROUND_GC (gcpriv.h:3566–3601), and the cdac_data template in datadescriptor.h only defines them under BACKGROUND_GC. So if a future platform disables BACKGROUND_GC while keeping SERVER_GC, this would be a compilation error.

Current impact: None — all platforms that disable BACKGROUND_GC (WASM) also disable SERVER_GC, so the server block is never compiled without BACKGROUND_GC today.

Recommended fix (for consistency):

#if !defined(USE_REGIONS) && defined(BACKGROUND_GC)
CDAC_TYPE_FIELD(GCHeap, T_POINTER, SavedSweepEphemeralSeg, ...)
CDAC_TYPE_FIELD(GCHeap, T_POINTER, SavedSweepEphemeralStart, ...)
#endif // !USE_REGIONS && BACKGROUND_GC

⚠️ Missing Test Coverage for Optional Background GC Fields

(Flagged by all three models)

The cDAC tests always provide background GC globals and fields:

• GCTests.cs (line 209): Always registers GCHeapMarkArray, GCHeapNextSweepObj, etc.
• MockDescriptors.GC.cs (line 168): Always adds MarkArray, NextSweepObj, etc. to the SVR layout.

No test exercises the new "fields absent" path where TryReadGlobalPointer returns false (WKS) or type.Fields.ContainsKey returns false (SVR). This means the null-fallback logic (?? TargetPointer.Null) is untested. A test that omits these fields from the mock descriptors and verifies the resulting GCHeapData fields are TargetPointer.Null would be valuable.

✅ cDAC Nullable Pattern — Correct

The TargetPointer? (nullable value type) pattern is properly implemented. When background GC fields are absent:

• GCHeapWKS.cs: TryReadGlobalPointer returns false → property stays null (default for nullable).
• GCHeapSVR.cs: type.Fields.ContainsKey returns false → property stays null.
• GC_1.cs: heap.MarkArray ?? TargetPointer.Null correctly falls back.

This follows the same pattern as the pre-existing SavedSweepEphemeralSeg and FreeRegions handling.

✅ GC Feature Guards — Correct

• gcpriv.h: #ifndef TARGET_WASM around BACKGROUND_GC is correct — WASM is the only target needing this (iOS/tvOS benefit from background GC for app responsiveness).
• clrdefinitions.cmake: Disabling FEATURE_SVR_GC for WASM/iOS/tvOS follows the established Android pattern.
• The datadescriptor.h and workstation block of datadescriptor.inc guards are correctly applied.

💡 Pre-existing: CLR_CMAKE_HOST_ANDROID vs CLR_CMAKE_TARGET_*

The cmake condition mixes CLR_CMAKE_HOST_ANDROID (pre-existing) with the new CLR_CMAKE_TARGET_ARCH_WASM/CLR_CMAKE_TARGET_IOS/CLR_CMAKE_TARGET_TVOS. The Android check should arguably use CLR_CMAKE_TARGET_ANDROID since server GC capability depends on the target, not the host. This is a pre-existing inconsistency and out of scope for this PR, but worth noting for a future cleanup.

✅ Documentation Updates — Accurate

The GC.md updates correctly describe the optional behavior for background GC fields in both workstation and server pseudocode sections. The table entries are updated to note "with background GC" conditioning. The pseudocode follows the established pattern from SavedSweepEphemeralSeg.

Generated by Code Review for issue #127178 · ◷