Skip to content

Add memoryPageSize configuration and WSLC backing-page opt-in - #42110

Draft
Ben Hillis (benhillis) wants to merge 8 commits into
microsoft:masterfrom
benhillis:benhill/large-memory-backing-pages
Draft

Ben Hillis (benhillis) wants to merge 8 commits into
microsoft:masterfrom
benhillis:benhill/large-memory-backing-pages

Conversation

@benhillis

@benhillis Ben Hillis (benhillis) commented Oct 29, 2026 •

Copy link
Copy Markdown
Member

Summary of the Pull Request

Add opt-in 2 MiB host backing pages for WSL2 and WSLC.

PR Checklist

  • Closes: No linked issue.
  • Communication: I've discussed this with core contributors already. If work hasn't been agreed, this work might be rejected
  • Tests: Added/updated if needed and all pass
  • Localization: All end user facing strings can be localized
  • Dev docs: Added/updated if needed
  • Documentation updated: If checked, please file a pull request on our docs repo and link it here: Not submitted.

Detailed Description of the Pull Request / Additional comments

[experimental]
memoryPageSize=medium

small is the default; medium requests 2 MiB backing pages. large is reserved for future support and currently rejected. Run wsl --shutdown to apply changes.

WSLC sessions opt in independently through C SDK and COM feature flags.

Validation Steps Performed

  • cmake --build . -- -m - passed.
  • .\FormatSource.ps1 -Branch -BaseBranch origin/master -Verify $true - passed.
  • CI passed: x64/ARM64 builds, WSL1/WSL2/WSLC tests, documentation, formatting and localization.

Copilot AI balanced review requested due to automatic review settings October 29, 2026 21:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Overlapping release checks newly enable small pages on Cobalt hosts below the required fix threshold, exposing unflagged WSLC sessions to the partition-teardown deadlock.

1 open issue
What changed in this PR

Adds disabled-by-default support for 2 MiB host backing pages in WSL2 and WSLC, with shared HCS configuration and a runtime-version check for C SDK callers.

Changes:

  • Adds the experimental .wslconfig setting and independent WSLC C/COM feature flags.
  • Centralizes backing-page policy and adds localized SDK diagnostics for unsupported runtime versions.
  • Adds helper and integration tests plus configuration and API documentation.
File Description
test/​windows/​wslc/​WSLCTests.cpp Tests the COM opt-in and updates default-policy expectations.
test/​windows/​wslc/​WslcSdkTests.cpp Tests session creation with the C SDK flag.
test/​windows/​wsl/​UnitTests.cpp Tests configuration values and page-reporting settings.
test/​windows/​common/​MemoryBackingPagesTests.cpp Adds helper and runtime-version tests.
src/​windows/​WslcSDK/​WslcsdkPrivate.h Adds runtime-version validation and diagnostics.
src/​windows/​WslcSDK/​wslcsdk.h Exposes the C SDK feature flag.
src/​windows/​WslcSDK/​wslcsdk.cpp Accepts the flag and checks runtime support.
src/​windows/​service/​inc/​WSLCShared.idl Defines and validates the COM feature flag.
src/​windows/​service/​exe/​WslCoreVm.cpp Applies shared backing-page configuration to WSL2.
src/​windows/​service/​exe/​HcsVirtualMachine.cpp Applies shared backing-page configuration to WSLC.
src/​windows/​common/​WslCoreConfig.h Defines the disabled-by-default setting and tracing field.
src/​windows/​common/​WslCoreConfig.cpp Parses the experimental setting.
src/​windows/​common/​hcs.hpp Declares the shared memory-policy helper.
src/​windows/​common/​hcs.cpp Implements backing-page and page-reporting policy.
src/​windows/​common/​hcs_schema.h Adds large-page JSON serialization support.
localization/​strings/​en-US/​Resources.resw Adds setting text and runtime-version diagnostics.
doc/​docs/​technical-documentation/​wslservice.exe.md Documents configuration, tradeoffs, and WSLC usage.
doc/​docs/​api-reference/​c/​session-apis/​wslcsetsessionsettingsfeatureflags.md Explains when runtime validation occurs.
doc/​docs/​api-reference/​c/​session-apis/​wslccreatesession.md Documents unsupported-runtime errors.
doc/​docs/​api-reference/​c/​enumerations/​wslcsessionfeatureflags.md Documents the new flag and requirements.

Review effort: Balanced

Comment thread src/windows/common/hcs.cpp Resolved
Copilot AI balanced review requested due to automatic review settings October 29, 2026 22:32

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Windows integration validation is still needed for HCS large-page allocation, VM creation and teardown in both paths, changed WSLC defaults on older hosts, and older-runtime rejection through the live SDK/COM path.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings October 29, 2026 22:42

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Windows integration testing is still needed to validate actual HCS large-page allocation, live SDK rejection of older runtimes, and the changed default WSLC backing-page policy on older hosts.

No open issues 🎉

Review effort: Balanced

@benhillis
Ben Hillis (benhillis) force-pushed the benhill/large-memory-backing-pages branch from fc0298f to db18759 Compare October 30, 2026 19:08
Copilot AI balanced review requested due to automatic review settings October 30, 2026 19:08

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The host backing-page and default WSLC policy changes still require live Windows/HCS validation of VM creation and teardown, actual large-page allocation, and SDK/COM rejection on older Windows runtimes.

No open issues 🎉

Review effort: Balanced

@craigloewen-msft

Copy link
Copy Markdown
Member

Naming wise I think instead of largeMemoryBackingPages=true , we could do something like memoryProfile=default and memoryProfile=performance for this one to make it clearer that you are trading off memory for perf?

@benhillis

Copy link
Copy Markdown
Member Author

Naming wise I think instead of largeMemoryBackingPages=true , we could do something like memoryProfile=default and memoryProfile=performance for this one to make it clearer that you are trading off memory for perf?

When presented with two options "default" and "performance" why would somebody ever choose default? I think the setting should reflect the tradeoffs.

Copilot AI balanced review requested due to automatic review settings November 2, 2026 19:04

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The default WSLC memory-backing change needs Windows/HCS owner review because historical-host allocation behavior and teardown-sensitive VID fix thresholds remain unvalidated.

No open issues 🎉

Review effort: Balanced

@craigloewen-msft

Copy link
Copy Markdown
Member

Naming wise I think instead of largeMemoryBackingPages=true , we could do something like memoryProfile=default and memoryProfile=performance for this one to make it clearer that you are trading off memory for perf?

When presented with two options "default" and "performance" why would somebody ever choose default? I think the setting should reflect the tradeoffs.

True. Perhaps conserveMemory or maxPerformance ?

Or Pierre's approach of memoryPageSize=small|medium|large| ?

My vote in order would be:

  1. memoryProfile=conserveMemory|maxPerformance
    1. Gives clearest description of what we are optimizing for, and allows us to bundle future improvements into this one setting
  2. memoryPageSize=small|medium|large
    1. Direct idea of what is actually changed, but a bit too low level to be understandable. I had to look up what effect this would even do on a VM, so what will a regular WSL user think for this?
  3. largeMemoryBackingPages=true
    1. I like the straightforward true or false, but it doesn't give an idea that memory will be hampered by this.

Blue (@OneBlue) what are your thoughts here?

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because the version-equality exception can admit an unsupported same-release runtime and produce the wrong session-creation error.

No open issues 🎉

Review effort: Balanced

Ben Hillis and others added 6 commits November 18, 2026 14:29
Add one minimum-version constant, localized runtime-update diagnostic, and isolated boundary tests for newly introduced SDK features. Preserve matching development-runtime support without changing existing feature compatibility.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c41a7ed8-95e1-43b6-adb5-b4e50c9dbff8
Expose experimental.largeMemoryBackingPages and WSLC session feature flags. Share HCS memory configuration and require WSL 3.1.0 for the new C SDK flag, with a matching development-runtime exception.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c41a7ed8-95e1-43b6-adb5-b4e50c9dbff8
Prevent newer Windows releases from falling through an older release's update revision threshold. Add boundary coverage and share the capability predicate with memory-policy tests while retaining host detection inside the configuration helper.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c41a7ed8-95e1-43b6-adb5-b4e50c9dbff8
Use feature bit 0x80 so nested virtualization can retain 0x40. Reuse shared runtime-version tests, minimum version, and localization without duplicate resources.

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

Copilot-Session: c41a7ed8-95e1-43b6-adb5-b4e50c9dbff8
Expose density and performance profiles while preserving the existing memory policy and default. Update documentation, localization, and configuration tests; leave WSLC feature flags unchanged.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: bbfcc7c8-242a-4d82-b768-0318e2c4fb78
Use small for the existing default and medium for 2 MiB backing pages. Reserve large for future support, rejecting it with the existing invalid-value warning for now. Update parsing, live VM tests, and developer documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9d91a4a8-bfd7-4045-89e0-5c70623c0247
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9d91a4a8-bfd7-4045-89e0-5c70623c0247
@benhillis
Ben Hillis (benhillis) force-pushed the benhill/large-memory-backing-pages branch from da45dee to 8375e99 Compare November 19, 2026 01:30
Copilot AI balanced review requested due to automatic review settings November 19, 2026 01:31
@benhillis Ben Hillis (benhillis) changed the title Add opt-in large memory backing pages for WSL2 and WSLC Add memoryPageSize configuration and WSLC backing-page opt-in Nov 19, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The version guard accepts older runtimes sharing the same three-part version, causing the new flag to fail with E_INVALIDARG instead of the promised localized runtime-update error.

1 open issue

Review effort: Balanced

Comment thread src/windows/WslcSDK/WslcsdkPrivate.h Resolved
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9d91a4a8-bfd7-4045-89e0-5c70623c0247
Copilot AI balanced review requested due to automatic review settings November 19, 2026 19:18

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Maintainer confirmation is needed for the VID teardown-fix build/UBR thresholds before defaulting additional pre-26100 WSLC hosts to small backing pages, since the tests do not independently establish teardown safety across supported servicing branches.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants