wslservice: Add swiotlb support with gating, vmId plumbing, and devicehost override by asherkariv · Pull Request #40518 · microsoft/WSL

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

Add SWIOTLB bounce buffer support for WSL VMs using virtio devices, with proper gating, VM identification, and a developer override for wsldevicehost.dll.

Summary of the Pull Request

experimental.swiotlb .wslconfig setting

New key experimental.swiotlb configures bounce buffer parameters for virtio devices
Supported format: 0x<gpa>,<size>K|M (e.g. experimental.swiotlb=0x100000000,64M)
Validated at parse time; invalid values emit a warning and fall back to computed default
Appends hv_pci_swiotlb=<gpa>,<size> to kernel command line
Appends ;swiotlb=<value> to virtiofs/virtio-net device options

Swiotlb gating

Only compute a default bounce buffer when a virtio device that requires bounce buffers is present (virtiofs, virtio9p, or VirtioProxy networking)
Applies to both WSL2 (WslCoreConfig.cpp) and WSLC (HcsVirtualMachine.cpp) paths
Runs after policy overrides so networking/fs modes reflect final values

vmId plumbing

GuestDeviceManager::AddHdvShareWithOptions unconditionally appends vmId=<machineId> to every virtio device's options
Allows wsldevicehost.dll to identify which VM owns each device

WSL_DEVICE_HOST_DLL CMake override

New CMake cache variable to substitute a local wsldevicehost.dll at build time without updating the NuGet package
Documented in UserConfig.cmake.sample and dev-loop.md

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

PR Checklist

Closes: Link to issue #xxx
Communication: I've discussed this with core contributors already.
Tests: Added/updated if needed and all pass
Localization: All end user facing strings can be localized
Dev docs: Added/updated if needed

Validation Steps Performed

Verified swiotlb default is only computed when virtiofs/virtio9p/virtioproxy is enabled
Verified vmId appears in device option strings for all virtio device types
Verified no double semicolons when Options is empty or null
Verified WSL_DEVICE_HOST_DLL override works with valid path and errors on missing file

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.

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>

- Gate swiotlb default computation: only compute when virtiofs, virtio9p, or VirtioProxy is enabled (both WSL2 and WSLC paths) - Inject vmId=<machineId> into all virtio device options via GuestDeviceManager::AddHdvShareWithOptions - Add WSL_DEVICE_HOST_DLL CMake override to replace wsldevicehost.dll without a NuGet update - Fix empty-options guard to prevent double semicolons 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

Comment thread src/windows/service/exe/WslCoreVm.cpp Outdated

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

benhillis force-pushed the user/askariv/swiotlb-enable branch from 146ca92 to 5664a8f Compare May 20, 2026 19:01

benhillis changed the title ~~wslservice: Add experimental.swiotlb .wslconfig setting~~ wslservice: Add swiotlb support with gating, vmId plumbing, and devicehost override May 20, 2026

benhillis reviewed May 20, 2026

View reviewed changes

Comment thread src/windows/common/helpers.cpp

benhillis force-pushed the user/askariv/swiotlb-enable branch 2 times, most recently from ac0aade to 4134f07 Compare May 20, 2026 22:38

benhillis force-pushed the user/askariv/swiotlb-enable branch from 4134f07 to a9fc266 Compare May 21, 2026 00:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

wslservice: Add swiotlb support with gating, vmId plumbing, and devicehost override#40518

wslservice: Add swiotlb support with gating, vmId plumbing, and devicehost override#40518
asherkariv wants to merge 2 commits into
masterfrom
user/askariv/swiotlb-enable

asherkariv commented May 13, 2026 •

edited by benhillis

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!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Summary of the Pull Request

experimental.swiotlb .wslconfig setting

Swiotlb gating

vmId plumbing

WSL_DEVICE_HOST_DLL CMake override

PR Checklist

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!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

asherkariv commented May 13, 2026 •

edited by benhillis

Loading