Skip to content

fix(wsl): give examine, serve and the probe one answer about WSL2 - #220

Merged
volen-silo merged 1 commit into
mainfrom
fix/one-wsl-answer
Aug 12, 2026
Merged

volen-silo merged 1 commit into
mainfrom
fix/one-wsl-answer

Conversation

@volen-silo

Copy link
Copy Markdown
Collaborator
  • If this PR fixes a bug, searched tests/e2e-cucumber/expectations.toml for the fixed ticket ID and removed/narrowed any now-stale xfail rows. No row references this behaviour — there is no WSL lane in CI (see below).

Branches off main, independent of the #216 → #217 → #218 stack and of #219.

Summary

Three places decided whether a host was WSL2, on different evidence:

evidence
install summary (detect_wsl_summary) /dev/dxg or microsoft in /proc/version
JSON probe (probe_os) microsoft or wsl in /proc/version, or $WSL_DISTRO_NAME
serve (probe_usable_amd_gpu_indices) counts KFD nodes and amdgpu DRM cards — neither exists on WSL2

So a host with /dev/dxg and a kernel string naming neither was WSL to one and not the other, and rocm examine could contradict rocm examine --json about the platform it was describing. The e2e harness derives is_wsl for its entire expectation matrix by scraping one of them.

There is now one predicate, the union of every signal any of them used. A false positive costs a route-out note; a false negative runs bare-metal driver checks against a platform with no amdgpu module and reports nonsense.

serve refusing on a machine examine called ready

linux_kfd_gpu_node_count returns Some(0) — an authoritative zero, not "unknown" — when the topology directory is unreadable and /dev/kfd is absent. That is exactly the WSL2 shape, so a GPU-required launch was refused on a machine whose own examine reported wsl_rocdxg_ready.

Verified from the code rather than taken from the report: on this WSL2 box /dev/kfd, /sys/class/kfd and /dev/dxg are all absent while /sys/class/drm exists, which lands on that branch.

serve now asks the plumbing WSL2 actually uses, through the same readiness rule the report prints — extracted to WslSummary::rocdxg_ready so there is one source. Ready means a device, not-ready means none, and both match what examine says. HIP_VISIBLE_DEVICES still applies on top.

The probe gave up before the frameworks

Deferred here from #218. The driver probes are rightly skipped on WSL2 — modprobe, the render group and /dev/kfd say nothing about a platform that does not use them. But PyTorch on WSL2 is a supported, documented configuration, and stopping before the framework probe meant --json could never say which ROCm build a user's torch was compiled against.

That one probe now runs before routing out. Measured on this box, diffing the document before and after — the only field that changes:

framework_notes: []
  -> ["torch import failed: ModuleNotFoundError: No module named 'torch'",
      "No llama.cpp binary (llama-cli/llama-server/main) on PATH."]

An actual answer instead of silence.

Cost, stated plainly: rocm diagnose on WSL2 now pays a Python interpreter start it previously skipped, and then declares itself out of scope as before. On any other platform it already paid that cost. Worth it for examine, arguably not for diagnose; if a reviewer disagrees, the cleaner fix is for diagnose to request FrameworkProbe::Skip, which #218 makes expressible.

Test plan

The predicate is split from the machine reads so the union can be tested. Seven new tests:

  • every signal is believed individually, and an ordinary kernel string is not WSL;
  • the two shapes that split the old implementations both resolve to WSL now — the regression this PR exists to prevent;
  • casing does not matter;
  • rocdxg_ready requires the whole chain, asserted by breaking each link in turn — any one missing and a GPU launch cannot work, so serve must not be told it can;
  • the EAI-7944 shape end to end: ready offers device 0, not-ready offers none, and an explicit empty HIP_VISIBLE_DEVICES still hides it.

cargo test -p rocm-core: 264 pass. Failures are the known WSL2-local proc_lifecycle::tests::tree_* pair and the pre-existing providers::tests::local_provider_* / therock flakes, all of which reproduce on main. cargo fmt --all --check, workspace clippy --all-targets -D warnings and the prek hygiene hooks are clean.

Verification gap. There is no WSL runner in CI, so none of this is exercised by any lane — the coverage is the unit tests plus manual verification on this WSL2 box. The serve half in particular cannot be proven end to end here, because this box has no /dev/dxg: it is a WSL2 install without GPU plumbing, so serve correctly refuses both before and after. Someone with a working ROCm-on-WSL2 setup should confirm the reported symptom is gone.

cargo xtask e2e reports the two diagnose scenarios failing — the known WSL2-local noise that #216 fixes with @requires-bare-metal and this branch does not carry, not a regression from this change.

🤖 Generated with Claude Code

Three places decided whether a host was WSL2, and they used different
evidence. The install summary asked for /dev/dxg or "microsoft" in
/proc/version; the JSON probe asked for "microsoft" or "wsl" in /proc/version,
or $WSL_DISTRO_NAME. A host with /dev/dxg and a kernel string naming neither
was WSL to one and not the other, so `rocm examine` and `rocm examine --json`
could disagree about the platform they were describing. The e2e harness
derives is_wsl for its whole expectation matrix by reading one of them.

There is now one predicate, the union of every signal any of them used. A
false positive costs a route-out note; a false negative runs bare-metal driver
checks against a platform with no amdgpu module and reports nonsense.

`serve` was a third answer, and a worse one. It counted KFD topology nodes and
amdgpu DRM cards -- neither of which exists on WSL2 -- and
`linux_kfd_gpu_node_count` reads "topology unreadable AND no /dev/kfd" as an
authoritative zero rather than as unknown. That is precisely the WSL2 shape, so
a machine whose own `examine` said `wsl_rocdxg_ready` was refused a
GPU-required launch for having no GPU. It now asks the plumbing WSL2 actually
uses, via the same readiness rule the report prints, so the two cannot
contradict each other in either direction.

The probe also stopped before its framework step on WSL2. The driver probes are
rightly skipped there -- modprobe, the render group and /dev/kfd say nothing
about a platform that does not use them -- but PyTorch on WSL2 is a supported,
documented configuration, and a user asking which ROCm build their torch has
was told nothing at all. That one probe now runs before routing out. On this
WSL2 box it turns an empty framework_notes into "torch import failed:
ModuleNotFoundError" plus "No llama.cpp binary on PATH" -- the actual answer.

The predicate is split from the machine reads so the union can be tested,
including the two shapes that split the old implementations.

Signed-off-by: Eugene Volen <Eugene.Volen@amd.com>
@volen-silo
volen-silo requested a review from a team as a code owner August 12, 2026 10:12
@juhovainio

Copy link
Copy Markdown
Collaborator

Reviewed this against the live code, not just the diff, and the three-implementations-into-one claim holds up exactly as described.

  • is_wsl_host()/wsl_signals_indicate_wsl() (lib.rs) is genuinely the union of what the three old checks used: /dev/dxg, $WSL_DISTRO_NAME, and microsoft/wsl in /proc/version. I diffed probe_os and detect_wsl_summary against origin/main - the old JSON probe only checked /dev/dxg OR microsoft in /proc/version (missing wsl and $WSL_DISTRO_NAME), and the old install summary only checked /dev/dxg OR microsoft (missing wsl and $WSL_DISTRO_NAME too, just a different pair) - so the "these two shapes used to split them" test case is a real, previously-possible disagreement, not a hypothetical.
  • Grepped for every consumer of WSL state (Examination.is_wsl, WslSummary.is_wsl) across diagnose.rs and main.rs: all of them read one of the two fields this PR now derives from the single predicate. No third path was missed.
  • WslSummary::rocdxg_ready() is correctly wired into both wsl_driver_summary (what examine prints) and the new WSL branch in probe_usable_amd_gpu_indices (what serve checks) - confirmed they're now literally the same boolean expression instead of two independent ones.
  • probe_framework is only reachable via which/subprocess calls (python, llama.cpp binary lookup) with no dependency on kernel modules or /dev/kfd, so running it before the WSL route-out is safe as claimed - it doesn't reintroduce the misleading driver-probe problem the route-out exists to avoid.
  • usable_amd_gpu_indices_from(usize::from(ready), mask) correctly returns Some(vec![0])/Some(vec![]) for ready/not-ready, and an explicit empty HIP_VISIBLE_DEVICES mask still overrides to empty - matches the new test and the PR's stated behavior.

One thing worth naming but not blocking: probe_usable_amd_gpu_indices now branches on is_wsl_host() before falling back to the KFD/DRM count. If that predicate ever produced a false positive on a genuine bare-metal box (e.g. a custom kernel build with "wsl" somewhere in its version string), serve would report zero GPUs from detect_wsl_summary() instead of running the real KFD/DRM check - a regression in that direction, versus today's real bug of false negatives on actual WSL2 hosts. Given how narrow that surface is ($WSL_DISTRO_NAME is WSL-specific by convention, and "wsl" showing up in /proc/version on real bare metal would be unusual), this reads as an accepted and reasonable trade-off rather than an oversight, especially since the PR is explicit that a false positive is the cheaper failure mode.

CI is green across every lane. The PR is upfront about the verification gap (no WSL runner in CI, and the serve half can't be proven end to end on the reporting box since it has no /dev/dxg) - that's a reasonable gap to leave stated rather than block on, given the predicate itself is unit-tested and the two production call sites both now route through it.

Looks safe to approve after final validation.

@volen-silo
volen-silo added this pull request to the merge queue Aug 12, 2026
Merged via the queue into main with commit 737c269 Aug 12, 2026
36 of 37 checks passed
@volen-silo
volen-silo deleted the fix/one-wsl-answer branch August 12, 2026 13:13
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.

2 participants