From eb16bc202076797f451c85f28bf1565ede63b444 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Fri, 13 Nov 2026 12:46:08 +0200 Subject: [PATCH 1/8] fix(rocm-core): report a timed-out rocm fix step as such (ROCMAI-345) The fix runners read the probe adapter's collapsed exit code, so a helper stopped at the one-minute bound was reported as "usermod exited 124; group membership NOT changed." That names no timeout, offers no way to recover, and asserts a state nobody checked: the executor stops only the direct child, so usermod under sudo can still finish. Run each step through the bounded executor and report from its typed outcome. A command that exits non-zero or cannot start still says the change was NOT made; one that times out, is signalled or cannot be waited for now says the change may or may not have been made, names a command to check it, and the rocm fix command to re-run. The line and exit code 4 come from one value, and the re-run ids are the catalog's own constants. On Windows, a PowerShell read of the current User/Machine value that did not complete used to be taken as "unset": fix-2 then reported the override as gone and exited 0, and fix-9 skipped its already-set guard and ran setx. Both now stop with exit 4 before planning or prompting, as fix-6 already did. Covered by unit tests over an injected command runner for every outcome of each runner, and by e2e scenarios diagnose-15 (extended), 39 (tightened) and the new 62 (Linux helper never finishes), 63 and 64 (Windows reads fail). Docs, --help and the rocm-doctor skill describe the new exit-4 cases. Signed-off-by: Roman Inflianskas --- README.md | 8 + apps/rocm/src/cli.rs | 6 + crates/rocm-core/src/fix.rs | 3 + crates/rocm-core/src/fix/catalog.rs | 17 +- crates/rocm-core/src/fix/consent.rs | 257 +++++ crates/rocm-core/src/fix/runners.rs | 885 +++++++++++++++--- docs/architecture.md | 2 +- docs/host-probing.md | 2 +- docs/manual-testing.md | 48 + docs/testing.md | 33 + skills/rocm-doctor/SKILL.md | 6 + skills/rocm-doctor/reference.md | 2 +- tests/e2e-cucumber/features/diagnose.feature | 47 +- .../e2e-cucumber/tests/e2e/diagnose_steps.rs | 266 +++++- 14 files changed, 1418 insertions(+), 164 deletions(-) diff --git a/README.md b/README.md index 143ff6f4c2..958c80dc20 100644 --- a/README.md +++ b/README.md @@ -506,6 +506,14 @@ hardware, not something an install or a setting can put right. applies no fix and exits 0. Together with a fix id it is refused, with exit code 1. +A fix that runs a command and fails exits 4 and says why on stderr. That +includes a command that does not finish within its time limit (one minute): +the CLI stops it and exits 4, but the change may have been made in part or may +still finish, so the message names a command to check it with and the +`rocm fix` command to re-run if it was not made. On Windows, a fix that cannot +read the current value of the variable it changes stops before changing +anything, also with exit 4. + ### ROCm installation ``` diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index 652003072f..fe76bf14fe 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -233,6 +233,12 @@ pub(crate) enum Command { /// marked that way today: a GPU ROCm has no runtime build for is a fact /// about the hardware, not something to put right). /// Use `--dry-run` to see any fix's plan without changing anything. + /// + /// A fix whose command fails exits 4 and says why on stderr. A command that + /// does not finish within its time limit is stopped and also exits 4; the + /// change may then be partial, so the message names how to check it and the + /// `rocm fix` command to re-run. On Windows, a fix that cannot read the + /// variable it changes stops before changing anything, with exit 4. Fix { /// Fix id, e.g. fix-4-render-group. Omit to list available fixes. fix_id: Option, diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index daa59a991a..532a80501a 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -858,10 +858,12 @@ mod tests { "apply", "act_on", "run_render_group", + "render_group_with", "run_unset_override", "run_unset_override_linux", "report_persistent_override", "run_unset_override_windows", + "unset_override_windows_with", "report_and_clear_override_windows", "run_path_export", "run_path_export_linux", @@ -871,6 +873,7 @@ mod tests { "run_hip_visible_devices_linux", "pin_device_in_rc_file", "run_hip_visible_devices_windows", + "hip_visible_devices_windows", ] { assert!( scan.checked.iter().any(|name| name == runner), diff --git a/crates/rocm-core/src/fix/catalog.rs b/crates/rocm-core/src/fix/catalog.rs index 9d392f907b..bbe8f0142e 100644 --- a/crates/rocm-core/src/fix/catalog.rs +++ b/crates/rocm-core/src/fix/catalog.rs @@ -153,6 +153,15 @@ impl FixRecipe { } } +/// The ids of the recipes whose runners name themselves in a recovery line +/// ("re-run `rocm fix `"). One constant serves the catalog entry and the +/// runner's message, so the command a stopped fix tells the user to re-run is +/// always a recipe that exists. +pub(super) const UNSET_OVERRIDE_ID: &str = "fix-2-unset-override"; +pub(super) const RENDER_GROUP_ID: &str = "fix-4-render-group"; +pub(super) const PATH_ID: &str = "fix-6-path"; +pub(super) const IGPU_DGPU_ID: &str = "fix-9-igpu-dgpu"; + /// The recipe registry. Mirrors the diagnosis catalog; only the small, safe /// fixes carry a `runner`, and what each one does can differ by platform. pub(super) const RECIPES: &[FixRecipe] = &[ @@ -187,7 +196,7 @@ pub(super) const RECIPES: &[FixRecipe] = &[ runner: None, }, FixRecipe { - fix_id: "fix-2-unset-override", + fix_id: UNSET_OVERRIDE_ID, title: "Unset HSA_OVERRIDE_GFX_VERSION", rationale: "HSA_OVERRIDE_GFX_VERSION is set, but your GPU now has a native wheel. The override hides the real gfx and causes page faults / OUT_OF_REGISTERS at runtime.", commands: &[ @@ -241,7 +250,7 @@ pub(super) const RECIPES: &[FixRecipe] = &[ runner: None, }, FixRecipe { - fix_id: "fix-4-render-group", + fix_id: RENDER_GROUP_ID, title: "Add user to render/video groups", rationale: "The current user can't open /dev/kfd because they aren't in the render group. Adding the user is the safe, standard fix.", commands: &["sudo usermod -a -G render,video \"$USER\""], @@ -279,7 +288,7 @@ pub(super) const RECIPES: &[FixRecipe] = &[ runner: None, }, FixRecipe { - fix_id: "fix-6-path", + fix_id: PATH_ID, title: "Add the ROCm/HIP bin directory to PATH", rationale: "Linux: ROCm is installed but its bin directory isn't on PATH, so `rocminfo` / `hipcc` aren't visible to the shell. Windows: the HIP SDK is installed but its bin directory isn't on the User PATH, so `hipInfo.exe` and the runtime DLLs can't be found.", commands: &[ @@ -366,7 +375,7 @@ pub(super) const RECIPES: &[FixRecipe] = &[ runner: None, }, FixRecipe { - fix_id: "fix-9-igpu-dgpu", + fix_id: IGPU_DGPU_ID, title: "Hide the iGPU with HIP_VISIBLE_DEVICES", rationale: "Both an APU iGPU and a discrete AMD GPU are visible. Pin the runtime to the dGPU so the iGPU doesn't destabilise it.", commands: &[ diff --git a/crates/rocm-core/src/fix/consent.rs b/crates/rocm-core/src/fix/consent.rs index 95b9d8931f..1282041ab3 100644 --- a/crates/rocm-core/src/fix/consent.rs +++ b/crates/rocm-core/src/fix/consent.rs @@ -9,9 +9,17 @@ //! selected by (`current_os`), and the stderr/stdout helpers (`fail!`, //! `relay_output`) that cannot themselves panic when a pipe is closed. Used //! by `fix.rs` and its runners. +//! +//! Also the one way a runner runs a host command ([`run_step`]) and reports +//! how it ended ([`Step`], [`StepFailure`]): the line printed and the exit +//! code returned come from the same value, so a timeout cannot be reported as +//! an exit code, nor an unfinished change as "NOT changed". +use super::options::exit; +use crate::command_capture::{CommandCapture, CommandOutcome}; use crate::{runtime_is_linux, runtime_is_windows}; use std::io::{IsTerminal, Write}; +use std::process::Command; use std::time::Duration; pub(super) const RUN_TIMEOUT: Duration = Duration::from_mins(1); @@ -35,6 +43,143 @@ pub(super) fn relay_output(out: &str, err: &str) { let _ = write!(std::io::stderr(), "{err}"); } +/// Run one host command of a fix under `timeout` and say how it ended. +/// +/// The runners take this as an injected +/// `FnMut(&str, &[&str], Duration) -> CommandCapture`, so their tests drive +/// every [`CommandOutcome`] without a real `setx`, `PowerShell` or `sudo`. It +/// calls the bounded executor directly rather than the `probe_exec::run` +/// adapter, which folds a timeout and a failed wait into exit code `124` and +/// a program that cannot start into `127` -- which is how a timed-out +/// `usermod` used to be reported as "usermod exited 124". +/// +/// The executor stops the direct child only (see `process/bounded.rs`), so a +/// command run under `sudo` may still finish after a timeout; [`Step::failure`] +/// says so rather than claiming nothing changed. +pub(super) fn run_step(program: &str, args: &[&str], timeout: Duration) -> CommandCapture { + let mut command = Command::new(program); + command.args(args); + crate::process::run_bounded(command, timeout, program) +} + +/// How a command ended, as the first half of a sentence: "`label` timed out +/// after 60s and was stopped". `timeout` is the bound the command ran under. +fn outcome_phrase(label: &str, outcome: CommandOutcome, timeout: Duration) -> String { + match outcome { + CommandOutcome::Exited(code) => format!("{label} exited {code}"), + CommandOutcome::NotFound => format!("{label} could not be started: it was not found"), + CommandOutcome::SpawnFailed(kind) => format!("{label} could not be started: {kind}"), + CommandOutcome::TimedOut => format!( + "{label} timed out after {}s and was stopped", + timeout.as_secs() + ), + CommandOutcome::WaitFailed => { + format!("{label} could not be waited for and was stopped") + } + CommandOutcome::Signaled(Some(signal)) => { + format!("{label} was killed by signal {signal} before it finished") + } + CommandOutcome::Signaled(None) => format!("{label} was killed before it finished"), + } +} + +/// Whether a command that ended this way may have made its change anyway. +/// +/// A command that ran to its own exit with a failure code, or never started, +/// did not. One that was stopped from outside -- the deadline, a failed wait, +/// a signal -- may have been part-way through, or (under `sudo`) may still be +/// running, so the honest answer is "may or may not". +const fn may_have_acted(outcome: CommandOutcome) -> bool { + matches!( + outcome, + CommandOutcome::TimedOut | CommandOutcome::WaitFailed | CommandOutcome::Signaled(_) + ) +} + +/// One host command a fix runs to make its change, and how to recover when +/// the command is stopped before it reports. +pub(super) struct Step<'a> { + /// The program run. + pub(super) program: &'a str, + /// Its arguments. + pub(super) args: &'a [&'a str], + /// The command as messages name it (`setx`, `PowerShell`, `sudo usermod`). + pub(super) label: &'a str, + /// What the command changes, as the subject of "... NOT changed." + pub(super) what: &'a str, + /// A command the user can run to see whether the change was made. + pub(super) check: &'a str, + /// The `rocm fix` invocation that makes the change if it was not made. + pub(super) rerun: &'a str, + /// The bound the command runs under; also the number the timeout line names. + pub(super) timeout: Duration, +} + +/// A failed step: the line to print on stderr and the exit code to return, +/// decided together so the two cannot disagree. +#[derive(Debug, PartialEq, Eq)] +pub(super) struct StepFailure { + pub(super) code: i32, + pub(super) line: String, +} + +impl Step<'_> { + /// `None` when the command exited `0`; otherwise what to print and return. + pub(super) fn failure(&self, outcome: CommandOutcome) -> Option { + if outcome == CommandOutcome::Exited(0) { + return None; + } + let phrase = outcome_phrase(self.label, outcome, self.timeout); + let line = if may_have_acted(outcome) { + format!( + "{phrase}; {} may or may not have changed. Check with `{}`, then re-run `{}` if it did not.", + self.what, self.check, self.rerun + ) + } else { + format!("{phrase}; {} NOT changed.", self.what) + }; + Some(StepFailure { + code: exit::FAILED, + line, + }) + } + + /// Run the command through `run`, relay what it printed, and on failure + /// write the [`StepFailure`] line to `err` and return its code. + pub(super) fn run( + &self, + run: &mut impl FnMut(&str, &[&str], Duration) -> CommandCapture, + err: &mut impl Write, + ) -> Result<(), i32> { + let capture = run(self.program, self.args, self.timeout); + relay_output(&capture.stdout, &capture.stderr); + match self.failure(capture.outcome) { + None => Ok(()), + Some(failure) => { + let _ = writeln!(err, "{}", failure.line); + Err(failure.code) + } + } + } +} + +/// A read that a fix depends on did not complete: nothing has been changed +/// yet, and the fix stops rather than guess what the value was. +pub(super) fn read_failure( + subject: &str, + label: &str, + outcome: CommandOutcome, + timeout: Duration, +) -> StepFailure { + StepFailure { + code: exit::FAILED, + line: format!( + "Could not read {subject}: {}; nothing was changed.", + outcome_phrase(label, outcome, timeout) + ), + } +} + /// The platform family a recipe is selected by. /// /// WSL is its own family, which is why recipes valid on both have to name `wsl` @@ -118,6 +263,118 @@ mod tests { ); } + const STEP: Step<'static> = Step { + program: "setx", + args: &[], + label: "setx", + what: "User-scope X", + check: "check-x", + rerun: "rocm fix fix-x", + timeout: RUN_TIMEOUT, + }; + + /// What [`Step::failure`] reports for `outcome`, written out per variant. + /// The `match` is exhaustive on purpose: a new [`CommandOutcome`] does not + /// compile here until someone decides what a stopped fix says about it. + fn expected(outcome: CommandOutcome) -> Option { + let maybe = "User-scope X may or may not have changed. Check with `check-x`, then \ + re-run `rocm fix fix-x` if it did not."; + let not_changed = "User-scope X NOT changed."; + Some(match outcome { + CommandOutcome::Exited(0) => return None, + CommandOutcome::Exited(_) => format!("setx exited 1; {not_changed}"), + CommandOutcome::NotFound => { + format!("setx could not be started: it was not found; {not_changed}") + } + CommandOutcome::SpawnFailed(_) => { + format!("setx could not be started: permission denied; {not_changed}") + } + CommandOutcome::TimedOut => { + format!("setx timed out after 60s and was stopped; {maybe}") + } + CommandOutcome::WaitFailed => { + format!("setx could not be waited for and was stopped; {maybe}") + } + CommandOutcome::Signaled(Some(_)) => { + format!("setx was killed by signal 9 before it finished; {maybe}") + } + CommandOutcome::Signaled(None) => { + format!("setx was killed before it finished; {maybe}") + } + }) + } + + /// The line and the code come from one value: every outcome but a clean + /// exit is exit 4, a timeout says "timed out" with the bound it ran under, + /// and only a command that ran to its own end (or never started) is + /// reported as having changed nothing. + #[test] + fn step_failure_reports_each_outcome_with_its_own_wording() { + for outcome in [ + CommandOutcome::Exited(0), + CommandOutcome::Exited(1), + CommandOutcome::NotFound, + CommandOutcome::SpawnFailed(std::io::ErrorKind::PermissionDenied), + CommandOutcome::TimedOut, + CommandOutcome::WaitFailed, + CommandOutcome::Signaled(Some(9)), + CommandOutcome::Signaled(None), + ] { + let got = STEP.failure(outcome); + match expected(outcome) { + None => assert_eq!(got, None, "{outcome:?} is success"), + Some(line) => assert_eq!( + got, + Some(StepFailure { + code: exit::FAILED, + line + }), + "{outcome:?}" + ), + } + } + } + + /// The runner the production paths use reports a program that is not + /// there as `NotFound`, not as the legacy adapter's `127`, so the line a + /// runner prints for it is "could not be started". + #[test] + fn run_step_reports_a_missing_program_as_not_found() { + let capture = run_step("rocm-fix-no-such-program-345", &[], QUERY_TIMEOUT); + assert_eq!(capture.outcome, CommandOutcome::NotFound); + } + + #[test] + fn a_timeout_names_the_bound_the_step_ran_under() { + let step = Step { + timeout: QUERY_TIMEOUT, + ..STEP + }; + let line = step + .failure(CommandOutcome::TimedOut) + .expect("a failure") + .line; + assert!(line.starts_with("setx timed out after 8s "), "{line}"); + } + + #[test] + fn a_failed_read_says_nothing_was_changed() { + assert_eq!( + read_failure( + "the current User PATH", + "PowerShell", + CommandOutcome::Exited(1), + QUERY_TIMEOUT + ), + StepFailure { + code: exit::FAILED, + line: "Could not read the current User PATH: PowerShell exited 1; nothing was \ + changed." + .to_owned() + } + ); + } + #[test] fn yes_flag_approves_without_prompting() { assert_eq!(consent_without_prompt(true, false), Some(true)); diff --git a/crates/rocm-core/src/fix/runners.rs b/crates/rocm-core/src/fix/runners.rs index 896091cc01..93b8ceb8c4 100644 --- a/crates/rocm-core/src/fix/runners.rs +++ b/crates/rocm-core/src/fix/runners.rs @@ -11,8 +11,10 @@ //! the catalog in `fix/catalog.rs` names the entry point of each recipe's //! runner and the running OS decides which variant runs. -use super::consent::{QUERY_TIMEOUT, RUN_TIMEOUT, confirm, fail, relay_output}; +use super::catalog::{IGPU_DGPU_ID, PATH_ID, RENDER_GROUP_ID, UNSET_OVERRIDE_ID}; +use super::consent::{QUERY_TIMEOUT, RUN_TIMEOUT, Step, confirm, fail, read_failure, run_step}; use super::options::{FixOptions, exit}; +use crate::command_capture::{CommandCapture, CommandOutcome}; use crate::probe_exec::{run, which}; use crate::quoting::ps_single_quote_escape; #[cfg(test)] @@ -22,6 +24,7 @@ use crate::rocm_install::{ use crate::runtime_is_windows; use std::io::Write; use std::path::{Path, PathBuf}; +use std::time::Duration; // --------------------------------------------------------------------------- // Environment helpers @@ -82,26 +85,31 @@ pub(super) fn run_render_group(opts: &FixOptions) -> i32 { fail!("`sudo` is not on PATH and we are not root; cannot add groups."); return exit::NOT_APPLICABLE; } - let (program, args): (&str, Vec) = if root { - ( - "usermod", - vec![ - "-a".into(), - "-G".into(), - "render,video".into(), - user.clone(), - ], - ) + render_group_with(opts, &user, root, run_step, &mut std::io::stderr()) +} + +/// Does the plan/consent/run work for [`run_render_group`] once the user and +/// the privilege route are known, with the command runner and the stderr sink +/// injected so every way `usermod` can end is testable on any host. +/// +/// A `usermod` stopped by the timeout is reported as such, not as an exit +/// code: the executor stops only `sudo`, so `usermod` may still finish, and +/// the line says how to find out (`id -nG`) and what to re-run. +fn render_group_with( + opts: &FixOptions, + user: &str, + root: bool, + mut run: impl FnMut(&str, &[&str], Duration) -> CommandCapture, + err: &mut impl Write, +) -> i32 { + let usermod_args = ["-a", "-G", "render,video", user]; + let (program, label, args): (&str, &str, Vec<&str>) = if root { + ("usermod", "usermod", usermod_args.to_vec()) } else { ( "sudo", - vec![ - "usermod".into(), - "-a".into(), - "-G".into(), - "render,video".into(), - user.clone(), - ], + "sudo usermod", + std::iter::once("usermod").chain(usermod_args).collect(), ) }; println!("Will run: {program} {}", args.join(" ")); @@ -112,12 +120,19 @@ pub(super) fn run_render_group(opts: &FixOptions) -> i32 { if !confirm("Add user to render,video groups?", opts.yes) { return exit::DECLINED; } - let arg_refs: Vec<&str> = args.iter().map(String::as_str).collect(); - let (rc, out, err) = run(program, &arg_refs, RUN_TIMEOUT); - relay_output(&out, &err); - if rc != 0 { - fail!("usermod exited {rc}; group membership NOT changed."); - return exit::FAILED; + let check = format!("id -nG {user}"); + let rerun = format!("rocm fix {RENDER_GROUP_ID}"); + let step = Step { + program, + args: &args, + label, + what: "group membership", + check: &check, + rerun: &rerun, + timeout: RUN_TIMEOUT, + }; + if let Err(code) = step.run(&mut run, err) { + return code; } println!("Added {user} to render,video."); println!( @@ -201,23 +216,51 @@ fn run_unset_override_windows(opts: &FixOptions) -> i32 { println!("Note: clearing it in your Windows env scope does NOT affect this"); println!("already-open shell -- close and reopen your terminal afterwards."); } - // A failed read here only affects this report-and-clear path, which never - // overwrites the whole variable (it only clears it via a dedicated - // `setx VAR ""`), so collapsing a failed read to "unset" preserves this - // function's existing behavior; it is `path_export_windows`'s - // read-then-overwrite-the-whole-value shape that made that collapse unsafe. - let user_val = ps_env_scope("HSA_OVERRIDE_GFX_VERSION", "User").unwrap_or_default(); - let machine_val = ps_env_scope("HSA_OVERRIDE_GFX_VERSION", "Machine").unwrap_or_default(); - report_and_clear_override_windows(opts, &user_val, &machine_val, |prompt| { - confirm(prompt, opts.yes) - }) + unset_override_windows_with( + opts, + run_step, + |prompt| confirm(prompt, opts.yes), + &mut std::io::stderr(), + ) +} + +/// Reads both env scopes through `run`, then hands over to +/// [`report_and_clear_override_windows`]. +/// +/// A read that does not complete stops the fix before anything is printed as +/// found or offered for clearing: read as "unset", it would report "No +/// persistent HSA_OVERRIDE_GFX_VERSION found ... You're done" on a machine +/// that still carries the override, which is the one thing this fix is for. +fn unset_override_windows_with( + opts: &FixOptions, + mut run: impl FnMut(&str, &[&str], Duration) -> CommandCapture, + consent: impl FnOnce(&str) -> bool, + err: &mut impl Write, +) -> i32 { + let mut values = [String::new(), String::new()]; + for (value, scope) in values.iter_mut().zip(["User", "Machine"]) { + match ps_env_scope(&mut run, OVERRIDE_VAR, scope) { + Ok(read) => *value = read, + Err(failure) => { + let _ = writeln!(err, "{}", failure.line); + return failure.code; + } + } + } + let [user_val, machine_val] = values; + report_and_clear_override_windows(opts, &user_val, &machine_val, consent, run, err) } +/// The variable fix-2 clears. +const OVERRIDE_VAR: &str = "HSA_OVERRIDE_GFX_VERSION"; + /// Does the reporting/clearing work for [`run_unset_override_windows`], with -/// the User/Machine scope values and the consent prompt taken as parameters -/// rather than read from `ps_env_scope`/`confirm` directly. That's what makes -/// the decline path testable without a real Windows host -- same reason -/// [`pin_device_in_rc_file`] takes its consent as a closure. +/// the User/Machine scope values, the consent prompt, the command runner and +/// the stderr sink taken as parameters rather than read from +/// `ps_env_scope`/`confirm`/`run_step` directly. That's what makes the +/// decline and the `setx` failure paths testable without a real Windows +/// host -- same reason [`pin_device_in_rc_file`] takes its consent as a +/// closure. /// /// A decline must still exit `5`: `skills/rocm-doctor/reference.md` documents /// `5` as "user declined", and a caller (human or agent) relies on that to @@ -232,6 +275,8 @@ fn report_and_clear_override_windows( user_val: &str, machine_val: &str, consent: impl FnOnce(&str) -> bool, + mut run: impl FnMut(&str, &[&str], Duration) -> CommandCapture, + err: &mut impl Write, ) -> i32 { if user_val.is_empty() && machine_val.is_empty() { println!("\nNo persistent HSA_OVERRIDE_GFX_VERSION found in either the User"); @@ -253,7 +298,7 @@ fn report_and_clear_override_windows( // 5.1 drops an empty argument, so pasting the line would not clear // anything; the plan above carries the line to paste. The text is built // from the argument list that is run, so the two cannot differ. - let setx_args = ["HSA_OVERRIDE_GFX_VERSION", ""]; + let setx_args = [OVERRIDE_VAR, ""]; let shown: Vec = setx_args.iter().map(|a| format!("\"{a}\"")).collect(); println!( " The CLI runs (arguments, not a line to paste): setx {}", @@ -262,11 +307,19 @@ fn report_and_clear_override_windows( if opts.dry_run { println!(" (dry-run; not executed)"); } else if consent("Clear HSA_OVERRIDE_GFX_VERSION from User scope?") { - let (rc, out, err) = run("setx", &setx_args, RUN_TIMEOUT); - relay_output(&out, &err); - if rc != 0 { - fail!("setx exited {rc}; User scope NOT changed."); - return exit::FAILED; + let check = env_scope_query(OVERRIDE_VAR, "User"); + let rerun = format!("rocm fix {UNSET_OVERRIDE_ID}"); + let step = Step { + program: "setx", + args: &setx_args, + label: "setx", + what: "User-scope HSA_OVERRIDE_GFX_VERSION", + check: &check, + rerun: &rerun, + timeout: RUN_TIMEOUT, + }; + if let Err(code) = step.run(&mut run, err) { + return code; } println!("Cleared from User scope. Reopen your terminal for it to take effect."); } else { @@ -372,7 +425,7 @@ fn run_path_export_windows(opts: &FixOptions) -> i32 { return exit::NOT_APPLICABLE; } let bin_dir = bin_dir.to_string_lossy().into_owned(); - path_export_windows(opts, &bin_dir, || ps_env_scope("PATH", "User")) + path_export_windows(opts, &bin_dir, run_step, &mut std::io::stderr()) } /// The literal value that will replace User-scope PATH on a non-empty @@ -396,12 +449,12 @@ fn windows_path_prepend(bin_dir: &str, user_path: &str) -> String { } /// Does the read/plan/write work for [`run_path_export_windows`], with the -/// User-scope PATH read taken as an injected closure rather than calling -/// `ps_env_scope` directly. That's what makes the "read failed" branch -/// testable on any host -- same reason [`report_and_clear_override_windows`] -/// takes consent as a closure. +/// command runner (both the User-scope PATH read and the write) and the stderr +/// sink injected. That's what makes the "read failed" and "write stopped" +/// branches testable on any host -- same reason +/// [`report_and_clear_override_windows`] takes consent as a closure. /// -/// A failed read (`None`) must never be treated as "PATH is empty": the +/// A failed read must never be treated as "PATH is empty": the /// write below replaces the *entire* User PATH value, so collapsing a /// PowerShell failure into "nothing there" would wipe the user's real PATH /// down to just `bin_dir`. So a failed read aborts here, before the @@ -411,11 +464,15 @@ fn windows_path_prepend(bin_dir: &str, user_path: &str) -> String { fn path_export_windows( opts: &FixOptions, bin_dir: &str, - read_user_path: impl FnOnce() -> Option, + mut run: impl FnMut(&str, &[&str], Duration) -> CommandCapture, + err: &mut impl Write, ) -> i32 { - let Some(user_path) = read_user_path() else { - fail!("Could not read the current User PATH; User PATH NOT changed."); - return exit::FAILED; + let user_path = match ps_env_scope(&mut run, "PATH", "User") { + Ok(user_path) => user_path, + Err(failure) => { + let _ = writeln!(err, "{}", failure.line); + return failure.code; + } }; if !user_path.is_empty() && user_path.to_lowercase().contains(&bin_dir.to_lowercase()) { println!("User PATH already contains {bin_dir}; no change."); @@ -442,15 +499,19 @@ fn path_export_windows( // normal-length PATH can hit even when the read above succeeded. let script = format!("[Environment]::SetEnvironmentVariable('PATH', '{escaped_new_path}', 'User')"); - let (rc, out, err) = run( - "powershell", - &["-NoProfile", "-Command", &script], - RUN_TIMEOUT, - ); - relay_output(&out, &err); - if rc != 0 { - fail!("PowerShell exited {rc}; User PATH NOT changed."); - return exit::FAILED; + let check = env_scope_query("PATH", "User"); + let rerun = format!("rocm fix {PATH_ID}"); + let step = Step { + program: POWERSHELL, + args: &["-NoProfile", "-Command", &script], + label: "PowerShell", + what: "User PATH", + check: &check, + rerun: &rerun, + timeout: RUN_TIMEOUT, + }; + if let Err(code) = step.run(&mut run, err) { + return code; } println!( "Added {bin_dir} to your User PATH. This only takes effect in NEW shells -- close this terminal and reopen it before re-running hipInfo." @@ -552,11 +613,28 @@ fn run_hip_visible_devices_windows(opts: &FixOptions) -> i32 { ); return exit::OK; }; - // Out of scope for ROCMAI-449 (that fix is specific to fix-6-path's - // read-then-overwrite-the-whole-PATH-value shape): a failed read here - // only risks re-running `setx HIP_VISIBLE_DEVICES `, which sets a - // single unrelated variable rather than overwriting PATH. - let existing = ps_env_scope("HIP_VISIBLE_DEVICES", "User").unwrap_or_default(); + hip_visible_devices_windows(opts, idx, run_step, &mut std::io::stderr()) +} + +/// Does the read/plan/write work for [`run_hip_visible_devices_windows`] once +/// a device index is known, with the command runner and the stderr sink +/// injected, as [`path_export_windows`] does. +/// +/// A read that does not complete stops the fix: read as "unset", it would skip +/// the guard below and overwrite a User-scope value the user set on purpose. +fn hip_visible_devices_windows( + opts: &FixOptions, + idx: i64, + mut run: impl FnMut(&str, &[&str], Duration) -> CommandCapture, + err: &mut impl Write, +) -> i32 { + let existing = match ps_env_scope(&mut run, "HIP_VISIBLE_DEVICES", "User") { + Ok(existing) => existing, + Err(failure) => { + let _ = writeln!(err, "{}", failure.line); + return failure.code; + } + }; if !existing.is_empty() { println!( "User scope already sets HIP_VISIBLE_DEVICES={existing:?}; remove or update it manually rather than overwriting from this command." @@ -572,15 +650,20 @@ fn run_hip_visible_devices_windows(opts: &FixOptions) -> i32 { if !confirm("Set HIP_VISIBLE_DEVICES in the User scope?", opts.yes) { return exit::DECLINED; } - let (rc, out, err) = run( - "setx", - &["HIP_VISIBLE_DEVICES", &idx.to_string()], - RUN_TIMEOUT, - ); - relay_output(&out, &err); - if rc != 0 { - fail!("setx exited {rc}; HIP_VISIBLE_DEVICES NOT changed."); - return exit::FAILED; + let idx_arg = idx.to_string(); + let check = env_scope_query("HIP_VISIBLE_DEVICES", "User"); + let rerun = format!("rocm fix {IGPU_DGPU_ID} --device-index {idx}"); + let step = Step { + program: "setx", + args: &["HIP_VISIBLE_DEVICES", &idx_arg], + label: "setx", + what: "User-scope HIP_VISIBLE_DEVICES", + check: &check, + rerun: &rerun, + timeout: RUN_TIMEOUT, + }; + if let Err(code) = step.run(&mut run, err) { + return code; } println!( "setx only takes effect in NEW shells -- close this terminal and reopen it before re-running your workload." @@ -588,25 +671,46 @@ fn run_hip_visible_devices_windows(opts: &FixOptions) -> i32 { exit::OK } -/// Read a Windows environment variable from a given scope via PowerShell. +/// The program the Windows runners read and write env scopes with. +const POWERSHELL: &str = "powershell"; + +/// The PowerShell expression that reads `var` from `scope`. Both the read and +/// the "Check with" line of a stopped write use it, so the check a user is +/// told to run is the read this fix itself trusts. +fn env_scope_query(var: &str, scope: &str) -> String { + format!("[Environment]::GetEnvironmentVariable('{var}','{scope}')") +} + +/// Read a Windows environment variable from a given scope via PowerShell, +/// run through `run`. /// -/// Returns `None` if the read itself failed -- PowerShell missing, blocked by -/// execution policy, or the query timing out -- which must stay distinguishable -/// from `Some(String::new())`, meaning the read succeeded and the variable is +/// `Err` if the read itself did not complete -- PowerShell missing, blocked by +/// execution policy, exiting non-zero, or timing out -- carrying the line and +/// exit code to stop the fix with. That must stay distinguishable from +/// `Ok(String::new())`, meaning the read succeeded and the variable is /// genuinely unset/empty in that scope. Collapsing both to `""` is what let a /// failed PATH read look like an empty PATH to a caller that then wrote the -/// "empty" value back out, wiping the real one (ROCMAI-449). -fn ps_env_scope(var: &str, scope: &str) -> Option { - let script = format!("[Environment]::GetEnvironmentVariable('{var}','{scope}')"); - let (rc, out, _) = run( - "powershell", +/// "empty" value back out, wiping the real one (ROCMAI-449), and let fix-2 +/// and fix-9 act on a value they never read. +fn ps_env_scope( + run: &mut impl FnMut(&str, &[&str], Duration) -> CommandCapture, + var: &str, + scope: &str, +) -> Result { + let script = env_scope_query(var, scope); + let capture = run( + POWERSHELL, &["-NoProfile", "-Command", &script], QUERY_TIMEOUT, ); - if rc == 0 { - Some(out.trim().to_owned()) - } else { - None + match capture.outcome { + CommandOutcome::Exited(0) => Ok(capture.stdout.trim().to_owned()), + outcome => Err(read_failure( + &format!("the current {scope} {var}"), + "PowerShell", + outcome, + QUERY_TIMEOUT, + )), } } @@ -890,6 +994,496 @@ mod tests { std::fs::remove_dir_all(&dir).ok(); } + // ── Host commands: every way a step's command can end ────────── + // + // ROCMAI-345: the runners used to read the `probe_exec::run` adapter's + // collapsed integer, so a timed-out `usermod`/`setx`/PowerShell was + // reported as "exited 124; ... NOT changed." -- which named no timeout, + // gave no way to recover, and claimed a state nobody had checked (the + // executor stops only the direct child, so `usermod` under `sudo` can + // still finish). And the Windows reads folded a failed read into "unset", + // so fix-2 reported "You're done" and fix-9 skipped its guard and wrote. + // These drive each runner through `FakeHost` and assert the exit code, the + // commands that ran and the stderr line in the same test. + + /// A stand-in for the host commands a runner runs. A PowerShell read + /// (`GetEnvironmentVariable`) answers `read` (or `machine_read` for the + /// Machine scope, when set); every other command ends with `write`. Each + /// call is recorded as its argv and the timeout it was run under. + struct FakeHost<'a> { + read: (CommandOutcome, &'a str), + machine_read: Option<(CommandOutcome, &'a str)>, + write: CommandOutcome, + calls: std::cell::RefCell, Duration)>>, + } + + impl<'a> FakeHost<'a> { + fn new(read: (CommandOutcome, &'a str), write: CommandOutcome) -> Self { + Self { + read, + machine_read: None, + write, + calls: std::cell::RefCell::new(Vec::new()), + } + } + + fn with_machine_read(mut self, machine_read: (CommandOutcome, &'a str)) -> Self { + self.machine_read = Some(machine_read); + self + } + + fn runner(&self) -> impl FnMut(&str, &[&str], Duration) -> CommandCapture + '_ { + move |program, args, timeout| { + let argv: Vec = std::iter::once(program) + .chain(args.iter().copied()) + .map(str::to_owned) + .collect(); + self.calls.borrow_mut().push((argv.clone(), timeout)); + let (outcome, stdout) = if !is_read(&argv) { + (self.write, "") + } else if argv.iter().any(|a| a.contains("'Machine'")) { + self.machine_read.unwrap_or(self.read) + } else { + self.read + }; + CommandCapture::from_run( + argv, + outcome, + None, + stdout.as_bytes().to_vec(), + Vec::new(), + None, + ) + } + } + + fn calls(&self) -> Vec> { + self.calls.borrow().iter().map(|(a, _)| a.clone()).collect() + } + + /// The commands that were not reads, with the timeout each ran under. + fn writes_with_timeouts(&self) -> Vec<(Vec, Duration)> { + self.calls + .borrow() + .iter() + .filter(|(a, _)| !is_read(a)) + .cloned() + .collect() + } + + fn writes(&self) -> Vec> { + self.writes_with_timeouts() + .into_iter() + .map(|(a, _)| a) + .collect() + } + } + + fn is_read(argv: &[String]) -> bool { + argv.iter().any(|a| a.contains("GetEnvironmentVariable")) + } + + const fn exited(code: i32) -> CommandOutcome { + CommandOutcome::Exited(code) + } + + /// A read that succeeded and found the variable unset. + const fn unset() -> (CommandOutcome, &'static str) { + (CommandOutcome::Exited(0), "") + } + + fn approved() -> FixOptions { + FixOptions { + yes: true, + ..FixOptions::default() + } + } + + fn text(err: &[u8]) -> String { + String::from_utf8(err.to_vec()).expect("stderr is UTF-8") + } + + // fix-4 ------------------------------------------------------------ + + const SUDO_USERMOD: [&str; 6] = ["sudo", "usermod", "-a", "-G", "render,video", "alice"]; + + fn render_group(write: CommandOutcome) -> (i32, Vec>, Duration, String) { + let host = FakeHost::new(unset(), write); + let mut err = Vec::new(); + let code = render_group_with(&approved(), "alice", false, host.runner(), &mut err); + let timeout = host + .writes_with_timeouts() + .first() + .map_or(Duration::ZERO, |(_, t)| *t); + (code, host.calls(), timeout, text(&err)) + } + + #[test] + fn render_group_success_runs_usermod_under_sudo_and_returns_0() { + let (code, calls, _, err) = render_group(exited(0)); + assert_eq!(code, exit::OK); + assert_eq!(calls, [SUDO_USERMOD.to_vec()]); + assert_eq!(err, "", "a success prints no failure line"); + } + + #[test] + fn render_group_as_root_runs_usermod_directly() { + let host = FakeHost::new(unset(), exited(0)); + let code = render_group_with(&approved(), "alice", true, host.runner(), &mut Vec::new()); + assert_eq!(code, exit::OK); + assert_eq!(host.calls(), [SUDO_USERMOD[1..].to_vec()]); + } + + #[test] + fn render_group_child_failure_says_nothing_changed_and_returns_4() { + let (code, calls, _, err) = render_group(exited(1)); + assert_eq!(code, exit::FAILED); + assert_eq!(calls, [SUDO_USERMOD.to_vec()]); + assert_eq!( + err, + "sudo usermod exited 1; group membership NOT changed.\n" + ); + } + + #[test] + fn render_group_timeout_says_timed_out_and_how_to_check_not_that_nothing_changed() { + let (code, calls, timeout, err) = render_group(CommandOutcome::TimedOut); + assert_eq!(code, exit::FAILED, "a timeout is still a failed attempt"); + assert_eq!(calls, [SUDO_USERMOD.to_vec()]); + assert_eq!( + timeout, RUN_TIMEOUT, + "the line names the bound it ran under" + ); + assert_eq!( + err, + "sudo usermod timed out after 60s and was stopped; group membership may or may not \ + have changed. Check with `id -nG alice`, then re-run `rocm fix fix-4-render-group` \ + if it did not.\n" + ); + } + + #[test] + fn render_group_missing_program_says_it_could_not_start() { + let (code, _, _, err) = render_group(CommandOutcome::NotFound); + assert_eq!(code, exit::FAILED); + assert_eq!( + err, + "sudo usermod could not be started: it was not found; group membership NOT changed.\n" + ); + } + + #[test] + fn render_group_dry_run_runs_nothing() { + let host = FakeHost::new(unset(), exited(0)); + let opts = FixOptions { + dry_run: true, + ..approved() + }; + let code = render_group_with(&opts, "alice", false, host.runner(), &mut Vec::new()); + assert_eq!(code, exit::OK); + assert!(host.calls().is_empty()); + } + + // fix-2 (Windows) -------------------------------------------------- + + fn unset_override(host: &FakeHost<'_>) -> (i32, String) { + let mut err = Vec::new(); + let code = unset_override_windows_with(&approved(), host.runner(), |_| true, &mut err); + (code, text(&err)) + } + + #[test] + fn unset_override_clears_a_user_scope_value_and_returns_0() { + let host = FakeHost::new((exited(0), "10.3.0\r\n"), exited(0)).with_machine_read(unset()); + let (code, err) = unset_override(&host); + assert_eq!(code, exit::OK); + assert_eq!(host.writes(), [vec!["setx", OVERRIDE_VAR, ""]]); + assert_eq!(err, ""); + } + + #[test] + fn unset_override_setx_failure_returns_4() { + let host = FakeHost::new((exited(0), "10.3.0"), exited(1)).with_machine_read(unset()); + let (code, err) = unset_override(&host); + assert_eq!(code, exit::FAILED); + assert_eq!(host.writes(), [vec!["setx", OVERRIDE_VAR, ""]]); + assert_eq!( + err, + "setx exited 1; User-scope HSA_OVERRIDE_GFX_VERSION NOT changed.\n" + ); + } + + #[test] + fn unset_override_setx_timeout_says_timed_out_and_how_to_check() { + let host = FakeHost::new((exited(0), "10.3.0"), CommandOutcome::TimedOut) + .with_machine_read(unset()); + let (code, err) = unset_override(&host); + assert_eq!(code, exit::FAILED); + assert_eq!(host.writes_with_timeouts()[0].1, RUN_TIMEOUT); + assert_eq!( + err, + "setx timed out after 60s and was stopped; User-scope HSA_OVERRIDE_GFX_VERSION may or \ + may not have changed. Check with \ + `[Environment]::GetEnvironmentVariable('HSA_OVERRIDE_GFX_VERSION','User')`, then \ + re-run `rocm fix fix-2-unset-override` if it did not.\n" + ); + } + + #[test] + fn unset_override_setx_missing_says_it_could_not_start() { + let host = FakeHost::new((exited(0), "10.3.0"), CommandOutcome::NotFound) + .with_machine_read(unset()); + let (code, err) = unset_override(&host); + assert_eq!(code, exit::FAILED); + assert_eq!( + err, + "setx could not be started: it was not found; User-scope HSA_OVERRIDE_GFX_VERSION NOT \ + changed.\n" + ); + } + + /// The reported bug's read half: a User-scope read that timed out used to + /// read as "unset", and with the Machine scope unset too the fix printed + /// "No persistent HSA_OVERRIDE_GFX_VERSION found ... You're done" and + /// exited 0 on a machine that still carried the override. + #[test] + fn unset_override_user_read_timeout_stops_before_anything_is_reported_or_cleared() { + let host = + FakeHost::new((CommandOutcome::TimedOut, ""), exited(0)).with_machine_read(unset()); + let mut err = Vec::new(); + let code = unset_override_windows_with( + &approved(), + host.runner(), + |_| panic!("a failed read must not reach the consent gate"), + &mut err, + ); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty(), "nothing may be written"); + assert_eq!( + host.calls().len(), + 1, + "the Machine scope is not read either" + ); + assert_eq!( + text(&err), + "Could not read the current User HSA_OVERRIDE_GFX_VERSION: PowerShell timed out after \ + 8s and was stopped; nothing was changed.\n" + ); + } + + #[test] + fn unset_override_missing_powershell_stops_before_anything_is_cleared() { + let host = FakeHost::new((CommandOutcome::NotFound, ""), exited(0)); + let (code, err) = unset_override(&host); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty()); + assert_eq!( + err, + "Could not read the current User HSA_OVERRIDE_GFX_VERSION: PowerShell could not be \ + started: it was not found; nothing was changed.\n" + ); + } + + /// A Machine-scope read that fails must stop the fix too, even when the + /// User scope has a value to clear: the report would otherwise omit the + /// Machine-scope guidance for a value that may well be there. + #[test] + fn unset_override_machine_read_failure_stops_before_clearing_the_user_scope() { + let host = FakeHost::new((exited(0), "10.3.0"), exited(0)) + .with_machine_read((CommandOutcome::TimedOut, "")); + let (code, err) = unset_override(&host); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty(), "setx must not run"); + assert_eq!( + err, + "Could not read the current Machine HSA_OVERRIDE_GFX_VERSION: PowerShell timed out \ + after 8s and was stopped; nothing was changed.\n" + ); + } + + #[test] + fn unset_override_with_both_scopes_genuinely_unset_is_done_without_writing() { + let host = FakeHost::new(unset(), exited(0)); + let (code, err) = unset_override(&host); + assert_eq!(code, exit::OK); + assert_eq!(host.calls().len(), 2, "both scopes are read"); + assert!(host.writes().is_empty()); + assert_eq!(err, ""); + } + + // fix-6 (Windows) -------------------------------------------------- + + fn path_export(host: &FakeHost<'_>) -> (i32, String) { + let mut err = Vec::new(); + let code = path_export_windows(&approved(), r"C:\ROCm\bin", host.runner(), &mut err); + (code, text(&err)) + } + + #[test] + fn path_export_success_writes_the_prepended_path_and_returns_0() { + let host = FakeHost::new((exited(0), r"C:\Windows"), exited(0)); + let (code, err) = path_export(&host); + assert_eq!(code, exit::OK); + let writes = host.writes(); + assert_eq!(writes.len(), 1); + assert_eq!(writes[0][..3], ["powershell", "-NoProfile", "-Command"]); + assert!( + writes[0][3].contains(r"'C:\ROCm\bin;C:\Windows'"), + "{:?}", + writes[0] + ); + assert_eq!(err, ""); + } + + #[test] + fn path_export_write_failure_returns_4() { + let host = FakeHost::new((exited(0), r"C:\Windows"), exited(1)); + let (code, err) = path_export(&host); + assert_eq!(code, exit::FAILED); + assert_eq!(host.writes().len(), 1); + assert_eq!(err, "PowerShell exited 1; User PATH NOT changed.\n"); + } + + #[test] + fn path_export_write_timeout_says_timed_out_and_how_to_check() { + let host = FakeHost::new((exited(0), r"C:\Windows"), CommandOutcome::TimedOut); + let (code, err) = path_export(&host); + assert_eq!(code, exit::FAILED); + assert_eq!(host.writes_with_timeouts()[0].1, RUN_TIMEOUT); + assert_eq!( + err, + "PowerShell timed out after 60s and was stopped; User PATH may or may not have \ + changed. Check with `[Environment]::GetEnvironmentVariable('PATH','User')`, then \ + re-run `rocm fix fix-6-path` if it did not.\n" + ); + } + + #[test] + fn path_export_write_missing_powershell_says_it_could_not_start() { + let host = FakeHost::new((exited(0), r"C:\Windows"), CommandOutcome::NotFound); + let (code, err) = path_export(&host); + assert_eq!(code, exit::FAILED); + assert_eq!( + err, + "PowerShell could not be started: it was not found; User PATH NOT changed.\n" + ); + } + + #[test] + fn path_export_read_timeout_stops_before_the_write_and_says_why() { + let host = FakeHost::new((CommandOutcome::TimedOut, ""), exited(0)); + let (code, err) = path_export(&host); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty()); + assert_eq!( + err, + "Could not read the current User PATH: PowerShell timed out after 8s and was stopped; \ + nothing was changed.\n" + ); + } + + // fix-9 (Windows) -------------------------------------------------- + + fn pin_device(host: &FakeHost<'_>) -> (i32, String) { + let mut err = Vec::new(); + let code = hip_visible_devices_windows(&approved(), 1, host.runner(), &mut err); + (code, text(&err)) + } + + #[test] + fn pin_device_success_runs_setx_and_returns_0() { + let host = FakeHost::new(unset(), exited(0)); + let (code, err) = pin_device(&host); + assert_eq!(code, exit::OK); + assert_eq!(host.writes(), [vec!["setx", "HIP_VISIBLE_DEVICES", "1"]]); + assert_eq!(err, ""); + } + + #[test] + fn pin_device_setx_failure_returns_4() { + let host = FakeHost::new(unset(), exited(1)); + let (code, err) = pin_device(&host); + assert_eq!(code, exit::FAILED); + assert_eq!(host.writes().len(), 1); + assert_eq!( + err, + "setx exited 1; User-scope HIP_VISIBLE_DEVICES NOT changed.\n" + ); + } + + #[test] + fn pin_device_setx_timeout_says_timed_out_and_how_to_check() { + let host = FakeHost::new(unset(), CommandOutcome::TimedOut); + let (code, err) = pin_device(&host); + assert_eq!(code, exit::FAILED); + assert_eq!(host.writes_with_timeouts()[0].1, RUN_TIMEOUT); + assert_eq!( + err, + "setx timed out after 60s and was stopped; User-scope HIP_VISIBLE_DEVICES may or may \ + not have changed. Check with \ + `[Environment]::GetEnvironmentVariable('HIP_VISIBLE_DEVICES','User')`, then re-run \ + `rocm fix fix-9-igpu-dgpu --device-index 1` if it did not.\n" + ); + } + + #[test] + fn pin_device_setx_missing_says_it_could_not_start() { + let host = FakeHost::new(unset(), CommandOutcome::NotFound); + let (code, err) = pin_device(&host); + assert_eq!(code, exit::FAILED); + assert_eq!( + err, + "setx could not be started: it was not found; User-scope HIP_VISIBLE_DEVICES NOT \ + changed.\n" + ); + } + + /// The reported bug's other read: a failed read used to read as "unset", + /// skip the "User scope already sets HIP_VISIBLE_DEVICES" guard and run + /// `setx` over whatever the user had set. + #[test] + fn pin_device_read_timeout_stops_before_setx() { + let host = FakeHost::new((CommandOutcome::TimedOut, ""), exited(0)); + let (code, err) = pin_device(&host); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty(), "setx must not run"); + assert_eq!( + err, + "Could not read the current User HIP_VISIBLE_DEVICES: PowerShell timed out after 8s \ + and was stopped; nothing was changed.\n" + ); + } + + #[test] + fn pin_device_read_with_missing_powershell_stops_before_setx() { + let host = FakeHost::new((CommandOutcome::NotFound, ""), exited(0)); + let (code, _) = pin_device(&host); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty(), "setx must not run"); + } + + #[test] + fn pin_device_leaves_an_existing_user_value_alone() { + let host = FakeHost::new((exited(0), "0"), exited(0)); + let (code, _) = pin_device(&host); + assert_eq!(code, exit::OK); + assert!( + host.writes().is_empty(), + "an existing value is not overwritten" + ); + } + + /// Every "re-run `rocm fix `" line names a recipe that exists and has + /// a runner, so the recovery it advises can actually be carried out. + #[test] + fn every_rerun_id_names_a_recipe_with_a_runner() { + for id in [RENDER_GROUP_ID, UNSET_OVERRIDE_ID, PATH_ID, IGPU_DGPU_ID] { + let recipe = super::super::catalog::find_recipe(id) + .unwrap_or_else(|| panic!("{id} is not in the catalog")); + assert!(recipe.runner.is_some(), "{id} has no runner to re-run"); + } + } + /// The Windows arm of fix-2 does mutate (it runs `setx` to clear the User /// scope), so unlike the Linux arm above, a decline has to come back as /// `5`, not `0` -- `skills/rocm-doctor/reference.md` documents `5` as @@ -897,10 +1491,18 @@ mod tests { /// this way. #[test] fn windows_decline_on_user_scope_returns_5() { - let code = - report_and_clear_override_windows(&FixOptions::default(), "10.3.0", "", |_| false); + let host = FakeHost::new(unset(), exited(0)); + let code = report_and_clear_override_windows( + &FixOptions::default(), + "10.3.0", + "", + |_| false, + host.runner(), + &mut Vec::new(), + ); assert_eq!(code, 5, "a declined User-scope clear must exit 5, not 0"); + assert!(host.writes().is_empty(), "a decline must not run setx"); } /// Declining the User scope must not swallow the Machine-scope guidance: @@ -912,26 +1514,37 @@ mod tests { /// would have to change this assertion to keep passing. #[test] fn windows_decline_with_machine_scope_also_set_still_returns_5() { - let code = - report_and_clear_override_windows(&FixOptions::default(), "10.3.0", "11.0.0", |_| { - false - }); + let host = FakeHost::new(unset(), exited(0)); + let code = report_and_clear_override_windows( + &FixOptions::default(), + "10.3.0", + "11.0.0", + |_| false, + host.runner(), + &mut Vec::new(), + ); assert_eq!(code, 5); + assert!(host.writes().is_empty(), "a decline must not run setx"); } #[test] fn windows_consent_granted_is_not_treated_as_a_decline() { - // `setx` isn't on this host, so a real run would report failure (`4`) - // -- the point here is only that the consent gate itself was - // reached and answered "yes", not routed as a decline. - let code = - report_and_clear_override_windows(&FixOptions::default(), "10.3.0", "", |_| true); + let host = FakeHost::new(unset(), exited(0)); + let code = report_and_clear_override_windows( + &FixOptions::default(), + "10.3.0", + "", + |_| true, + host.runner(), + &mut Vec::new(), + ); - assert_ne!( - code, 5, - "granted consent must never be reported as declined" + assert_eq!( + code, 0, + "granted consent and a setx that exits 0 is success" ); + assert_eq!(host.writes(), [vec!["setx", OVERRIDE_VAR, ""]]); } #[test] @@ -941,18 +1554,32 @@ mod tests { ..FixOptions::default() }; - let code = report_and_clear_override_windows(&opts, "10.3.0", "", |_| { - panic!("dry-run must not reach the consent gate") - }); + let host = FakeHost::new(unset(), exited(0)); + let code = report_and_clear_override_windows( + &opts, + "10.3.0", + "", + |_| panic!("dry-run must not reach the consent gate"), + host.runner(), + &mut Vec::new(), + ); + assert!(host.calls().is_empty(), "a dry-run runs nothing"); assert_eq!(code, 0, "a dry-run preview is not a decline"); } #[test] fn windows_nothing_persisted_in_either_scope_returns_0_without_prompting() { - let code = report_and_clear_override_windows(&FixOptions::default(), "", "", |_| { - panic!("nothing to clear means no consent gate at all") - }); + let host = FakeHost::new(unset(), exited(0)); + let code = report_and_clear_override_windows( + &FixOptions::default(), + "", + "", + |_| panic!("nothing to clear means no consent gate at all"), + host.runner(), + &mut Vec::new(), + ); + assert!(host.calls().is_empty(), "nothing to clear runs nothing"); assert_eq!(code, 0); } @@ -964,18 +1591,10 @@ mod tests { /// `setx PATH ""` -- replacing the user's entire real PATH with /// one entry. /// - /// `opts.dry_run = true` is the discriminator, not `opts.yes`: on a host - /// without a real `powershell`/`setx` (this Mac included), the actual - /// write fails regardless of whether it was ever reached, so asserting - /// against a "the write failed" code cannot tell "aborted before the - /// write" apart from "attempted the write and the write itself failed" - /// -- both land on the same non-zero code by coincidence of this host's - /// missing binary. Collapsing the failed read to `""` instead falls - /// through to the dry-run short-circuit (which returns `0`, "preview - /// printed, nothing to do"), while the fix aborts at the read itself and - /// never reaches that branch -- so this is the one assertion that is - /// both host-independent and still fails against the unfixed - /// collapse-to-empty behavior. + /// `opts.dry_run = true` is the discriminator: collapsing the failed read + /// to `""` falls through to the dry-run short-circuit (which returns `0`, + /// "preview printed, nothing to do"), while the fix aborts at the read + /// itself and never reaches that branch. #[test] fn windows_path_read_failure_aborts_before_plan_or_write() { let opts = FixOptions { @@ -983,9 +1602,9 @@ mod tests { ..FixOptions::default() }; - let code = path_export_windows(&opts, r"C:\ROCm\bin", || { - None // the read itself failed (PowerShell missing/blocked/timed out) - }); + // The read itself failed (PowerShell missing/blocked/timed out). + let host = FakeHost::new((CommandOutcome::NotFound, ""), exited(0)); + let code = path_export_windows(&opts, r"C:\ROCm\bin", host.runner(), &mut Vec::new()); assert_ne!( code, 0, @@ -995,6 +1614,7 @@ mod tests { code, 5, "a failed read was never offered a prompt to decline" ); + assert!(host.writes().is_empty(), "a failed read writes nothing"); } /// A genuinely empty User PATH (the read succeeded and returned `""`, @@ -1095,9 +1715,14 @@ mod tests { #[test] fn windows_path_already_contains_bin_dir_short_circuits_with_no_change() { let bin_dir = r"C:\ROCm\bin"; - let code = path_export_windows(&FixOptions::default(), bin_dir, || { - Some(format!(r"C:\Windows;{bin_dir}")) - }); + let existing = format!(r"C:\Windows;{bin_dir}"); + let host = FakeHost::new((CommandOutcome::Exited(0), &existing), exited(0)); + let code = path_export_windows( + &FixOptions::default(), + bin_dir, + host.runner(), + &mut Vec::new(), + ); assert_eq!( code, 0, @@ -1116,7 +1741,9 @@ mod tests { ..FixOptions::default() }; - let code = path_export_windows(&opts, r"C:\ROCm\bin", || Some(String::new())); + let host = FakeHost::new(unset(), exited(0)); + let code = path_export_windows(&opts, r"C:\ROCm\bin", host.runner(), &mut Vec::new()); + assert!(host.writes().is_empty(), "a dry-run writes nothing"); assert_eq!(code, 0, "a dry-run preview is not a decline"); } diff --git a/docs/architecture.md b/docs/architecture.md index a303a91f88..c947b1e111 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -303,7 +303,7 @@ The library every first-party app and engine crate depends on. It holds host exa | [`fake_executable.rs`](../crates/rocm-core/src/fake_executable.rs) | `write_fake_executable`: writes a stand-in script for tests from a short-lived child, so running it does not fail with `ETXTBSY`. It is built into every build, without a `cfg(test)` gate, so dependent crates' tests can call it. | flat | | [`fix.rs`](../crates/rocm-core/src/fix.rs) | Root of `rocm fix`: the dispatch (`apply`) that plans, confirms and runs a catalog remediation, and the re-exports of its children's public names. | flat | | [`fix/catalog.rs`](../crates/rocm-core/src/fix/catalog.rs) | The closed remediation catalog: `FixRecipe`, the per-platform class table, `RECIPES`, the lookups by fix-id, and the test-only oracles. | flat | -| [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs) | The consent decision and `confirm`, the timeouts the runners use, `current_os`, and output helpers that cannot panic on a closed pipe. | flat | +| [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs) | The consent decision and `confirm`, the timeouts the runners use, `current_os`, output helpers that cannot panic on a closed pipe, and `run_step`/`Step`, which run a runner's host command on the bounded executor and turn how it ended (exit code, not started, timed out) into the one stderr line and exit code the runner reports. | flat | | [`fix/manifest.rs`](../crates/rocm-core/src/fix/manifest.rs) | The JSON catalog manifest `rocm fix --json` publishes, derived from `RECIPES` on every call. | flat | | [`fix/options.rs`](../crates/rocm-core/src/fix/options.rs) | The vocabulary of `rocm fix`: the exit codes (`exit`), `FixOptions` and `FixClass`. | flat | | [`fix/render.rs`](../crates/rocm-core/src/fix/render.rs) | Rendering the catalog for people: the listing, a recipe's plan and verify lines, the flag summary `rocm diagnose` shares, and the refusal of a diagnosis position as a fix-id. | flat | diff --git a/docs/host-probing.md b/docs/host-probing.md index 097a970258..e6b6b3342f 100644 --- a/docs/host-probing.md +++ b/docs/host-probing.md @@ -306,7 +306,7 @@ One pair per change. Each begins with a commit that adds a characterisation test The later steps of item 6, each its own change and all still open: -- Retire the adapters site by site, as items 2 to 5 remove call sites: a probe that calls `run_bounded` directly reads the typed outcome, so "not installed" stays quiet and "timed out" becomes a `probe_failures` entry without parsing a message, which the adapters cannot do because they keep their return shapes. +- Retire the adapters site by site, as items 2 to 5 remove call sites: a probe that calls `run_bounded` directly reads the typed outcome, so "not installed" stays quiet and "timed out" becomes a `probe_failures` entry without parsing a message, which the adapters cannot do because they keep their return shapes. The `rocm fix` runners' commands and their Windows env-scope reads already do: they run through `run_step` in [fix/consent.rs](../crates/rocm-core/src/fix/consent.rs), so a timed-out step is reported as one, not as exit code `124`. The one other command the runners start, the `id -u` root check, still goes through `run`. - Move `wait_with_output_bounded` in [process.rs](../apps/rocm/src/therock/process.rs) of `apps/rocm` onto the executor, which is the last helper of [#623](https://github.com/ROCm/rocm-cli/issues/623) that still joins its readers with no limit, and decide where `rocmd`'s `parse_sandbox_child_output` quote is bounded. - Make the candidate loop of `capture_optional_command_with_timeout` stop on a timeout instead of starting the next spelling of a program that hung. - Decide whether the runners refuse to resolve a bare program name through an empty `PATH` entry, and whether the adapters take a per-call drain grace: two items of the open list below. diff --git a/docs/manual-testing.md b/docs/manual-testing.md index eb3f8de017..2394e3f87c 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -1677,3 +1677,51 @@ Expected result: the same command reading that file still reports the same causes, and a paste with a non-ASCII character in it (`é`, `→`, a typographic quote) reports the same causes as in PowerShell 7. + +## 14. `rocm fix` When A Step Does Not Finish Or A Read Fails + +The automated scenarios (`diagnose-15`, `diagnose-62` on bare-metal Linux; +`diagnose-39`, `diagnose-63`, `diagnose-64` on Windows) cover these; repeat +them by hand on a release build. + +Linux, a helper that never finishes. Stand a hanging `sudo` in for the real +one, on a `PATH` that holds nothing else (so the run is not as root and changes +no group): + +```bash +ROCM=$(command -v rocm) +FAKE=$(mktemp -d) +printf '#!/bin/sh\nexec /bin/sleep 600\n' > "$FAKE/sudo" +printf '#!/bin/sh\nexit 1\n' > "$FAKE/usermod" +chmod +x "$FAKE/sudo" "$FAKE/usermod" +PATH="$FAKE" "$ROCM" fix fix-4-render-group --yes; echo "exit $?" +``` + +Expected result: + +- After about a minute, stderr says ``sudo usermod timed out after 60s and was + stopped; group membership may or may not have changed. Check with + `id -nG `, then re-run `rocm fix fix-4-render-group` if it did not.`` +- The exit code is 4. Nothing says `NOT changed`, and there is no + `Added to render,video.` line. +- `pgrep -f 'sleep 600'` finds nothing afterwards. + +Windows, a read that fails. In a PowerShell window, empty `PATH` for that window +only and start `rocm.exe` by its full path: + +```powershell +$rocm = (Get-Command rocm).Source +$env:Path = '' +& $rocm fix fix-2-unset-override --yes; "exit $LASTEXITCODE" +& $rocm fix fix-9-igpu-dgpu --device-index 1 --yes; "exit $LASTEXITCODE" +``` + +Expected result: + +- fix-2 prints `Could not read the current User HSA_OVERRIDE_GFX_VERSION: + PowerShell could not be started: it was not found; nothing was changed.` on + stderr and exits 4. It does not print `No persistent HSA_OVERRIDE_GFX_VERSION + found` or `You're done`. +- fix-9 prints the same line for `HIP_VISIBLE_DEVICES`, exits 4, and prints no + `Plan: persist HIP_VISIBLE_DEVICES` line; the User-scope value is unchanged. +- Close the window afterwards; the empty `PATH` was only that window's. diff --git a/docs/testing.md b/docs/testing.md index 7e4e853b33..a6d6898d9c 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -2916,6 +2916,39 @@ catalog in [host.rs](../crates/rocm-core/src/diagnose/host.rs) ([fix/catalog.rs](../crates/rocm-core/src/fix/catalog.rs)) runs the catalog's `verify_linux` line for fix-2, not the `rocm diagnose` one, on an empty `PATH`. +When a fix's own command does not succeed, `rocm fix` exits 4 and prints one +line on stderr, built from how the command ended +(`Step` in [fix/consent.rs](../crates/rocm-core/src/fix/consent.rs)): + +| How the command ended | What the line says | +|---|---| +| exited non-zero, or could not be started | it exited `N` (or could not be started), and the change was NOT made | +| timed out (60s for a change), or was stopped by a signal or a failed wait | it was stopped, the change may or may not have been made, a command to check it, and the `rocm fix` command to re-run | +| a Windows read of the current value did not complete (8s) | it could not read the current value, and nothing was changed; the fix stops before any plan or prompt | + +Each row for each runner is unit-tested with an injected command runner in +[fix/runners.rs](../crates/rocm-core/src/fix/runners.rs) and +[fix/consent.rs](../crates/rocm-core/src/fix/consent.rs), on every host. The +scenarios in [diagnose.feature](../tests/e2e-cucumber/features/diagnose.feature) +run the real binary: `diagnose-15` (fix-4's helper exits 1) and `diagnose-62` +(it never finishes) stand a fake `sudo` on a restricted `PATH` that records the +arguments it was given, and assert the line together with the exit code, that +the helper was asked to add the user to the groups, and that the success line is +absent. `diagnose-62` waits out the real one-minute bound; there is no switch to +shorten it. Both are `@requires-os:linux @requires-bare-metal`. On Windows, +`diagnose-39` (fix-6), `diagnose-63` (fix-2) and `diagnose-64` (fix-9 with +`--device-index 1`) give the CLI an empty `PATH`, so its PowerShell read cannot +start, and assert exit 4, the read-failure line, and that the fix printed no plan +and did not report the variable as absent. They run on the Windows lanes only; +the Linux lanes compile them. No scenario times out a Windows `setx` or +PowerShell write: those rows are covered by the unit tests. To run the two +Linux scenarios on a bare-metal Linux host (`-n` skips the tag gates, so on WSL2 +they fail at the platform refusal instead): + +```bash +cargo xtask e2e -- -n '(diagnose-15|diagnose-62) ' +``` + Provider audit focused test: ```bash diff --git a/skills/rocm-doctor/SKILL.md b/skills/rocm-doctor/SKILL.md index c3377ee89b..41fe6766c4 100644 --- a/skills/rocm-doctor/SKILL.md +++ b/skills/rocm-doctor/SKILL.md @@ -260,6 +260,12 @@ passes — the GPU is AMD or no vendor was named. pinned. Once the user knows N, re-run with `rocm fix fix-9-igpu-dgpu --device-index N`. + If `rocm fix` exits 4, the command it ran failed or did not finish in time. + Relay its stderr line. After a timeout that line says the change may or may + not have been made, and names a command to check it and the `rocm fix` + command to re-run; do not tell the user the fix was applied, or that nothing + changed, until that check has been run. + 4. **Verify.** Have the user run the `verify` command from the diagnosis. Use `rocm examine` (or `rocm examine --json`) when you only need the host state diff --git a/skills/rocm-doctor/reference.md b/skills/rocm-doctor/reference.md index b6da05de3e..4c17395055 100644 --- a/skills/rocm-doctor/reference.md +++ b/skills/rocm-doctor/reference.md @@ -105,7 +105,7 @@ id is refused, and the refusal exits 1 (see the table). Exit codes: | 1 | internal error; also the refusal of `--json` together with a fix id | | 2 | usage error (incl. unknown fix-id) | | 3 | not applicable on this host (OS mismatch, negative `--device-index`) — nothing changed | -| 4 | attempted but the command failed | +| 4 | attempted but the command failed or timed out; after a timeout the change may be partial — the message names how to check it and what to re-run | | 5 | user declined at the prompt | Three ids are ever auto-applicable — never four, and `fix-9-igpu-dgpu` is not diff --git a/tests/e2e-cucumber/features/diagnose.feature b/tests/e2e-cucumber/features/diagnose.feature index a94f59e824..5a6bd0274c 100644 --- a/tests/e2e-cucumber/features/diagnose.feature +++ b/tests/e2e-cucumber/features/diagnose.feature @@ -215,6 +215,11 @@ Feature: Diagnosing failures and listing fixes # `fix-4-render-group`'s `applies_on` does not include `wsl`, so on a WSL2 # host the CLI refuses it as the wrong platform before ever invoking the # (faked) `usermod` — there is no command-failure branch to reach there. + # + # The Then step also holds the claim against the state: the stand-in records + # that it was asked to add the user to the groups, and the success line is + # absent, so "NOT changed" is said about a change that was attempted and + # refused, not about one that never ran or quietly went through. @id:diagnose-fix-command-failure-reported-on-stderr @requires-os:linux @requires-bare-metal Scenario: diagnose-15 - A fix whose helper command fails explains why, on stderr, with exit code 4 Given a user who has approved a fix whose helper command will fail @@ -601,7 +606,8 @@ Feature: Diagnosing failures and listing fixes # `ps_env_scope`'s doc comment names -- "PowerShell missing") rather than # faking the read failing, so the abort this proves is a real one, not a # simulated one, and it never touches the real User PATH at all, so no - # capture/restore is needed here. + # capture/restore is needed here. diagnose-63 and diagnose-64 hold fix-2 and + # fix-9 to the same rule. @id:diagnose-fix-path-aborts-on-unreadable-user-path @requires-os:windows Scenario: diagnose-39 - A fix-6-path run that cannot read the real User PATH aborts instead of wiping it Given a Windows host with a HIP SDK install and no way to resolve PowerShell @@ -914,3 +920,42 @@ Feature: Diagnosing failures and listing fixes When the user asks the CLI to diagnose the error in each file Then each is refused as a usage error that names the file and says why And nothing is diagnosed + + # The sibling of diagnose-15 the reported bug was about: the helper command + # never finishes. The CLI stops it at the fix's one-minute bound, but it can + # only stop the command it started (`sudo`), so the change may still have + # been made. Before ROCMAI-345 this was reported as "usermod exited 124; + # group membership NOT changed." -- naming no timeout and claiming a state + # nobody had checked. The stand-in records its arguments and then sleeps far + # past the bound, so the scenario waits out the real minute: there is no + # test-only way to shorten it, on purpose, so the bound under test is the one + # users get. Same lane as diagnose-15, for the same reasons. + @id:diagnose-fix-command-timeout-says-change-may-be-partial @requires-os:linux @requires-bare-metal + Scenario: diagnose-62 - A fix whose helper command never finishes says the change may be partial and how to check it + Given a user who has approved a fix whose helper command never finishes + When the user asks the CLI to apply the approved fix + Then the CLI reports on stderr, with exit code 4, that the helper was stopped after a minute, how to check the change and which fix to re-run + And the CLI claims neither that the change was made nor that nothing changed + And the helper was asked to add the user to the render and video groups + + # A User-scope read that cannot complete used to be taken as "not set": with + # nothing in the Machine scope either, fix-2 printed that no persistent + # override was found and the user was done, and exited 0, on a machine that + # may still carry it. Same real "PowerShell missing" cause as diagnose-39. + @id:diagnose-fix-override-aborts-on-unreadable-user-scope @requires-os:windows + Scenario: diagnose-63 - Clearing the GPU override stops when the saved value cannot be read, instead of calling it gone + Given a Windows host where PowerShell cannot be found + And a user who has chosen the fix for the GPU override + When the user asks the CLI to apply the approved fix + Then the CLI stops with exit code 4, saying it could not read the saved override and that nothing was changed + And the CLI does not report the override as already gone + + # The same failed read made fix-9 skip its "already set" guard and overwrite + # a User-scope device setting the user may have chosen on purpose. + @id:diagnose-fix-igpu-aborts-on-unreadable-user-scope @requires-os:windows + Scenario: diagnose-64 - Pinning the discrete GPU stops when the saved device setting cannot be read, before planning a write + Given a Windows host where PowerShell cannot be found + And a user who has chosen the fix that hides the integrated GPU + When the user asks the CLI to apply the approved fix to the second GPU + Then the CLI stops with exit code 4, saying it could not read the saved device setting and that nothing was changed + And no plan to save a device setting is printed diff --git a/tests/e2e-cucumber/tests/e2e/diagnose_steps.rs b/tests/e2e-cucumber/tests/e2e/diagnose_steps.rs index 369b13626c..bd295e1700 100644 --- a/tests/e2e-cucumber/tests/e2e/diagnose_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/diagnose_steps.rs @@ -43,13 +43,13 @@ const PREVIEW_FIX_ID: &str = "fix-1-arch"; /// found". This one needs only `--device-index`, which the scenario supplies. const MUTATING_FIX_ID: &str = "fix-9-igpu-dgpu"; -/// The recipe used to prove a failed helper command is explained on stderr with -/// exit code 4. `fix-4-render-group` is the only AUTO recipe whose command-failure -/// branch this suite can force deterministically: its helper (`usermod`, run -/// directly as root or via `sudo` otherwise) is resolved off `$PATH`, so a -/// scenario-controlled `$PATH` (see `command_fails_bin_dir`) can stand a fake -/// `usermod`/`sudo` in for it, unconditionally failing, without needing real -/// root or touching real group membership. +/// The recipe used to prove a failed or timed-out helper command is explained +/// on stderr with exit code 4. `fix-4-render-group` is the only AUTO recipe whose +/// command-failure branch this suite can force deterministically: its helper +/// (`usermod`, run directly as root or via `sudo` otherwise) is resolved off +/// `$PATH`, so a scenario-controlled `$PATH` (see `command_fails_bin_dir`) can +/// stand a fake `usermod`/`sudo` in for it, failing or never finishing, without +/// needing real root or touching real group membership. const COMMAND_FAILURE_FIX_ID: &str = "fix-4-render-group"; /// The Windows PATH-repair recipe at the center of ROCMAI-449. Its own e2e @@ -269,6 +269,26 @@ fn command_fails_bin_dir(world: &E2eWorld) -> std::path::PathBuf { .join("fake-bin") } +/// Where the fake `usermod`/`sudo` record each call, one ` ` line +/// per call. Outside [`command_fails_bin_dir`] so it is not on the CLI's PATH. +fn render_group_helper_log(world: &E2eWorld) -> std::path::PathBuf { + world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .join("fake-bin-calls.log") +} + +/// The `$USER` the render-group scenarios run the fix as. +const RENDER_GROUP_USER: &str = "e2e-test-user"; + +/// The line `fix-4-render-group` prints once the user was added. Built from +/// the same user the scenario sets, and absent from every failure path. +fn render_group_success_line() -> String { + format!("Added {RENDER_GROUP_USER} to render,video.") +} + // ── Given ────────────────────────────────────────────────────────── #[given("a user who hit a known ROCm failure")] @@ -518,23 +538,47 @@ async fn user_chose_fix_for_another_os(world: &mut E2eWorld) { #[given("a user who has approved a fix whose helper command will fail")] async fn user_approved_fix_that_will_fail(world: &mut E2eWorld) { + plant_render_group_helpers(world, "exit 1"); +} + +#[given("a user who has approved a fix whose helper command never finishes")] +async fn user_approved_fix_that_never_finishes(world: &mut E2eWorld) { + // `exec`, so the process `rocm` started *is* the sleep: the executor stops + // only its direct child, and a `sleep` left as the shell's own child would + // outlive the scenario by ten minutes. The absolute path because the + // scenario's PATH holds only the stand-ins. + plant_render_group_helpers(world, "exec /bin/sleep 600"); +} + +/// Stands fake `usermod`/`sudo` scripts in for the fix's helper on a `$PATH` +/// holding nothing else. Each appends ` ` to +/// [`render_group_helper_log`] and then runs `tail`, so a scenario can say +/// both what the CLI reported and what it asked the helper to do. +fn plant_render_group_helpers(world: &mut E2eWorld, tail: &str) { let bin_dir = command_fails_bin_dir(world); std::fs::create_dir_all(&bin_dir).expect("failed to create the scenario's fake PATH dir"); + let log = render_group_helper_log(world); + let log = log.to_str().expect("the scenario root is UTF-8"); + assert!( + !log.contains('\''), + "the helper log path is single-quoted in the stand-in script: {log}" + ); // `usermod` only has to exist for the `which` probe; the command actually run // -- `usermod` directly if already root, `sudo usermod ...` otherwise -- goes - // through one of these two scripts either way, and both fail unconditionally. + // through one of these two scripts either way. for name in ["usermod", "sudo"] { let script = bin_dir.join(name); - rocm_core::fake_executable::write_fake_executable(&script, "#!/bin/sh\nexit 1\n") + let body = format!("#!/bin/sh\necho \"{name} $*\" >> '{log}'\n{tail}\n"); + rocm_core::fake_executable::write_fake_executable(&script, body) .unwrap_or_else(|e| panic!("failed to write fake {name}: {e}")); } // Restricting `$PATH` to only the fakes above also makes the recipe's // root-detection deterministic: it shells out to `id -u`, which is not on // this PATH, so the spawn itself fails and reads as "not root" regardless of - // who runs the suite -- the same `sudo usermod` branch fails on every host, + // who runs the suite -- the same `sudo usermod` branch runs on every host, // CI or developer machine, root or not. world.command_env.push(("PATH", bin_dir.into_os_string())); - world.command_env.push(("USER", "e2e-test-user".into())); + world.command_env.push(("USER", RENDER_GROUP_USER.into())); world.model_name = Some(COMMAND_FAILURE_FIX_ID.to_string()); } @@ -574,16 +618,31 @@ async fn user_on_windows_with_hip_sdk_and_no_powershell(world: &mut E2eWorld) { world .command_env .push(("HIP_PATH", path_fix_sdk_dir(world).into_os_string())); + deny_powershell(world); + world.model_name = Some(PATH_FIX_ID.to_string()); +} + +#[given("a Windows host where PowerShell cannot be found")] +async fn windows_host_without_powershell(world: &mut E2eWorld) { + deny_powershell(world); +} + +#[given("a user who has chosen the fix that hides the integrated GPU")] +async fn user_chose_igpu_fix(world: &mut E2eWorld) { + world.model_name = Some(MUTATING_FIX_ID.to_string()); +} + +/// Gives the CLI an empty `PATH`, so its own PowerShell reads cannot start. +fn deny_powershell(world: &mut E2eWorld) { // An empty child PATH means the CLI's own `Command::new("powershell")` // cannot resolve the binary at all -- `powershell.exe` lives under // `System32\WindowsPowerShell\v1.0`, which Windows does NOT search // unconditionally the way it does System32 itself, so this is a real // instance of the "PowerShell missing" cause `ps_env_scope`'s doc comment - // names, not a faked one. Nothing here touches the real machine's - // User-scope PATH, so no capture/restore is needed: the read never gets - // far enough to risk it. + // names, not a faked one. Every fix that reads a User-scope value stops + // at that read, so nothing on the real machine is touched and no + // capture/restore is needed. world.command_env.push(("PATH", std::ffi::OsString::new())); - world.model_name = Some(PATH_FIX_ID.to_string()); } // ── When ─────────────────────────────────────────────────────────── @@ -680,6 +739,16 @@ async fn user_applies_approved_fix(world: &mut E2eWorld) { world.cli_rc = Some(rc); } +#[when("the user asks the CLI to apply the approved fix to the second GPU")] +async fn user_applies_approved_fix_to_second_gpu(world: &mut E2eWorld) { + let fix_id = world.model_name.clone().expect("no fix id set"); + let (stdout, stderr, rc) = + crate::run_rocm_with_scenario_env(world, &["fix", &fix_id, "--device-index", "1", "--yes"]); + world.cli_output = Some(stdout); + world.cli_stderr = Some(stderr); + world.cli_rc = Some(rc); +} + #[when("the user is asked interactively to apply it and types no")] async fn user_declines_fix_interactively(world: &mut E2eWorld) { let fix_id = world.model_name.clone().expect("no fix id set"); @@ -1674,7 +1743,7 @@ async fn assert_command_failure_reported_on_stderr(world: &mut E2eWorld) { ); let stderr = world.cli_stderr.as_deref().unwrap_or(""); assert!( - stderr.contains("usermod exited") && stderr.contains("group membership NOT changed"), + stderr.contains("usermod exited 1; group membership NOT changed."), "the command-failure explanation must be on stderr:\n{stderr}" ); let stdout = world.cli_output.as_deref().unwrap_or(""); @@ -1682,6 +1751,83 @@ async fn assert_command_failure_reported_on_stderr(world: &mut E2eWorld) { !stdout.contains("group membership NOT changed"), "the command-failure explanation must not also be on stdout:\n{stdout}" ); + // "NOT changed" is a claim about state: it holds only for a change that + // was asked for, refused, and not then reported as made. + assert!( + !stdout.contains(&render_group_success_line()), + "a failed helper must not be followed by the success line:\n{stdout}" + ); + assert_render_group_helper_was_asked(world); +} + +#[then( + "the CLI reports on stderr, with exit code 4, that the helper was stopped after a minute, how to check the change and which fix to re-run" +)] +async fn assert_command_timeout_reported_on_stderr(world: &mut E2eWorld) { + let stdout = world.cli_output.as_deref().unwrap_or(""); + let stderr = world.cli_stderr.as_deref().unwrap_or(""); + assert_eq!( + world.cli_rc, + Some(4), + "a helper stopped at the deadline is a failed attempt, exit 4:\n{stdout}\n{stderr}" + ); + // Not run as root (see `plant_render_group_helpers`), so the command is + // `sudo usermod`; the bound is the fix's own one-minute RUN_TIMEOUT. + let expected = format!( + "sudo usermod timed out after 60s and was stopped; group membership may or may not have \ + changed. Check with `id -nG {RENDER_GROUP_USER}`, then re-run \ + `rocm fix {COMMAND_FAILURE_FIX_ID}` if it did not." + ); + assert!( + stderr.lines().any(|line| line == expected), + "expected the timeout line on stderr:\n {expected}\ngot:\n{stderr}" + ); + assert!( + !stdout.contains("timed out"), + "the timeout explanation must not also be on stdout:\n{stdout}" + ); +} + +#[then("the CLI claims neither that the change was made nor that nothing changed")] +async fn assert_no_claim_about_the_unfinished_change(world: &mut E2eWorld) { + let combined = format!( + "{}\n{}", + world.cli_output.as_deref().unwrap_or(""), + world.cli_stderr.as_deref().unwrap_or("") + ); + // The CLI stopped `sudo`, not `usermod`, so either claim could be false. + assert!( + !combined.contains("NOT changed"), + "a stopped helper may have made the change; the CLI must not say it did not:\n{combined}" + ); + assert!( + !combined.contains(&render_group_success_line()), + "a stopped helper may not have made the change; the CLI must not say it did:\n{combined}" + ); +} + +#[then("the helper was asked to add the user to the render and video groups")] +async fn assert_render_group_helper_asked(world: &mut E2eWorld) { + assert_render_group_helper_was_asked(world); +} + +/// The stand-in's log shows the CLI asked to add [`RENDER_GROUP_USER`] to the +/// render and video groups, via `sudo` or directly. +fn assert_render_group_helper_was_asked(world: &E2eWorld) { + let log_path = render_group_helper_log(world); + let log = std::fs::read_to_string(&log_path).unwrap_or_else(|e| { + panic!( + "the helper stand-in was never run ({}: {e}), so the reported outcome is about a \ + command that did not happen", + log_path.display() + ) + }); + let asked = format!("usermod -a -G render,video {RENDER_GROUP_USER}"); + assert!( + log.lines() + .any(|line| line == format!("sudo {asked}") || line == asked), + "expected the helper to be asked `{asked}`; it recorded:\n{log}" + ); } #[then("the CLI used PowerShell's SetEnvironmentVariable, not setx, to update the User PATH")] @@ -1737,24 +1883,90 @@ async fn assert_path_fix_prepended_with_apostrophe_intact(world: &mut E2eWorld) #[then("the CLI aborts the PATH fix with exit code 4 and changes nothing")] async fn assert_path_fix_aborts_on_unreadable_path(world: &mut E2eWorld) { - let output = world.cli_output.as_deref().unwrap_or(""); + // Exit 4 -- the same code as a write failure -- rather than a failed read + // being silently treated as an empty PATH (ROCMAI-449). + assert_read_failure_stops_the_fix( + world, + "PATH", + &["Plan: prepend", "This only takes effect in NEW shells"], + ); +} + +#[then( + "the CLI stops with exit code 4, saying it could not read the saved override and that nothing was changed" +)] +async fn assert_override_fix_aborts_on_unreadable_scope(world: &mut E2eWorld) { + assert_read_failure_stops_the_fix( + world, + "HSA_OVERRIDE_GFX_VERSION", + &["Cleared from User scope"], + ); +} + +#[then("the CLI does not report the override as already gone")] +async fn assert_override_not_reported_gone(world: &mut E2eWorld) { + let stdout = world.cli_output.as_deref().unwrap_or(""); + for claim in ["No persistent HSA_OVERRIDE_GFX_VERSION", "You're done"] { + assert!( + !stdout.contains(claim), + "a value that could not be read must not be reported as absent ({claim:?}):\n{stdout}" + ); + } +} + +#[then( + "the CLI stops with exit code 4, saying it could not read the saved device setting and that nothing was changed" +)] +async fn assert_igpu_fix_aborts_on_unreadable_scope(world: &mut E2eWorld) { + assert_read_failure_stops_the_fix( + world, + "HIP_VISIBLE_DEVICES", + &["setx only takes effect in NEW shells"], + ); +} + +#[then("no plan to save a device setting is printed")] +async fn assert_no_device_setting_plan(world: &mut E2eWorld) { + let stdout = world.cli_output.as_deref().unwrap_or(""); + for line in [ + "Plan: persist HIP_VISIBLE_DEVICES", + "already sets HIP_VISIBLE_DEVICES", + ] { + assert!( + !stdout.contains(line), + "a failed read must stop the fix before it plans or judges a write ({line:?}):\n{stdout}" + ); + } +} + +/// A Windows fix whose User-scope read of `var` could not complete exits 4 +/// with the one line that says so and that nothing was changed, and prints +/// none of `after`, the lines only a fix that went on would print. +fn assert_read_failure_stops_the_fix(world: &E2eWorld, var: &str, after: &[&str]) { + let stdout = world.cli_output.as_deref().unwrap_or(""); let stderr = world.cli_stderr.as_deref().unwrap_or(""); assert_eq!( world.cli_rc, Some(4), - "a failed PATH read must abort with exit code 4 -- the same code as a \ - write failure -- rather than being silently treated as an empty PATH \ - (ROCMAI-449):\n{output}\n{stderr}" + "a read that did not complete must stop the fix with exit 4:\n{stdout}\n{stderr}" ); - let combined = format!("{output}\n{stderr}"); + // How PowerShell failed to start is the host's to say (not found, or a + // spawn error), so the middle of the line is not pinned. + let start = format!("Could not read the current User {var}: PowerShell "); + let end = "; nothing was changed."; assert!( - combined.contains("Could not read the current User PATH"), - "expected the abort message naming the failed read:\n{combined}" - ); - assert!( - !combined.contains("Plan: prepend"), - "a failed read must abort before any write plan is printed:\n{combined}" + stderr + .lines() + .any(|line| line.starts_with(&start) && line.ends_with(end)), + "expected a stderr line `{start}...{end}`:\n{stderr}" ); + let combined = format!("{stdout}\n{stderr}"); + for line in after { + assert!( + !combined.contains(line), + "a failed read must stop the fix before {line:?}:\n{combined}" + ); + } } // ── `rocm diagnose --model` ──────────────────────────────────────── From f4eaca040de6ef7c1019af5a3f07903490134bca Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Fri, 13 Nov 2026 12:49:29 +0200 Subject: [PATCH 2/8] fix(rocm-core): keep the e2e suite polled and state fix read failures precisely (ROCMAI-345) diagnose-62 waits out fix-4's real one-minute timeout. Its step ran the CLI synchronously inside the single future the cucumber suite is polled on, so every concurrent scenario stalled for that minute and the TUI scenarios beside it overran their wall-clock caps, failing the hosted E2E lanes. The step now waits for the CLI on spawn_blocking. On Windows, the timeout line of a setx or PowerShell write said "Check with" before a PowerShell expression that cmd cannot run. Step now carries where its check runs, and those lines say "Check in PowerShell with". The Windows runners for fix-2, fix-6 and fix-9 write their own lines through injected stdout sinks, so the unit tests assert what is printed together with the exit code and what was run: a read that exits non-zero stops each fix with exit 4 and nothing written, a failed read prints no plan, and a dry run with a readable scope previews without running setx. diagnose-64 now previews fix-9 with --dry-run instead of applying it. The empty PATH hides PowerShell but not setx.exe, so a regressed read guard could otherwise set the runner's real User-scope HIP_VISIBLE_DEVICES. README, --help, the exit-code docs and the rocm-doctor skill now say exactly which fixes this covers: on Windows, fix-2, fix-6 and fix-9 with --device-index read the current value first, and a failed read exits 4 with no plan, under --dry-run too; the catalog entry printed before it is not a preview. Signed-off-by: Roman Inflianskas --- README.md | 18 +- apps/rocm/src/cli.rs | 17 +- crates/rocm-core/src/fix.rs | 3 +- crates/rocm-core/src/fix/consent.rs | 48 +- crates/rocm-core/src/fix/options.rs | 15 +- crates/rocm-core/src/fix/runners.rs | 539 +++++++++++++++--- docs/architecture.md | 4 +- docs/manual-testing.md | 18 +- docs/testing.md | 49 +- skills/rocm-doctor/SKILL.md | 28 +- skills/rocm-doctor/reference.md | 10 +- tests/e2e-cucumber/features/diagnose.feature | 20 +- tests/e2e-cucumber/tests/e2e.rs | 44 +- .../e2e-cucumber/tests/e2e/diagnose_steps.rs | 60 +- 14 files changed, 720 insertions(+), 153 deletions(-) diff --git a/README.md b/README.md index 958c80dc20..68ce52903d 100644 --- a/README.md +++ b/README.md @@ -493,7 +493,13 @@ hardware, not something an install or a setting can put right. `rocm fix` takes these flags: -- `--dry-run` shows any fix's plan without changing anything. +- `--dry-run` shows a fix's plan without changing anything. On Windows, + `fix-2-unset-override`, `fix-6-path` and `fix-9-igpu-dgpu --device-index N` + read the current value of the variable they change before planning, so a dry + run whose read fails stops with exit 4 and shows no plan. It still prints the + fix's catalog entry, which describes the fix in general terms (for + `fix-9-igpu-dgpu`, a `setx HIP_VISIBLE_DEVICES ` template) and is + not a preview of the change on this machine. - `--yes` skips the interactive confirmation once you've reviewed it. Without it, a fix that changes files or settings asks `[y/N]` (default: no). When stdin is not a terminal it prints the plan and refuses with exit code 5, @@ -509,10 +515,12 @@ hardware, not something an install or a setting can put right. A fix that runs a command and fails exits 4 and says why on stderr. That includes a command that does not finish within its time limit (one minute): the CLI stops it and exits 4, but the change may have been made in part or may -still finish, so the message names a command to check it with and the -`rocm fix` command to re-run if it was not made. On Windows, a fix that cannot -read the current value of the variable it changes stops before changing -anything, also with exit 4. +still finish, so the message says how to check it (on Windows, an expression +to run in PowerShell) and names the `rocm fix` command to re-run if it was not +made. On Windows, when one of those three fixes cannot read the current value +of the variable it changes, it stops before changing anything, also with exit 4; +under `--dry-run` it stops the same way, before showing the change it would +make. ### ROCm installation diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index fe76bf14fe..0680071edb 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -232,13 +232,18 @@ pub(crate) enum Command { /// problem and changes nothing (`info-20-gpu-no-rocm-support` is the entry /// marked that way today: a GPU ROCm has no runtime build for is a fact /// about the hardware, not something to put right). - /// Use `--dry-run` to see any fix's plan without changing anything. + /// Use `--dry-run` to see a fix's plan without changing anything. /// /// A fix whose command fails exits 4 and says why on stderr. A command that /// does not finish within its time limit is stopped and also exits 4; the /// change may then be partial, so the message names how to check it and the - /// `rocm fix` command to re-run. On Windows, a fix that cannot read the - /// variable it changes stops before changing anything, with exit 4. + /// `rocm fix` command to re-run. On Windows, `fix-2-unset-override`, + /// `fix-6-path` and `fix-9-igpu-dgpu --device-index N` read the current + /// value of the variable they change before planning; when that read + /// fails they stop before changing anything, with exit 4. Under + /// `--dry-run` they stop the same way and show no plan; the catalog entry + /// printed first is the fix's generic description, not a preview of the + /// change on this machine. Fix { /// Fix id, e.g. fix-4-render-group. Omit to list available fixes. fix_id: Option, @@ -249,7 +254,11 @@ pub(crate) enum Command { /// Fixes that only print steps never ask. #[arg(long)] yes: bool, - /// Show the plan without changing anything. + /// Show the plan without changing anything. On Windows, a dry run of a + /// fix that reads the current value of the variable it would change + /// stops with exit 4 and shows no plan when that read fails; the + /// catalog entry printed first is the fix's generic description, not a + /// preview of the change on this machine. #[arg(long = "dry-run")] dry_run: bool, /// For fix-9-igpu-dgpu: the discrete GPU index to pin. diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 532a80501a..4b6e41ad35 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -165,7 +165,8 @@ fn act_on(recipe: &FixRecipe, opts: &FixOptions) -> i32 { Plan::MissingRunner => { // A recipe the catalog says the CLI carries out, with nothing to // carry it out with -> INTERNAL, not FAILED (which is reserved for - // "attempted, and the command failed"). Held by + // "attempted, and a command or the read it planned from failed"). + // Held by // `a_recipe_that_acts_has_a_runner`. fail!("Internal error: a recipe the catalog says is applied here has no runner."); exit::INTERNAL diff --git a/crates/rocm-core/src/fix/consent.rs b/crates/rocm-core/src/fix/consent.rs index 1282041ab3..4a1c52bcd1 100644 --- a/crates/rocm-core/src/fix/consent.rs +++ b/crates/rocm-core/src/fix/consent.rs @@ -109,12 +109,34 @@ pub(super) struct Step<'a> { pub(super) what: &'a str, /// A command the user can run to see whether the change was made. pub(super) check: &'a str, + /// Where `check` runs, which the line names when it is not a plain shell. + pub(super) check_in: CheckIn, /// The `rocm fix` invocation that makes the change if it was not made. pub(super) rerun: &'a str, /// The bound the command runs under; also the number the timeout line names. pub(super) timeout: Duration, } +/// Where a [`Step`]'s `check` command is run. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum CheckIn { + /// Any shell: "Check with `id -nG alice`". + Shell, + /// A PowerShell expression, which `cmd` cannot run: "Check in PowerShell + /// with `[Environment]::GetEnvironmentVariable(...)`". + PowerShell, +} + +impl CheckIn { + /// The words before the backticked command. + const fn lead(self) -> &'static str { + match self { + Self::Shell => "Check with", + Self::PowerShell => "Check in PowerShell with", + } + } +} + /// A failed step: the line to print on stderr and the exit code to return, /// decided together so the two cannot disagree. #[derive(Debug, PartialEq, Eq)] @@ -132,8 +154,11 @@ impl Step<'_> { let phrase = outcome_phrase(self.label, outcome, self.timeout); let line = if may_have_acted(outcome) { format!( - "{phrase}; {} may or may not have changed. Check with `{}`, then re-run `{}` if it did not.", - self.what, self.check, self.rerun + "{phrase}; {} may or may not have changed. {} `{}`, then re-run `{}` if it did not.", + self.what, + self.check_in.lead(), + self.check, + self.rerun ) } else { format!("{phrase}; {} NOT changed.", self.what) @@ -269,6 +294,7 @@ mod tests { label: "setx", what: "User-scope X", check: "check-x", + check_in: CheckIn::Shell, rerun: "rocm fix fix-x", timeout: RUN_TIMEOUT, }; @@ -344,6 +370,24 @@ mod tests { assert_eq!(capture.outcome, CommandOutcome::NotFound); } + /// A PowerShell expression is not something `cmd` can run, so the line + /// says where to run it; a plain shell command keeps "Check with". + #[test] + fn a_powershell_check_says_to_run_it_in_powershell() { + let step = Step { + check_in: CheckIn::PowerShell, + ..STEP + }; + let line = step + .failure(CommandOutcome::TimedOut) + .expect("a failure") + .line; + assert!( + line.contains(" Check in PowerShell with `check-x`, then re-run"), + "{line}" + ); + } + #[test] fn a_timeout_names_the_bound_the_step_ran_under() { let step = Step { diff --git a/crates/rocm-core/src/fix/options.rs b/crates/rocm-core/src/fix/options.rs index adf32a997f..d147ab5009 100644 --- a/crates/rocm-core/src/fix/options.rs +++ b/crates/rocm-core/src/fix/options.rs @@ -21,6 +21,8 @@ use serde::{Deserialize, Serialize}; /// the same defect this whole contract exists to remove, one level up. pub mod exit { /// Applied, previewed with `--dry-run`, printed, or listed. Nothing failed. + /// A `--dry-run` whose read of the current value fails is [`FAILED`], not + /// this. pub const OK: i32 = 0; /// The CLI is inconsistent with itself -- a recipe it says it can carry out, /// with nothing to carry it out with. Never a fault of the machine. @@ -30,7 +32,14 @@ pub mod exit { /// Real, but not for this machine: wrong platform, or a precondition the /// host does not meet. Distinct from [`FAILED`], which means it was tried. pub const NOT_APPLICABLE: i32 = 3; - /// Attempted, and a command it ran failed. + /// Attempted, and a command it ran failed, could not start, or did not + /// finish. + /// + /// After a timeout the change may be partial. Also returned on Windows by + /// `fix-2-unset-override`, `fix-6-path` and `fix-9-igpu-dgpu` with a device + /// index when the read of the current value they plan from does not + /// complete -- under `--dry-run` too, with no plan shown and nothing + /// changed. pub const FAILED: i32 = 4; /// The user was asked and said no. pub const DECLINED: i32 = 5; @@ -41,7 +50,9 @@ pub mod exit { pub struct FixOptions { /// Skip the interactive confirmation (the user already approved the plan). pub yes: bool, - /// Show the plan without changing anything. + /// Show the plan without changing anything. A Windows fix that reads the + /// current value first stops with [`exit::FAILED`] and no plan when that + /// read fails. pub dry_run: bool, /// For `fix-9-igpu-dgpu`: the discrete GPU index to pin. pub device_index: Option, diff --git a/crates/rocm-core/src/fix/runners.rs b/crates/rocm-core/src/fix/runners.rs index 93b8ceb8c4..f0ec276331 100644 --- a/crates/rocm-core/src/fix/runners.rs +++ b/crates/rocm-core/src/fix/runners.rs @@ -12,7 +12,9 @@ //! runner and the running OS decides which variant runs. use super::catalog::{IGPU_DGPU_ID, PATH_ID, RENDER_GROUP_ID, UNSET_OVERRIDE_ID}; -use super::consent::{QUERY_TIMEOUT, RUN_TIMEOUT, Step, confirm, fail, read_failure, run_step}; +use super::consent::{ + CheckIn, QUERY_TIMEOUT, RUN_TIMEOUT, Step, confirm, fail, read_failure, run_step, +}; use super::options::{FixOptions, exit}; use crate::command_capture::{CommandCapture, CommandOutcome}; use crate::probe_exec::{run, which}; @@ -128,6 +130,7 @@ fn render_group_with( label, what: "group membership", check: &check, + check_in: CheckIn::Shell, rerun: &rerun, timeout: RUN_TIMEOUT, }; @@ -208,35 +211,57 @@ fn report_persistent_override(candidates: &[PathBuf]) -> i32 { } fn run_unset_override_windows(opts: &FixOptions) -> i32 { - let current = std::env::var("HSA_OVERRIDE_GFX_VERSION").unwrap_or_default(); - if current.is_empty() { - println!("HSA_OVERRIDE_GFX_VERSION is not set in this shell."); - } else { - println!("HSA_OVERRIDE_GFX_VERSION={current} is set in this shell."); - println!("Note: clearing it in your Windows env scope does NOT affect this"); - println!("already-open shell -- close and reopen your terminal afterwards."); - } + let current = std::env::var(OVERRIDE_VAR).unwrap_or_default(); unset_override_windows_with( opts, + ¤t, run_step, |prompt| confirm(prompt, opts.yes), + &mut std::io::stdout(), &mut std::io::stderr(), ) } -/// Reads both env scopes through `run`, then hands over to -/// [`report_and_clear_override_windows`]. +/// Reports `current` (this process's own value of the variable), reads both +/// env scopes through `run`, then hands over to +/// [`report_and_clear_override_windows`]. The lines this runner writes itself +/// go to `out` (and its failure lines to `err`), so a test sees them on every +/// path. Two things still reach the real streams: a child's own output, which +/// `Step::run` relays, and everything `confirm` (which production passes in as +/// `consent`) writes -- its `[y/N]` prompt and answer handling on stdout, and +/// its refusal lines ("Non-interactive shell and --yes not passed; refusing to +/// apply.", "Not confirmed; refusing to apply.") on stderr. /// /// A read that does not complete stops the fix before anything is printed as /// found or offered for clearing: read as "unset", it would report "No /// persistent HSA_OVERRIDE_GFX_VERSION found ... You're done" on a machine /// that still carries the override, which is the one thing this fix is for. +/// That holds under `--dry-run` too: a plan built from a value that was never +/// read would preview a change the real run might not make. fn unset_override_windows_with( opts: &FixOptions, + current: &str, mut run: impl FnMut(&str, &[&str], Duration) -> CommandCapture, consent: impl FnOnce(&str) -> bool, + out: &mut impl Write, err: &mut impl Write, ) -> i32 { + if current.is_empty() { + let _ = writeln!(out, "HSA_OVERRIDE_GFX_VERSION is not set in this shell."); + } else { + let _ = writeln!( + out, + "HSA_OVERRIDE_GFX_VERSION={current} is set in this shell." + ); + let _ = writeln!( + out, + "Note: clearing it in your Windows env scope does NOT affect this" + ); + let _ = writeln!( + out, + "already-open shell -- close and reopen your terminal afterwards." + ); + } let mut values = [String::new(), String::new()]; for (value, scope) in values.iter_mut().zip(["User", "Machine"]) { match ps_env_scope(&mut run, OVERRIDE_VAR, scope) { @@ -248,7 +273,7 @@ fn unset_override_windows_with( } } let [user_val, machine_val] = values; - report_and_clear_override_windows(opts, &user_val, &machine_val, consent, run, err) + report_and_clear_override_windows(opts, &user_val, &machine_val, consent, run, out, err) } /// The variable fix-2 clears. @@ -256,7 +281,7 @@ const OVERRIDE_VAR: &str = "HSA_OVERRIDE_GFX_VERSION"; /// Does the reporting/clearing work for [`run_unset_override_windows`], with /// the User/Machine scope values, the consent prompt, the command runner and -/// the stderr sink taken as parameters rather than read from +/// the stdout and stderr sinks taken as parameters rather than read from /// `ps_env_scope`/`confirm`/`run_step` directly. That's what makes the /// decline and the `setx` failure paths testable without a real Windows /// host -- same reason [`pin_device_in_rc_file`] takes its consent as a @@ -276,36 +301,46 @@ fn report_and_clear_override_windows( machine_val: &str, consent: impl FnOnce(&str) -> bool, mut run: impl FnMut(&str, &[&str], Duration) -> CommandCapture, + out: &mut impl Write, err: &mut impl Write, ) -> i32 { if user_val.is_empty() && machine_val.is_empty() { - println!("\nNo persistent HSA_OVERRIDE_GFX_VERSION found in either the User"); - println!("or Machine env scope. You're done after closing/reopening shells."); + let _ = writeln!( + out, + "\nNo persistent HSA_OVERRIDE_GFX_VERSION found in either the User" + ); + let _ = writeln!( + out, + "or Machine env scope. You're done after closing/reopening shells." + ); return exit::OK; } - println!("\nPersistent HSA_OVERRIDE_GFX_VERSION found in:"); + let _ = writeln!(out, "\nPersistent HSA_OVERRIDE_GFX_VERSION found in:"); if !user_val.is_empty() { - println!(" User scope: {user_val}"); + let _ = writeln!(out, " User scope: {user_val}"); } if !machine_val.is_empty() { - println!(" Machine scope: {machine_val}"); + let _ = writeln!(out, " Machine scope: {machine_val}"); } let mut declined = false; if !user_val.is_empty() { - println!("\nClear from the User scope (no admin needed):"); + let _ = writeln!(out, "\nClear from the User scope (no admin needed):"); // What the CLI runs, not a line to paste: the process is started // directly with these arguments, empty one included. Windows PowerShell // 5.1 drops an empty argument, so pasting the line would not clear - // anything; the plan above carries the line to paste. The text is built - // from the argument list that is run, so the two cannot differ. + // anything; the line to paste is the PowerShell one in the catalog + // entry's `Commands:`, which `act_on` prints before this runner. The + // text is built from the argument list that is run, so the two cannot + // differ. let setx_args = [OVERRIDE_VAR, ""]; let shown: Vec = setx_args.iter().map(|a| format!("\"{a}\"")).collect(); - println!( + let _ = writeln!( + out, " The CLI runs (arguments, not a line to paste): setx {}", shown.join(" ") ); if opts.dry_run { - println!(" (dry-run; not executed)"); + let _ = writeln!(out, " (dry-run; not executed)"); } else if consent("Clear HSA_OVERRIDE_GFX_VERSION from User scope?") { let check = env_scope_query(OVERRIDE_VAR, "User"); let rerun = format!("rocm fix {UNSET_OVERRIDE_ID}"); @@ -315,25 +350,32 @@ fn report_and_clear_override_windows( label: "setx", what: "User-scope HSA_OVERRIDE_GFX_VERSION", check: &check, + check_in: CheckIn::PowerShell, rerun: &rerun, timeout: RUN_TIMEOUT, }; if let Err(code) = step.run(&mut run, err) { return code; } - println!("Cleared from User scope. Reopen your terminal for it to take effect."); + let _ = writeln!( + out, + "Cleared from User scope. Reopen your terminal for it to take effect." + ); } else { declined = true; } } if !machine_val.is_empty() { - println!( + let _ = writeln!( + out, "\nThe Machine scope value cannot be cleared without an Admin shell. Either run an elevated PowerShell and execute:" ); - println!( + let _ = writeln!( + out, " [Environment]::SetEnvironmentVariable('HSA_OVERRIDE_GFX_VERSION', $null, 'Machine')" ); - println!( + let _ = writeln!( + out, "or remove it through System Properties -> Environment Variables -> System variables. This command does NOT elevate itself." ); } @@ -425,7 +467,13 @@ fn run_path_export_windows(opts: &FixOptions) -> i32 { return exit::NOT_APPLICABLE; } let bin_dir = bin_dir.to_string_lossy().into_owned(); - path_export_windows(opts, &bin_dir, run_step, &mut std::io::stderr()) + path_export_windows( + opts, + &bin_dir, + run_step, + &mut std::io::stdout(), + &mut std::io::stderr(), + ) } /// The literal value that will replace User-scope PATH on a non-empty @@ -449,8 +497,8 @@ fn windows_path_prepend(bin_dir: &str, user_path: &str) -> String { } /// Does the read/plan/write work for [`run_path_export_windows`], with the -/// command runner (both the User-scope PATH read and the write) and the stderr -/// sink injected. That's what makes the "read failed" and "write stopped" +/// command runner (both the User-scope PATH read and the write) and the stdout +/// and stderr sinks injected. That's what makes the "read failed" and "write stopped" /// branches testable on any host -- same reason /// [`report_and_clear_override_windows`] takes consent as a closure. /// @@ -465,6 +513,7 @@ fn path_export_windows( opts: &FixOptions, bin_dir: &str, mut run: impl FnMut(&str, &[&str], Duration) -> CommandCapture, + out: &mut impl Write, err: &mut impl Write, ) -> i32 { let user_path = match ps_env_scope(&mut run, "PATH", "User") { @@ -475,7 +524,7 @@ fn path_export_windows( } }; if !user_path.is_empty() && user_path.to_lowercase().contains(&bin_dir.to_lowercase()) { - println!("User PATH already contains {bin_dir}; no change."); + let _ = writeln!(out, "User PATH already contains {bin_dir}; no change."); return exit::OK; } let new_path = windows_path_prepend(bin_dir, &user_path); @@ -485,10 +534,13 @@ fn path_export_windows( // being shared, above) -- see `ps_single_quote_escape`'s doc comment // for why this escape is required at all. let escaped_new_path = ps_single_quote_escape(&new_path); - println!("Plan: prepend {bin_dir} to your User PATH:"); - println!(" [Environment]::SetEnvironmentVariable('PATH', '{escaped_new_path}', 'User')"); + let _ = writeln!(out, "Plan: prepend {bin_dir} to your User PATH:"); + let _ = writeln!( + out, + " [Environment]::SetEnvironmentVariable('PATH', '{escaped_new_path}', 'User')" + ); if opts.dry_run { - println!("(dry-run; not executed)"); + let _ = writeln!(out, "(dry-run; not executed)"); return exit::OK; } if !confirm("Update User PATH?", opts.yes) { @@ -507,13 +559,15 @@ fn path_export_windows( label: "PowerShell", what: "User PATH", check: &check, + check_in: CheckIn::PowerShell, rerun: &rerun, timeout: RUN_TIMEOUT, }; if let Err(code) = step.run(&mut run, err) { return code; } - println!( + let _ = writeln!( + out, "Added {bin_dir} to your User PATH. This only takes effect in NEW shells -- close this terminal and reopen it before re-running hipInfo." ); exit::OK @@ -613,19 +667,28 @@ fn run_hip_visible_devices_windows(opts: &FixOptions) -> i32 { ); return exit::OK; }; - hip_visible_devices_windows(opts, idx, run_step, &mut std::io::stderr()) + hip_visible_devices_windows( + opts, + idx, + run_step, + &mut std::io::stdout(), + &mut std::io::stderr(), + ) } /// Does the read/plan/write work for [`run_hip_visible_devices_windows`] once -/// a device index is known, with the command runner and the stderr sink -/// injected, as [`path_export_windows`] does. +/// a device index is known, with the command runner and the stdout and +/// stderr sinks injected, as [`path_export_windows`] does. /// /// A read that does not complete stops the fix: read as "unset", it would skip /// the guard below and overwrite a User-scope value the user set on purpose. +/// Under `--dry-run` it stops as well, rather than preview a `setx` that the +/// guard might refuse once the read works. fn hip_visible_devices_windows( opts: &FixOptions, idx: i64, mut run: impl FnMut(&str, &[&str], Duration) -> CommandCapture, + out: &mut impl Write, err: &mut impl Write, ) -> i32 { let existing = match ps_env_scope(&mut run, "HIP_VISIBLE_DEVICES", "User") { @@ -636,15 +699,19 @@ fn hip_visible_devices_windows( } }; if !existing.is_empty() { - println!( + let _ = writeln!( + out, "User scope already sets HIP_VISIBLE_DEVICES={existing:?}; remove or update it manually rather than overwriting from this command." ); return exit::OK; } - println!("Plan: persist HIP_VISIBLE_DEVICES in the User env scope:"); - println!(" setx HIP_VISIBLE_DEVICES {idx}"); + let _ = writeln!( + out, + "Plan: persist HIP_VISIBLE_DEVICES in the User env scope:" + ); + let _ = writeln!(out, " setx HIP_VISIBLE_DEVICES {idx}"); if opts.dry_run { - println!("(dry-run; not executed)"); + let _ = writeln!(out, "(dry-run; not executed)"); return exit::OK; } if !confirm("Set HIP_VISIBLE_DEVICES in the User scope?", opts.yes) { @@ -659,13 +726,15 @@ fn hip_visible_devices_windows( label: "setx", what: "User-scope HIP_VISIBLE_DEVICES", check: &check, + check_in: CheckIn::PowerShell, rerun: &rerun, timeout: RUN_TIMEOUT, }; if let Err(code) = step.run(&mut run, err) { return code; } - println!( + let _ = writeln!( + out, "setx only takes effect in NEW shells -- close this terminal and reopen it before re-running your workload." ); exit::OK @@ -675,8 +744,8 @@ fn hip_visible_devices_windows( const POWERSHELL: &str = "powershell"; /// The PowerShell expression that reads `var` from `scope`. Both the read and -/// the "Check with" line of a stopped write use it, so the check a user is -/// told to run is the read this fix itself trusts. +/// the "Check in PowerShell with" line of a stopped write use it, so the +/// check a user is told to run is the read this fix itself trusts. fn env_scope_query(var: &str, scope: &str) -> String { format!("[Environment]::GetEnvironmentVariable('{var}','{scope}')") } @@ -697,19 +766,19 @@ fn ps_env_scope( var: &str, scope: &str, ) -> Result { + // One binding for both the bound the read runs under and the seconds its + // failure line names. `a_read_timeout_names_the_bound_the_read_ran_under` + // pins the bound the read actually runs under. + let timeout = QUERY_TIMEOUT; let script = env_scope_query(var, scope); - let capture = run( - POWERSHELL, - &["-NoProfile", "-Command", &script], - QUERY_TIMEOUT, - ); + let capture = run(POWERSHELL, &["-NoProfile", "-Command", &script], timeout); match capture.outcome { CommandOutcome::Exited(0) => Ok(capture.stdout.trim().to_owned()), outcome => Err(read_failure( &format!("the current {scope} {var}"), "PowerShell", outcome, - QUERY_TIMEOUT, + timeout, )), } } @@ -1071,6 +1140,16 @@ mod tests { .collect() } + /// The timeout each read ran under, in call order. + fn read_timeouts(&self) -> Vec { + self.calls + .borrow() + .iter() + .filter(|(a, _)| is_read(a)) + .map(|(_, t)| *t) + .collect() + } + fn writes(&self) -> Vec> { self.writes_with_timeouts() .into_iter() @@ -1099,8 +1178,9 @@ mod tests { } } - fn text(err: &[u8]) -> String { - String::from_utf8(err.to_vec()).expect("stderr is UTF-8") + /// A captured stdout or stderr sink as text. + fn text(captured: &[u8]) -> String { + String::from_utf8(captured.to_vec()).expect("captured output is UTF-8") } // fix-4 ------------------------------------------------------------ @@ -1186,25 +1266,81 @@ mod tests { // fix-2 (Windows) -------------------------------------------------- + /// Run fix-2's Windows arm against `host` with consent granted; returns + /// the exit code, stdout and stderr. + fn unset_override_with(host: &FakeHost<'_>, opts: &FixOptions) -> (i32, String, String) { + let (mut out, mut err) = (Vec::new(), Vec::new()); + let code = + unset_override_windows_with(opts, "", host.runner(), |_| true, &mut out, &mut err); + (code, text(&out), text(&err)) + } + fn unset_override(host: &FakeHost<'_>) -> (i32, String) { - let mut err = Vec::new(); - let code = unset_override_windows_with(&approved(), host.runner(), |_| true, &mut err); - (code, text(&err)) + let (code, _, err) = unset_override_with(host, &approved()); + (code, err) + } + + /// What fix-2 on Windows prints first when this process does not carry + /// the override (the helpers above pass `""` for it). + const SHELL_UNSET: &str = "HSA_OVERRIDE_GFX_VERSION is not set in this shell.\n"; + + /// What the real command prints on a failed read, with this shell's own + /// value set: the shell-state lines, then nothing about either scope. + #[test] + fn unset_override_failed_read_prints_only_the_shell_state() { + let host = FakeHost::new((CommandOutcome::TimedOut, ""), exited(0)); + let (mut out, mut err) = (Vec::new(), Vec::new()); + let code = unset_override_windows_with( + &approved(), + "10.3.0", + host.runner(), + |_| panic!("a failed read must not reach the consent gate"), + &mut out, + &mut err, + ); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty()); + assert_eq!( + text(&out), + "HSA_OVERRIDE_GFX_VERSION=10.3.0 is set in this shell.\nNote: clearing it in your \ + Windows env scope does NOT affect this\nalready-open shell -- close and reopen your \ + terminal afterwards.\n" + ); + assert!( + text(&err).starts_with("Could not read the current User HSA_OVERRIDE_GFX_VERSION:"), + "{}", + text(&err) + ); } #[test] fn unset_override_clears_a_user_scope_value_and_returns_0() { let host = FakeHost::new((exited(0), "10.3.0\r\n"), exited(0)).with_machine_read(unset()); - let (code, err) = unset_override(&host); + let (code, out, err) = unset_override_with(&host, &approved()); assert_eq!(code, exit::OK); assert_eq!(host.writes(), [vec!["setx", OVERRIDE_VAR, ""]]); assert_eq!(err, ""); + assert!( + out.starts_with(&format!( + "{SHELL_UNSET}\nPersistent HSA_OVERRIDE_GFX_VERSION found in:\n User scope: \ + 10.3.0\n" + )), + "{out}" + ); + assert!( + out.ends_with("Cleared from User scope. Reopen your terminal for it to take effect.\n"), + "{out}" + ); } #[test] fn unset_override_setx_failure_returns_4() { let host = FakeHost::new((exited(0), "10.3.0"), exited(1)).with_machine_read(unset()); - let (code, err) = unset_override(&host); + let (code, out, err) = unset_override_with(&host, &approved()); + assert!( + !out.contains("Cleared"), + "a failed setx is not reported as cleared:\n{out}" + ); assert_eq!(code, exit::FAILED); assert_eq!(host.writes(), [vec!["setx", OVERRIDE_VAR, ""]]); assert_eq!( @@ -1223,7 +1359,7 @@ mod tests { assert_eq!( err, "setx timed out after 60s and was stopped; User-scope HSA_OVERRIDE_GFX_VERSION may or \ - may not have changed. Check with \ + may not have changed. Check in PowerShell with \ `[Environment]::GetEnvironmentVariable('HSA_OVERRIDE_GFX_VERSION','User')`, then \ re-run `rocm fix fix-2-unset-override` if it did not.\n" ); @@ -1250,15 +1386,23 @@ mod tests { fn unset_override_user_read_timeout_stops_before_anything_is_reported_or_cleared() { let host = FakeHost::new((CommandOutcome::TimedOut, ""), exited(0)).with_machine_read(unset()); - let mut err = Vec::new(); + let (mut out, mut err) = (Vec::new(), Vec::new()); let code = unset_override_windows_with( &approved(), + "", host.runner(), |_| panic!("a failed read must not reach the consent gate"), + &mut out, &mut err, ); assert_eq!(code, exit::FAILED); assert!(host.writes().is_empty(), "nothing may be written"); + assert_eq!( + text(&out), + SHELL_UNSET, + "after the shell's own value, nothing is reported as found or absent from a read \ + that failed" + ); assert_eq!( host.calls().len(), 1, @@ -1304,26 +1448,47 @@ mod tests { #[test] fn unset_override_with_both_scopes_genuinely_unset_is_done_without_writing() { let host = FakeHost::new(unset(), exited(0)); - let (code, err) = unset_override(&host); + let (code, out, err) = unset_override_with(&host, &approved()); assert_eq!(code, exit::OK); assert_eq!(host.calls().len(), 2, "both scopes are read"); + assert_eq!( + out, + format!( + "{SHELL_UNSET}\nNo persistent HSA_OVERRIDE_GFX_VERSION found in either the \ + User\nor Machine env scope. You're done after closing/reopening shells.\n" + ) + ); assert!(host.writes().is_empty()); assert_eq!(err, ""); } // fix-6 (Windows) -------------------------------------------------- + /// Run fix-6's Windows arm for `C:\ROCm\bin` against `host`; returns the + /// exit code, stdout and stderr. + fn path_export_with(host: &FakeHost<'_>, opts: &FixOptions) -> (i32, String, String) { + let (mut out, mut err) = (Vec::new(), Vec::new()); + let code = path_export_windows(opts, r"C:\ROCm\bin", host.runner(), &mut out, &mut err); + (code, text(&out), text(&err)) + } + fn path_export(host: &FakeHost<'_>) -> (i32, String) { - let mut err = Vec::new(); - let code = path_export_windows(&approved(), r"C:\ROCm\bin", host.runner(), &mut err); - (code, text(&err)) + let (code, _, err) = path_export_with(host, &approved()); + (code, err) } #[test] fn path_export_success_writes_the_prepended_path_and_returns_0() { let host = FakeHost::new((exited(0), r"C:\Windows"), exited(0)); - let (code, err) = path_export(&host); + let (code, out, err) = path_export_with(&host, &approved()); assert_eq!(code, exit::OK); + assert!( + out.ends_with( + "Added C:\\ROCm\\bin to your User PATH. This only takes effect in NEW shells -- \ + close this terminal and reopen it before re-running hipInfo.\n" + ), + "{out}" + ); let writes = host.writes(); assert_eq!(writes.len(), 1); assert_eq!(writes[0][..3], ["powershell", "-NoProfile", "-Command"]); @@ -1353,7 +1518,8 @@ mod tests { assert_eq!( err, "PowerShell timed out after 60s and was stopped; User PATH may or may not have \ - changed. Check with `[Environment]::GetEnvironmentVariable('PATH','User')`, then \ + changed. Check in PowerShell with \ + `[Environment]::GetEnvironmentVariable('PATH','User')`, then \ re-run `rocm fix fix-6-path` if it did not.\n" ); } @@ -1384,25 +1550,40 @@ mod tests { // fix-9 (Windows) -------------------------------------------------- + /// Run fix-9's Windows arm for device 1 against `host`; returns the exit + /// code, stdout and stderr. + fn pin_device_with(host: &FakeHost<'_>, opts: &FixOptions) -> (i32, String, String) { + let (mut out, mut err) = (Vec::new(), Vec::new()); + let code = hip_visible_devices_windows(opts, 1, host.runner(), &mut out, &mut err); + (code, text(&out), text(&err)) + } + fn pin_device(host: &FakeHost<'_>) -> (i32, String) { - let mut err = Vec::new(); - let code = hip_visible_devices_windows(&approved(), 1, host.runner(), &mut err); - (code, text(&err)) + let (code, _, err) = pin_device_with(host, &approved()); + (code, err) } #[test] fn pin_device_success_runs_setx_and_returns_0() { let host = FakeHost::new(unset(), exited(0)); - let (code, err) = pin_device(&host); + let (code, out, err) = pin_device_with(&host, &approved()); assert_eq!(code, exit::OK); assert_eq!(host.writes(), [vec!["setx", "HIP_VISIBLE_DEVICES", "1"]]); + assert!( + out.ends_with( + "setx only takes effect in NEW shells -- close this terminal and reopen it \ + before re-running your workload.\n" + ), + "{out}" + ); assert_eq!(err, ""); } #[test] fn pin_device_setx_failure_returns_4() { let host = FakeHost::new(unset(), exited(1)); - let (code, err) = pin_device(&host); + let (code, out, err) = pin_device_with(&host, &approved()); + assert!(!out.contains("setx only takes effect"), "{out}"); assert_eq!(code, exit::FAILED); assert_eq!(host.writes().len(), 1); assert_eq!( @@ -1420,7 +1601,7 @@ mod tests { assert_eq!( err, "setx timed out after 60s and was stopped; User-scope HIP_VISIBLE_DEVICES may or may \ - not have changed. Check with \ + not have changed. Check in PowerShell with \ `[Environment]::GetEnvironmentVariable('HIP_VISIBLE_DEVICES','User')`, then re-run \ `rocm fix fix-9-igpu-dgpu --device-index 1` if it did not.\n" ); @@ -1465,14 +1646,164 @@ mod tests { #[test] fn pin_device_leaves_an_existing_user_value_alone() { let host = FakeHost::new((exited(0), "0"), exited(0)); - let (code, _) = pin_device(&host); + let (code, out, _) = pin_device_with(&host, &approved()); assert_eq!(code, exit::OK); + assert_eq!( + out, + "User scope already sets HIP_VISIBLE_DEVICES=\"0\"; remove or update it manually \ + rather than overwriting from this command.\n" + ); assert!( host.writes().is_empty(), "an existing value is not overwritten" ); } + // Reads that exit non-zero, and the bound a read runs under ----------- + + /// A PowerShell read that runs to its end with a failure code is a failed + /// read, not an answer: each read every Windows fix depends on stops the + /// fix with exit 4, no write, and a line naming the exit code. + #[test] + fn a_read_that_exits_non_zero_stops_every_windows_fix_without_writing() { + let failed = (exited(1), ""); + let cases: [(&str, FakeHost<'_>, &str); 4] = [ + ( + "fix-2 User", + FakeHost::new(failed, exited(0)).with_machine_read(unset()), + "User HSA_OVERRIDE_GFX_VERSION", + ), + ( + "fix-2 Machine", + FakeHost::new((exited(0), "10.3.0"), exited(0)).with_machine_read(failed), + "Machine HSA_OVERRIDE_GFX_VERSION", + ), + ("fix-6", FakeHost::new(failed, exited(0)), "User PATH"), + ( + "fix-9", + FakeHost::new(failed, exited(0)), + "User HIP_VISIBLE_DEVICES", + ), + ]; + for (fix, host, subject) in cases { + let (code, out, err) = match fix { + "fix-6" => path_export_with(&host, &approved()), + "fix-9" => pin_device_with(&host, &approved()), + _ => unset_override_with(&host, &approved()), + }; + assert_eq!(code, exit::FAILED, "{fix}"); + assert!(host.writes().is_empty(), "{fix} must not write"); + let expected = if fix.starts_with("fix-2") { + SHELL_UNSET + } else { + "" + }; + assert_eq!( + out, expected, + "{fix} reports nothing from a read that failed" + ); + assert_eq!( + err, + format!( + "Could not read the current {subject}: PowerShell exited 1; nothing was \ + changed.\n" + ), + "{fix}" + ); + } + } + + /// The bound a read runs under and the seconds its timeout line names are + /// one value: every read runs under `QUERY_TIMEOUT`, and the line names + /// the bound that read actually ran under. + #[test] + fn a_read_timeout_names_the_bound_the_read_ran_under() { + let host = FakeHost::new((CommandOutcome::TimedOut, ""), exited(0)); + let (code, err) = pin_device(&host); + assert_eq!(code, exit::FAILED); + let ran_under = host.read_timeouts(); + assert_eq!(ran_under, [QUERY_TIMEOUT], "one read, under QUERY_TIMEOUT"); + assert!( + err.contains(&format!( + "PowerShell timed out after {}s and was stopped", + ran_under[0].as_secs() + )), + "{err}" + ); + } + + // --dry-run against the Windows reads ----------------------------------- + + fn dry_run() -> FixOptions { + FixOptions { + dry_run: true, + ..approved() + } + } + + /// A dry run with a readable scope prints the plan and changes nothing, + /// even with `--yes`: the read runs, `setx` does not. + #[test] + fn pin_device_dry_run_prints_the_plan_and_runs_no_setx() { + let host = FakeHost::new(unset(), exited(0)); + let (code, out, err) = pin_device_with(&host, &dry_run()); + assert_eq!(code, exit::OK); + assert_eq!(host.calls().len(), 1, "only the read runs"); + assert!(host.writes().is_empty(), "a dry run runs no setx"); + assert_eq!( + out, + "Plan: persist HIP_VISIBLE_DEVICES in the User env scope:\n setx \ + HIP_VISIBLE_DEVICES 1\n(dry-run; not executed)\n" + ); + assert_eq!(err, ""); + } + + /// A dry run whose read fails stops like a real run: exit 4, no plan, no + /// write. A plan built on a value that was never read could preview a + /// `setx` the guard would refuse. + #[test] + fn pin_device_dry_run_with_a_failed_read_stops_without_a_plan() { + let host = FakeHost::new((CommandOutcome::TimedOut, ""), exited(0)); + let (code, out, err) = pin_device_with(&host, &dry_run()); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty()); + assert_eq!(out, "", "no plan is printed"); + assert!( + err.starts_with("Could not read the current User HIP_VISIBLE_DEVICES"), + "{err}" + ); + } + + #[test] + fn unset_override_dry_run_prints_the_plan_and_runs_no_setx() { + let host = FakeHost::new((exited(0), "10.3.0"), exited(0)).with_machine_read(unset()); + let (code, out, err) = unset_override_with(&host, &dry_run()); + assert_eq!(code, exit::OK); + assert_eq!(host.calls().len(), 2, "only the two reads run"); + assert!(host.writes().is_empty(), "a dry run runs no setx"); + assert!( + out.contains( + "The CLI runs (arguments, not a line to paste): setx \ + \"HSA_OVERRIDE_GFX_VERSION\" \"\"\n (dry-run; not executed)\n" + ), + "{out}" + ); + assert_eq!(err, ""); + } + + #[test] + fn unset_override_dry_run_with_a_failed_read_stops_without_a_plan() { + let host = FakeHost::new((CommandOutcome::NotFound, ""), exited(0)); + let (code, out, err) = unset_override_with(&host, &dry_run()); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty()); + assert_eq!(out, SHELL_UNSET, "no plan is printed"); + assert!( + err.starts_with("Could not read the current User HSA_OVERRIDE_GFX_VERSION"), + "{err}" + ); + } + /// Every "re-run `rocm fix `" line names a recipe that exists and has /// a runner, so the recovery it advises can actually be carried out. #[test] @@ -1499,6 +1830,7 @@ mod tests { |_| false, host.runner(), &mut Vec::new(), + &mut Vec::new(), ); assert_eq!(code, 5, "a declined User-scope clear must exit 5, not 0"); @@ -1509,23 +1841,36 @@ mod tests { /// a user with both scopes set still needs the elevated-shell /// instructions printed, so the decline can't `return 5` on the spot -- /// it has to fall through and let the Machine-scope block run first. - /// This test can't see stdout, but it pins the return code so a future - /// change that reintroduces an early `return 5` (skipping that block) - /// would have to change this assertion to keep passing. + /// Asserted on the captured stdout together with the exit code, so an + /// early `return 5` that skips the block fails here. #[test] fn windows_decline_with_machine_scope_also_set_still_returns_5() { let host = FakeHost::new(unset(), exited(0)); + let mut out = Vec::new(); let code = report_and_clear_override_windows( &FixOptions::default(), "10.3.0", "11.0.0", |_| false, host.runner(), + &mut out, &mut Vec::new(), ); assert_eq!(code, 5); assert!(host.writes().is_empty(), "a decline must not run setx"); + let out = text(&out); + assert!(out.contains(" Machine scope: 11.0.0\n"), "{out}"); + assert!( + out.ends_with( + "\nThe Machine scope value cannot be cleared without an Admin shell. Either run \ + an elevated PowerShell and execute:\n \ + [Environment]::SetEnvironmentVariable('HSA_OVERRIDE_GFX_VERSION', $null, \ + 'Machine')\nor remove it through System Properties -> Environment Variables -> \ + System variables. This command does NOT elevate itself.\n" + ), + "the elevated-shell guidance must still be printed after a decline:\n{out}" + ); } #[test] @@ -1538,6 +1883,7 @@ mod tests { |_| true, host.runner(), &mut Vec::new(), + &mut Vec::new(), ); assert_eq!( @@ -1562,6 +1908,7 @@ mod tests { |_| panic!("dry-run must not reach the consent gate"), host.runner(), &mut Vec::new(), + &mut Vec::new(), ); assert!(host.calls().is_empty(), "a dry-run runs nothing"); @@ -1571,15 +1918,18 @@ mod tests { #[test] fn windows_nothing_persisted_in_either_scope_returns_0_without_prompting() { let host = FakeHost::new(unset(), exited(0)); + let mut out = Vec::new(); let code = report_and_clear_override_windows( &FixOptions::default(), "", "", |_| panic!("nothing to clear means no consent gate at all"), host.runner(), + &mut out, &mut Vec::new(), ); assert!(host.calls().is_empty(), "nothing to clear runs nothing"); + assert!(text(&out).contains("You're done"), "{}", text(&out)); assert_eq!(code, 0); } @@ -1604,17 +1954,19 @@ mod tests { // The read itself failed (PowerShell missing/blocked/timed out). let host = FakeHost::new((CommandOutcome::NotFound, ""), exited(0)); - let code = path_export_windows(&opts, r"C:\ROCm\bin", host.runner(), &mut Vec::new()); + let (code, out, err) = path_export_with(&host, &opts); - assert_ne!( - code, 0, + assert_eq!( + code, + exit::FAILED, "a failed read must not be silently absorbed by the dry-run preview" ); - assert_ne!( - code, 5, - "a failed read was never offered a prompt to decline" - ); assert!(host.writes().is_empty(), "a failed read writes nothing"); + assert_eq!(out, "", "no plan is printed from a read that failed"); + assert!( + err.starts_with("Could not read the current User PATH: "), + "{err}" + ); } /// A genuinely empty User PATH (the read succeeded and returned `""`, @@ -1717,11 +2069,10 @@ mod tests { let bin_dir = r"C:\ROCm\bin"; let existing = format!(r"C:\Windows;{bin_dir}"); let host = FakeHost::new((CommandOutcome::Exited(0), &existing), exited(0)); - let code = path_export_windows( - &FixOptions::default(), - bin_dir, - host.runner(), - &mut Vec::new(), + let (code, out, _) = path_export_with(&host, &FixOptions::default()); + assert_eq!( + out, + format!("User PATH already contains {bin_dir}; no change.\n") ); assert_eq!( @@ -1741,9 +2092,17 @@ mod tests { ..FixOptions::default() }; - let host = FakeHost::new(unset(), exited(0)); - let code = path_export_windows(&opts, r"C:\ROCm\bin", host.runner(), &mut Vec::new()); + let host = FakeHost::new((exited(0), r"C:\Windows"), exited(0)); + let (code, out, err) = path_export_with(&host, &opts); assert!(host.writes().is_empty(), "a dry-run writes nothing"); + assert_eq!(host.calls().len(), 1, "only the read runs"); + assert_eq!( + out, + "Plan: prepend C:\\ROCm\\bin to your User PATH:\n \ + [Environment]::SetEnvironmentVariable('PATH', 'C:\\ROCm\\bin;C:\\Windows', 'User')\n\ + (dry-run; not executed)\n" + ); + assert_eq!(err, ""); assert_eq!(code, 0, "a dry-run preview is not a decline"); } diff --git a/docs/architecture.md b/docs/architecture.md index c947b1e111..0228c845a7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -303,7 +303,7 @@ The library every first-party app and engine crate depends on. It holds host exa | [`fake_executable.rs`](../crates/rocm-core/src/fake_executable.rs) | `write_fake_executable`: writes a stand-in script for tests from a short-lived child, so running it does not fail with `ETXTBSY`. It is built into every build, without a `cfg(test)` gate, so dependent crates' tests can call it. | flat | | [`fix.rs`](../crates/rocm-core/src/fix.rs) | Root of `rocm fix`: the dispatch (`apply`) that plans, confirms and runs a catalog remediation, and the re-exports of its children's public names. | flat | | [`fix/catalog.rs`](../crates/rocm-core/src/fix/catalog.rs) | The closed remediation catalog: `FixRecipe`, the per-platform class table, `RECIPES`, the lookups by fix-id, and the test-only oracles. | flat | -| [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs) | The consent decision and `confirm`, the timeouts the runners use, `current_os`, output helpers that cannot panic on a closed pipe, and `run_step`/`Step`, which run a runner's host command on the bounded executor and turn how it ended (exit code, not started, timed out) into the one stderr line and exit code the runner reports. | flat | +| [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs) | The consent decision and `confirm`, the timeouts the runners use, `current_os`, output helpers that cannot panic on a closed pipe, and `run_step`/`Step`, which run a runner's host command on the bounded executor and turn how it ended (exit code, not started, timed out) into the one stderr line and exit code the runner reports, with `CheckIn` saying whether its check command runs in any shell or in PowerShell. | flat | | [`fix/manifest.rs`](../crates/rocm-core/src/fix/manifest.rs) | The JSON catalog manifest `rocm fix --json` publishes, derived from `RECIPES` on every call. | flat | | [`fix/options.rs`](../crates/rocm-core/src/fix/options.rs) | The vocabulary of `rocm fix`: the exit codes (`exit`), `FixOptions` and `FixClass`. | flat | | [`fix/render.rs`](../crates/rocm-core/src/fix/render.rs) | Rendering the catalog for people: the listing, a recipe's plan and verify lines, the flag summary `rocm diagnose` shares, and the refusal of a diagnosis position as a fix-id. | flat | @@ -825,7 +825,7 @@ Gherkin `.feature` files under `features/` backed by Rust step functions that dr | File | Responsibility | Class | | --- | --- | --- | | [`tests/driver_host_guard.rs`](../tests/e2e-cucumber/tests/driver_host_guard.rs) | Ordinary test that the Windows driver-install steps run the host guard before calling the CLI, checked against the step source. | flat | -| [`tests/e2e.rs`](../tests/e2e-cucumber/tests/e2e.rs) | The cucumber test binary: the `E2eWorld` state and its cleanup on drop, the `run_rocm` helpers, the runner `main`, and reconciliation of results with expectations. | flat | +| [`tests/e2e.rs`](../tests/e2e-cucumber/tests/e2e.rs) | The cucumber test binary: the `E2eWorld` state and its cleanup on drop, the `run_rocm` helpers (including `run_rocm_with_scenario_env_off_executor`, which waits for a long CLI run on a blocking thread so it does not stall concurrent scenarios), the runner `main`, and reconciliation of results with expectations. | flat | | [`tests/feature_naming.rs`](../tests/e2e-cucumber/tests/feature_naming.rs) | Drift guard, in the ordinary `cargo test` set, for the `-` scenario names and ids in the `.feature` files. | flat | | [`tests/skill_reference.rs`](../tests/e2e-cucumber/tests/skill_reference.rs) | Drift guard, in the ordinary `cargo test` set, that the catalog table in [`reference.md`](../skills/rocm-doctor/reference.md) uses the vocabulary `rocm fix` prints. | flat | diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 2394e3f87c..26a0676e8f 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -1713,7 +1713,9 @@ only and start `rocm.exe` by its full path: $rocm = (Get-Command rocm).Source $env:Path = '' & $rocm fix fix-2-unset-override --yes; "exit $LASTEXITCODE" -& $rocm fix fix-9-igpu-dgpu --device-index 1 --yes; "exit $LASTEXITCODE" +& $rocm fix fix-9-igpu-dgpu --device-index 1 --dry-run; "exit $LASTEXITCODE" +& $rocm fix fix-2-unset-override --dry-run; "exit $LASTEXITCODE" +& $rocm fix fix-6-path --dry-run; "exit $LASTEXITCODE" ``` Expected result: @@ -1722,6 +1724,16 @@ Expected result: PowerShell could not be started: it was not found; nothing was changed.` on stderr and exits 4. It does not print `No persistent HSA_OVERRIDE_GFX_VERSION found` or `You're done`. -- fix-9 prints the same line for `HIP_VISIBLE_DEVICES`, exits 4, and prints no - `Plan: persist HIP_VISIBLE_DEVICES` line; the User-scope value is unchanged. +- fix-9, a dry run here, prints the same line for `HIP_VISIBLE_DEVICES`, exits + 4, and prints no `Plan: persist HIP_VISIBLE_DEVICES` line (the catalog entry + that starts `Fix:` is still printed before it). It is run as a dry + run because the empty `PATH` hides PowerShell but not `setx.exe`: a fix-9 that + wrongly went on would set your real User-scope value. +- The fix-2 dry run stops the same way: exit 4 and the read-failure line, after + the catalog entry, with no `The CLI runs (arguments, not a line to paste)` + line. +- fix-6 (needs a HIP SDK install; without one it exits 3 before reading) + prints `Could not read the current User PATH: PowerShell + could not be started: it was not found; nothing was changed.`, exits 4, and + prints no `Plan: prepend` line. - Close the window afterwards; the empty `PATH` was only that window's. diff --git a/docs/testing.md b/docs/testing.md index a6d6898d9c..f1c0b9fd06 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -2923,8 +2923,8 @@ line on stderr, built from how the command ended | How the command ended | What the line says | |---|---| | exited non-zero, or could not be started | it exited `N` (or could not be started), and the change was NOT made | -| timed out (60s for a change), or was stopped by a signal or a failed wait | it was stopped, the change may or may not have been made, a command to check it, and the `rocm fix` command to re-run | -| a Windows read of the current value did not complete (8s) | it could not read the current value, and nothing was changed; the fix stops before any plan or prompt | +| timed out (60s for a change), or was stopped by a signal or a failed wait | it was stopped, the change may or may not have been made, how to check it (`Check with` a shell command on Linux, `Check in PowerShell with` an expression on Windows), and the `rocm fix` command to re-run | +| a Windows read of the current value did not complete (8s) | it could not read the current value, and nothing was changed; the runner stops before its preview of the change or any prompt, under `--dry-run` too; the catalog entry printed before it still appears | Each row for each runner is unit-tested with an injected command runner in [fix/runners.rs](../crates/rocm-core/src/fix/runners.rs) and @@ -2934,16 +2934,41 @@ run the real binary: `diagnose-15` (fix-4's helper exits 1) and `diagnose-62` (it never finishes) stand a fake `sudo` on a restricted `PATH` that records the arguments it was given, and assert the line together with the exit code, that the helper was asked to add the user to the groups, and that the success line is -absent. `diagnose-62` waits out the real one-minute bound; there is no switch to -shorten it. Both are `@requires-os:linux @requires-bare-metal`. On Windows, -`diagnose-39` (fix-6), `diagnose-63` (fix-2) and `diagnose-64` (fix-9 with -`--device-index 1`) give the CLI an empty `PATH`, so its PowerShell read cannot -start, and assert exit 4, the read-failure line, and that the fix printed no plan -and did not report the variable as absent. They run on the Windows lanes only; -the Linux lanes compile them. No scenario times out a Windows `setx` or -PowerShell write: those rows are covered by the unit tests. To run the two -Linux scenarios on a bare-metal Linux host (`-n` skips the tag gates, so on WSL2 -they fail at the platform refusal instead): +absent. Both are `@requires-os:linux @requires-bare-metal`. `diagnose-62` +waits out the real one-minute bound; there is no switch to shorten it. The step +waits for the CLI on a blocking thread (`run_rocm_with_scenario_env_off_executor` +in [e2e.rs](../tests/e2e-cucumber/tests/e2e.rs)): the whole suite is polled on +one thread, so a synchronous wait would stall every concurrent scenario for that +minute and push the TUI scenarios past their wall-clock caps. + +On Windows, `diagnose-39` (fix-6), `diagnose-63` (fix-2) and `diagnose-64` +(fix-9 with `--device-index 1`, run as a `--dry-run`) give the CLI an empty +`PATH`, so its PowerShell read cannot start. They assert exit 4 and the +read-failure line, and that the runner went no further: no `Plan: ...` preview +of the change for fix-6 and fix-9, and no report that fix-2's variable is +absent. The catalog entry `rocm fix` prints before the runner still appears. The +empty `PATH` denies PowerShell only: Rust's `Command` looks for a bare program +name in the CLI's own directory, System32 and the Windows directory before +`PATH`, so `setx.exe` (in System32) is still found, while `powershell.exe` (in a +System32 subdirectory) is not. None of the three can write the runner's real +User environment even if the read guard regressed: fix-6 writes through +PowerShell, which cannot start; fix-2 would read both scopes as unset and find +nothing to clear, so it never reaches its `setx`; and `diagnose-64` is a dry +run, which never runs `setx`. The fix-9 path that does write is held by the unit +tests. These three run only on the self-hosted Strix Halo Windows lanes, neither +of which is a required check: `E2E tests (Strix Halo, Windows, )` +(`e2e-gpu-strix-windows` in +[e2e-selfhosted.yml](../.github/workflows/e2e-selfhosted.yml), on a pull request +that touches its `serve` paths, on pushes and in the merge queue) and `E2E tests +(Strix Halo, Windows, incl. nightly-only)` (`e2e-gpu-nightly-strix-windows` in +[nightly.yml](../.github/workflows/nightly.yml)). The required hosted Windows +lane (`windows-release` in [ci.yml](../.github/workflows/ci.yml), behind +`windows-build-and-test`) runs only `@lifecycle` scenarios and the ids in its +`E2E_ALSO_RUN_IDS`, which do not include them. The Linux lanes compile them. No +scenario times out a Windows `setx` or PowerShell write: those rows are covered +by the unit tests. To run the two Linux scenarios on a bare-metal Linux host +(`-n` skips the tag gates, so on WSL2 they fail at the platform refusal +instead): ```bash cargo xtask e2e -- -n '(diagnose-15|diagnose-62) ' diff --git a/skills/rocm-doctor/SKILL.md b/skills/rocm-doctor/SKILL.md index 41fe6766c4..314464a405 100644 --- a/skills/rocm-doctor/SKILL.md +++ b/skills/rocm-doctor/SKILL.md @@ -231,7 +231,7 @@ passes — the GPU is AMD or no vendor was named. ``` rocm fix # prompts before changing anything - rocm fix --dry-run # show the exact change, touch nothing + rocm fix --dry-run # show the exact change, touch nothing (see the Windows exit 4 below) rocm fix --yes # required to apply in a non-interactive shell ``` @@ -260,11 +260,24 @@ passes — the GPU is AMD or no vendor was named. pinned. Once the user knows N, re-run with `rocm fix fix-9-igpu-dgpu --device-index N`. - If `rocm fix` exits 4, the command it ran failed or did not finish in time. - Relay its stderr line. After a timeout that line says the change may or may - not have been made, and names a command to check it and the `rocm fix` - command to re-run; do not tell the user the fix was applied, or that nothing - changed, until that check has been run. + If `rocm fix` exits 4, relay its stderr line and act on how it ends: + + - `Could not read the current …; nothing was changed.` — on Windows, + `fix-2-unset-override`, `fix-6-path` and `fix-9-igpu-dgpu --device-index N` + read the variable they change before planning, and that read failed + (`--dry-run` included). Tell the user nothing was changed and relay the + cause the line states; once it is cleared (for example PowerShell starts + and answers in time), offer to re-run the same `rocm fix` command. Do not + present the printed catalog entry as a preview, and do not hand the user + its commands (such as `setx HIP_VISIBLE_DEVICES `) instead. + - `… NOT changed.` — the command ran and failed, or could not start. + Nothing was changed. + - `… may or may not have changed. Check … then re-run …` — the command + timed out or was killed. Relay the check (on Windows, an expression to run + in PowerShell) and the `rocm fix` command to re-run; claim neither that + the fix was applied nor that nothing changed until the check has run. + - `Failed to write : …` — the rc-file append failed; have the user + look at that file. 4. **Verify.** Have the user run the `verify` command from the diagnosis. @@ -323,7 +336,8 @@ start of the reply, before relaying a multi-step plan. - Never invent a fix. If `rocm diagnose` returns no match, route upstream. - Never run a mutating fix without the user's explicit OK; prefer `--dry-run` - first. New failure modes are added to the CLI catalog, not improvised here. + first (on Windows that dry run can itself exit 4 when its read fails; see + step 3). New failure modes are added to the CLI catalog, not improvised here. Read [reference.md](reference.md) when `rocm fix` exits non-zero (its exit codes are listed there), before telling the user which platforms a fix id applies to, diff --git a/skills/rocm-doctor/reference.md b/skills/rocm-doctor/reference.md index 4c17395055..e1e3dad479 100644 --- a/skills/rocm-doctor/reference.md +++ b/skills/rocm-doctor/reference.md @@ -101,11 +101,11 @@ id is refused, and the refusal exits 1 (see the table). Exit codes: | code | meaning | | --- | --- | -| 0 | applied / dry-run / print-only plan / list | +| 0 | applied / dry-run (except the Windows read failure under 4) / print-only plan / list | | 1 | internal error; also the refusal of `--json` together with a fix id | | 2 | usage error (incl. unknown fix-id) | | 3 | not applicable on this host (OS mismatch, negative `--device-index`) — nothing changed | -| 4 | attempted but the command failed or timed out; after a timeout the change may be partial — the message names how to check it and what to re-run | +| 4 | attempted but the command failed or timed out; after a timeout the change may be partial — the message names how to check it and what to re-run. Also, on Windows only, `fix-2-unset-override`, `fix-6-path` or `fix-9-igpu-dgpu --device-index N` when it could not read the current value of the variable it changes, `--dry-run` included — nothing changed and no plan shown; the catalog entry printed first is the fix's generic description, not a preview of the change on this machine | | 5 | user declined at the prompt | Three ids are ever auto-applicable — never four, and `fix-9-igpu-dgpu` is not @@ -134,8 +134,10 @@ a promise that the runner mutates anything, and — per the per-host list above not the same claim on Windows or WSL2 for the one entry whose behaviour depends on more than the host alone. -The ones that do mutate print the exact command, honor `--dry-run`, refuse on a -non-interactive shell without `--yes`, and confirm first. **Two exceptions:** +The ones that do mutate print the exact command, honor `--dry-run` (on +Windows a dry run whose read fails exits 4 with no plan; see 4 in the exit-code +table), refuse on a non-interactive shell without `--yes`, and confirm first. +**Two exceptions:** - **`fix-2-unset-override` mutates on Windows only.** Its Linux runner reports where the override is set and which rc files carry it, then stops — it will diff --git a/tests/e2e-cucumber/features/diagnose.feature b/tests/e2e-cucumber/features/diagnose.feature index 5a6bd0274c..95282e068d 100644 --- a/tests/e2e-cucumber/features/diagnose.feature +++ b/tests/e2e-cucumber/features/diagnose.feature @@ -942,6 +942,9 @@ Feature: Diagnosing failures and listing fixes # nothing in the Machine scope either, fix-2 printed that no persistent # override was found and the user was done, and exited 0, on a machine that # may still carry it. Same real "PowerShell missing" cause as diagnose-39. + # Applied for real: should the guard regress, both reads would read as unset + # and fix-2 would find nothing to clear, so the runner's User environment is + # never written. @id:diagnose-fix-override-aborts-on-unreadable-user-scope @requires-os:windows Scenario: diagnose-63 - Clearing the GPU override stops when the saved value cannot be read, instead of calling it gone Given a Windows host where PowerShell cannot be found @@ -951,11 +954,20 @@ Feature: Diagnosing failures and listing fixes And the CLI does not report the override as already gone # The same failed read made fix-9 skip its "already set" guard and overwrite - # a User-scope device setting the user may have chosen on purpose. + # a User-scope device setting the user may have chosen on purpose. Previewed + # rather than applied: the empty PATH hides PowerShell but not setx.exe, so + # an applied fix-9 whose guard regressed would set HIP_VISIBLE_DEVICES on the + # runner itself, with nothing to restore it. The preview reads the setting + # before planning, the same way the apply does, and a preview never runs + # setx. So this holds the stop and what the preview prints: the catalog entry + # still appears, the change it would make does not. That an applied fix-9 + # writes nothing after a failed read is held by the unit tests in + # fix/runners.rs (`pin_device_read_timeout_stops_before_setx`, + # `a_read_that_exits_non_zero_stops_every_windows_fix_without_writing`). @id:diagnose-fix-igpu-aborts-on-unreadable-user-scope @requires-os:windows - Scenario: diagnose-64 - Pinning the discrete GPU stops when the saved device setting cannot be read, before planning a write + Scenario: diagnose-64 - A dry run of the discrete-GPU pin that cannot read the saved device setting stops with exit code 4 and previews no change Given a Windows host where PowerShell cannot be found And a user who has chosen the fix that hides the integrated GPU - When the user asks the CLI to apply the approved fix to the second GPU + When the user previews that fix for the second GPU Then the CLI stops with exit code 4, saying it could not read the saved device setting and that nothing was changed - And no plan to save a device setting is printed + And the fix's catalog entry is printed, but not the device setting it would save diff --git a/tests/e2e-cucumber/tests/e2e.rs b/tests/e2e-cucumber/tests/e2e.rs index 296bb51ef5..e77de20e16 100644 --- a/tests/e2e-cucumber/tests/e2e.rs +++ b/tests/e2e-cucumber/tests/e2e.rs @@ -1112,6 +1112,37 @@ pub fn run_rocm_without_data_dir_override( /// Run `rocm` with the behavioral fixture established by a Given step, then /// consume it so it cannot leak into a later action in the same scenario. pub fn run_rocm_with_scenario_env(world: &mut E2eWorld, args: &[&str]) -> (String, String, i32) { + let (mut cmd, binary) = scenario_command(world, args); + let output = cmd + .output() + .unwrap_or_else(|e| panic!("failed to run {binary}: {e}")); + scenario_command_result(world, args, &output) +} + +/// [`run_rocm_with_scenario_env`] for a run that may take long, waited for on +/// a blocking thread instead of the one the whole suite is polled on. +/// +/// The cucumber run is one future under `block_on` (see `main`), so a +/// synchronous wait inside a step stops every other concurrent scenario for as +/// long as it lasts. A fix that waits out its one-minute timeout (diagnose-62) +/// stalled the TUI scenarios running beside it past their own wall-clock caps +/// ("the harness left this step unpolled"). The same reason +/// `probe_device_memory` in `serving_steps.rs` runs on `spawn_blocking`. +pub async fn run_rocm_with_scenario_env_off_executor( + world: &mut E2eWorld, + args: &[&str], +) -> (String, String, i32) { + let (mut cmd, binary) = scenario_command(world, args); + let output = tokio::task::spawn_blocking(move || cmd.output()) + .await + .unwrap_or_else(|e| panic!("the thread running {binary} failed: {e}")) + .unwrap_or_else(|e| panic!("failed to run {binary}: {e}")); + scenario_command_result(world, args, &output) +} + +/// The `rocm` command [`run_rocm_with_scenario_env`] runs, with the scenario's +/// fixture moved into it, and the binary's name for messages. +fn scenario_command(world: &mut E2eWorld, args: &[&str]) -> (std::process::Command, String) { let binary = rocm_binary(); // A binary given as a relative path was meant relative to this process's // directory, not to the scenario's, so it is made absolute before the child @@ -1133,9 +1164,16 @@ pub fn run_rocm_with_scenario_env(world: &mut E2eWorld, args: &[&str]) -> (Strin if let Some(dir) = world.command_dir.take() { cmd.current_dir(dir); } - let output = cmd - .output() - .unwrap_or_else(|e| panic!("failed to run {binary}: {e}")); + (cmd, binary) +} + +/// `(stdout, stderr, rc)` of a finished scenario command, recorded for the +/// command-coverage report. +fn scenario_command_result( + world: &E2eWorld, + args: &[&str], + output: &std::process::Output, +) -> (String, String, i32) { let rc = output.status.code().unwrap_or(-1); let stdout = String::from_utf8_lossy(&output.stdout).to_string(); record_command(world.current_scenario.as_deref(), args, rc, &stdout); diff --git a/tests/e2e-cucumber/tests/e2e/diagnose_steps.rs b/tests/e2e-cucumber/tests/e2e/diagnose_steps.rs index bd295e1700..7c5df45b8f 100644 --- a/tests/e2e-cucumber/tests/e2e/diagnose_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/diagnose_steps.rs @@ -633,15 +633,25 @@ async fn user_chose_igpu_fix(world: &mut E2eWorld) { } /// Gives the CLI an empty `PATH`, so its own PowerShell reads cannot start. +/// +/// It denies PowerShell only. The CLI starts both programs by bare name, and +/// on Windows Rust's `Command` looks for a bare name in the CLI's own +/// directory, then the system directory (System32), then the Windows +/// directory, and only then in the CLI's `PATH` (empty here). `setx.exe` is in +/// System32, so it is still found; `powershell.exe` is in a subdirectory of +/// System32 that only `PATH` reaches, so it is not. What keeps each +/// scenario off the runner's real User environment, should the read guard +/// regress, is the scenario's own: fix-6 (diagnose-39) writes through +/// PowerShell, which cannot start; fix-2 (diagnose-63) would read both scopes +/// as unset and find nothing to clear; fix-9 (diagnose-64) is only previewed. fn deny_powershell(world: &mut E2eWorld) { // An empty child PATH means the CLI's own `Command::new("powershell")` // cannot resolve the binary at all -- `powershell.exe` lives under // `System32\WindowsPowerShell\v1.0`, which Windows does NOT search // unconditionally the way it does System32 itself, so this is a real // instance of the "PowerShell missing" cause `ps_env_scope`'s doc comment - // names, not a faked one. Every fix that reads a User-scope value stops - // at that read, so nothing on the real machine is touched and no - // capture/restore is needed. + // names, not a faked one. No capture/restore is needed: see above for why + // none of the three scenarios can write the real User environment. world.command_env.push(("PATH", std::ffi::OsString::new())); } @@ -733,17 +743,25 @@ async fn user_applies_fix_without_agreeing(world: &mut E2eWorld) { #[when("the user asks the CLI to apply the approved fix")] async fn user_applies_approved_fix(world: &mut E2eWorld) { let fix_id = world.model_name.clone().expect("no fix id set"); - let (stdout, stderr, rc) = crate::run_rocm_with_scenario_env(world, &["fix", &fix_id, "--yes"]); + // Off the executor: in diagnose-62 the fix waits out its one-minute + // timeout, which would otherwise stall every concurrent scenario. + let (stdout, stderr, rc) = + crate::run_rocm_with_scenario_env_off_executor(world, &["fix", &fix_id, "--yes"]).await; world.cli_output = Some(stdout); world.cli_stderr = Some(stderr); world.cli_rc = Some(rc); } -#[when("the user asks the CLI to apply the approved fix to the second GPU")] -async fn user_applies_approved_fix_to_second_gpu(world: &mut E2eWorld) { +#[when("the user previews that fix for the second GPU")] +async fn user_previews_fix_for_second_gpu(world: &mut E2eWorld) { let fix_id = world.model_name.clone().expect("no fix id set"); - let (stdout, stderr, rc) = - crate::run_rocm_with_scenario_env(world, &["fix", &fix_id, "--device-index", "1", "--yes"]); + // `--dry-run` and no `--yes`: even a fix that wrongly went past its read + // would stop at the preview, and failing that, at the consent gate (stdin + // is piped), before running `setx` on the runner. + let (stdout, stderr, rc) = crate::run_rocm_with_scenario_env( + world, + &["fix", &fix_id, "--device-index", "1", "--dry-run"], + ); world.cli_output = Some(stdout); world.cli_stderr = Some(stderr); world.cli_rc = Some(rc); @@ -1918,19 +1936,33 @@ async fn assert_override_not_reported_gone(world: &mut E2eWorld) { "the CLI stops with exit code 4, saying it could not read the saved device setting and that nothing was changed" )] async fn assert_igpu_fix_aborts_on_unreadable_scope(world: &mut E2eWorld) { - assert_read_failure_stops_the_fix( - world, - "HIP_VISIBLE_DEVICES", - &["setx only takes effect in NEW shells"], - ); + // Nothing after the read is listed here: this is a dry run, so the lines a + // fix that went on would print are the preview, which the next step checks. + assert_read_failure_stops_the_fix(world, "HIP_VISIBLE_DEVICES", &[]); } -#[then("no plan to save a device setting is printed")] +#[then("the fix's catalog entry is printed, but not the device setting it would save")] async fn assert_no_device_setting_plan(world: &mut E2eWorld) { let stdout = world.cli_output.as_deref().unwrap_or(""); + // `rocm fix` prints the catalog entry before the runner reads anything, + // so a stopped dry run still shows it; the docs say exactly that. The + // `Fix:` line is the one `print_recipe` opens the entry with. + let fix_id = world.model_name.as_deref().expect("no fix id set"); + assert!( + stdout + .lines() + .any(|line| line.starts_with("Fix:") && line.contains(fix_id)), + "the catalog entry for {fix_id} must still be printed on stdout:\n{stdout}" + ); + // The runner's own preview, whatever its heading says: the concrete + // `setx` for the index the When step passed and the dry-run marker. The + // catalog entry's `Commands:` lists `setx HIP_VISIBLE_DEVICES `, + // a template, so only the concrete index is forbidden. for line in [ "Plan: persist HIP_VISIBLE_DEVICES", "already sets HIP_VISIBLE_DEVICES", + "setx HIP_VISIBLE_DEVICES 1", + "(dry-run; not executed)", ] { assert!( !stdout.contains(line), From 106213f2d34a8a52aa6f6f991e4c447df64b327b Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Fri, 13 Nov 2026 14:03:01 +0200 Subject: [PATCH 3/8] docs(architecture): say the Windows fix runners read before planning (ROCMAI-345) The runners.rs entry promised only print, dry-run and consent. On Windows fix-2, fix-6 and fix-9 now read the current env-scope value first and stop with exit 4, before the runner's own preview or any prompt, when that read fails, dry-run included; the entry should say so. "Consent first" becomes "consent before any write", and the report-only arms (fix-2 on Linux, fix-9 without a device index) are named as the exception, as the module header already does. Signed-off-by: Roman Inflianskas --- docs/architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 0228c845a7..7193bc7584 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -307,7 +307,7 @@ The library every first-party app and engine crate depends on. It holds host exa | [`fix/manifest.rs`](../crates/rocm-core/src/fix/manifest.rs) | The JSON catalog manifest `rocm fix --json` publishes, derived from `RECIPES` on every call. | flat | | [`fix/options.rs`](../crates/rocm-core/src/fix/options.rs) | The vocabulary of `rocm fix`: the exit codes (`exit`), `FixOptions` and `FixClass`. | flat | | [`fix/render.rs`](../crates/rocm-core/src/fix/render.rs) | Rendering the catalog for people: the listing, a recipe's plan and verify lines, the flag summary `rocm diagnose` shares, and the refusal of a diagnosis position as a fix-id. | flat | -| [`fix/runners.rs`](../crates/rocm-core/src/fix/runners.rs) | The host-mutating runners, one per auto-applicable fix, each printing the exact change, honouring `--dry-run` and asking consent first. | flat | +| [`fix/runners.rs`](../crates/rocm-core/src/fix/runners.rs) | The host-mutating runners, one per auto-applicable fix, each printing the exact change, honouring `--dry-run` and asking consent before any write, except the report-only arms (fix-2 on Linux, fix-9 without `--device-index`). On Windows, fix-2, fix-6 and fix-9 (with `--device-index`) first read the env-scope value their plan depends on, and if that read fails they stop with exit 4 before the runner's own preview or any prompt, under `--dry-run` too. | flat | | [`foreign_temp_probe.rs`](../crates/rocm-core/src/foreign_temp_probe.rs) | Test probe that a writer publishing through `atomic_write` never touches another writer's temp file; built only for tests and the `test-support` feature. | flat | | [`gfx_target.rs`](../crates/rocm-core/src/gfx_target.rs) | Pure gfx-target lookups: extracting a gfx token, mapping a target to its TheRock family, the AMD PCI-id and marketing-name tables, and kernel gfx-version decoding. | domain | | [`gguf.rs`](../crates/rocm-core/src/gguf.rs) | Reads a GGUF model's shape (layers, heads, head width, parameter count, data offset) from its header, never the weights. | domain | From 35548d2dcb1b916f2df89e6517212d0b40b0afe6 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Fri, 13 Nov 2026 15:32:29 +0200 Subject: [PATCH 4/8] docs(rocm-doctor): read an older CLI's "exited 124" as a timeout (ROCMAI-345) The skill is federated from main ahead of a release, and its Phase 0 installs the release-channel CLI. A released CLI reports a timed-out fix step as " exited 124; NOT changed.", so an agent following the skill would tell the user nothing changed when the step may have landed. Treat that line as a timeout: say the change may or may not have landed, give the user the check for that fix (the group list on Linux, the User-scope variable on Windows), and offer the same re-run. Signed-off-by: Roman Inflianskas --- skills/rocm-doctor/SKILL.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/skills/rocm-doctor/SKILL.md b/skills/rocm-doctor/SKILL.md index 314464a405..621d5d6fcb 100644 --- a/skills/rocm-doctor/SKILL.md +++ b/skills/rocm-doctor/SKILL.md @@ -271,7 +271,14 @@ passes — the GPU is AMD or no vendor was named. present the printed catalog entry as a preview, and do not hand the user its commands (such as `setx HIP_VISIBLE_DEVICES `) instead. - `… NOT changed.` — the command ran and failed, or could not start. - Nothing was changed. + Nothing was changed. The exception is a line saying `exited 124`, which + is how an older CLI reports a timed-out step: the change may or may not + have landed. Say so, have the user check (`id -nG ` for + `fix-4-render-group`; on Windows, in PowerShell, + `[Environment]::GetEnvironmentVariable('','User')` with `` + being `HSA_OVERRIDE_GFX_VERSION`, `PATH` or `HIP_VISIBLE_DEVICES` for + fix-2, fix-6 or fix-9), and offer to re-run the same `rocm fix` command + if it did not land. - `… may or may not have changed. Check … then re-run …` — the command timed out or was killed. Relay the check (on Windows, an expression to run in PowerShell) and the `rocm fix` command to re-run; claim neither that From d9e9fa1026561086e46dfcf41a541d3517f63a37 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 13:54:08 +0200 Subject: [PATCH 5/8] docs(rocm-core): name the proving tests and cover older CLIs in the skill (ROCMAI-345) The wording tests in fix/consent.rs pin each failure line against a stand-in step; their comments now name the runner tests that prove what each line claims, and say that no runner test drives a wait failure or a signal. The rocm-doctor skill special-cased only `exited 124`. A CLI released before this change also reports a signalled step as `exited -1` with `NOT changed`, and on Windows takes a failed read for an unset variable: fix-2 can then report the override gone and exit 0, and fix-9 can run setx over a value the user chose. One passage now covers both, with the check to run, and the exit-4 row in reference.md points at it. Also refresh three stale comments: what fix.rs says consent.rs holds, fix-2's class in the report_persistent_override doc, and a PR-relative note on the current_os WSL test. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 6 ++++-- crates/rocm-core/src/fix/consent.rs | 24 ++++++++++++++++++++---- crates/rocm-core/src/fix/runners.rs | 5 +++-- docs/architecture.md | 2 +- skills/rocm-doctor/SKILL.md | 29 +++++++++++++++++++++-------- skills/rocm-doctor/reference.md | 2 +- 6 files changed, 50 insertions(+), 18 deletions(-) diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index ad76d943e7..8673381664 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -16,8 +16,10 @@ //! place. //! //! This file is the module root. The exit codes, [`FixOptions`] and [`FixClass`] -//! live in `fix/options.rs`, and the consent decision, the timeouts and the -//! `fail!` helper in `fix/consent.rs`; the names are re-exported from here, so +//! live in `fix/options.rs`. `fix/consent.rs` holds the consent decision, the +//! timeouts, the `fail!` helper, and the one way a runner runs a host command +//! and reports how it ended (`run_step`, `Step`, `CheckIn`, `StepFailure`, +//! `read_failure`); the names are re-exported from here, so //! `crate::fix::exit` and `rocm_core::fix::FixClass` keep resolving. The //! runners, one per auto-applicable fix, are in `fix/runners.rs`. The closed //! catalog (`RECIPES`, `FixRecipe`, the lookups by fix-id and the test-only diff --git a/crates/rocm-core/src/fix/consent.rs b/crates/rocm-core/src/fix/consent.rs index 4a1c52bcd1..b6adcadc14 100644 --- a/crates/rocm-core/src/fix/consent.rs +++ b/crates/rocm-core/src/fix/consent.rs @@ -258,10 +258,9 @@ pub(super) fn confirm(prompt: &str, assume_yes: bool) -> bool { mod tests { use super::*; - /// Restored, not new. This PR made the `wsl` arm of the platform lookup - /// carry more weight, not less -- it now drives the per-platform class, the - /// plan, the recipe printer and the listing -- so the guard tying that arm - /// to the real host detector matters more here than it did before. + /// The `wsl` answer selects the per-platform class, the plan, the recipe + /// printer and the listing, so it must be the real host detector's answer + /// and not a second, drifting one. #[test] fn current_os_reports_wsl_exactly_when_is_wsl_host_does() { // `current_os()`'s wsl branch is `crate::is_wsl_host()`, which is @@ -334,6 +333,18 @@ mod tests { /// exit is exit 4, a timeout says "timed out" with the bound it ran under, /// and only a command that ran to its own end (or never started) is /// reported as having changed nothing. + /// + /// This pins the wording against a stand-in step. What each line claims is + /// proved where a runner prints it, in `fix/runners.rs`: + /// `render_group_child_failure_says_nothing_changed_and_returns_4` and + /// `unset_override_setx_failure_returns_4` (an exit code: NOT changed); + /// `render_group_missing_program_says_it_could_not_start` (never started); + /// `render_group_timeout_says_timed_out_and_how_to_check_not_that_nothing_changed` + /// and `unset_override_setx_timeout_says_timed_out_and_how_to_check` (a + /// timeout: may have changed, how to check, what to re-run); and + /// `every_rerun_id_names_a_recipe_with_a_runner` (the re-run command exists). + /// No runner test drives `WaitFailed` or `Signaled`; they take the + /// timeout's "may or may not have changed" wording from this match. #[test] fn step_failure_reports_each_outcome_with_its_own_wording() { for outcome in [ @@ -401,6 +412,11 @@ mod tests { assert!(line.starts_with("setx timed out after 8s "), "{line}"); } + /// Pins the wording. That a runner really stops before writing anything + /// after a failed read is proved in `fix/runners.rs` by + /// `pin_device_read_timeout_stops_before_setx`, + /// `unset_override_user_read_timeout_stops_before_anything_is_reported_or_cleared` + /// and `a_read_that_exits_non_zero_stops_every_windows_fix_without_writing`. #[test] fn a_failed_read_says_nothing_was_changed() { assert_eq!( diff --git a/crates/rocm-core/src/fix/runners.rs b/crates/rocm-core/src/fix/runners.rs index 39cd166c25..3232187fe6 100644 --- a/crates/rocm-core/src/fix/runners.rs +++ b/crates/rocm-core/src/fix/runners.rs @@ -181,8 +181,9 @@ fn run_unset_override_linux() -> i32 { /// Takes the paths rather than deriving them from `$HOME`, for the same reason /// [`pin_device_in_rc_file`] takes its rc path: it makes the promise testable /// without mutating a process-global. And the promise needs testing — fix-2 is -/// flagged `auto_applicable`, so `skills/rocm-doctor/` has to say plainly that -/// this arm still only reports, and something has to hold that true. +/// `FixClass::Auto` on Windows and `FixClass::PrintOnly` here, yet it still +/// has a runner that this arm is part of, so `skills/rocm-doctor/` has to say +/// plainly that this arm only reports, and something has to hold that true. fn report_persistent_override(candidates: &[PathBuf]) -> i32 { let hits: Vec<&PathBuf> = candidates .iter() diff --git a/docs/architecture.md b/docs/architecture.md index bf0a8a6f10..5e15bbfd63 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -303,7 +303,7 @@ The library every first-party app and engine crate depends on. It holds host exa | [`fake_executable.rs`](../crates/rocm-core/src/fake_executable.rs) | `write_fake_executable`: writes a stand-in script for tests from a short-lived child, so running it does not fail with `ETXTBSY`. It is built into every build, without a `cfg(test)` gate, so dependent crates' tests can call it. | flat | | [`fix.rs`](../crates/rocm-core/src/fix.rs) | Root of `rocm fix`: the dispatch (`apply`) that plans, confirms and runs a catalog remediation, and the re-exports of its children's public names. | flat | | [`fix/catalog.rs`](../crates/rocm-core/src/fix/catalog.rs) | The closed remediation catalog: `FixRecipe`, the per-platform class table, `RECIPES`, the lookups by fix-id, and the test-only oracles. | flat | -| [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs) | The consent decision and `confirm`, the timeouts the runners use, `current_os`, output helpers that cannot panic on a closed pipe, and `run_step`/`Step`, which run a runner's host command on the bounded executor and turn how it ended (exit code, not started, timed out) into the one stderr line and exit code the runner reports, with `CheckIn` saying whether its check command runs in any shell or in PowerShell. | flat | +| [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs) | The consent decision and `confirm`, the timeouts the runners use, `current_os`, output helpers that cannot panic on a closed pipe, and `run_step`/`Step`, which run a runner's host command on the bounded executor and turn how it ended (exit code, not started, timed out) into the one stderr line and exit code the runner reports, with `CheckIn` saying whether its check command runs in any shell or in PowerShell, and `read_failure`, the line and exit code for a read the runner plans from that did not complete. | flat | | [`fix/manifest.rs`](../crates/rocm-core/src/fix/manifest.rs) | The JSON catalog manifest `rocm fix --json` publishes, derived from `RECIPES` on every call. | flat | | [`fix/options.rs`](../crates/rocm-core/src/fix/options.rs) | The vocabulary of `rocm fix`: the exit codes (`exit`), `FixOptions` and `FixClass`. | flat | | [`fix/render.rs`](../crates/rocm-core/src/fix/render.rs) | Rendering the catalog for people: the listing, a recipe's plan and verify lines, the flag summary `rocm diagnose` shares, and the refusal of a diagnosis position as a fix-id. | flat | diff --git a/skills/rocm-doctor/SKILL.md b/skills/rocm-doctor/SKILL.md index af1b4c3ed0..fb8ef42310 100644 --- a/skills/rocm-doctor/SKILL.md +++ b/skills/rocm-doctor/SKILL.md @@ -275,14 +275,8 @@ passes — the GPU is AMD or no vendor was named. present the printed catalog entry as a preview, and do not hand the user its commands (such as `setx HIP_VISIBLE_DEVICES `) instead. - `… NOT changed.` — the command ran and failed, or could not start. - Nothing was changed. The exception is a line saying `exited 124`, which - is how an older CLI reports a timed-out step: the change may or may not - have landed. Say so, have the user check (`id -nG ` for - `fix-4-render-group`; on Windows, in PowerShell, - `[Environment]::GetEnvironmentVariable('','User')` with `` - being `HSA_OVERRIDE_GFX_VERSION`, `PATH` or `HIP_VISIBLE_DEVICES` for - fix-2, fix-6 or fix-9), and offer to re-run the same `rocm fix` command - if it did not land. + Nothing was changed, unless the line says `exited 124` or `exited -1` + (see below). - `… may or may not have changed. Check … then re-run …` — the command timed out or was killed. Relay the check (on Windows, an expression to run in PowerShell) and the `rocm fix` command to re-run; claim neither that @@ -290,6 +284,25 @@ passes — the GPU is AMD or no vendor was named. - `Failed to write : …` — the rc-file append failed; have the user look at that file. + Some CLIs that pass the Phase 0 contract check are older than these lines + and report two cases differently: + + - A `NOT changed` line saying `exited 124` (timed out) or `exited -1` + (killed by a signal) does not prove nothing changed: the change may or + may not have landed. Say so, have the user check (`id -nG ` for + `fix-4-render-group`; on Windows, in PowerShell, + `[Environment]::GetEnvironmentVariable('','User')` with `` + being `HSA_OVERRIDE_GFX_VERSION`, `PATH` or `HIP_VISIBLE_DEVICES` for + fix-2, fix-6 or fix-9), and offer to re-run the same `rocm fix` command + if it did not land. + - On Windows such a CLI takes a failed read for an unset variable, so a + clean result is not proof. `fix-2-unset-override` can say + `No persistent HSA_OVERRIDE_GFX_VERSION found` and that the user is done, + and exit 0, with the override still set; `fix-9-igpu-dgpu --device-index N` + can run `setx` over a value the user set on purpose. Have the user run + that PowerShell check for fix-2 before calling it done, and for fix-9 + before applying it. + 4. **Verify.** Have the user run the `verify` command from the diagnosis. Use `rocm examine` (or `rocm examine --json`) when you only need the host state diff --git a/skills/rocm-doctor/reference.md b/skills/rocm-doctor/reference.md index 52162b27ba..7e2dbf43f8 100644 --- a/skills/rocm-doctor/reference.md +++ b/skills/rocm-doctor/reference.md @@ -105,7 +105,7 @@ id is refused, and the refusal exits 1 (see the table). Exit codes: | 1 | internal error; also the refusal of `--json` together with a fix id | | 2 | usage error (incl. unknown fix-id) | | 3 | not applicable on this host (OS mismatch, negative `--device-index`) — nothing changed | -| 4 | attempted but the command failed or timed out; after a timeout the change may be partial — the message names how to check it and what to re-run. Also, on Windows only, `fix-2-unset-override`, `fix-6-path` or `fix-9-igpu-dgpu --device-index N` when it could not read the current value of the variable it changes, `--dry-run` included — nothing changed and no plan shown; the catalog entry printed first is the fix's generic description, not a preview of the change on this machine | +| 4 | attempted but the command failed or timed out; after a timeout the change may be partial — the message names how to check it and what to re-run (an older CLI instead prints `exited 124` or `exited -1` with `NOT changed`; see step 3 in [SKILL.md](SKILL.md)). Also, on Windows only, `fix-2-unset-override`, `fix-6-path` or `fix-9-igpu-dgpu --device-index N` when it could not read the current value of the variable it changes, `--dry-run` included — nothing changed and no plan shown; the catalog entry printed first is the fix's generic description, not a preview of the change on this machine | | 5 | user declined at the prompt | Three ids are ever auto-applicable — never four, and `fix-9-igpu-dgpu` is not From 83a2cc9c51fd1b8c71a07a9e531a3ef9bc4e74fb Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 13:59:54 +0200 Subject: [PATCH 6/8] chore(catalog): publish the merged `failed` exit-code description (ROCMAI-345) The merge with main moved exit-code wording into `exit::MEANINGS`, and this branch's `failed` entry now says a timed-out or stopped command may have made its change. Regenerate the published catalog so tools read the same text the CLI prints. Signed-off-by: Roman Inflianskas --- doctor-catalog.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doctor-catalog.json b/doctor-catalog.json index 64580f82b4..ae4c29a89f 100644 --- a/doctor-catalog.json +++ b/doctor-catalog.json @@ -456,7 +456,7 @@ }, "exit_code_descriptions": { "declined": "The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.", - "failed": "A step of the fix failed: a command it ran, a file it wrote, or a read of state it needed before planning (the current User PATH on Windows, read even under `--dry-run`). The change that step was to make was not made.", + "failed": "A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.", "internal": "The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.", "not_applicable": "The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).", "ok": "Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.", From ccfe192aafb36b0ff230c42a1823fdd4885a8412 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 14:33:26 +0200 Subject: [PATCH 7/8] fix(rocm-core): cover fix-2's Machine-scope read in the skill and catalog (ROCMAI-345) An older CLI swallows a failed read of either scope, so with an override set only in the Machine scope fix-2 can still report it gone. The skill's check for that case now reads both scopes, and since the output does not say which CLI produced it, the skill asks for the check on every Windows fix-2 and fix-9 run. The published `failed` description names the Machine read too, and the skill-eval replays are re-recorded against the new catalog text. Also stop the fix.rs module doc implying the consent.rs helpers are re-exported; only the options.rs names are. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 10 +++++----- crates/rocm-core/src/fix/options.rs | 10 ++++++---- doctor-catalog.json | 2 +- skills/rocm-doctor/SKILL.md | 10 ++++++---- .../fixtures/rocm-current-cli-carries-on/replies.json | 2 +- .../rocm-examine-fails-relays-the-error/replies.json | 2 +- .../replies.json | 2 +- .../replies.json | 2 +- .../replies.json | 2 +- .../evals/fixtures/rocm-vllm-import-error/replies.json | 2 +- .../fixtures/rocm-vllm-oom-at-startup/replies.json | 2 +- 11 files changed, 25 insertions(+), 21 deletions(-) diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 8673381664..668e5e2389 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -16,11 +16,11 @@ //! place. //! //! This file is the module root. The exit codes, [`FixOptions`] and [`FixClass`] -//! live in `fix/options.rs`. `fix/consent.rs` holds the consent decision, the -//! timeouts, the `fail!` helper, and the one way a runner runs a host command -//! and reports how it ended (`run_step`, `Step`, `CheckIn`, `StepFailure`, -//! `read_failure`); the names are re-exported from here, so -//! `crate::fix::exit` and `rocm_core::fix::FixClass` keep resolving. The +//! live in `fix/options.rs` and are re-exported from here, so +//! `crate::fix::exit` and `rocm_core::fix::FixClass` keep resolving. +//! `fix/consent.rs` holds the consent decision, the timeouts, the `fail!` +//! helper, and the one way a runner runs a host command and reports how it +//! ended (`run_step`, `Step`, `CheckIn`, `StepFailure`, `read_failure`). The //! runners, one per auto-applicable fix, are in `fix/runners.rs`. The closed //! catalog (`RECIPES`, `FixRecipe`, the lookups by fix-id and the test-only //! oracles) is in `fix/catalog.rs`, its rendering in `fix/render.rs` and its diff --git a/crates/rocm-core/src/fix/options.rs b/crates/rocm-core/src/fix/options.rs index 94912e45ff..2dd4b7c6b5 100644 --- a/crates/rocm-core/src/fix/options.rs +++ b/crates/rocm-core/src/fix/options.rs @@ -155,6 +155,7 @@ pub mod exit { // command that does not finish); and // `windows_path_read_failure_aborts_before_plan_or_write`, // `unset_override_user_read_timeout_stops_before_anything_is_reported_or_cleared`, + // `unset_override_machine_read_failure_stops_before_clearing_the_user_scope`, // `pin_device_read_timeout_stops_before_setx` and // `pin_device_dry_run_with_a_failed_read_stops_without_a_plan` (a failed // read, under `--dry-run` too). Those runners take an injected command @@ -166,10 +167,11 @@ pub mod exit { not be started, a file it wrote could not be written, or a read of \ state it needed before planning did not complete (on Windows, the \ current User value that fix-2, fix-6, and fix-9 with a device index \ - read first, even under `--dry-run`). The change that step was to \ - make was not made. If a command instead did not finish (it timed \ - out or was stopped), the change may or may not have been made: \ - stderr says how to check it and which `rocm fix` to re-run.", + read first, and for fix-2 the Machine value too, even under \ + `--dry-run`). The change that step was to make was not made. If a \ + command instead did not finish (it timed out or was stopped), the \ + change may or may not have been made: stderr says how to check it \ + and which `rocm fix` to re-run.", }, // Proved in `fix/runners.rs` by `declining_consent_returns_5_and_writes_nothing`, // `windows_decline_on_user_scope_returns_5` and diff --git a/doctor-catalog.json b/doctor-catalog.json index ae4c29a89f..82ee7bf66d 100644 --- a/doctor-catalog.json +++ b/doctor-catalog.json @@ -456,7 +456,7 @@ }, "exit_code_descriptions": { "declined": "The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.", - "failed": "A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.", + "failed": "A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, and for fix-2 the Machine value too, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.", "internal": "The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.", "not_applicable": "The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).", "ok": "Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.", diff --git a/skills/rocm-doctor/SKILL.md b/skills/rocm-doctor/SKILL.md index fb8ef42310..0546e52c14 100644 --- a/skills/rocm-doctor/SKILL.md +++ b/skills/rocm-doctor/SKILL.md @@ -298,10 +298,12 @@ passes — the GPU is AMD or no vendor was named. - On Windows such a CLI takes a failed read for an unset variable, so a clean result is not proof. `fix-2-unset-override` can say `No persistent HSA_OVERRIDE_GFX_VERSION found` and that the user is done, - and exit 0, with the override still set; `fix-9-igpu-dgpu --device-index N` - can run `setx` over a value the user set on purpose. Have the user run - that PowerShell check for fix-2 before calling it done, and for fix-9 - before applying it. + and exit 0, with the override still set in either scope; + `fix-9-igpu-dgpu --device-index N` can run `setx` over a value the user + set on purpose. Its output looks the same as a current CLI's, so on + Windows always have the user run that PowerShell check: for fix-2 before + calling it done, with `'User'` and again with `'Machine'` (both must come + back empty), and for fix-9 before applying it. 4. **Verify.** Have the user run the `verify` command from the diagnosis. diff --git a/skills/rocm-doctor/evals/fixtures/rocm-current-cli-carries-on/replies.json b/skills/rocm-doctor/evals/fixtures/rocm-current-cli-carries-on/replies.json index 9c0ed11c4b..105fa7e6e3 100644 --- a/skills/rocm-doctor/evals/fixtures/rocm-current-cli-carries-on/replies.json +++ b/skills/rocm-doctor/evals/fixtures/rocm-current-cli-carries-on/replies.json @@ -5,7 +5,7 @@ "rc": 0 }, "fix_json": { - "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran, a file it wrote, or a read of state it needed before planning (the current User PATH on Windows, read even under `--dry-run`). The change that step was to make was not made.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", + "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, and for fix-2 the Machine value too, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", "stderr": "", "rc": 0 }, diff --git a/skills/rocm-doctor/evals/fixtures/rocm-examine-fails-relays-the-error/replies.json b/skills/rocm-doctor/evals/fixtures/rocm-examine-fails-relays-the-error/replies.json index 6b3f182c39..11a2e84b07 100644 --- a/skills/rocm-doctor/evals/fixtures/rocm-examine-fails-relays-the-error/replies.json +++ b/skills/rocm-doctor/evals/fixtures/rocm-examine-fails-relays-the-error/replies.json @@ -5,7 +5,7 @@ "rc": 0 }, "fix_json": { - "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran, a file it wrote, or a read of state it needed before planning (the current User PATH on Windows, read even under `--dry-run`). The change that step was to make was not made.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", + "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, and for fix-2 the Machine value too, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", "stderr": "", "rc": 0 }, diff --git a/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-amd-found-goes-on-to-diagnose/replies.json b/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-amd-found-goes-on-to-diagnose/replies.json index 5592989a87..53a62d268e 100644 --- a/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-amd-found-goes-on-to-diagnose/replies.json +++ b/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-amd-found-goes-on-to-diagnose/replies.json @@ -5,7 +5,7 @@ "rc": 0 }, "fix_json": { - "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran, a file it wrote, or a read of state it needed before planning (the current User PATH on Windows, read even under `--dry-run`). The change that step was to make was not made.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", + "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, and for fix-2 the Machine value too, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", "stderr": "", "rc": 0 }, diff --git a/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-no-amd-gpu-asks-which-gpu/replies.json b/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-no-amd-gpu-asks-which-gpu/replies.json index f98514ddff..0ce2ef0f49 100644 --- a/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-no-amd-gpu-asks-which-gpu/replies.json +++ b/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-no-amd-gpu-asks-which-gpu/replies.json @@ -5,7 +5,7 @@ "rc": 0 }, "fix_json": { - "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran, a file it wrote, or a read of state it needed before planning (the current User PATH on Windows, read even under `--dry-run`). The change that step was to make was not made.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", + "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, and for fix-2 the Machine value too, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", "stderr": "", "rc": 0 }, diff --git a/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-wsl-host-gpu-hidden-asks-which-gpu/replies.json b/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-wsl-host-gpu-hidden-asks-which-gpu/replies.json index b45069b6ca..4e8ee964fb 100644 --- a/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-wsl-host-gpu-hidden-asks-which-gpu/replies.json +++ b/skills/rocm-doctor/evals/fixtures/rocm-no-vendor-wsl-host-gpu-hidden-asks-which-gpu/replies.json @@ -5,7 +5,7 @@ "rc": 0 }, "fix_json": { - "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran, a file it wrote, or a read of state it needed before planning (the current User PATH on Windows, read even under `--dry-run`). The change that step was to make was not made.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", + "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, and for fix-2 the Machine value too, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", "stderr": "", "rc": 0 }, diff --git a/skills/rocm-doctor/evals/fixtures/rocm-vllm-import-error/replies.json b/skills/rocm-doctor/evals/fixtures/rocm-vllm-import-error/replies.json index eb3b977605..476d2694c5 100644 --- a/skills/rocm-doctor/evals/fixtures/rocm-vllm-import-error/replies.json +++ b/skills/rocm-doctor/evals/fixtures/rocm-vllm-import-error/replies.json @@ -5,7 +5,7 @@ "rc": 0 }, "fix_json": { - "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran, a file it wrote, or a read of state it needed before planning (the current User PATH on Windows, read even under `--dry-run`). The change that step was to make was not made.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", + "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, and for fix-2 the Machine value too, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", "stderr": "", "rc": 0 }, diff --git a/skills/rocm-doctor/evals/fixtures/rocm-vllm-oom-at-startup/replies.json b/skills/rocm-doctor/evals/fixtures/rocm-vllm-oom-at-startup/replies.json index d385254b59..ac06cbab70 100644 --- a/skills/rocm-doctor/evals/fixtures/rocm-vllm-oom-at-startup/replies.json +++ b/skills/rocm-doctor/evals/fixtures/rocm-vllm-oom-at-startup/replies.json @@ -5,7 +5,7 @@ "rc": 0 }, "fix_json": { - "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran, a file it wrote, or a read of state it needed before planning (the current User PATH on Windows, read even under `--dry-run`). The change that step was to make was not made.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", + "stdout": "{\n \"contract_version\": 1,\n \"entries\": [\n {\n \"id\": \"fix-1-arch\",\n \"title\": \"GPU gfx target not in framework arch list\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-2-unset-override\",\n \"title\": \"Unset HSA_OVERRIDE_GFX_VERSION\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-3-rocm-kernel\",\n \"title\": \"ROCm/distro/kernel triple unsupported\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-4-render-group\",\n \"title\": \"Add user to render/video groups\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": true\n },\n {\n \"id\": \"fix-5-amdgpu-load\",\n \"title\": \"Load amdgpu (and clear any blacklist)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-6-path\",\n \"title\": \"Add the ROCm/HIP bin directory to PATH\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"auto\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"auto\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-7-stale-repos\",\n \"title\": \"Quarantine duplicate AMD repos\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-8-wheel-rocm\",\n \"title\": \"Reinstall the framework against the system ROCm/HIP X.Y release\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n },\n {\n \"id\": \"fix-9-igpu-dgpu\",\n \"title\": \"Hide the iGPU with HIP_VISIBLE_DEVICES\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"needs-argument\",\n \"needs\": \"--device-index\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-10-container\",\n \"title\": \"Re-launch the container with AMD devices passed through\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-11-iommu\",\n \"title\": \"Add iommu=pt to the kernel command line\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-12-installer\",\n \"title\": \"Reset repo-native install state and reinstall\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": true,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-13-hip-sdk-missing\",\n \"title\": \"Install the AMD HIP SDK for Windows\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html\"\n },\n {\n \"id\": \"fix-14-adrenalin-too-old\",\n \"title\": \"Update the Adrenalin / kernel-mode driver\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-windows/en/latest/install/install.html\"\n },\n {\n \"id\": \"fix-15-msvc-redist\",\n \"title\": \"Install the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-16-vllm-oom\",\n \"title\": \"vLLM ran the GPU out of memory at startup\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-17-torch-dlpack\",\n \"title\": \"Restore the engine's pinned torch (torch-c-dlpack-ext loads the CUDA variant)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-1-gpu-not-exposed\",\n \"title\": \"Expose the GPU to the WSL distro (/dev/dxg)\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-2-dxcore-missing\",\n \"title\": \"Restore the WSL DXCore libraries\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-3-rocdxg-missing\",\n \"title\": \"Install ROCDXG in the WSL distro\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-4-rocdxg-not-linked\",\n \"title\": \"Refresh the linker cache so ROCDXG is loadable\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-5-distro-too-old\",\n \"title\": \"Move to a distro release the WSL path supports\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-6-host-driver-too-old\",\n \"title\": \"Update the AMD driver on the Windows host\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-wsl-7-wsl1\",\n \"title\": \"Convert the distro from WSL 1 to WSL 2\",\n \"platforms\": [\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-18-comgr-conflict\",\n \"title\": \"Code object manager library does not belong to the active HIP runtime\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-19-shm-too-small\",\n \"title\": \"Raise the shared memory allowance\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"print-only\"\n },\n {\n \"os\": \"wsl\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": true,\n \"needs_reboot\": false,\n \"needs_relogin\": false\n },\n {\n \"id\": \"fix-21-msvc-redist-outdated\",\n \"title\": \"Update the MSVC 2015-2022 runtime redistributable\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://aka.ms/vs/17/release/vc_redist.x64.exe\"\n },\n {\n \"id\": \"fix-22-display-driver-old\",\n \"title\": \"Look for a newer AMD display driver (advice only)\",\n \"platforms\": [\n {\n \"os\": \"windows\",\n \"class\": \"print-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": true,\n \"needs_relogin\": false,\n \"doc_url\": \"https://www.amd.com/en/support\"\n },\n {\n \"id\": \"info-20-gpu-no-rocm-support\",\n \"title\": \"GPU has no ROCm/HIP support (Vulkan backend still works)\",\n \"platforms\": [\n {\n \"os\": \"linux\",\n \"class\": \"diagnose-only\"\n },\n {\n \"os\": \"windows\",\n \"class\": \"diagnose-only\"\n }\n ],\n \"needs_sudo\": false,\n \"needs_reboot\": false,\n \"needs_relogin\": false,\n \"doc_url\": \"https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html\"\n }\n ],\n \"exit_codes\": {\n \"declined\": 5,\n \"failed\": 4,\n \"internal\": 1,\n \"not_applicable\": 3,\n \"ok\": 0,\n \"unknown_id\": 2\n },\n \"exit_code_descriptions\": {\n \"declined\": \"The fix needed confirmation and did not get it: the user answered no, or stdin is not a terminal and `--yes` was not given. Nothing the confirmation guarded was changed.\",\n \"failed\": \"A step of the fix failed: a command it ran exited non-zero or could not be started, a file it wrote could not be written, or a read of state it needed before planning did not complete (on Windows, the current User value that fix-2, fix-6, and fix-9 with a device index read first, and for fix-2 the Machine value too, even under `--dry-run`). The change that step was to make was not made. If a command instead did not finish (it timed out or was stopped), the change may or may not have been made: stderr says how to check it and which `rocm fix` to re-run.\",\n \"internal\": \"The CLI is inconsistent with itself (a recipe it says it can carry out, with nothing to carry it out with); never a fault of the machine. Exit 1 is also any other error the command reports on stderr, such as `--json` combined with a fix-id.\",\n \"not_applicable\": \"The entry exists but cannot be used here: it is for another platform, the host lacks something the fix cannot do without (a tool it runs, or `sudo` when not root; an install it points at; the current user's name; or a home directory to write a file in), or an argument it was given is one it cannot use, such as a negative device index written `--device-index=-1`. Nothing was tried. Written with a space instead, `--device-index -1` is a usage error and exits 2 (see `unknown_id`).\",\n \"ok\": \"Nothing failed: the fix was applied, found nothing to change (already in place, or a setting it leaves for you to edit), was previewed with `--dry-run`, or only printed what to do (steps to run yourself, or the explanation of a diagnose-only entry); or the catalog was listed. A `--dry-run` preview is not always 0: it exits 3 or 4 when the fix cannot be planned.\",\n \"unknown_id\": \"No catalog entry has that fix-id; no fix step was run, and a stderr line starts with `Unknown fix-id:`. Exit 2 is also what the argument parser returns for a malformed command line (an unknown option, a missing value, or a value it cannot read, such as a non-number for `--device-index`, or a negative one written after a space, `--device-index -1`, which it reads as an unknown option), before any fix-id is looked up; that refusal has a stderr line starting with `error:` and never says `Unknown fix-id:`. Another line, such as a one-time `rocm:` notice, can come first. The code alone cannot tell the two apart; the message can.\"\n }\n}\n", "stderr": "", "rc": 0 }, From 49c744528ca4ee97a286b5255cc68c75e132c817 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 14:59:00 +0200 Subject: [PATCH 8/8] test(rocm-core): pin fix-2's Machine read under --dry-run, say what to do with a set value (ROCMAI-345) The published `failed` description says fix-2 reads its Machine value even under `--dry-run`, but only the User read had a dry-run test. A new test fails the Machine read under `--dry-run` with a User value set and asserts exit 4 with no plan; it goes red when the Machine read failure is swallowed. The skill's older-CLI check told the agent to read both scopes without saying what a set value means. It now says: a User value means re-running fix-2, a Machine value needs an elevated PowerShell, and for fix-9 an existing value is left for the user to change by hand. The lead-in says the Windows case applies to every run, since the output cannot tell an older CLI apart. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix/options.rs | 8 +++++--- crates/rocm-core/src/fix/runners.rs | 18 ++++++++++++++++++ skills/rocm-doctor/SKILL.md | 16 +++++++++++----- 3 files changed, 34 insertions(+), 8 deletions(-) diff --git a/crates/rocm-core/src/fix/options.rs b/crates/rocm-core/src/fix/options.rs index 2dd4b7c6b5..d7f199dd5f 100644 --- a/crates/rocm-core/src/fix/options.rs +++ b/crates/rocm-core/src/fix/options.rs @@ -156,9 +156,11 @@ pub mod exit { // `windows_path_read_failure_aborts_before_plan_or_write`, // `unset_override_user_read_timeout_stops_before_anything_is_reported_or_cleared`, // `unset_override_machine_read_failure_stops_before_clearing_the_user_scope`, - // `pin_device_read_timeout_stops_before_setx` and - // `pin_device_dry_run_with_a_failed_read_stops_without_a_plan` (a failed - // read, under `--dry-run` too). Those runners take an injected command + // `pin_device_read_timeout_stops_before_setx`, + // `unset_override_dry_run_with_a_failed_read_stops_without_a_plan`, + // `unset_override_dry_run_with_a_failed_machine_read_stops_without_a_plan` + // and `pin_device_dry_run_with_a_failed_read_stops_without_a_plan` (a + // failed read, under `--dry-run` too). Those runners take an injected command // runner, so no test starts the real program. Meaning { name: "failed", diff --git a/crates/rocm-core/src/fix/runners.rs b/crates/rocm-core/src/fix/runners.rs index 3232187fe6..5e11d9d9c2 100644 --- a/crates/rocm-core/src/fix/runners.rs +++ b/crates/rocm-core/src/fix/runners.rs @@ -1805,6 +1805,24 @@ mod tests { ); } + /// fix-2 reads the Machine scope before `--dry-run` is consulted too, so a + /// Machine read that fails stops a dry run with no plan, even with the + /// User value read and set. + #[test] + fn unset_override_dry_run_with_a_failed_machine_read_stops_without_a_plan() { + let host = FakeHost::new((exited(0), "10.3.0"), exited(0)) + .with_machine_read((CommandOutcome::NotFound, "")); + let (code, out, err) = unset_override_with(&host, &dry_run()); + assert_eq!(code, exit::FAILED); + assert!(host.writes().is_empty()); + assert_eq!(out, SHELL_UNSET, "no plan is printed"); + assert_eq!( + err, + "Could not read the current Machine HSA_OVERRIDE_GFX_VERSION: PowerShell could not \ + be started: it was not found; nothing was changed.\n" + ); + } + /// Every "re-run `rocm fix `" line names a recipe that exists and has /// a runner, so the recovery it advises can actually be carried out. #[test] diff --git a/skills/rocm-doctor/SKILL.md b/skills/rocm-doctor/SKILL.md index 0546e52c14..7af50732ce 100644 --- a/skills/rocm-doctor/SKILL.md +++ b/skills/rocm-doctor/SKILL.md @@ -285,7 +285,8 @@ passes — the GPU is AMD or no vendor was named. look at that file. Some CLIs that pass the Phase 0 contract check are older than these lines - and report two cases differently: + and report two cases differently. The second looks the same as a current + CLI's output, so it applies to every Windows fix-2 and fix-9 run: - A `NOT changed` line saying `exited 124` (timed out) or `exited -1` (killed by a signal) does not prove nothing changed: the change may or @@ -300,10 +301,15 @@ passes — the GPU is AMD or no vendor was named. `No persistent HSA_OVERRIDE_GFX_VERSION found` and that the user is done, and exit 0, with the override still set in either scope; `fix-9-igpu-dgpu --device-index N` can run `setx` over a value the user - set on purpose. Its output looks the same as a current CLI's, so on - Windows always have the user run that PowerShell check: for fix-2 before - calling it done, with `'User'` and again with `'Machine'` (both must come - back empty), and for fix-9 before applying it. + set on purpose. So have the user run that PowerShell check. For fix-2, + run it before calling the fix done, with `'User'` and again with + `'Machine'`; blank output means unset. A User value means re-running + `rocm fix fix-2-unset-override`; a Machine value has to be cleared from + an elevated PowerShell with + `[Environment]::SetEnvironmentVariable('HSA_OVERRIDE_GFX_VERSION', $null, 'Machine')`. + For fix-9, run it before applying the fix; if a value is already set, do + not apply it, and tell the user to change that value by hand if they + want a different GPU, as the CLI itself says when its read works. 4. **Verify.** Have the user run the `verify` command from the diagnosis.