Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions skills/rocm-doctor/.federated.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
12 changes: 10 additions & 2 deletions skills/rocm-doctor/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` /
Expand Down Expand Up @@ -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:

Expand All @@ -172,7 +180,7 @@ passes — the GPU is AMD. Linux, Windows and WSL2 all run the same workflow.
rocm fix <fix-id> --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 <id>` just prints the plan for the user to run themselves — no prompt, and
the CLI never performs those.
Expand Down
12 changes: 9 additions & 3 deletions skills/rocm-doctor/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 |
Expand All @@ -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.
Expand Down
Loading