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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -591,7 +591,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 <dGPU-index>` 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,
Expand All @@ -617,6 +623,16 @@ on how it is written: `--device-index=-1` is accepted by the parser and the fix
refuses it with exit 3, while `--device-index -1` (with a space) is read as an
unknown option `-1`, a usage error that exits 2.

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 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

```
Expand Down
19 changes: 17 additions & 2 deletions apps/rocm/src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,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, `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<String>,
Expand All @@ -247,7 +258,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.
Expand Down
14 changes: 10 additions & 4 deletions crates/rocm-core/src/fix.rs
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,11 @@
//! 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
//! `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
Expand Down Expand Up @@ -167,7 +169,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
Expand Down Expand Up @@ -879,10 +882,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",
Expand All @@ -892,6 +897,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),
Expand Down
17 changes: 13 additions & 4 deletions crates/rocm-core/src/fix/catalog.rs
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,15 @@ impl FixRecipe {
}
}

/// The ids of the recipes whose runners name themselves in a recovery line
/// ("re-run `rocm fix <id>`"). 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] = &[
Expand Down Expand Up @@ -204,7 +213,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: &[
Expand Down Expand Up @@ -258,7 +267,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\""],
Expand Down Expand Up @@ -296,7 +305,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: &[
Expand Down Expand Up @@ -383,7 +392,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: &[
Expand Down
Loading
Loading