wslservice: Add experimental.swiotlb .wslconfig setting by asherkariv · Pull Request #40518 · microsoft/WSL

asherkariv · 2026-05-13T01:18:24Z

Add a new experimental .wslconfig key "experimental.swiotlb" that configures SWIOTLB bounce buffer parameters for WSL VMs using virtio devices. The setting is validated, propagated to wsldevicehost.dll via control tokens in the share name, and (for range mode) also passed to the guest kernel command line.

Supported values:

"0x,K|M" (range mode): explicit bounce buffer location Example: experimental.swiotlb=0x100000000,64M

Behavior:

Validated against regex at config parse time; invalid values emit a user warning and are ignored
Requires virtiofs to be enabled; emits a warning and clears the setting if virtiofs is disabled
Appends "hv_pci_swiotlb=," to the kernel command line so the guest driver can locate the bounce buffer
Append ";swiotlb=" to the virtiofs mount options string, which wsldevicehost.dll parses as a control configuration token and strips before passing mount options to the guest

Files changed:

WslCoreConfig.h/cpp: SwiotlbCfg fields, parsing, validation, virtiofs dependency check
WslCoreVm.cpp: kernel cmdline and virtiofs share name plumbing
Resources.resw: error/warning message strings

Related work items: https://microsoft.visualstudio.com/OS/_workitems/edit/61002501

Summary of the Pull Request

PR Checklist

Closes: Link to issue #xxx
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: #xxx

Detailed Description of the Pull Request / Additional comments

Validation Steps Performed

Copilot

Pull request overview

This PR introduces a new experimental .wslconfig key (experimental.swiotlb) to control SWIOTLB bounce buffer behavior for WSL VMs using virtio devices. The setting is validated during config parsing, optionally propagated to the guest kernel command line (range mode), and also forwarded to wsldevicehost.dll via a virtiofs “name-with-options” control token.

Changes:

Add experimental.swiotlb parsing/validation and store both a virtiofs token value (SwiotlbCfg) and an optional kernel cmdline value (SwiotlbKernelCfg).
Plumb SWIOTLB configuration into virtiofs share options and (range mode) append hv_pci_swiotlb= to the guest kernel command line.
Add new constants and localization strings for invalid-value and virtiofs-required warnings.

Reviewed changes

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

Show a summary per file

File	Description
src/windows/service/inc/wslservice.idl	Adds `LXSS_VM_KERNEL_SWIOTLB_CONFIG` constant used when building the kernel cmdline.
src/windows/service/exe/WslCoreVm.cpp	Appends SWIOTLB kernel parameter (range mode) and adds virtiofs control token in share options.
src/windows/common/WslCoreConfig.h	Adds config key name and new config fields (`SwiotlbCfg`, `SwiotlbKernelCfg`) + telemetry presence bit.
src/windows/common/WslCoreConfig.cpp	Implements `experimental.swiotlb` parsing/validation and enforces virtiofs dependency.
src/shared/inc/lxinitshared.h	Adds `LX_INIT_SWIOTLB_MOUNT_OPTIONS` mount-option/control-token prefix.
localization/strings/en-US/Resources.resw	Adds localized warning strings for invalid SWIOTLB and virtiofs-required cases.

Copilot

Pull request overview

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

Copilot

Pull request overview

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

benhillis · 2026-05-13T23:57:12Z

I might be confused but I thought we didn’t need this setting until we have the updated kernel?

…n WSLC A user-supplied WSL2 kernel without the WSL swiotlb patch ignores hv_pci_swiotlb= but still receives the wsldevicehost `;swiotlb=` tokens from PR #40518, mis-configuring DMA. Detect kernel support at runtime in mini_init via env-var presence (unrecognized key=value cmdline params are passed to init as env vars; early_param/__setup consumes them when the patch is present). Report the bit back through LX_INIT_GUEST_CAPABILITIES and cache the effective swiotlb value on WslCoreVm right after ReadGuestCapabilities so both consumer sites (drvfs virtiofs and VirtioProxy networking) reuse it and the kernel-unsupported warning fires at most once. Move drvfs thread spawn after ReadGuestCapabilities so the flag is available without a wait/event dance. Enable swiotlb unconditionally on WSLC since it ships its own patched kernel. Hoist c_swiotlbDefault to GuestDeviceManager.h and fold the swiotlb=force hv_pci_swiotlb=<cfg> append into AppendCommonKernelCommandLine. Replace the ad-hoc EnableVirtioFs/VirtioProxy consumer detection with the EnableVirtio master switch, which also covers WSLg's virtio-fs device. Reject NetworkingMode=VirtioProxy when EnableVirtio=false with a fallback to NAT and a user warning. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

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

@@ -859,7 +881,7 @@ void WslCoreVm::AddDrvFsShare(_In_ bool Admin, _In_ HANDLE UserToken)
            ULONG index;
            WI_VERIFY(_BitScanForward(&index, fixedDrives) != FALSE);
            const wchar_t fixedDrivePath[] = {gsl::narrow_cast<wchar_t>(L'A' + index), L':', L'\\', L'\0'};
-            AddVirtioFsShare(Admin, fixedDrivePath, TEXT(LX_INIT_DEFAULT_PLAN9_MOUNT_OPTIONS), UserToken);
+            AddVirtioFsShare(Admin, fixedDrivePath, mountOptions.c_str(), UserToken);


Lets WSL2 users opt in to a swiotlb bounce buffer for virtio devices via .wslconfig. The setting is gated on a runtime kernel capability probe: mini_init checks whether hv_pci_swiotlb= was consumed by the kernel and reports the result back to wslservice through the guest capabilities channel. If the user enables swiotlb but the running kernel lacks the patch, the value is silently dropped and a one-time perf-hint warning is emitted. The configured value is appended as a ;swiotlb=<config> token to all virtio device option strings: initial fixed-drive virtiofs shares, dynamic virtiofs shares (guest add and remount paths), and the VirtioProxy virtio-net adapter (host-routed + loopback). WSLC ships its own patched kernel, so swiotlb is hardcoded on for WSLC virtio devices with no config knob. Also gates virtio-related settings behind a single EnableVirtio master switch and falls VirtioProxy networking back to NAT (or None) with a warning when the user disables virtio. Co-authored-by: Asher Kariv <askariv@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 13, 2026 01:18

Copilot started reviewing on behalf of asherkariv May 13, 2026 01:19 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Comment thread src/windows/common/WslCoreConfig.cpp Outdated

Comment thread src/windows/common/WslCoreConfig.cpp Outdated

benhillis reviewed May 13, 2026

View reviewed changes

Comment thread src/shared/inc/lxinitshared.h Outdated

benhillis reviewed May 13, 2026

View reviewed changes

Comment thread src/windows/common/WslCoreConfig.cpp

benhillis reviewed May 13, 2026

View reviewed changes

Comment thread src/windows/service/inc/wslservice.idl Outdated

Copilot AI review requested due to automatic review settings May 13, 2026 21:49

Copilot started reviewing on behalf of asherkariv May 13, 2026 21:52 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Comment thread src/windows/common/WslCoreConfig.h Outdated

benhillis requested a review from Copilot May 13, 2026 23:52

Copilot started reviewing on behalf of benhillis May 13, 2026 23:53 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Comment thread test/windows/UnitTests.cpp Outdated

Copilot AI review requested due to automatic review settings May 18, 2026 21:05

Copilot started reviewing on behalf of benhillis May 18, 2026 21:07 View session

Copilot AI reviewed May 18, 2026

View reviewed changes

benhillis force-pushed the user/askariv/swiotlb-enable branch from 643d5f7 to 31ef8c1 Compare May 19, 2026 01:45

Copilot AI review requested due to automatic review settings May 19, 2026 22:27

benhillis force-pushed the user/askariv/swiotlb-enable branch from 31ef8c1 to 0468b35 Compare May 19, 2026 22:27

Copilot started reviewing on behalf of benhillis May 19, 2026 22:33 View session

provide a way to override wsldevicehost.dll

146ca92

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

wslservice: Add experimental.swiotlb .wslconfig setting#40518

wslservice: Add experimental.swiotlb .wslconfig setting#40518
asherkariv wants to merge 2 commits into
masterfrom
user/askariv/swiotlb-enable

asherkariv commented May 13, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

benhillis commented May 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Summary of the Pull Request

PR Checklist

Detailed Description of the Pull Request / Additional comments

Validation Steps Performed

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!

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!

benhillis commented May 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

asherkariv commented May 13, 2026 •

edited

Loading