diff --git a/skills/rocm-doctor/.federated.json b/skills/rocm-doctor/.federated.json index f9e9f89..a39d758 100644 --- a/skills/rocm-doctor/.federated.json +++ b/skills/rocm-doctor/.federated.json @@ -2,9 +2,9 @@ "source": "rocm-rocm-cli", "repo": "ROCm/rocm-cli", "ref": "main", - "commit": "1c33248c318c72a9e837627ff71476c8583f1930", + "commit": "79f6e08c42b9b2e6cf7f21edad059c96cb9983f1", "path": "skills/rocm-doctor", "license": "MIT", - "content_hash": "9a7912109e4b0720c418203e6229f39e39254876f4252e1f1675e79517f90a2c", - "imported_at": "2026-10-26T07:00:26Z" + "content_hash": "2f597d3b525bbc2bb7107656af50ca361c688a89a0501416eadc5472fcb951dd", + "imported_at": "2026-10-28T06:35:51Z" } diff --git a/skills/rocm-doctor/SKILL.md b/skills/rocm-doctor/SKILL.md index 120cf49..a168784 100644 --- a/skills/rocm-doctor/SKILL.md +++ b/skills/rocm-doctor/SKILL.md @@ -118,6 +118,12 @@ passes — the GPU is AMD. Linux, Windows and WSL2 all run the same workflow. automatically the end of the question, either: a `diagnose-only` top match can clear the gate from host state alone, independent of whatever symptom was pasted — see the refinement in step 2. + - An **advice-only** entry in `matched[]` (today `fix-22-display-driver-old`) + scores below the threshold on purpose and never sets `has_match`. It is + not a cause of the symptom. Relay the entry's `title` and `evidence` to + the user as advice, and never apply it for them. Keep routing upstream if + `has_match` is false. Step 2's rule that a lower cause may be mentioned only + if it also clears `min_score_for_match` does not apply to this entry. - `matched[]` — ranked causes, each with `id`, `title`, `score` (0–100), `evidence[]`, and a `fix` (with `fix_id`, `summary`, `commands`, `verify`, `notes`, and the `needs_sudo` / `needs_reboot` / `needs_relogin` / @@ -162,7 +168,9 @@ passes — the GPU is AMD. Linux, Windows and WSL2 all run the same workflow. would if `has_match` were false. You may mention a lower cause only if it *also* clears `min_score_for_match` — below that threshold nothing was established, which is the same bar the `has_match` paragraph above sets, - and a `diagnose-only` top match does not lower it. + and a `diagnose-only` top match does not lower it. The one exception is the + advice-only `fix-22-display-driver-old` entry described under `has_match` + above: relay it as advice, never as a cause. 3. **Apply with consent.** For an auto-applicable fix: @@ -172,7 +180,7 @@ passes — the GPU is AMD. Linux, Windows and WSL2 all run the same workflow. rocm fix --yes # required to apply in a non-interactive shell ``` - Only the four auto-applicable fixes are ones the CLI runs itself. The other 23 + Only the four auto-applicable fixes are ones the CLI runs itself. The other 24 are **print-only** (bootloader, kernel, reinstall, Windows driver, …): `rocm fix ` just prints the plan for the user to run themselves — no prompt, and the CLI never performs those. diff --git a/skills/rocm-doctor/reference.md b/skills/rocm-doctor/reference.md index f8130fc..9bafc22 100644 --- a/skills/rocm-doctor/reference.md +++ b/skills/rocm-doctor/reference.md @@ -36,6 +36,11 @@ the result from `--json`: container, an APU alongside a discrete GPU), so a healthy host produces a non-empty `matched` full of sub-threshold entries. Gating on emptiness proposes a fix for a machine with nothing wrong and never routes upstream. + The exception is an **advice-only** entry (today `fix-22-display-driver-old`): + it scores below the threshold on purpose, so it never sets `has_match`, yet it + is advice worth giving. Relay the entry's `title` and `evidence` to the user as + advice and never apply it automatically. It does not answer the symptom, so route + upstream as usual when `has_match` is false. - `min_score_for_match` (50), `high_confidence_threshold` (75). - `out_of_scope` — set when the host's platform family has **no catalog entries at all**, in which case `matched` is empty. Linux, Windows and WSL2 are all @@ -100,7 +105,7 @@ non-interactive shell without `--yes`, and confirm first. **Two exceptions:** pinned. Run `rocm fix fix-9-igpu-dgpu --device-index N` (not the bare id) once you know N. -## Closed catalog (28 failure modes) +## Closed catalog (29 failure modes) The OS column is the platform family the CLI scopes an entry to, and WSL2 is a family of its own — not a flavour of `linux`. An entry reaches a WSL host only @@ -131,6 +136,7 @@ reporting confident nonsense. | `fix-19-shm-too-small` | linux/wsl | `/dev/shm` too small for a serving workload, which needs gigabytes where a container and WSL2 both default to 64 MB | reported under 1 GiB; a data-loader worker killed by a bus error, or a failed write to a temporary file, with nothing naming shared memory | print-only | | `info-20-gpu-no-rocm-support` | linux/windows | Every AMD GPU on the host is a part ROCm has never shipped a runtime build for (today: gfx90c, the Vega iGPU in Renoir / Lucienne / Cezanne / Barcelo). Vulkan-based engines still work | every detected AMD GPU identifies as an unsupported target, and none is unidentified; scores a flat 60 | diagnose-only | | `fix-21-msvc-redist-outdated` | windows | MSVC runtime present but older than 14.40, so programs built with a recent toolset (such as the llama.cpp server that Lemonade installs) crash | `rocm examine --json` shows `msvc_redist_version` below 14.40; an access violation (`0xC0000005`, `-1073741819`) with `msvcp140.dll` as the faulting module | print-only | +| `fix-22-display-driver-old` | windows | The AMD display driver is dated before the first HIP SDK for Windows (27 July 2023). Advice only: AMD publishes no minimum driver version for the HIP SDK or the Lemonade Vulkan backend, so the minimum is not established and the entry never claims the driver is broken. The date is only a floor and cannot judge newer GPUs such as gfx120X, gfx1150 and gfx1151, which may need newer drivers | `rocm examine` shows `driver_age: older than the first HIP SDK for Windows`; the entry scores below the match threshold (WEAK) | print-only | | `fix-wsl-1-gpu-not-exposed` | wsl | `/dev/dxg` absent, so the distro cannot reach the GPU at all | no `/dev/dxg`; in a container, the device was never passed through | print-only | | `fix-wsl-2-dxcore-missing` | wsl | `/usr/lib/wsl/lib` DXCore shims missing, so the runtime cannot reach the host driver | `/usr/lib/wsl/lib/libdxcore.so` missing (or the directory absent entirely) | print-only | | `fix-wsl-3-rocdxg-missing` | wsl | ROCDXG, the ROCm-to-DXCore shim the WSL path runs on, is not installed | `librocdxg.so` not found under any ROCm install | print-only | @@ -142,13 +148,13 @@ reporting confident nonsense. One thing the numbering does not tell you: the `fix-wsl-N` entries are a parallel series, not a continuation of the numeric one, because they answer for a different platform family. The numeric series itself runs `fix-1` through -`fix-19`, then `fix-21`. The ids are stable handles rather than positions, so +`fix-19`, then `fix-21` and `fix-22`. The ids are stable handles rather than positions, so the number `fix-20` is simply not used here: slot 20 belongs to `info-20-gpu-no-rocm-support`, which is in the table above but under an `info-` prefix because it has no fix to offer. A gap is not an error, and a retired entry would leave a hole rather than renumber the ones after it. -Linux-only: fix-3, -4, -5, -7, -10, -11, -12. Windows-only: fix-13, -14, -15, -21. +Linux-only: fix-3, -4, -5, -7, -10, -11, -12. Windows-only: fix-13, -14, -15, -21, -22. Linux + Windows: info-20 (diagnose-only). WSL-only: fix-wsl-1 through fix-wsl-7. Linux + Windows: fix-9. Linux + WSL: fix-16, -17, -18, -19. Linux + Windows + WSL: fix-1, -2, -6, -8.