fix(wsl): install ROCDXG from the CLI instead of naming a repo script - #224
Open
rominf wants to merge 1 commit into
Open
fix(wsl): install ROCDXG from the CLI instead of naming a repo script#224rominf wants to merge 1 commit into
rominf wants to merge 1 commit into
Conversation
On WSL2 `rocm install driver` refused to do anything and told the user to run `scripts/wsl_setup_rocdxg.sh`. That script shipped only in a git checkout -- the release bundle is `bin/`, README, LICENSE and the installer -- so for anyone who installed rocm-cli normally the guidance named a file they do not have. It matters because ROCDXG is what lets the runtime reach the GPU under WSL2. Without it `examine` reports `wsl_rocdxg_missing` and `serve` refuses with "no usable AMD GPU detected" while still detecting a gfx target, which is read from the Windows-side driver. So the one platform where a ROCm library decides whether the GPU works was the one platform where the CLI would not install it. The WSL branch now returns a real plan -- the same steps the script ran, through the machinery every other platform already uses, so it inherits plan-then-approve, `--dry-run` and the recorded install state. It guards on /dev/dxg, dxcore and sudo before touching anything, since those come from the platform and no package substitutes for them, then verifies the two things `examine` keys `wsl_rocdxg_ready` on. The script is deleted rather than left beside it: two implementations of one privileged install means two version pins and two digest variables to drift apart, and nothing in CI ever ran it. Version and checksum follow the conventions already in this file: `ROCM_CLI_ROCDXG_VERSION` mirrors `ROCM_CLI_AMDGPU_VERSION`, and no digest is embedded because the release is not reproducible from here -- an unset `ROCM_CLI_ROCDXG_SHA256` says so rather than reporting an unverified download as verified. Plans now carry `reboot_required`. It stays true for the DKMS paths, which are not live until the machine restarts, and is false here: ROCDXG is userspace and `ldconfig` publishes it immediately. Previously the post-execution output asserted a reboot unconditionally, which would have been wrong advice on this path, and the verification steps are labelled post_install rather than post_reboot to match. Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
rominf
force-pushed
the
fix/wsl-install-rocdxg
branch
from
August 12, 2026 13:34
c4d8367 to
02144d4
Compare
rominf
marked this pull request as ready for review
August 12, 2026 16:18
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
On WSL2,
rocm install driverrefused to do anything and pointed the user at ascript that is not shipped:
scripts/is not in the release bundle —xtask packagestagesbin/rocm,bin/rocmd,README.md,LICENSE.TXTand the platform installer — so foranyone who installed rocm-cli normally that names a file they do not have.
It matters because ROCDXG (
librocdxg) is what lets the ROCm runtime reach theGPU under WSL2. Without it
examinereportswsl_rocdxg_missingandserverefuses with "no usable AMD GPU detected", while still detecting a gfx target —
that target is read from the Windows-side driver, so its presence says nothing
about whether ROCm can use the device. The one platform where a ROCm-provided
library decides whether the GPU works was the one platform where the CLI would
not install it.
Fixes #223.
What changes
The WSL branch of
build_driver_install_planreturns a real plan instead of arefusal — the same steps
scripts/wsl_setup_rocdxg.shruns, expressed throughthe machinery every other platform already uses. That is deliberate: it inherits
plan-then-approve,
--dry-run, the recorded install state and the post-installreconciliation without any new download or verification code.
Guards before anything mutates.
/dev/dxgand dxcore come from the Windowsside; if they are absent the fix is on the host and installing the bridge
library accomplishes nothing, so the plan stops rather than reporting a
successful install of something inert.
Verification asserts what
examinekeys on.wsl_rocdxg_readyrequires thelibrary and its ldconfig entry, so both are checked — a partial install cannot
report success.
Version and checksum follow the conventions already in this file.
ROCM_CLI_ROCDXG_VERSIONmirrors the existingROCM_CLI_AMDGPU_VERSIONtreatment: a shell-expanded expression, so the printed plan shows both the
variable and the default. One expression drives the archive name, the tag and
the path, so an override cannot leave a URL pointing at the default. No digest
is embedded, because the release is not reproducible from here — an unset
ROCM_CLI_ROCDXG_SHA256says so explicitly rather than letting an unverifieddownload read as verified.
reboot_requiredis now a property of the planPreviously the post-execution output asserted
reboot_required: trueunconditionally. That is right for the DKMS paths — an amdgpu module is not live
until the machine restarts — and wrong here: ROCDXG is userspace and
ldconfigpublishes it in the current boot. Plans now carry the flag, the DKMS paths keep
true, and the verification steps are labelledpost_installrather thanpost_rebootso the rendered plan does not contradict the state it records.The script is deleted, not kept alongside
scripts/wsl_setup_rocdxg.shis removed. Keeping it would leave twoimplementations of one privileged install, and specifically two of everything
that can drift: a
ROCDXG_VERSION=1.2.0pin beside${ROCM_CLI_ROCDXG_VERSION:-1.2.0}, and aROCDXG_SHA256variable besideROCM_CLI_ROCDXG_SHA256. Nothing in CI ever ran it — theROCDXG_CHECKSUM_SELF_TESThook existed only as a manual step indocs/testing.md— so it was an unshipped, untested installer.Its one behaviour the plan lacked, an explicit "sudo is required" message
instead of a bare
sudo: command not found, is folded in as a third guard.scripts/wsl_preflight.pyis untouched: it still has a Windows-to-distro checkwith no CLI equivalent.
Docs now lead with
rocm install driver.Not addressed here:
rocm diagnosestill declares the bare-metal catalog out ofscope on WSL with no entry for
wsl_rocdxg_missing, so that finding has norunnable command — the class of problem #209 fixed elsewhere. It wants a catalog
entry pointing at this command, which is a separate change.
Test plan
Six unit tests, covering the install steps and URL, the ordering guarantee that
the plumbing and sudo guards precede the first mutating command, the verification pair,
checksum opt-in/enforcement, override reach, and that WSL asks for no reboot
while bare metal still does.
Verified on a real WSL2 host: the reproduction from the report now prints the
plan above instead of the refusal. The plumbing guard and the three checksum
branches (unset / matching / mismatched) were exercised directly and behave as
intended — exit 1 with the stated message, skip-with-notice,
OK, andFAILEDrespectively.
Verification gap. This box is WSL2 without GPU passthrough
(
driver_status: wsl_gpu_plumbing_missing, no/dev/dxg), so the installitself cannot be run through end to end here — the plan correctly refuses at the
first guard. Someone with
/dev/dxgand dxcore present should confirm a real--yesrun reacheswsl_rocdxg_ready. The self-hosted WSL2 CI runner is acandidate once #141 lands.
cargo clippy --locked --workspace --all-targets -- -D warnings,cargo clippy --locked -p e2e-cucumber --test e2e -- -D warnings,cargo fmt --all --checkandprek run --all-filesare clean.cargo test -p rocm --bin rocm: 433 pass; the two failures are the known local flakes(
providers::tests::local_provider_default_chat_requires_builtin_qwen_assistant,therock::tests::extracting_the_sdk_archive_removes_it), both of whichreproduce on an unmodified
maincheckout in this environment.Risk: medium. A command that previously did nothing on WSL now runs privileged
package operations — but only behind the same explicit
--yesapproval as everyother platform, and only after the plumbing guards pass.