From f9d3edeacd2c597bda2cc952ec76cbf4c3494a1e Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Wed, 14 Oct 2026 09:12:57 +0000 Subject: [PATCH 01/18] fix: fall back to /usr/lib/os-release when /etc/os-release is absent os-release(5) says to read /etc/os-release and, if it does not exist, fall back to /usr/lib/os-release. Every reader in rocm-cli read only /etc/os-release, so a host that ships the file only at /usr/lib/os-release (minimal/container images, some distro variants) read as an unknown distro: `rocm examine` reported nothing and `rocm install driver` planned nothing. Add one shared helper (hardware_root::read_os_release) that tries /etc/os-release then /usr/lib/os-release, and wire it into the two functions that now do all the reading for the six call sites this fixes (examine's distro probe, host_gpu's distro name, openmpi's install-hint reader, and runtime_install_finalize's package-manager reader), preserving each site's existing host_path vs. real-host resolution strategy. Fixes #545. Signed-off-by: Jussi Elo --- .github/workflows/ci.yml | 4 +- apps/rocm/src/runtime_install_finalize.rs | 9 ++- crates/rocm-core/src/examine.rs | 47 +++++++++++++- crates/rocm-core/src/hardware_root.rs | 62 +++++++++++++++++-- crates/rocm-core/src/host_gpu.rs | 4 +- crates/rocm-core/src/openmpi.rs | 6 +- docs/release-trust.md | 13 ++-- docs/testing.md | 40 +++++++++--- tests/e2e-cucumber/features/examine.feature | 11 ++++ tests/e2e-cucumber/tests/e2e/examine_steps.rs | 26 ++++++++ 10 files changed, 194 insertions(+), 28 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1dd2725c17..05f8884cc9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -553,7 +553,9 @@ jobs: # `is_wsl_host`, `/run/.containerenv` and `/proc/1/cgroup` via # `probe_container`, and both `/etc/os-release` reads (the distro # fields and the distro name, in - # `os_release_reads_follow_the_simulated_host_root`). The other routed + # `os_release_reads_follow_the_simulated_host_root` and, for the + # `/usr/lib/os-release` fallback, in + # `os_release_reads_fall_back_to_usr_lib_when_etc_is_absent`). The other routed # reads (`/dev/dri`, `/sys/class/drm`, `/sys/module/amdgpu`, the other # `/proc` files, the modprobe directories, the `/usr/lib/wsl/lib` and # ROCDXG checks) have no planted-root unit assertion; they are covered diff --git a/apps/rocm/src/runtime_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index 23de4e8357..e856854a19 100644 --- a/apps/rocm/src/runtime_install_finalize.rs +++ b/apps/rocm/src/runtime_install_finalize.rs @@ -14,7 +14,6 @@ //! and read from `engines_cmd.rs`. use std::fmt::Write as _; -use std::fs; use std::path::{Path, PathBuf}; use std::process::{Command as ProcessCommand, Stdio}; @@ -149,7 +148,8 @@ pub(crate) const fn empty_as_unknown(value: &str) -> &str { if value.is_empty() { "" } else { value } } -/// The real host's `/etc/os-release`. +/// 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`, `amdgpu-install`) that then runs @@ -157,7 +157,8 @@ pub(crate) const fn empty_as_unknown(value: &str) -> &str { /// distro. The descriptive distro name `examine` reports comes from /// `rocm_core::detect_distro_name`, which does follow a simulated root. pub(crate) fn read_os_release() -> Result { - fs::read_to_string("/etc/os-release").context("failed to read /etc/os-release") + rocm_core::hardware_root::read_os_release(|p| PathBuf::from(p)) + .context("failed to read /etc/os-release or /usr/lib/os-release") } /// Run a command given as an argv vector directly, without going through a shell. @@ -1970,6 +1971,8 @@ pub(crate) fn finalize_successful_sdk_install( #[cfg(test)] pub(crate) mod tests { + use std::fs; + use super::*; use crate::test_support::write_test_pip_runtime; use crate::tests::{ diff --git a/crates/rocm-core/src/examine.rs b/crates/rocm-core/src/examine.rs index 0df5300a16..a49d9ca9cc 100644 --- a/crates/rocm-core/src/examine.rs +++ b/crates/rocm-core/src/examine.rs @@ -728,7 +728,10 @@ fn probe_os(e: &mut Examination) { e.os_family = "linux".to_owned(); e.kernel_release = run("uname", &["-r"], SHORT).1.trim().to_owned(); e.kernel_cmdline = read_host_text("/proc/cmdline").trim().to_owned(); - record_distro(e, &read_host_text("/etc/os-release")); + record_distro( + e, + &crate::hardware_root::read_os_release(|p| crate::host_path(p)).unwrap_or_default(), + ); if let Some(param) = parse_iommu_param(&e.kernel_cmdline) { e.iommu_kernel_param = param; } @@ -5673,6 +5676,48 @@ mod tests { ); assert_eq!(name.as_deref(), Some("Planted 0.1")); } + + /// `os-release(5)` falls back to `/usr/lib/os-release` when `/etc/os-release` + /// is absent. Both `rocm examine` reads must still answer from a host that + /// ships only the fallback path — a probe that stopped after the first + /// candidate would read as an unknown distro instead. + #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] + #[test] + fn os_release_reads_fall_back_to_usr_lib_when_etc_is_absent() { + use crate::hardware_root::TEST_HOST_ROOT_ENV; + use crate::test_env::RestoredEnvVar; + + let root = std::env::temp_dir().join(format!( + "rocm-core-os-release-fallback-root-{}", + crate::test_support::unique_suffix() + )); + std::fs::create_dir_all(root.join("usr/lib")).expect("create planted /usr/lib"); + std::fs::write( + root.join("usr/lib/os-release"), + "ID='fallback'\nVERSION_ID='1.2'\nPRETTY_NAME='Fallback 1.2'\n", + ) + .expect("write planted os-release"); + + let (examined, name) = { + let _guard = crate::hardware_root::HOST_ROOT_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let _root = RestoredEnvVar::set(TEST_HOST_ROOT_ENV, &root); + let mut examined = Examination::default(); + probe_os(&mut examined); + (examined, crate::host_gpu::detect_distro_name()) + }; + std::fs::remove_dir_all(&root).ok(); + + assert_eq!( + ( + examined.distro_id.as_str(), + examined.distro_version.as_str() + ), + ("fallback", "1.2") + ); + assert_eq!(name.as_deref(), Some("Fallback 1.2")); + } } /// Property tests for the driver-side text readers above; a child module so it diff --git a/crates/rocm-core/src/hardware_root.rs b/crates/rocm-core/src/hardware_root.rs index 4fd460f870..135f84b7a5 100644 --- a/crates/rocm-core/src/hardware_root.rs +++ b/crates/rocm-core/src/hardware_root.rs @@ -15,7 +15,9 @@ //! - `procfs`: `/proc/version`, `/proc/cpuinfo`, `/proc/meminfo`, //! `/proc/cmdline`, `/proc/modules` (the fallback when `lsmod` cannot run) //! and `/proc/1/cgroup`; -//! - the `/etc/os-release` behind the distro name `rocm examine` reports; +//! - the `/etc/os-release` behind the distro fields and name `rocm examine` +//! reports, falling back to `/usr/lib/os-release` when the former is absent, +//! per `os-release(5)`; //! - the modprobe configuration directories `/etc/modprobe.d`, //! `/usr/lib/modprobe.d` and `/run/modprobe.d`; //! - the WSL plumbing: the `/usr/lib/wsl/lib` directory check and @@ -33,9 +35,10 @@ //! `LD_LIBRARY_PATH`; re-rooting it would put the simulated directory in front //! of a real loader. Programs the probes execute, such as `ldconfig`, stay on //! the real host too: a simulated root holds no binary to run. Every -//! package-manager plan reads the real `/etc/os-release` — the install hints in -//! `openmpi.rs`, and the driver, OpenMPI and runtime-library installs in the -//! `rocm` binary — because the commands it builds run against the real +//! package-manager plan reads the real `/etc/os-release` (with the same +//! `/usr/lib/os-release` fallback) — the OpenMPI, libatomic and libnuma install +//! hints in `openmpi.rs`, and the driver, OpenMPI and runtime-library installs +//! in the `rocm` binary — because the commands it builds run against the real //! machine. Process liveness under `/proc/` and `/dev/shm` sizing are //! about this process's environment, not the hardware. //! @@ -110,6 +113,19 @@ fn host_path_under(root: Option<&Path>, path: &Path) -> PathBuf { } } +/// Reads `/etc/os-release`, falling back to `/usr/lib/os-release` per +/// `os-release(5)` when the former is absent. +/// +/// `resolve` maps each candidate to where it should actually be read from — +/// [`host_path`] for a probe that must honour a simulated test root, or the +/// identity for one that must always read the real machine (see the module +/// doc above). +pub fn read_os_release(resolve: impl Fn(&str) -> PathBuf) -> Option { + ["/etc/os-release", "/usr/lib/os-release"] + .into_iter() + .find_map(|candidate| std::fs::read_to_string(resolve(candidate)).ok()) +} + /// Serialises every test that sets [`TEST_HOST_ROOT_ENV`], including the /// downstream probe test in `examine.rs`, so two of them never see each other's /// simulated root. @@ -182,4 +198,42 @@ mod tests { let _empty = crate::test_env::RestoredEnvVar::set(TEST_HOST_ROOT_ENV, Path::new("")); assert_eq!(host_path("/dev/kfd"), PathBuf::from("/dev/kfd")); } + + /// Maps `/etc/os-release` to `primary` and `/usr/lib/os-release` to + /// `fallback` under `dir`, so [`read_os_release`]'s fallback can be tested + /// without touching the real host's files. + fn candidate(dir: &Path, name: &str) -> PathBuf { + match name { + "/etc/os-release" => dir.join("primary"), + "/usr/lib/os-release" => dir.join("fallback"), + other => panic!("unexpected os-release candidate: {other}"), + } + } + + #[test] + fn read_os_release_prefers_the_primary_candidate() { + let dir = tempfile::tempdir().expect("create temp dir"); + std::fs::write(dir.path().join("primary"), "ID=primary\n").expect("write primary"); + std::fs::write(dir.path().join("fallback"), "ID=fallback\n").expect("write fallback"); + assert_eq!( + read_os_release(|name| candidate(dir.path(), name)), + Some("ID=primary\n".to_owned()) + ); + } + + #[test] + fn read_os_release_falls_back_when_the_primary_is_absent() { + let dir = tempfile::tempdir().expect("create temp dir"); + std::fs::write(dir.path().join("fallback"), "ID=fallback\n").expect("write fallback"); + assert_eq!( + read_os_release(|name| candidate(dir.path(), name)), + Some("ID=fallback\n".to_owned()) + ); + } + + #[test] + fn read_os_release_is_none_when_neither_candidate_exists() { + let dir = tempfile::tempdir().expect("create temp dir"); + assert_eq!(read_os_release(|name| candidate(dir.path(), name)), None); + } } diff --git a/crates/rocm-core/src/host_gpu.rs b/crates/rocm-core/src/host_gpu.rs index c985ed5358..f342ad3f9e 100644 --- a/crates/rocm-core/src/host_gpu.rs +++ b/crates/rocm-core/src/host_gpu.rs @@ -18,7 +18,7 @@ use crate::{ AppPaths, LegacyRocmSummary, TheRockFamilyManifest, detect_legacy_rocm_summary, - detect_managed_therock_family, discover_rocm_installs, examine, host_path, + detect_managed_therock_family, discover_rocm_installs, examine, hardware_root, host_path, managed_sdk_tool_path, runtime_is_linux, runtime_is_windows, runtime_os_name, unix_time_millis, }; use anyhow::Result; @@ -1969,7 +1969,7 @@ pub(crate) fn detect_distro_name() -> Option { if runtime_is_linux() { return Some(distro_name_from_os_release( - &fs::read_to_string(host_path("/etc/os-release")).ok()?, + &hardware_root::read_os_release(|p| host_path(p))?, )); } diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 953effd6f5..c9969fa21d 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -939,14 +939,16 @@ fn libnuma_install_hint_for(text: &str) -> InstallHint { install_hint_for(text, build_libnuma_install_plan, LIBNUMA_MANUAL_HINT) } -/// The real host's `/etc/os-release`, empty when it cannot be read. +/// The real host's `/etc/os-release`, falling back to `/usr/lib/os-release` +/// when the former is absent (per `os-release(5)`), empty when neither can be +/// read. /// /// Not routed through [`crate::host_path`]: the hints name package-manager /// commands for the real machine, so a simulated host root must not choose /// their distribution. #[cfg(target_os = "linux")] fn real_os_release() -> String { - std::fs::read_to_string("/etc/os-release").unwrap_or_default() + crate::hardware_root::read_os_release(|p| std::path::PathBuf::from(p)).unwrap_or_default() } const OPENMPI_MANUAL_HINT: &str = "install your distribution's OpenMPI runtime package (providing libmpi.so / libmpi_cxx.so and mpirun)"; diff --git a/docs/release-trust.md b/docs/release-trust.md index 3bb57583ed..b5d4429b9b 100644 --- a/docs/release-trust.md +++ b/docs/release-trust.md @@ -317,7 +317,8 @@ under `/sys/class/kfd`, the DRM cards under `/sys/class/drm`, `/sys/module/amdgpu` and its `version` file, `/proc/version`, `/proc/cpuinfo`, `/proc/meminfo`, `/proc/cmdline`, `/proc/modules`, `/proc/1/cgroup`, the container markers `/.dockerenv` and `/run/.containerenv`, the `/etc/os-release` -behind the distro fields and name `rocm examine` reports, the modprobe +(falling back to `/usr/lib/os-release` when absent, per `os-release(5)`) behind +the distro fields and name `rocm examine` reports, the modprobe configuration directories `/etc/modprobe.d`, `/usr/lib/modprobe.d` and `/run/modprobe.d`, the WSL plumbing under `/usr/lib/wsl` (the `lib` directory and `lib/libdxcore.so`), and the WSL ROCDXG capability check, which looks for @@ -350,11 +351,11 @@ Some reads stay on the real machine even in a hook build: two files under each discovered install's path inside the simulated root. - The `/usr/lib/wsl/lib` loader entry an engine is launched with, and programs the probes execute, such as `ldconfig`. -- Every package-manager plan, which reads the real `/etc/os-release`: the - OpenMPI, libatomic and libnuma install hints, and the driver, OpenMPI and - runtime-library installs `rocm` runs before serving. Their commands run - against the real machine, so a simulated host must not pick the distro they - are built for. +- Every package-manager plan, which reads the real `/etc/os-release` (with the + same `/usr/lib/os-release` fallback): the OpenMPI, libatomic and libnuma + install hints, and the driver, OpenMPI and runtime-library installs `rocm` + runs before serving. Their commands run against the real machine, so a + simulated host must not pick the distro they are built for. - Process liveness under `/proc/` and `/dev/shm` sizing. Both describe this process's own environment, not the hardware. diff --git a/docs/testing.md b/docs/testing.md index 1374b0bd51..5a41849419 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1576,6 +1576,18 @@ and the distro name it prints `rocm diagnose --distro` run from Windows, which has the WSL distribution's own `sh` source the file and reports what it assigned. +Every one of those readers goes through +[`hardware_root::read_os_release`](../crates/rocm-core/src/hardware_root.rs), +which reads `/etc/os-release` and, if that file does not exist, falls back to +`/usr/lib/os-release` per `os-release(5)` — a file present but unreadable (the +line-reporting cases below) does not fall back, since the fix there is to +correct the line, not to read a second file. The two reads this covers are +`os_release.rs`'s own: a probe routed through a simulated test root +(`rocm examine`'s distro fields and distro name) resolves both candidates +through `host_path`; a package-manager plan (the driver install, and the +OpenMPI/libatomic/libnuma installs and hints) always resolves both against the +real machine, for the same reason it never follows a simulated root at all. + A line that is not a plain assignment makes the whole file unreadable, and each reader names that line instead of reporting an unknown distro. Where the message asks for a fix, it also says what to change on the line: LF line @@ -1602,28 +1614,38 @@ cargo test -p rocm-core --lib os_release cargo test -p rocm-core --lib -- pretty_name_reads_as_sh_reads_it an_unreadable_os_release cargo test -p rocm-core --lib openmpi::tests cargo test -p rocm --bin rocm os_release -cargo test -p rocm-core --lib --features e2e-test-hooks os_release_reads_follow_the_simulated_host_root +cargo test -p rocm-core --lib hardware_root::tests::read_os_release +cargo test -p rocm-core --lib --features e2e-test-hooks os_release_reads_follow_the_simulated_host_root os_release_reads_fall_back_to_usr_lib_when_etc_is_absent ``` -The parser tests that compare against `/bin/sh` itself are Linux-only. The last -command plants a file under the simulated host root and checks that both -`rocm examine` reads answer from it through the shared parser; the feature it -needs is enabled only by its own CI step. +The parser tests that compare against `/bin/sh` itself are Linux-only. The +`hardware_root::tests::read_os_release*` tests check the fallback itself +(primary found, primary absent, neither found) against an injected temp +directory rather than the real host. The two `--features e2e-test-hooks` +tests plant a file under the simulated host root and check that both +`rocm examine` reads answer from it through the shared parser: the first at +`/etc/os-release`, the second with only `/usr/lib/os-release` present, so the +fallback is exercised through the real `host_path`-routed call sites, not just +the helper in isolation; the feature they need is enabled only by its own CI +step. `rocm examine` reads the file through the simulated host root (see Simulated Host Root in [release-trust.md](release-trust.md)), so scenarios -`examine-20` to `examine-23` in +`examine-20` to `examine-24` in [examine.feature](../tests/e2e-cucumber/features/examine.feature) plant one. `examine-23` also plants a GPU in the kernel topology and puts an `lspci` listing an empty bus on `PATH`, so `status: degraded` is checked on every Linux -lane, with or without a GPU: +lane, with or without a GPU. `examine-24` plants only `/usr/lib/os-release`, +with no `/etc/os-release` present, to check the `os-release(5)` fallback: ```bash -RUSTC_WRAPPER= cargo xtask e2e -- -n 'examine-2[0-3] ' +RUSTC_WRAPPER= cargo xtask e2e -- -n 'examine-2[0-4] ' ``` The install plans deliberately read the real file, so no scenario plants one -for them; their parsing is covered by the unit tests above. +for them, including for the fallback; their parsing is covered by the unit +tests above, and the fallback itself by `hardware_root`'s own unit tests, +since both now read through the same helper with an identity resolver. ## Model Fit Preflight diff --git a/tests/e2e-cucumber/features/examine.feature b/tests/e2e-cucumber/features/examine.feature index 34bdb8b5ca..7555f7440b 100644 --- a/tests/e2e-cucumber/features/examine.feature +++ b/tests/e2e-cucumber/features/examine.feature @@ -325,3 +325,14 @@ Feature: GPU detection and system inspection Given a GPU machine whose release file runs a command on line 3 When the user inspects that machine in machine-readable form Then the inspection's verdict is degraded, and its only failure is line 3 of the release file + + # `os-release(5)` says to read `/etc/os-release` and, if it does not exist, + # fall back to `/usr/lib/os-release`. This plants a simulated host root with + # only the fallback path populated, so a reader that stopped after the first + # candidate would see no file at all and report an unknown distribution. + @id:examine-falls-back-to-usr-lib-os-release @requires-os:linux + Scenario: examine-24 - The inspection falls back to /usr/lib/os-release when /etc/os-release is absent + Given a machine whose release file exists only at /usr/lib/os-release + When the user inspects that machine in machine-readable form + Then the inspection reports the distribution "ubuntu" version "24.04" named "Ubuntu 24.04 LTS" + And the inspection reports no trouble reading the release file diff --git a/tests/e2e-cucumber/tests/e2e/examine_steps.rs b/tests/e2e-cucumber/tests/e2e/examine_steps.rs index 067e1c11db..3ee41cbbec 100644 --- a/tests/e2e-cucumber/tests/e2e/examine_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/examine_steps.rs @@ -1296,6 +1296,32 @@ fn plant_os_release(world: &mut E2eWorld, body: &str) { .push(("ROCM_CLI_TEST_HOST_ROOT", root.into_os_string())); } +/// Plant `body` as `/usr/lib/os-release` under a simulated host root, with no +/// `/etc/os-release` present — the fallback `os-release(5)` defines, and the +/// one `plant_os_release` above does not exercise. +fn plant_os_release_fallback_only(world: &mut E2eWorld, body: &str) { + let root = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .join("host-root"); + std::fs::create_dir_all(root.join("usr/lib")).expect("failed to create planted /usr/lib"); + std::fs::write(root.join("usr/lib").join("os-release"), body) + .expect("failed to write planted os-release"); + world + .command_env + .push(("ROCM_CLI_TEST_HOST_ROOT", root.into_os_string())); +} + +#[given("a machine whose release file exists only at /usr/lib/os-release")] +async fn os_release_only_at_usr_lib(world: &mut E2eWorld) { + plant_os_release_fallback_only( + world, + "NAME=\"Ubuntu\"\nID=ubuntu\nVERSION_ID=\"24.04\"\nPRETTY_NAME=\"Ubuntu 24.04 LTS\"\n", + ); +} + #[given("a machine whose release file quotes every value in single quotes")] async fn os_release_single_quoted(world: &mut E2eWorld) { plant_os_release( From 838a521cdc5e0672af626ae94974eca957089fee Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Wed, 14 Oct 2026 09:53:30 +0000 Subject: [PATCH 02/18] fix: address review on os-release fallback - read_os_release_ignores_a_simulated_host_root compared against a raw /etc/os-release read, which would fail on exactly the /usr/lib/os-release-only hosts this fix supports; compare through the same fallback helper instead. - hardware_root::read_os_release fell back on any read error, not just absence; a permission-denied /etc/os-release could silently adopt a stale /usr/lib/os-release. Narrow to ErrorKind::NotFound. - The WSL remote-distro shell probe in examine.rs sources /etc/os-release directly in guest-side sh, a reader this fix missed. Apply the same existence-based fallback there, factored into a function so its logic can run under a real /bin/sh against test-controlled paths. Signed-off-by: Jussi Elo --- apps/rocm/src/runtime_install_finalize.rs | 7 +- crates/rocm-core/src/examine.rs | 80 ++++++++++++++++++++++- crates/rocm-core/src/hardware_root.rs | 30 ++++++++- 3 files changed, 112 insertions(+), 5 deletions(-) diff --git a/apps/rocm/src/runtime_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index e856854a19..f4c27e62aa 100644 --- a/apps/rocm/src/runtime_install_finalize.rs +++ b/apps/rocm/src/runtime_install_finalize.rs @@ -2120,9 +2120,14 @@ pub(crate) mod tests { !read.contains("planted-distro"), "read the simulated root's os-release: {read:?}" ); + // Not `fs::read_to_string("/etc/os-release")` directly: on a host that + // is itself one of the `/usr/lib/os-release`-only machines this fix + // supports, that would compare against an empty string while `read` + // correctly holds the real fallback file's contents, failing the + // assertion on exactly the configuration this test means to allow. assert_eq!( read, - fs::read_to_string("/etc/os-release").unwrap_or_default() + rocm_core::hardware_root::read_os_release(|p| PathBuf::from(p)).unwrap_or_default() ); } diff --git a/crates/rocm-core/src/examine.rs b/crates/rocm-core/src/examine.rs index a49d9ca9cc..7cd489ef3c 100644 --- a/crates/rocm-core/src/examine.rs +++ b/crates/rocm-core/src/examine.rs @@ -822,6 +822,12 @@ fn host_driver_fields(probe: crate::WslHostDriverProbe) -> (bool, Option /// /// `librocdxg` is globbed across `/opt/rocm*` for the same reason the in-guest /// probe resolves it across installs: a versioned root must not read as missing. +/// +/// The distro's `id`/`version` fields fall back from `/etc/os-release` to +/// `/usr/lib/os-release` per `os-release(5)`, matching every other reader in +/// this crate — this is the one that runs inside the distro over `wsl.exe` +/// rather than through [`crate::host_path`], so it needs its own copy of the +/// fallback rather than sharing `hardware_root::read_os_release`. const WSL_REMOTE_PROBE: &str = r#" echo "kernel=$(uname -r 2>/dev/null)" if [ -e /dev/dxg ]; then echo dxg=1; else echo dxg=0; fi @@ -843,11 +849,28 @@ if command -v rocminfo >/dev/null 2>&1; then else echo rocminfo=0 fi -. /etc/os-release 2>/dev/null +try_os_release() { + if [ -e "$1" ]; then . "$1" 2>/dev/null + elif [ -e "$2" ]; then . "$2" 2>/dev/null + fi +} +try_os_release /etc/os-release /usr/lib/os-release echo "id=${ID}" echo "version=${VERSION_ID}" "#; +/// The `try_os_release` shell function embedded in [`WSL_REMOTE_PROBE`]: sources +/// `$1`, falling back to `$2` per `os-release(5)` when `$1` does not exist — an +/// existence check (`[ -e ... ]`), not a readability one, so a permission-denied +/// primary is not silently replaced by a possibly stale fallback. +/// +/// Duplicated as its own constant, with the paths left as parameters, so the +/// test below can run this exact function body against temp-directory paths +/// instead of the real `/etc`; [`try_os_release_fn_is_embedded_in_the_wsl_remote_probe`] +/// guards against the two drifting apart. +#[cfg(test)] +const TRY_OS_RELEASE_FN: &str = "try_os_release() {\n if [ -e \"$1\" ]; then . \"$1\" 2>/dev/null\n elif [ -e \"$2\" ]; then . \"$2\" 2>/dev/null\n fi\n}"; + /// Parse `wsl.exe -l -q` into distribution names. /// /// `-q` prints one bare name per line, so the whole line is the name. It is NOT @@ -5718,6 +5741,61 @@ mod tests { ); assert_eq!(name.as_deref(), Some("Fallback 1.2")); } + + /// Guards [`TRY_OS_RELEASE_FN`] against drifting from the copy embedded in + /// [`WSL_REMOTE_PROBE`]: the test below exercises the standalone constant, + /// so if a future edit touches one and not the other, this catches it + /// rather than the test silently proving the wrong logic. + #[test] + fn try_os_release_fn_is_embedded_in_the_wsl_remote_probe() { + assert!( + WSL_REMOTE_PROBE.contains(TRY_OS_RELEASE_FN), + "WSL_REMOTE_PROBE's os-release handling has drifted from the tested function" + ); + } + + /// The WSL remote probe's `try_os_release` shell function, run for real + /// under `/bin/sh` against temp-directory paths rather than the real + /// `/etc`: it sources the first path that exists, falling back to the + /// second only when the first is absent, matching `os-release(5)` and the + /// Rust-side `hardware_root::read_os_release`. + #[cfg(target_os = "linux")] + #[test] + fn try_os_release_sources_the_fallback_only_when_the_primary_is_absent() { + let dir = tempfile::tempdir().expect("create temp dir"); + let primary = dir.path().join("primary"); + let fallback = dir.path().join("fallback"); + std::fs::write(&fallback, "ID=fallback\n").expect("write fallback"); + + let script = format!("{TRY_OS_RELEASE_FN}\ntry_os_release \"$1\" \"$2\"\necho \"id=$ID\""); + let run = || { + std::process::Command::new("sh") + .arg("-c") + .arg(&script) + .arg("sh") + .arg(&primary) + .arg(&fallback) + .output() + .expect("run sh") + }; + + let before = run(); + assert_eq!( + String::from_utf8_lossy(&before.stdout).trim(), + "id=fallback", + "stderr: {}", + String::from_utf8_lossy(&before.stderr) + ); + + std::fs::write(&primary, "ID=primary\n").expect("write primary"); + let after = run(); + assert_eq!( + String::from_utf8_lossy(&after.stdout).trim(), + "id=primary", + "stderr: {}", + String::from_utf8_lossy(&after.stderr) + ); + } } /// Property tests for the driver-side text readers above; a child module so it diff --git a/crates/rocm-core/src/hardware_root.rs b/crates/rocm-core/src/hardware_root.rs index 135f84b7a5..f0e8f1c379 100644 --- a/crates/rocm-core/src/hardware_root.rs +++ b/crates/rocm-core/src/hardware_root.rs @@ -120,10 +120,21 @@ fn host_path_under(root: Option<&Path>, path: &Path) -> PathBuf { /// [`host_path`] for a probe that must honour a simulated test root, or the /// identity for one that must always read the real machine (see the module /// doc above). +/// +/// Falls back only when `/etc/os-release` does not exist, never for another +/// read error (permission denied, a directory in its place, ...): `os-release(5)` +/// defines the fallback as existence-based, and treating any error the same +/// way would silently build commands for the wrong distro from a stale +/// `/usr/lib/os-release` on a host where `/etc/os-release` exists but is +/// merely unreadable. pub fn read_os_release(resolve: impl Fn(&str) -> PathBuf) -> Option { - ["/etc/os-release", "/usr/lib/os-release"] - .into_iter() - .find_map(|candidate| std::fs::read_to_string(resolve(candidate)).ok()) + match std::fs::read_to_string(resolve("/etc/os-release")) { + Ok(text) => Some(text), + Err(err) if err.kind() == std::io::ErrorKind::NotFound => { + std::fs::read_to_string(resolve("/usr/lib/os-release")).ok() + } + Err(_) => None, + } } /// Serialises every test that sets [`TEST_HOST_ROOT_ENV`], including the @@ -236,4 +247,17 @@ mod tests { let dir = tempfile::tempdir().expect("create temp dir"); assert_eq!(read_os_release(|name| candidate(dir.path(), name)), None); } + + /// A primary that exists but fails to read for a reason other than + /// absence (here, a directory in its place) must not fall back: that + /// would silently build commands for the wrong distro from a fallback + /// file that may not describe this host at all. A directory read as a + /// file is a portable, root-free way to get a non-`NotFound` `io::Error`. + #[test] + fn read_os_release_does_not_fall_back_when_the_primary_errors_for_another_reason() { + let dir = tempfile::tempdir().expect("create temp dir"); + std::fs::create_dir(dir.path().join("primary")).expect("create primary as a directory"); + std::fs::write(dir.path().join("fallback"), "ID=fallback\n").expect("write fallback"); + assert_eq!(read_os_release(|name| candidate(dir.path(), name)), None); + } } From 5f2c3ffc38644011c5405fcfdac7e17ac690f30e Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Wed, 14 Oct 2026 13:34:49 +0000 Subject: [PATCH 03/18] fix: name the file a fallback read actually read, not always /etc/os-release Every message that reports an unreadable os-release line hardcoded "/etc/os-release", even when the text came from the /usr/lib/os-release fallback this PR adds. Fix that by threading which candidate was actually read through hardware_root::read_os_release's new OsRelease return type (Found/Absent/Unreadable) into every message-building call site: the driver install plan, the OpenMPI/libatomic/libnuma install plans and hints, and rocm examine's distro fields and distro name. The same type change closes a second gap: a file that exists but cannot be read (permission denied, a directory in its place) was previously indistinguishable from an unknown distribution by the time it reached these call sites, since every caller discarded the read error with unwrap_or_default(). It is now reported as itself. Also: - add a test exercising the WSL remote probe's try_os_release shell function against a primary that exists but errors, mirroring the existing non-absence case on the Rust side - add tests pinning that a fallback-sourced read plans and hints identically to a primary-sourced read with the same text, at the one seam the real call sites (which must always read the real machine and so can't honour a simulated root) hand their result to - fix a dangling doc reference to rocm_core::detect_distro_name, which is pub(crate) and unreachable from apps/rocm - fix two testing.md wording bugs: a misattribution of two file reads to os_release.rs, which does no file reads, and a blanket "every reader" claim contradicting the WSL-probe exception stated two sentences earlier Signed-off-by: Jussi Elo --- apps/rocm/src/driver_install.rs | 145 +++++++++++++- apps/rocm/src/runtime_install_finalize.rs | 32 ++-- crates/rocm-core/src/examine.rs | 95 ++++++++-- crates/rocm-core/src/hardware_root.rs | 128 +++++++++++-- crates/rocm-core/src/host_gpu.rs | 69 +++++-- crates/rocm-core/src/openmpi.rs | 221 ++++++++++++++++++---- docs/testing.md | 91 ++++++--- 7 files changed, 654 insertions(+), 127 deletions(-) diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 7c7c1bb812..bf0d006cc3 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -35,11 +35,15 @@ pub(crate) fn install_driver( ) -> std::result::Result { let examine = ExamineSummary::gather().map_err(|source| DriverInstallError::new(source, false))?; - let os_release = read_os_release().unwrap_or_default(); + let os_release = read_os_release(); // The only place the real privilege level is read; every builder below takes // it as a parameter so both branches stay testable on any host. - let plan = - build_driver_install_plan(&examine, &os_release, dkms, PrivilegeEscalation::detect()); + let plan = build_driver_install_plan_read( + &examine, + &os_release, + dkms, + PrivilegeEscalation::detect(), + ); let mut output = render_driver_install_plan(&plan, yes, dry_run); if !yes || dry_run || !plan.supported || !plan.mutating { return Ok(DriverInstallResult { @@ -798,11 +802,29 @@ fn wsl_rocdxg_driver_plan(escalation: PrivilegeEscalation) -> DriverInstallPlan } } +/// [`build_driver_install_plan_at`], naming `/etc/os-release` in any +/// unreadable-line message. Only the unit tests fixturing bare +/// `os_release_text` (never the real host) use this one; the real call site +/// in [`install_driver`] knows the path it actually read and calls +/// [`build_driver_install_plan_read`] directly. +#[cfg(test)] fn build_driver_install_plan( examine: &ExamineSummary, os_release_text: &str, dkms: bool, escalation: PrivilegeEscalation, +) -> DriverInstallPlan { + build_driver_install_plan_at(examine, "/etc/os-release", os_release_text, dkms, escalation) +} + +/// [`build_driver_install_plan`], 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 { // Resolve the AMD graphics version and amdgpu-install package release once, // here at plan-build time, so the concrete values are baked into both the @@ -850,7 +872,7 @@ fn build_driver_install_plan( codename: String::new(), repo_version, reason: format!( - "/etc/os-release {unreadable}; no driver commands were planned \ + "{os_release_path} {unreadable}; no driver commands were planned \ because the distro cannot be read. To fix it, {}.", unreadable.fix() ), @@ -971,6 +993,49 @@ fn build_driver_install_plan( } } +/// [`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 + { + return DriverInstallPlan { + supported: false, + mutating: false, + policy: "unreadable_os_release".to_owned(), + os_id: String::new(), + version_id: String::new(), + codename: String::new(), + repo_version: resolve_shell_default_template("${ROCM_CLI_AMDGPU_VERSION:-7.2.4}"), + reason: format!( + "{path} could not be read: {error}; no driver commands were planned \ + because the distro cannot be read." + ), + preflight_checks: Vec::new(), + commands: Vec::new(), + checks: vec!["rocm examine".to_owned()], + reboot_required: false, + }; + } + 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. /// @@ -1875,6 +1940,78 @@ mod tests { ); } + /// `build_driver_install_plan_read` is the one seam `install_driver` hands + /// its `read_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." + ); + } + /// 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`. diff --git a/apps/rocm/src/runtime_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index f4c27e62aa..3507bae111 100644 --- a/apps/rocm/src/runtime_install_finalize.rs +++ b/apps/rocm/src/runtime_install_finalize.rs @@ -155,10 +155,10 @@ pub(crate) const fn empty_as_unknown(value: &str) -> &str { /// a package-manager plan (`apt`, `dnf`, `amdgpu-install`) 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 -/// `rocm_core::detect_distro_name`, which does follow a simulated root. -pub(crate) fn read_os_release() -> Result { +/// `ExamineSummary::gather`'s `distro` field, which does follow a simulated +/// root. +pub(crate) fn read_os_release() -> rocm_core::hardware_root::OsRelease { rocm_core::hardware_root::read_os_release(|p| PathBuf::from(p)) - .context("failed to read /etc/os-release or /usr/lib/os-release") } /// Run a command given as an argv vector directly, without going through a shell. @@ -203,8 +203,8 @@ pub(crate) fn ensure_openmpi_for_vllm(approved: bool) -> Result<()> { return Ok(()); } - let plan = rocm_core::openmpi::plan_for_os_release( - &read_os_release().unwrap_or_default(), + let plan = rocm_core::openmpi::plan_for_os_release_read( + &read_os_release(), rocm_core::openmpi::build_openmpi_install_plan, ); @@ -378,10 +378,7 @@ fn ensure_torch_runtime_dep(approved: bool, dep: &TorchRuntimeDep) { return; } - let plan = rocm_core::openmpi::plan_for_os_release( - &read_os_release().unwrap_or_default(), - dep.build_plan, - ); + let plan = rocm_core::openmpi::plan_for_os_release_read(&read_os_release(), dep.build_plan); println!("{} setup", dep.name); println!(" reason: {}", dep.reason); @@ -2112,23 +2109,26 @@ pub(crate) mod tests { rocm_core::hardware_root::TEST_HOST_ROOT_ENV, &root.to_string_lossy(), ); - read_os_release().unwrap_or_default() + read_os_release() }; fs::remove_dir_all(&root).ok(); assert!( - !read.contains("planted-distro"), - "read the simulated root's os-release: {read:?}" + !read.text().contains("planted-distro"), + "read the simulated root's os-release: {:?}", + read.text() ); // Not `fs::read_to_string("/etc/os-release")` directly: on a host that // is itself one of the `/usr/lib/os-release`-only machines this fix // supports, that would compare against an empty string while `read` // correctly holds the real fallback file's contents, failing the // assertion on exactly the configuration this test means to allow. - assert_eq!( - read, - rocm_core::hardware_root::read_os_release(|p| PathBuf::from(p)).unwrap_or_default() - ); + // Compared by `(path, text)` rather than `OsRelease` itself: an + // `Unreadable` variant carries an `io::Error`, which has no + // `PartialEq`, and the path/text pair is what this test means to pin + // regardless. + let real = rocm_core::hardware_root::read_os_release(|p| PathBuf::from(p)); + assert_eq!((read.path(), read.text()), (real.path(), real.text())); } // The install report is only as honest as the reconciliation that reaches diff --git a/crates/rocm-core/src/examine.rs b/crates/rocm-core/src/examine.rs index 7cd489ef3c..1c5b210694 100644 --- a/crates/rocm-core/src/examine.rs +++ b/crates/rocm-core/src/examine.rs @@ -730,7 +730,7 @@ fn probe_os(e: &mut Examination) { e.kernel_cmdline = read_host_text("/proc/cmdline").trim().to_owned(); record_distro( e, - &crate::hardware_root::read_os_release(|p| crate::host_path(p)).unwrap_or_default(), + &crate::hardware_root::read_os_release(|p| crate::host_path(p)), ); if let Some(param) = parse_iommu_param(&e.kernel_cmdline) { e.iommu_kernel_param = param; @@ -746,21 +746,30 @@ fn probe_os(e: &mut Examination) { } } -/// Fill the distro fields from os-release `text`, through the same parser the -/// driver plan uses, so the two report the same distro. +/// Fill the distro fields from `read`, through the same parser the driver +/// plan uses, so the two report the same distro. /// -/// An unreadable file leaves both fields empty and says why in -/// `probe_failures`, naming the line — an empty distro with no explanation -/// would read as "nothing to report" rather than "something to fix". A missing -/// file reads as empty text, which is not a failure. -fn record_distro(e: &mut Examination, text: &str) { - match crate::os_release::parse(text) { +/// An unreadable line leaves both fields empty and says why in +/// `probe_failures`, naming the file actually read and the line — an empty +/// distro with no explanation would read as "nothing to report" rather than +/// "something to fix". A missing file reads as empty text, which is not a +/// failure; a file that exists but could not be read is, and is reported as +/// itself rather than as an unreadable line it never reached. +fn record_distro(e: &mut Examination, read: &crate::hardware_root::OsRelease) { + if let crate::hardware_root::OsRelease::Unreadable { path, error } = read { + e.probe_failures.push(format!( + "{path} could not be read: {error}; the distro is not reported." + )); + return; + } + match crate::os_release::parse(read.text()) { Ok(mut fields) => { e.distro_id = fields.remove("ID").unwrap_or_default(); e.distro_version = fields.remove("VERSION_ID").unwrap_or_default(); } Err(unreadable) => e.probe_failures.push(format!( - "/etc/os-release {unreadable}; the distro is not reported." + "{} {unreadable}; the distro is not reported.", + read.path() )), } } @@ -3119,7 +3128,9 @@ mod tests { let mut e = linux_host_with_a_gpu(); record_distro( &mut e, - "ID=ubuntu\nVERSION_ID=\"24.04\"\nexport ID=debian\n", + &crate::hardware_root::OsRelease::found( + "ID=ubuntu\nVERSION_ID=\"24.04\"\nexport ID=debian\n", + ), ); assert_eq!( e.probe_failures, @@ -3133,7 +3144,10 @@ mod tests { assert_eq!(e.compute_status(), "degraded"); let mut e = linux_host_with_a_gpu(); - record_distro(&mut e, "ID='ubuntu'\nVERSION_ID='24.04' # LTS\n"); + record_distro( + &mut e, + &crate::hardware_root::OsRelease::found("ID='ubuntu'\nVERSION_ID='24.04' # LTS\n"), + ); assert!(e.probe_failures.is_empty(), "{:?}", e.probe_failures); assert_eq!( (e.distro_id.as_str(), e.distro_version.as_str()), @@ -3143,10 +3157,32 @@ mod tests { // No file at all is not a failure: there is nothing to fix. let mut e = Examination::default(); - record_distro(&mut e, ""); + record_distro(&mut e, &crate::hardware_root::OsRelease::Absent); assert!(e.probe_failures.is_empty(), "{:?}", e.probe_failures); } + /// A file that exists but could not be read is reported as itself — not + /// folded into an empty, unreported distro the way `Absent` is, and not + /// pointing at the wrong candidate when the fallback was the one that + /// failed. + #[test] + fn an_unreadable_file_names_itself_instead_of_a_distro() { + let mut e = linux_host_with_a_gpu(); + record_distro( + &mut e, + &crate::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }, + ); + assert_eq!( + e.probe_failures, + vec!["/usr/lib/os-release could not be read: denied; the distro is not reported.".to_owned()] + ); + assert_eq!((e.distro_id.as_str(), e.distro_version.as_str()), ("", "")); + assert_eq!(e.compute_status(), "degraded"); + } + /// Serialises the tests that read or replace the process-global /// `RUNTIME_LIBRARY_PATH_ENV` while they run. Env is shared by every test /// thread, so a test that sets it and one that composes a child env from it @@ -5796,6 +5832,39 @@ mod tests { String::from_utf8_lossy(&after.stderr) ); } + + /// `[ -e "$1" ]` is an existence check, not a readability one: a primary + /// that exists but cannot be sourced (here, a directory in its place, the + /// same portable non-readable fixture the Rust-side test above uses) + /// must not fall through to the `elif` and source the fallback — that + /// would silently read a file that may not describe this host, matching + /// `hardware_root::read_os_release`'s own non-absence rule. + #[cfg(target_os = "linux")] + #[test] + fn try_os_release_does_not_source_the_fallback_when_the_primary_exists_but_errors() { + let dir = tempfile::tempdir().expect("create temp dir"); + let primary = dir.path().join("primary"); + let fallback = dir.path().join("fallback"); + std::fs::create_dir(&primary).expect("create primary as a directory"); + std::fs::write(&fallback, "ID=fallback\n").expect("write fallback"); + + let script = format!("{TRY_OS_RELEASE_FN}\ntry_os_release \"$1\" \"$2\"\necho \"id=$ID\""); + let output = std::process::Command::new("sh") + .arg("-c") + .arg(&script) + .arg("sh") + .arg(&primary) + .arg(&fallback) + .output() + .expect("run sh"); + + assert_eq!( + String::from_utf8_lossy(&output.stdout).trim(), + "id=", + "stderr: {}", + String::from_utf8_lossy(&output.stderr) + ); + } } /// Property tests for the driver-side text readers above; a child module so it diff --git a/crates/rocm-core/src/hardware_root.rs b/crates/rocm-core/src/hardware_root.rs index f0e8f1c379..1e6c61fdd4 100644 --- a/crates/rocm-core/src/hardware_root.rs +++ b/crates/rocm-core/src/hardware_root.rs @@ -113,6 +113,65 @@ fn host_path_under(root: Option<&Path>, path: &Path) -> PathBuf { } } +/// What reading `/etc/os-release` (falling back to `/usr/lib/os-release` per +/// `os-release(5)`) produced. +/// +/// Kept as three states, not collapsed to `Option`, so a caller can +/// name the file it actually read in a parse-error message (`Found`'s `path`) +/// and can tell "nothing to report" (`Absent`, the documented fallback +/// contract: a missing file is not a failure) apart from "something is +/// wrong" (`Unreadable`: a candidate exists but could not be read). Before +/// this distinction existed, every caller folded both into the same empty +/// text and reported a host with a merely-unreadable file as an unsupported +/// distribution. +#[derive(Debug)] +pub enum OsRelease { + /// Read from `path` (`/etc/os-release` or `/usr/lib/os-release`). + Found { path: &'static str, text: String }, + /// Neither candidate exists. + Absent, + /// `path` exists but could not be read, for a reason other than absence + /// (permission denied, a directory in its place, ...). + Unreadable { + path: &'static str, + error: std::io::Error, + }, +} + +impl OsRelease { + /// The text to parse: the file's contents when one was read, empty for + /// [`Self::Absent`] or [`Self::Unreadable`] — an absent file declares + /// nothing, and an unreadable one must be reported as itself by the + /// caller rather than parsed as an empty, unknown distribution. + #[must_use] + pub fn text(&self) -> &str { + match self { + Self::Found { text, .. } => text, + Self::Absent | Self::Unreadable { .. } => "", + } + } + + /// The path a parse-error message should name: the one actually read, or + /// `/etc/os-release` for [`Self::Absent`] — which never reaches such a + /// message, since empty text never fails to parse. + #[must_use] + pub const fn path(&self) -> &'static str { + match self { + Self::Found { path, .. } | Self::Unreadable { path, .. } => path, + Self::Absent => "/etc/os-release", + } + } + + /// For tests: a [`Self::Found`] at the default `/etc/os-release` path. + #[cfg(test)] + pub(crate) fn found(text: impl Into) -> Self { + Self::Found { + path: "/etc/os-release", + text: text.into(), + } + } +} + /// Reads `/etc/os-release`, falling back to `/usr/lib/os-release` per /// `os-release(5)` when the former is absent. /// @@ -127,13 +186,29 @@ fn host_path_under(root: Option<&Path>, path: &Path) -> PathBuf { /// way would silently build commands for the wrong distro from a stale /// `/usr/lib/os-release` on a host where `/etc/os-release` exists but is /// merely unreadable. -pub fn read_os_release(resolve: impl Fn(&str) -> PathBuf) -> Option { +pub fn read_os_release(resolve: impl Fn(&str) -> PathBuf) -> OsRelease { match std::fs::read_to_string(resolve("/etc/os-release")) { - Ok(text) => Some(text), + Ok(text) => OsRelease::Found { + path: "/etc/os-release", + text, + }, Err(err) if err.kind() == std::io::ErrorKind::NotFound => { - std::fs::read_to_string(resolve("/usr/lib/os-release")).ok() + match std::fs::read_to_string(resolve("/usr/lib/os-release")) { + Ok(text) => OsRelease::Found { + path: "/usr/lib/os-release", + text, + }, + Err(err) if err.kind() == std::io::ErrorKind::NotFound => OsRelease::Absent, + Err(error) => OsRelease::Unreadable { + path: "/usr/lib/os-release", + error, + }, + } } - Err(_) => None, + Err(error) => OsRelease::Unreadable { + path: "/etc/os-release", + error, + }, } } @@ -221,14 +296,24 @@ mod tests { } } + /// Extracts `(path, text)` from a [`OsRelease::Found`], panicking on any + /// other variant — the shape every "a candidate was read" assertion below + /// wants, written once so each test states only what differs. + fn found(read: OsRelease) -> (&'static str, String) { + match read { + OsRelease::Found { path, text } => (path, text), + other => panic!("expected OsRelease::Found, got {other:?}"), + } + } + #[test] fn read_os_release_prefers_the_primary_candidate() { let dir = tempfile::tempdir().expect("create temp dir"); std::fs::write(dir.path().join("primary"), "ID=primary\n").expect("write primary"); std::fs::write(dir.path().join("fallback"), "ID=fallback\n").expect("write fallback"); assert_eq!( - read_os_release(|name| candidate(dir.path(), name)), - Some("ID=primary\n".to_owned()) + found(read_os_release(|name| candidate(dir.path(), name))), + ("/etc/os-release", "ID=primary\n".to_owned()) ); } @@ -237,15 +322,18 @@ mod tests { let dir = tempfile::tempdir().expect("create temp dir"); std::fs::write(dir.path().join("fallback"), "ID=fallback\n").expect("write fallback"); assert_eq!( - read_os_release(|name| candidate(dir.path(), name)), - Some("ID=fallback\n".to_owned()) + found(read_os_release(|name| candidate(dir.path(), name))), + ("/usr/lib/os-release", "ID=fallback\n".to_owned()) ); } #[test] - fn read_os_release_is_none_when_neither_candidate_exists() { + fn read_os_release_is_absent_when_neither_candidate_exists() { let dir = tempfile::tempdir().expect("create temp dir"); - assert_eq!(read_os_release(|name| candidate(dir.path(), name)), None); + assert!(matches!( + read_os_release(|name| candidate(dir.path(), name)), + OsRelease::Absent + )); } /// A primary that exists but fails to read for a reason other than @@ -253,11 +341,29 @@ mod tests { /// would silently build commands for the wrong distro from a fallback /// file that may not describe this host at all. A directory read as a /// file is a portable, root-free way to get a non-`NotFound` `io::Error`. + /// It must also be reported as itself, not folded into `Absent`: an + /// unreadable file is not "nothing to report". #[test] fn read_os_release_does_not_fall_back_when_the_primary_errors_for_another_reason() { let dir = tempfile::tempdir().expect("create temp dir"); std::fs::create_dir(dir.path().join("primary")).expect("create primary as a directory"); std::fs::write(dir.path().join("fallback"), "ID=fallback\n").expect("write fallback"); - assert_eq!(read_os_release(|name| candidate(dir.path(), name)), None); + match read_os_release(|name| candidate(dir.path(), name)) { + OsRelease::Unreadable { path, .. } => assert_eq!(path, "/etc/os-release"), + other => panic!("expected OsRelease::Unreadable, got {other:?}"), + } + } + + /// The same non-absence distinction, but on the fallback candidate: a + /// primary that is genuinely absent and a fallback that exists but + /// cannot be read must not read as `Absent` either. + #[test] + fn read_os_release_reports_the_fallback_as_unreadable_when_it_errors_for_another_reason() { + let dir = tempfile::tempdir().expect("create temp dir"); + std::fs::create_dir(dir.path().join("fallback")).expect("create fallback as a directory"); + match read_os_release(|name| candidate(dir.path(), name)) { + OsRelease::Unreadable { path, .. } => assert_eq!(path, "/usr/lib/os-release"), + other => panic!("expected OsRelease::Unreadable, got {other:?}"), + } } } diff --git a/crates/rocm-core/src/host_gpu.rs b/crates/rocm-core/src/host_gpu.rs index f342ad3f9e..84ae58dee7 100644 --- a/crates/rocm-core/src/host_gpu.rs +++ b/crates/rocm-core/src/host_gpu.rs @@ -1968,28 +1968,38 @@ pub(crate) fn detect_distro_name() -> Option { } if runtime_is_linux() { - return Some(distro_name_from_os_release( - &hardware_root::read_os_release(|p| host_path(p))?, - )); + return match hardware_root::read_os_release(|p| host_path(p)) { + // Absent matches the pre-fallback behaviour this function has + // always had: no file at all leaves the distro name unknown + // entirely, rather than reporting "Linux" for a machine that + // might not even be running a standard distro. + hardware_root::OsRelease::Absent => None, + read => Some(distro_name_from_os_release(&read)), + }; } None } -/// The distribution name `rocm examine` prints, from os-release `text`: -/// `PRETTY_NAME` as `sh` reads it, else `Linux`. +/// The distribution name `rocm examine` prints, from `read`: `PRETTY_NAME` as +/// `sh` reads it, else `Linux`. /// -/// An unreadable file says which line made it so, on the line a person reads -/// — `rocm examine`'s `probe_failures`, which carries the same reason, is only -/// in the `--json` form. A blank `PRETTY_NAME` also falls back to `Linux`. -fn distro_name_from_os_release(text: &str) -> String { - match crate::os_release::parse(text) { +/// An unreadable line says which file and line made it so, on the line a +/// person reads — `rocm examine`'s `probe_failures`, which carries the same +/// reason, is only in the `--json` form. A blank `PRETTY_NAME` also falls +/// back to `Linux`. A file that exists but could not be read at all is +/// reported as itself, distinctly from a bad line it never reached. +fn distro_name_from_os_release(read: &hardware_root::OsRelease) -> String { + if let hardware_root::OsRelease::Unreadable { path, error } = read { + return format!("Linux ({path} could not be read: {error})"); + } + match crate::os_release::parse(read.text()) { Ok(mut fields) => fields .remove("PRETTY_NAME") .map(|value| value.trim().to_owned()) .filter(|value| !value.is_empty()) .unwrap_or_else(|| "Linux".to_owned()), - Err(unreadable) => format!("Linux (/etc/os-release {unreadable})"), + Err(unreadable) => format!("Linux ({} {unreadable})", read.path()), } } @@ -4787,7 +4797,9 @@ Class Name: Display #[test] fn parses_os_release_pretty_name() { assert_eq!( - distro_name_from_os_release("NAME=Ubuntu\nPRETTY_NAME=\"Ubuntu 24.04.2 LTS\"\n"), + distro_name_from_os_release(&hardware_root::OsRelease::found( + "NAME=Ubuntu\nPRETTY_NAME=\"Ubuntu 24.04.2 LTS\"\n" + )), "Ubuntu 24.04.2 LTS" ); } @@ -4800,17 +4812,40 @@ Class Name: Display #[test] fn pretty_name_reads_as_sh_reads_it() { assert_eq!( - distro_name_from_os_release( + distro_name_from_os_release(&hardware_root::OsRelease::found( "PRETTY_NAME=\"Debian GNU/Linux 12\"\nPRETTY_NAME='Ubuntu 24.04 LTS' # LTS\n" - ), + )), "Ubuntu 24.04 LTS" ); assert_eq!( - distro_name_from_os_release("PRETTY_NAME=\"Ubuntu 24.04 LTS\"\nunset ID\n"), + distro_name_from_os_release(&hardware_root::OsRelease::found( + "PRETTY_NAME=\"Ubuntu 24.04 LTS\"\nunset ID\n" + )), "Linux (/etc/os-release line 2 is not a plain assignment: \"unset ID\")" ); - assert_eq!(distro_name_from_os_release("PRETTY_NAME=\" \"\n"), "Linux"); - assert_eq!(distro_name_from_os_release("ID=ubuntu\n"), "Linux"); + assert_eq!( + distro_name_from_os_release(&hardware_root::OsRelease::found("PRETTY_NAME=\" \"\n")), + "Linux" + ); + assert_eq!( + distro_name_from_os_release(&hardware_root::OsRelease::found("ID=ubuntu\n")), + "Linux" + ); + } + + /// A file that exists but could not be read names itself and the error, + /// distinctly from a bad line it never reached and from "no file at all" + /// — which `detect_distro_name` keeps reporting as unknown, unchanged by + /// this PR (see its own doc comment). + #[test] + fn distro_name_names_an_unreadable_file_instead_of_guessing_linux() { + assert_eq!( + distro_name_from_os_release(&hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }), + "Linux (/usr/lib/os-release could not be read: denied)" + ); } #[test] diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index c9969fa21d..123678b08a 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -827,7 +827,22 @@ pub fn build_libnuma_install_plan(os_id: &str, id_like: &str) -> SystemPackageIn /// `ID_LIKE` to the plan that installs one runtime on it. pub type InstallPlanBuilder = fn(&str, &str) -> SystemPackageInstallPlan; -/// `build`'s plan for the distribution os-release `text` declares. +/// `build`'s plan for the distribution os-release `text` declares, naming +/// `/etc/os-release` in any unreadable-line message. +/// +/// Delegates to [`plan_for_os_release_at`] with that default path; a caller +/// that actually read the file — which may have come from the +/// `/usr/lib/os-release` fallback — uses that function directly so an +/// unreadable line names the file really read rather than always the +/// primary. The many unit tests fixturing bare `text` (never the real host) +/// keep using this one. +#[must_use] +pub fn plan_for_os_release(text: &str, build: InstallPlanBuilder) -> SystemPackageInstallPlan { + plan_for_os_release_at("/etc/os-release", text, build) +} + +/// [`plan_for_os_release`], naming `path` instead of always `/etc/os-release` +/// in an unreadable-line message. /// /// An unreadable file (see [`crate::os_release`]) plans nothing, and the /// reason names the line that made it unreadable and what to change on it, @@ -835,13 +850,17 @@ pub type InstallPlanBuilder = fn(&str, &str) -> SystemPackageInstallPlan; /// Without that, the plan would blame the distribution for what is a fixable /// line in the file. #[must_use] -pub fn plan_for_os_release(text: &str, build: InstallPlanBuilder) -> SystemPackageInstallPlan { +pub fn plan_for_os_release_at( + path: &str, + text: &str, + build: InstallPlanBuilder, +) -> SystemPackageInstallPlan { match crate::os_release::id_and_id_like(text) { Ok((os_id, id_like)) => build(&os_id, &id_like), Err(unreadable) => { let mut plan = build("", ""); plan.reason = format!( - "/etc/os-release {unreadable}, so the distribution cannot be read; to fix it, {}. {}", + "{path} {unreadable}, so the distribution cannot be read; to fix it, {}. {}", unreadable.fix(), plan.reason ); @@ -850,6 +869,31 @@ pub fn plan_for_os_release(text: &str, build: InstallPlanBuilder) -> SystemPacka } } +/// [`plan_for_os_release_at`] for `read`. +/// +/// Names the file actually read in an unreadable-line message, and reports 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 "Could not map distribution (ID=)" — the same message an +/// actually unknown distribution gets — sending the user looking for a +/// support gap instead of a filesystem problem. +#[must_use] +pub fn plan_for_os_release_read( + read: &crate::hardware_root::OsRelease, + build: InstallPlanBuilder, +) -> SystemPackageInstallPlan { + if let crate::hardware_root::OsRelease::Unreadable { path, error } = read { + let mut plan = build("", ""); + plan.reason = format!( + "{path} could not be read: {error}, so the distribution cannot be read. {}", + plan.reason + ); + return plan; + } + plan_for_os_release_at(read.path(), read.text(), build) +} + /// What a user missing a runtime is told to do, and whether the plan behind /// the advice installs anything. /// @@ -885,24 +929,39 @@ impl std::fmt::Display for InstallHint { } } -/// The hint for os-release `text`: the commands [`plan_for_os_release`] plans -/// with `build` when it plans any, otherwise `manual` — followed, for an +/// The hint for os-release `text`, naming `/etc/os-release` in any +/// unreadable-line message: the commands [`plan_for_os_release`] plans with +/// `build` when it plans any, otherwise `manual` — followed, for an /// unreadable file, by the line that made it so and what to change on it. -// Only the Linux hints read os-release at runtime; off Linux this is exercised -// solely by the cross-platform unit tests. -#[cfg_attr(not(target_os = "linux"), allow(dead_code))] +/// +/// Delegates to [`install_hint_for_at`]; only the cross-platform unit tests, +/// which fixture bare `text`, use this one — every production call site +/// knows the real path it read and calls [`install_hint_for_at`] or +/// [`install_hint_for_read`] directly. +#[cfg(test)] fn install_hint_for(text: &str, build: InstallPlanBuilder, manual: &str) -> InstallHint { + install_hint_for_at("/etc/os-release", text, build, manual) +} + +/// [`install_hint_for`], naming `path` instead of always `/etc/os-release` in +/// an unreadable-line message. +fn install_hint_for_at( + path: &str, + text: &str, + build: InstallPlanBuilder, + manual: &str, +) -> InstallHint { if let Err(unreadable) = crate::os_release::id_and_id_like(text) { return InstallHint { text: format!( - "{manual}; /etc/os-release {unreadable}, so the distribution cannot be read; \ + "{manual}; {path} {unreadable}, so the distribution cannot be read; \ to fix it, {}", unreadable.fix() ), plan_installs: false, }; } - let plan = plan_for_os_release(text, build); + let plan = plan_for_os_release_at(path, text, build); if plan.supported && !plan.commands.is_empty() { let rendered = plan .commands @@ -921,34 +980,36 @@ fn install_hint_for(text: &str, build: InstallPlanBuilder, manual: &str) -> Inst } } -/// [`install_hint`] for os-release `text`. -#[cfg_attr(not(target_os = "linux"), allow(dead_code))] -fn openmpi_install_hint_for(text: &str) -> InstallHint { - install_hint_for(text, build_openmpi_install_plan, OPENMPI_MANUAL_HINT) -} - -/// [`libatomic_install_hint`] for os-release `text`. -#[cfg_attr(not(target_os = "linux"), allow(dead_code))] -fn libatomic_install_hint_for(text: &str) -> InstallHint { - install_hint_for(text, build_libatomic_install_plan, LIBATOMIC_MANUAL_HINT) -} - -/// [`libnuma_install_hint`] for os-release `text`. +/// [`install_hint_for_at`] for `read`, naming the file actually read, and +/// reporting a file that exists but could not be read as itself rather than +/// as an unknown distribution — the same reasoning as +/// [`plan_for_os_release_read`], for the hint rather than the plan. #[cfg_attr(not(target_os = "linux"), allow(dead_code))] -fn libnuma_install_hint_for(text: &str) -> InstallHint { - install_hint_for(text, build_libnuma_install_plan, LIBNUMA_MANUAL_HINT) +fn install_hint_for_read( + read: &crate::hardware_root::OsRelease, + build: InstallPlanBuilder, + manual: &str, +) -> InstallHint { + if let crate::hardware_root::OsRelease::Unreadable { path, error } = read { + return InstallHint { + text: format!( + "{manual}; {path} could not be read: {error}, so the distribution cannot be read" + ), + plan_installs: false, + }; + } + install_hint_for_at(read.path(), read.text(), build, manual) } /// The real host's `/etc/os-release`, falling back to `/usr/lib/os-release` -/// when the former is absent (per `os-release(5)`), empty when neither can be -/// read. +/// when the former is absent (per `os-release(5)`). /// /// Not routed through [`crate::host_path`]: the hints name package-manager /// commands for the real machine, so a simulated host root must not choose /// their distribution. #[cfg(target_os = "linux")] -fn real_os_release() -> String { - crate::hardware_root::read_os_release(|p| std::path::PathBuf::from(p)).unwrap_or_default() +fn real_os_release() -> crate::hardware_root::OsRelease { + crate::hardware_root::read_os_release(|p| std::path::PathBuf::from(p)) } const OPENMPI_MANUAL_HINT: &str = "install your distribution's OpenMPI runtime package (providing libmpi.so / libmpi_cxx.so and mpirun)"; @@ -969,7 +1030,7 @@ const LIBNUMA_MANUAL_HINT: &str = pub fn install_hint() -> InstallHint { #[cfg(target_os = "linux")] { - openmpi_install_hint_for(&real_os_release()) + install_hint_for_read(&real_os_release(), build_openmpi_install_plan, OPENMPI_MANUAL_HINT) } #[cfg(not(target_os = "linux"))] { @@ -991,7 +1052,11 @@ pub fn install_hint() -> InstallHint { pub fn libatomic_install_hint() -> InstallHint { #[cfg(target_os = "linux")] { - libatomic_install_hint_for(&real_os_release()) + install_hint_for_read( + &real_os_release(), + build_libatomic_install_plan, + LIBATOMIC_MANUAL_HINT, + ) } #[cfg(not(target_os = "linux"))] { @@ -1013,7 +1078,11 @@ pub fn libatomic_install_hint() -> InstallHint { pub fn libnuma_install_hint() -> InstallHint { #[cfg(target_os = "linux")] { - libnuma_install_hint_for(&real_os_release()) + install_hint_for_read( + &real_os_release(), + build_libnuma_install_plan, + LIBNUMA_MANUAL_HINT, + ) } #[cfg(not(target_os = "linux"))] { @@ -1260,41 +1329,113 @@ mod tests { } } - /// Each public hint uses its own runtime's builder and manual advice: - /// the three wrappers, against fixed text rather than the host's file. + /// Each public hint uses its own runtime's builder and manual advice, + /// against fixed text rather than the host's file. #[test] fn each_hint_names_its_own_runtime() { let apt = |packages: &str| { format!("install it with `sudo apt-get update && sudo apt-get install -y {packages}`") }; assert_eq!( - openmpi_install_hint_for("ID=ubuntu\n").text, + install_hint_for("ID=ubuntu\n", build_openmpi_install_plan, OPENMPI_MANUAL_HINT).text, apt("openmpi-bin libopenmpi-dev") ); assert_eq!( - libatomic_install_hint_for("ID=ubuntu\n").text, + install_hint_for( + "ID=ubuntu\n", + build_libatomic_install_plan, + LIBATOMIC_MANUAL_HINT + ) + .text, apt("libatomic1") ); assert_eq!( - libnuma_install_hint_for("ID=ubuntu\n").text, + install_hint_for("ID=ubuntu\n", build_libnuma_install_plan, LIBNUMA_MANUAL_HINT).text, apt("libnuma1") ); // And each one's own manual advice for a distribution it cannot map. assert_eq!( - openmpi_install_hint_for("ID=plan9\n").text, + install_hint_for("ID=plan9\n", build_openmpi_install_plan, OPENMPI_MANUAL_HINT).text, "install your distribution's OpenMPI runtime package \ (providing libmpi.so / libmpi_cxx.so and mpirun)" ); assert_eq!( - libatomic_install_hint_for("ID=plan9\n").text, + install_hint_for( + "ID=plan9\n", + build_libatomic_install_plan, + LIBATOMIC_MANUAL_HINT + ) + .text, "install your distribution's libatomic runtime package (providing libatomic.so.1)" ); assert_eq!( - libnuma_install_hint_for("ID=plan9\n").text, + install_hint_for("ID=plan9\n", build_libnuma_install_plan, LIBNUMA_MANUAL_HINT).text, "install your distribution's numactl runtime package (providing libnuma.so.1)" ); } + /// [`install_hint_for_read`] and [`plan_for_os_release_read`] report a + /// file that exists but could not be read as itself, not as an unknown + /// distribution — the gap `install_hint_for`/`plan_for_os_release` alone + /// cannot close, since by the time they see `text` the distinction + /// between "absent" and "unreadable" is already lost. + #[test] + fn an_unreadable_file_is_reported_as_itself_not_an_unknown_distribution() { + let read = crate::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }; + let hint = install_hint_for_read(&read, build_openmpi_install_plan, OPENMPI_MANUAL_HINT); + assert_eq!( + hint.text, + format!( + "{OPENMPI_MANUAL_HINT}; /usr/lib/os-release could not be read: denied, so the \ + distribution cannot be read" + ) + ); + assert!(!hint.plan_installs); + + let plan = plan_for_os_release_read(&read, build_openmpi_install_plan); + assert!(!plan.supported); + assert!(plan.commands.is_empty()); + assert!( + plan.reason + .starts_with("/usr/lib/os-release could not be read: denied"), + "{}", + plan.reason + ); + } + + /// `install_hint_for_read`/`plan_for_os_release_read` are the one seam + /// `openmpi::real_os_release()` and `runtime_install_finalize::read_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. + /// This still pins the behaviour at the seam itself: an `OsRelease` that + /// says the fallback path was read produces the same plan and hint a + /// primary-path read with the same content would. + #[test] + fn a_fallback_read_plans_and_hints_exactly_like_a_primary_read() { + let fallback = crate::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\n".to_owned(), + }; + let primary = crate::hardware_root::OsRelease::found("ID=ubuntu\n"); + + assert_eq!( + plan_for_os_release_read(&fallback, build_openmpi_install_plan), + plan_for_os_release_read(&primary, build_openmpi_install_plan), + ); + assert_eq!( + install_hint_for_read(&fallback, build_openmpi_install_plan, OPENMPI_MANUAL_HINT), + install_hint_for_read(&primary, build_openmpi_install_plan, OPENMPI_MANUAL_HINT), + ); + assert_eq!( + install_hint_for_read(&fallback, build_openmpi_install_plan, OPENMPI_MANUAL_HINT).text, + "install it with `sudo apt-get update && sudo apt-get install -y openmpi-bin libopenmpi-dev`" + ); + } + /// The message and the plan it describes, together: an unreadable file /// plans nothing, and both the plan's reason and the hint name the line /// and what to change on it, rather than blaming an unknown distribution. diff --git a/docs/testing.md b/docs/testing.md index 5a41849419..be15197cfd 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1576,58 +1576,97 @@ and the distro name it prints `rocm diagnose --distro` run from Windows, which has the WSL distribution's own `sh` source the file and reports what it assigned. -Every one of those readers goes through +Every one of those readers except the WSL remote probe above goes through [`hardware_root::read_os_release`](../crates/rocm-core/src/hardware_root.rs), which reads `/etc/os-release` and, if that file does not exist, falls back to `/usr/lib/os-release` per `os-release(5)` — a file present but unreadable (the -line-reporting cases below) does not fall back, since the fix there is to -correct the line, not to read a second file. The two reads this covers are -`os_release.rs`'s own: a probe routed through a simulated test root +line-reporting cases below, and the file-level case further down) does not +fall back, since a stale fallback could describe the wrong host entirely. +The two reads it covers: a probe routed through a simulated test root (`rocm examine`'s distro fields and distro name) resolves both candidates through `host_path`; a package-manager plan (the driver install, and the OpenMPI/libatomic/libnuma installs and hints) always resolves both against the real machine, for the same reason it never follows a simulated root at all. +Each production call site is a one-line delegation to this shared reader, so +it names the candidate it actually read — `/etc/os-release` or +`/usr/lib/os-release` — rather than always the former, in every message below. A line that is not a plain assignment makes the whole file unreadable, and -each reader names that line instead of reporting an unknown distro. Where the -message asks for a fix, it also says what to change on the line: LF line -endings, single quotes around the value, or a `NAME=value` line in place of -anything else. +each reader names that file and line instead of reporting an unknown distro. +Where the message asks for a fix, it also says what to change on the line: LF +line endings, single quotes around the value, or a `NAME=value` line in place +of anything else. - `rocm install driver`: policy `unreadable_os_release`, no commands, and a - reason naming the line. -- The OpenMPI, libatomic and libnuma installs: no commands, and the line ahead - of the manual-install advice in the plan's reason. -- The hints naming those installs in vLLM's warnings and errors: the line - after the manual-install advice, and no offer of `rocm engines install vllm - --yes`, which would plan nothing. That command is offered only when its plan - has commands, so it is not offered for an unknown distribution either. + reason naming the file and line. +- The OpenMPI, libatomic and libnuma installs: no commands, and the file and + line ahead of the manual-install advice in the plan's reason. +- The hints naming those installs in vLLM's warnings and errors: the file and + line after the manual-install advice, and no offer of `rocm engines install + vllm --yes`, which would plan nothing. That command is offered only when its + plan has commands, so it is not offered for an unknown distribution either. - `rocm examine`: `distro: Linux (/etc/os-release line N is not a plain assignment: "…")`; with `--json`, also an empty `distro_id` and - `distro_version`, the same line in `probe_failures`, and `status: degraded` - on an otherwise healthy GPU host. + `distro_version`, the same file and line in `probe_failures`, and `status: + degraded` on an otherwise healthy GPU host. A CRLF file is unreadable too: `sh` would assign `ubuntu\r`. +A candidate that exists but cannot be read at all (permission denied, a +directory in its place) is reported distinctly from both of the above: not as +an unknown distribution (which would send the user looking for a support +matrix for what is a filesystem problem) and not folded into "absent, so fall +back to the other candidate" (which could silently plan from a stale file that +may not describe this host). This is `hardware_root::OsRelease`, the fallback +reader's return type: `Found { path, text }` for a successful read (naming +whichever candidate it was), `Absent` when neither candidate exists (not a +failure; a missing file declares nothing), or `Unreadable { path, error }` +when a candidate exists but could not be read. Every production call site +above matches on all three: `rocm install driver` via +`build_driver_install_plan_read`, the OpenMPI/libatomic/libnuma installs and +hints via `plan_for_os_release_read`/`install_hint_for_read`, and `rocm +examine`'s distro fields and distro name via `record_distro` and +`distro_name_from_os_release`, which both take the whole `OsRelease` directly. +The three `_read`-suffixed functions are the one seam the real call site hands +its result to; the bare-text functions they delegate to (`plan_for_os_release`, +`install_hint_for`, `build_driver_install_plan`) are kept only for the unit +tests below, which fixture text directly and have no `OsRelease` of their +own to construct. + ```bash cargo test -p rocm-core --lib os_release cargo test -p rocm-core --lib -- pretty_name_reads_as_sh_reads_it an_unreadable_os_release cargo test -p rocm-core --lib openmpi::tests cargo test -p rocm --bin rocm os_release +cargo test -p rocm --bin rocm -- a_fallback_read_plans an_unreadable_file_plans_nothing_and_names_itself cargo test -p rocm-core --lib hardware_root::tests::read_os_release -cargo test -p rocm-core --lib --features e2e-test-hooks os_release_reads_follow_the_simulated_host_root os_release_reads_fall_back_to_usr_lib_when_etc_is_absent +cargo test -p rocm-core --lib -- a_fallback_read_plans an_unreadable_file_is_reported_as_itself distro_name_names_an_unreadable_file an_unreadable_file_names_itself +cargo test -p rocm-core --lib --features e2e-test-hooks -- os_release_reads_follow_the_simulated_host_root os_release_reads_fall_back_to_usr_lib_when_etc_is_absent try_os_release_does_not_source_the_fallback_when_the_primary_exists_but_errors ``` The parser tests that compare against `/bin/sh` itself are Linux-only. The `hardware_root::tests::read_os_release*` tests check the fallback itself -(primary found, primary absent, neither found) against an injected temp -directory rather than the real host. The two `--features e2e-test-hooks` -tests plant a file under the simulated host root and check that both -`rocm examine` reads answer from it through the shared parser: the first at -`/etc/os-release`, the second with only `/usr/lib/os-release` present, so the -fallback is exercised through the real `host_path`-routed call sites, not just -the helper in isolation; the feature they need is enabled only by its own CI -step. +(primary found, primary absent, neither found, and each candidate existing but +erroring for a reason other than absence) against an injected temp directory +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 (`real_os_release`, +`runtime_install_finalize::read_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 +with the same text, and that a file which exists but cannot be read is named +as itself rather than silently treated as an unknown distribution. The two +`--features e2e-test-hooks` os-release tests plant a file under the simulated +host root and check that both `rocm examine` reads answer from it through the +shared parser: the first at `/etc/os-release`, the second with only +`/usr/lib/os-release` present, so the fallback is exercised through the real +`host_path`-routed call sites, not just the helper in isolation; the feature +they need is enabled only by its own CI step. The `try_os_release_does_not_*` +test runs the WSL remote probe's own shell fallback for real under `/bin/sh` +against a primary that exists but errors (a directory in its place), the same +non-absence case the Rust-side `hardware_root` tests cover for the two +in-process readers. `rocm examine` reads the file through the simulated host root (see Simulated Host Root in [release-trust.md](release-trust.md)), so scenarios From 988d4d032ef5e50a98a92014fa9ca2664ae8c85f Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 05:00:03 +0000 Subject: [PATCH 04/18] style: apply cargo fmt Signed-off-by: Jussi Elo --- apps/rocm/src/driver_install.rs | 16 +++++++++------- crates/rocm-core/src/examine.rs | 5 ++++- crates/rocm-core/src/openmpi.rs | 34 ++++++++++++++++++++++++++++----- 3 files changed, 42 insertions(+), 13 deletions(-) diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index bf0d006cc3..75a641d4b0 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -38,12 +38,8 @@ pub(crate) fn install_driver( let os_release = read_os_release(); // The only place the real privilege level is read; every builder below takes // it as a parameter so both branches stay testable on any host. - let plan = build_driver_install_plan_read( - &examine, - &os_release, - dkms, - PrivilegeEscalation::detect(), - ); + let plan = + build_driver_install_plan_read(&examine, &os_release, dkms, PrivilegeEscalation::detect()); let mut output = render_driver_install_plan(&plan, yes, dry_run); if !yes || dry_run || !plan.supported || !plan.mutating { return Ok(DriverInstallResult { @@ -814,7 +810,13 @@ fn build_driver_install_plan( dkms: bool, escalation: PrivilegeEscalation, ) -> DriverInstallPlan { - build_driver_install_plan_at(examine, "/etc/os-release", os_release_text, dkms, escalation) + build_driver_install_plan_at( + examine, + "/etc/os-release", + os_release_text, + dkms, + escalation, + ) } /// [`build_driver_install_plan`], naming `os_release_path` instead of always diff --git a/crates/rocm-core/src/examine.rs b/crates/rocm-core/src/examine.rs index 1c5b210694..ee53b49169 100644 --- a/crates/rocm-core/src/examine.rs +++ b/crates/rocm-core/src/examine.rs @@ -3177,7 +3177,10 @@ mod tests { ); assert_eq!( e.probe_failures, - vec!["/usr/lib/os-release could not be read: denied; the distro is not reported.".to_owned()] + vec![ + "/usr/lib/os-release could not be read: denied; the distro is not reported." + .to_owned() + ] ); assert_eq!((e.distro_id.as_str(), e.distro_version.as_str()), ("", "")); assert_eq!(e.compute_status(), "degraded"); diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 123678b08a..a191c3d179 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -1030,7 +1030,11 @@ const LIBNUMA_MANUAL_HINT: &str = pub fn install_hint() -> InstallHint { #[cfg(target_os = "linux")] { - install_hint_for_read(&real_os_release(), build_openmpi_install_plan, OPENMPI_MANUAL_HINT) + install_hint_for_read( + &real_os_release(), + build_openmpi_install_plan, + OPENMPI_MANUAL_HINT, + ) } #[cfg(not(target_os = "linux"))] { @@ -1337,7 +1341,12 @@ mod tests { format!("install it with `sudo apt-get update && sudo apt-get install -y {packages}`") }; assert_eq!( - install_hint_for("ID=ubuntu\n", build_openmpi_install_plan, OPENMPI_MANUAL_HINT).text, + install_hint_for( + "ID=ubuntu\n", + build_openmpi_install_plan, + OPENMPI_MANUAL_HINT + ) + .text, apt("openmpi-bin libopenmpi-dev") ); assert_eq!( @@ -1350,12 +1359,22 @@ mod tests { apt("libatomic1") ); assert_eq!( - install_hint_for("ID=ubuntu\n", build_libnuma_install_plan, LIBNUMA_MANUAL_HINT).text, + install_hint_for( + "ID=ubuntu\n", + build_libnuma_install_plan, + LIBNUMA_MANUAL_HINT + ) + .text, apt("libnuma1") ); // And each one's own manual advice for a distribution it cannot map. assert_eq!( - install_hint_for("ID=plan9\n", build_openmpi_install_plan, OPENMPI_MANUAL_HINT).text, + install_hint_for( + "ID=plan9\n", + build_openmpi_install_plan, + OPENMPI_MANUAL_HINT + ) + .text, "install your distribution's OpenMPI runtime package \ (providing libmpi.so / libmpi_cxx.so and mpirun)" ); @@ -1369,7 +1388,12 @@ mod tests { "install your distribution's libatomic runtime package (providing libatomic.so.1)" ); assert_eq!( - install_hint_for("ID=plan9\n", build_libnuma_install_plan, LIBNUMA_MANUAL_HINT).text, + install_hint_for( + "ID=plan9\n", + build_libnuma_install_plan, + LIBNUMA_MANUAL_HINT + ) + .text, "install your distribution's numactl runtime package (providing libnuma.so.1)" ); } From 45c537c47a880aba1fd65558d2b01d09dc5d11a9 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 06:17:32 +0000 Subject: [PATCH 05/18] fix: delete dead openmpi::plan_for_os_release It was the one non-test pub fn among the bare-text os-release helpers with no production caller - every real call site already goes through plan_for_os_release_at/_read. Migrate its 4 test call sites to plan_for_os_release_read with OsRelease::found(text) and drop it, along with the doc references that named it. install_hint_for and build_driver_install_plan stay as bare-text test helpers: they're load-bearing for dozens of unrelated test scenarios, not redundant plumbing, so collapsing them is left for a follow-up. Signed-off-by: Jussi Elo (cherry picked from commit f88888f70d81e5a3534d26715aa05894cd43c149) --- crates/rocm-core/src/openmpi.rs | 46 ++++++++++++++++----------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index a191c3d179..6f8a806f7d 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -827,22 +827,16 @@ pub fn build_libnuma_install_plan(os_id: &str, id_like: &str) -> SystemPackageIn /// `ID_LIKE` to the plan that installs one runtime on it. pub type InstallPlanBuilder = fn(&str, &str) -> SystemPackageInstallPlan; -/// `build`'s plan for the distribution os-release `text` declares, naming -/// `/etc/os-release` in any unreadable-line message. +/// `build`'s plan for the distribution the os-release `text` at `path` +/// declares, naming `path` instead of always `/etc/os-release` in an +/// unreadable-line message. /// -/// Delegates to [`plan_for_os_release_at`] with that default path; a caller -/// that actually read the file — which may have come from the -/// `/usr/lib/os-release` fallback — uses that function directly so an -/// unreadable line names the file really read rather than always the -/// primary. The many unit tests fixturing bare `text` (never the real host) -/// keep using this one. -#[must_use] -pub fn plan_for_os_release(text: &str, build: InstallPlanBuilder) -> SystemPackageInstallPlan { - plan_for_os_release_at("/etc/os-release", text, build) -} - -/// [`plan_for_os_release`], naming `path` instead of always `/etc/os-release` -/// in an unreadable-line message. +/// Unit tests that fixture bare `text` (never the real host) construct an +/// [`crate::hardware_root::OsRelease`] with +/// [`crate::hardware_root::OsRelease::found`] and call +/// [`plan_for_os_release_read`]; every production call site knows the real +/// path it read and calls this function or [`plan_for_os_release_read`] +/// directly. /// /// An unreadable file (see [`crate::os_release`]) plans nothing, and the /// reason names the line that made it unreadable and what to change on it, @@ -898,7 +892,8 @@ pub fn plan_for_os_release_read( /// the advice installs anything. /// /// `rocm engines install vllm --yes` runs the same plan -/// ([`plan_for_os_release`] over the same builder and the same real file), so +/// ([`plan_for_os_release_read`] over the same builder and the same real +/// file), so /// a message may offer that command only when [`InstallHint::plan_installs`] /// is true; [`InstallHint::or`] does the offering. #[derive(Debug, Clone, PartialEq, Eq)] @@ -930,8 +925,8 @@ impl std::fmt::Display for InstallHint { } /// The hint for os-release `text`, naming `/etc/os-release` in any -/// unreadable-line message: the commands [`plan_for_os_release`] plans with -/// `build` when it plans any, otherwise `manual` — followed, for an +/// unreadable-line message: the commands [`plan_for_os_release_at`] plans +/// with `build` when it plans any, otherwise `manual` — followed, for an /// unreadable file, by the line that made it so and what to change on it. /// /// Delegates to [`install_hint_for_at`]; only the cross-platform unit tests, @@ -1308,7 +1303,10 @@ mod tests { ("ID=derivative\nID_LIKE=\"rhel fedora\"\n", &dnf), ] { assert_eq!( - &plan_for_os_release(text, build), + &plan_for_os_release_read( + &crate::hardware_root::OsRelease::found(text), + build + ), expected, "{label}: {text:?}" ); @@ -1400,8 +1398,8 @@ mod tests { /// [`install_hint_for_read`] and [`plan_for_os_release_read`] report a /// file that exists but could not be read as itself, not as an unknown - /// distribution — the gap `install_hint_for`/`plan_for_os_release` alone - /// cannot close, since by the time they see `text` the distinction + /// distribution — the gap `install_hint_for`/`plan_for_os_release_at` + /// alone cannot close, since by the time they see `text` the distinction /// between "absent" and "unreadable" is already lost. #[test] fn an_unreadable_file_is_reported_as_itself_not_an_unknown_distribution() { @@ -1469,7 +1467,8 @@ mod tests { fn an_unreadable_file_plans_nothing_and_names_its_line() { let text = "ID=ubuntu\nexport ID=debian\n"; for (label, build, manual) in BUILDERS { - let plan = plan_for_os_release(text, build); + let plan = + plan_for_os_release_read(&crate::hardware_root::OsRelease::found(text), build); assert!(!plan.supported, "{label}"); assert_eq!(plan.package_manager, None, "{label}"); assert!(plan.commands.is_empty(), "{label}"); @@ -1512,7 +1511,8 @@ mod tests { "ID=ubuntu\nNAME=a b\n", "ID=ubuntu\r\n", ] { - let plan = plan_for_os_release(text, build); + let plan = + plan_for_os_release_read(&crate::hardware_root::OsRelease::found(text), build); let hint = install_hint_for(text, build, manual); let offered = hint.or("rerun with --yes"); let installs = plan.supported && !plan.commands.is_empty(); From 2dcb831447e77e447bbfda9547354f8f9103e3c4 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 06:26:59 +0000 Subject: [PATCH 06/18] fix: make the simulated-host-root test compare against an independent read read_os_release_ignores_a_simulated_host_root's second assertion compared the function under test against a second call to the exact same hardware_root::read_os_release helper with the same identity resolver - not independent, so a bug in the wrapper's .context(...) call or resolver closure would pass unnoticed. Replace it with a direct read of both candidate paths, applying the same existence-only fallback rule inline; where neither candidate is cleanly readable on this box, assert only the Absent/Unreadable shape rather than exact text. Also rename runtime_install_finalize::read_os_release to real_os_release, matching openmpi.rs's existing name for the analogous real-host-only reader and resolving the naming collision with the hardware_root helper it wraps. Signed-off-by: Jussi Elo (cherry picked from commit a247bc6e4897ed64dc1b98683f5c07c32f9f777f) --- apps/rocm/src/driver_install.rs | 6 +-- apps/rocm/src/runtime_install_finalize.rs | 55 ++++++++++++++++------- crates/rocm-core/src/openmpi.rs | 7 +-- docs/testing.md | 5 ++- 4 files changed, 46 insertions(+), 27 deletions(-) diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 75a641d4b0..bb77fc77e1 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -25,7 +25,7 @@ use rocm_core::{AppPaths, ExamineSummary, shell_command_for_host}; use serde::{Deserialize, Serialize}; use crate::cli_report; -use crate::runtime_install_finalize::{empty_as_unknown, read_os_release}; +use crate::runtime_install_finalize::{empty_as_unknown, real_os_release}; pub(crate) fn install_driver( paths: &AppPaths, @@ -35,7 +35,7 @@ pub(crate) fn install_driver( ) -> std::result::Result { let examine = ExamineSummary::gather().map_err(|source| DriverInstallError::new(source, false))?; - let os_release = read_os_release(); + let os_release = real_os_release(); // The only place the real privilege level is read; every builder below takes // it as a parameter so both branches stay testable on any host. let plan = @@ -1943,7 +1943,7 @@ mod tests { } /// `build_driver_install_plan_read` is the one seam `install_driver` hands - /// its `read_os_release()` result to. Both are now one-line delegations + /// 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 diff --git a/apps/rocm/src/runtime_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index 3507bae111..24b928e5a2 100644 --- a/apps/rocm/src/runtime_install_finalize.rs +++ b/apps/rocm/src/runtime_install_finalize.rs @@ -157,7 +157,7 @@ pub(crate) const fn empty_as_unknown(value: &str) -> &str { /// distro. The descriptive distro name `examine` reports comes from /// `ExamineSummary::gather`'s `distro` field, which does follow a simulated /// root. -pub(crate) fn read_os_release() -> rocm_core::hardware_root::OsRelease { +pub(crate) fn real_os_release() -> rocm_core::hardware_root::OsRelease { rocm_core::hardware_root::read_os_release(|p| PathBuf::from(p)) } @@ -204,7 +204,7 @@ pub(crate) fn ensure_openmpi_for_vllm(approved: bool) -> Result<()> { } let plan = rocm_core::openmpi::plan_for_os_release_read( - &read_os_release(), + &real_os_release(), rocm_core::openmpi::build_openmpi_install_plan, ); @@ -378,7 +378,7 @@ fn ensure_torch_runtime_dep(approved: bool, dep: &TorchRuntimeDep) { return; } - let plan = rocm_core::openmpi::plan_for_os_release_read(&read_os_release(), dep.build_plan); + let plan = rocm_core::openmpi::plan_for_os_release_read(&real_os_release(), dep.build_plan); println!("{} setup", dep.name); println!(" reason: {}", dep.reason); @@ -2084,11 +2084,11 @@ pub(crate) mod tests { /// 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, `read_os_release` + /// 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 read_os_release_ignores_a_simulated_host_root() { + 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(), @@ -2109,7 +2109,7 @@ pub(crate) mod tests { rocm_core::hardware_root::TEST_HOST_ROOT_ENV, &root.to_string_lossy(), ); - read_os_release() + real_os_release() }; fs::remove_dir_all(&root).ok(); @@ -2118,17 +2118,38 @@ pub(crate) mod tests { "read the simulated root's os-release: {:?}", read.text() ); - // Not `fs::read_to_string("/etc/os-release")` directly: on a host that - // is itself one of the `/usr/lib/os-release`-only machines this fix - // supports, that would compare against an empty string while `read` - // correctly holds the real fallback file's contents, failing the - // assertion on exactly the configuration this test means to allow. - // Compared by `(path, text)` rather than `OsRelease` itself: an - // `Unreadable` variant carries an `io::Error`, which has no - // `PartialEq`, and the path/text pair is what this test means to pin - // regardless. - let real = rocm_core::hardware_root::read_os_release(|p| PathBuf::from(p)); - assert_eq!((read.path(), read.text()), (real.path(), real.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. Where + // neither candidate is cleanly readable on this box (a minimal or + // sandboxed CI image), assert only the shape (`Absent`/`Unreadable`) + // rather than exact text — this test's job is "did it ignore the + // simulated root", not "what exactly is on this machine". + let expected = match fs::read_to_string("/etc/os-release") { + Ok(text) => Some(("/etc/os-release", text)), + Err(e) if e.kind() == std::io::ErrorKind::NotFound => { + fs::read_to_string("/usr/lib/os-release") + .ok() + .map(|text| ("/usr/lib/os-release", text)) + } + Err(_) => None, + }; + match expected { + Some((path, text)) => { + assert_eq!((read.path(), read.text()), (path, text.as_str())); + } + None => assert!( + matches!( + &read, + rocm_core::hardware_root::OsRelease::Absent + | rocm_core::hardware_root::OsRelease::Unreadable { .. } + ), + "expected Absent or Unreadable when neither candidate is cleanly \ + readable, got {read:?}" + ), + } } // The install report is only as honest as the reconciliation that reaches diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 6f8a806f7d..7a808bd8da 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -1303,10 +1303,7 @@ mod tests { ("ID=derivative\nID_LIKE=\"rhel fedora\"\n", &dnf), ] { assert_eq!( - &plan_for_os_release_read( - &crate::hardware_root::OsRelease::found(text), - build - ), + &plan_for_os_release_read(&crate::hardware_root::OsRelease::found(text), build), expected, "{label}: {text:?}" ); @@ -1429,7 +1426,7 @@ mod tests { } /// `install_hint_for_read`/`plan_for_os_release_read` are the one seam - /// `openmpi::real_os_release()` and `runtime_install_finalize::read_os_release()` + /// `openmpi::real_os_release()` and `runtime_install_finalize::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/testing.md b/docs/testing.md index be15197cfd..e80fc3f686 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1651,8 +1651,9 @@ erroring for a reason other than absence) against an injected temp directory 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 (`real_os_release`, -`runtime_install_finalize::read_os_release`) read the real machine +read entirely, since the production functions that do it +(`openmpi::real_os_release`, `runtime_install_finalize::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 with the same text, and that a file which exists but cannot be read is named From 2b533f9fbe1904c233146684f663e2860e09be7a Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 06:52:02 +0000 Subject: [PATCH 07/18] test: cover malformed-line fallback path naming at all four call sites rominf's mutation testing found that replacing read.path() with a hardcoded /etc/os-release at the five message-building call sites still passed every existing test: every malformed-line test went through either the bare /etc-only functions or OsRelease::found (which also hardcodes /etc/os-release), never a Found{path: "/usr/lib/os-release", ...} fed to the path-aware _read functions. Add one test per site (openmpi.rs's plan_for_os_release_read/ install_hint_for_read, driver_install.rs's build_driver_install_plan_read, examine.rs's record_distro, host_gpu.rs's distro_name_from_os_release) that would have caught it. Also add a_wsl_host_ignores_an_unreadable_local_os_release_read: on WSL, build_driver_install_plan_read's Unreadable branch must not fire at all, since WSL has its own guest-side probe and the local Rust-side read is never authoritative for it - nothing previously pinned that the reaches_os_release_parse guard keeps this true. Signed-off-by: Jussi Elo (cherry picked from commit 94eddfcca97f4cb0a428777722276df31ca7cbc3) --- apps/rocm/src/driver_install.rs | 58 ++++++++++++++++++++++++++++++++ crates/rocm-core/src/examine.rs | 29 ++++++++++++++++ crates/rocm-core/src/host_gpu.rs | 18 ++++++++++ crates/rocm-core/src/openmpi.rs | 43 +++++++++++++++++++++++ 4 files changed, 148 insertions(+) diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index bb77fc77e1..4d95747ac4 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -2014,6 +2014,64 @@ mod tests { ); } + /// 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 the bare, + /// hardcoded-`/etc` `build_driver_install_plan`, 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.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); + } + /// 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`. diff --git a/crates/rocm-core/src/examine.rs b/crates/rocm-core/src/examine.rs index ee53b49169..59bcfe4724 100644 --- a/crates/rocm-core/src/examine.rs +++ b/crates/rocm-core/src/examine.rs @@ -3186,6 +3186,35 @@ mod tests { assert_eq!(e.compute_status(), "degraded"); } + /// The same malformed line as + /// [`an_unreadable_os_release_names_its_line_instead_of_a_distro`], but + /// read through the fallback path: `probe_failures` must name + /// `/usr/lib/os-release`, not `/etc/os-release`. That test only exercises + /// [`crate::hardware_root::OsRelease::found`], which hardcodes + /// `/etc/os-release`, so a regression that hardcoded the path back into + /// `record_distro`'s message would still pass it. + #[test] + fn a_fallback_reads_malformed_line_names_the_fallback_path_in_probe_failures() { + let mut e = linux_host_with_a_gpu(); + record_distro( + &mut e, + &crate::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nexport ID=debian\n".to_owned(), + }, + ); + assert_eq!( + e.probe_failures, + vec![ + "/usr/lib/os-release line 3 is not a plain assignment: \"export ID=debian\"; \ + the distro is not reported." + .to_owned() + ] + ); + assert_eq!((e.distro_id.as_str(), e.distro_version.as_str()), ("", "")); + assert_eq!(e.compute_status(), "degraded"); + } + /// Serialises the tests that read or replace the process-global /// `RUNTIME_LIBRARY_PATH_ENV` while they run. Env is shared by every test /// thread, so a test that sets it and one that composes a child env from it diff --git a/crates/rocm-core/src/host_gpu.rs b/crates/rocm-core/src/host_gpu.rs index 84ae58dee7..cd66b24994 100644 --- a/crates/rocm-core/src/host_gpu.rs +++ b/crates/rocm-core/src/host_gpu.rs @@ -4848,6 +4848,24 @@ Class Name: Display ); } + /// The same malformed line as the second case in + /// [`pretty_name_reads_as_sh_reads_it`], but read through the fallback + /// path: the message must name `/usr/lib/os-release`, not + /// `/etc/os-release`. That test only exercises + /// [`hardware_root::OsRelease::found`], which hardcodes + /// `/etc/os-release`, so a regression that hardcoded the path back into + /// `distro_name_from_os_release`'s message would still pass it. + #[test] + fn a_fallback_reads_malformed_line_names_the_fallback_path() { + assert_eq!( + distro_name_from_os_release(&hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "PRETTY_NAME=\"Ubuntu 24.04 LTS\"\nunset ID\n".to_owned(), + }), + "Linux (/usr/lib/os-release line 2 is not a plain assignment: \"unset ID\")" + ); + } + #[test] fn dev_dxg_is_believed_on_its_own() { // Nothing but WSLg's GPU passthrough creates this device node, so it is diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 7a808bd8da..8ebff2c4cf 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -1496,6 +1496,49 @@ mod tests { } } + /// The same malformed line as + /// [`an_unreadable_file_plans_nothing_and_names_its_line`], but read + /// through the fallback path: both the plan's reason and the hint must + /// name `/usr/lib/os-release`, not `/etc/os-release`. Every malformed-line + /// test before this one went through either the bare, hardcoded-`/etc` + /// functions or [`crate::hardware_root::OsRelease::found`] (which also + /// hardcodes `/etc/os-release`), so a regression that hardcoded the path + /// back into `plan_for_os_release_read`/`install_hint_for_read` would + /// have passed every one of them. + #[test] + fn a_fallback_reads_malformed_line_names_the_fallback_path() { + let read = crate::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\nexport ID=debian\n".to_owned(), + }; + for (label, build, manual) in BUILDERS { + let plan = plan_for_os_release_read(&read, build); + assert!(!plan.supported, "{label}"); + assert!( + plan.reason.starts_with( + "/usr/lib/os-release line 2 is not a plain assignment: \ + \"export ID=debian\", so the distribution cannot be read; to fix \ + it, remove that line or rewrite it as NAME=value. Could not map \ + distribution" + ), + "{label}: {}", + plan.reason + ); + + let hint = install_hint_for_read(&read, build, manual); + assert_eq!( + hint.text, + format!( + "{manual}; /usr/lib/os-release line 2 is not a plain assignment: \ + \"export ID=debian\", so the distribution cannot be read; to fix it, \ + remove that line or rewrite it as NAME=value" + ), + "{label}" + ); + assert!(!hint.plan_installs, "{label}"); + } + } + /// An automatic install is offered exactly when the plan it would run /// installs something: for a recognised distribution, and not for an /// unknown one or an unreadable file. From 83c528c16ba221987960ca5c9c84dd4f72c7b9f9 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 07:11:36 +0000 Subject: [PATCH 08/18] fix: match either os-release path in e2e failure filter, add examine-25 os_release_failures()'s filter hardcoded "/etc/os-release", so a release-file failure on a fallback-only host (every message now names the file actually read) was silently dropped before examine-24's "reports no trouble reading the release file" step ever saw it - the step could not fail. Broaden the filter to match either candidate path. Add examine-25: before this change, a release file that exists but cannot be read silently produced an empty, unreported distro with no failure recorded; it now reports the file as itself and degrades the verdict, which had no e2e coverage. Factor the GPU-fixture planting shared with examine-23 into plant_gpu_fixtures to avoid duplicating it. Signed-off-by: Jussi Elo (cherry picked from commit 093b970648585777f03f5bddc1d083fb87344e0d) --- tests/e2e-cucumber/features/examine.feature | 15 +++- tests/e2e-cucumber/tests/e2e/examine_steps.rs | 77 +++++++++++++++++-- 2 files changed, 83 insertions(+), 9 deletions(-) diff --git a/tests/e2e-cucumber/features/examine.feature b/tests/e2e-cucumber/features/examine.feature index 7555f7440b..dee1159a04 100644 --- a/tests/e2e-cucumber/features/examine.feature +++ b/tests/e2e-cucumber/features/examine.feature @@ -282,7 +282,7 @@ 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 `read_os_release`); its + # deliberately reads the real `/etc/os-release` (see `real_os_release`); its # parsing is covered by the unit tests in `driver_install.rs`. # # The planted distributions are ones no CI runner or developer host here runs, @@ -336,3 +336,16 @@ Feature: GPU detection and system inspection When the user inspects that machine in machine-readable form Then the inspection reports the distribution "ubuntu" version "24.04" named "Ubuntu 24.04 LTS" And the inspection reports no trouble reading the release file + + # Before this change, a release file that exists but cannot be read (not + # absent, so no fallback candidate is tried either) silently produced an + # empty, unreported distro with no failure recorded. It now reports the + # file as itself, distinctly from both an unknown distribution and a + # malformed line it never reached. A directory in place of the file is a + # non-`NotFound` read error that needs no root privilege, unlike a + # mode-000 file, which CI running as root would read anyway. + @id:examine-degrades-on-unreadable-release-file @requires-os:linux + Scenario: examine-25 - An unreadable release file degrades the verdict on a machine with a GPU + Given a GPU machine whose release file cannot be read + When the user inspects that machine in machine-readable form + Then the inspection's verdict is degraded, and its only failure says the release file could not be read diff --git a/tests/e2e-cucumber/tests/e2e/examine_steps.rs b/tests/e2e-cucumber/tests/e2e/examine_steps.rs index 3ee41cbbec..b9639387f6 100644 --- a/tests/e2e-cucumber/tests/e2e/examine_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/examine_steps.rs @@ -1352,17 +1352,20 @@ async fn os_release_with_a_command(world: &mut E2eWorld) { const RUNS_A_COMMAND_ON_LINE_3: &str = "ID=ubuntu\nVERSION_ID=\"24.04\"\nexport ID=debian\nPRETTY_NAME=\"Ubuntu 24.04 LTS\"\n"; -#[given("a GPU machine whose release file runs a command on line 3")] -async fn gpu_machine_with_unreadable_os_release(world: &mut E2eWorld) { - plant_os_release(world, RUNS_A_COMMAND_ON_LINE_3); +/// One GPU node in the kernel topology: a gfx1101 with no PCI address, so it +/// matches no `lspci` entry and is listed from the topology alone. Plus an +/// `lspci` that lists an empty bus, ahead of any real one, so the PCI probe +/// succeeds on every runner without describing the runner's cards. +/// +/// Used by every scenario that needs a verdict to degrade *from* — without a +/// GPU, the verdict is `no-amd-gpu` whatever the release file says. +fn plant_gpu_fixtures(world: &mut E2eWorld) { let root = world .isolated_root .as_ref() .expect("no isolated root") .path() .to_owned(); - // One GPU node in the kernel topology: a gfx1101 with no PCI address, so it - // matches no `lspci` entry and is listed from the topology alone. let node = root.join("host-root/sys/class/kfd/kfd/topology/nodes/1"); std::fs::create_dir_all(&node).expect("failed to create planted KFD node"); std::fs::write( @@ -1370,8 +1373,6 @@ async fn gpu_machine_with_unreadable_os_release(world: &mut E2eWorld) { "cpu_cores_count 0\nsimd_count 120\ngfx_target_version 110001\n", ) .expect("failed to write planted KFD node properties"); - // An `lspci` that lists an empty bus, ahead of any real one, so the PCI - // probe succeeds on every runner without describing the runner's cards. let bin = root.join("fake-bin"); std::fs::create_dir_all(&bin).expect("failed to create the fake PATH dir"); rocm_core::fake_executable::write_fake_executable(&bin.join("lspci"), "#!/bin/sh\nexit 0\n") @@ -1383,6 +1384,32 @@ async fn gpu_machine_with_unreadable_os_release(world: &mut E2eWorld) { world.command_env.push(("PATH", path)); } +#[given("a GPU machine whose release file runs a command on line 3")] +async fn gpu_machine_with_unreadable_os_release(world: &mut E2eWorld) { + plant_os_release(world, RUNS_A_COMMAND_ON_LINE_3); + plant_gpu_fixtures(world); +} + +/// A directory in place of the file is a non-`NotFound` read error that needs +/// no root privilege — unlike a mode-000 file, which CI running as root would +/// read anyway — the same portable fixture the `hardware_root` and WSL-probe +/// unit tests use for "exists but errors". +#[given("a GPU machine whose release file cannot be read")] +async fn gpu_machine_with_unreadable_release_file(world: &mut E2eWorld) { + let root = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .join("host-root"); + std::fs::create_dir_all(root.join("etc/os-release")) + .expect("failed to create planted os-release directory"); + world + .command_env + .push(("ROCM_CLI_TEST_HOST_ROOT", root.into_os_string())); + plant_gpu_fixtures(world); +} + #[when("the user inspects that machine in machine-readable form")] async fn user_inspects_planted_machine(world: &mut E2eWorld) { let (stdout, stderr, rc) = @@ -1399,13 +1426,19 @@ fn inspection_str<'a>(json: &'a serde_json::Value, pointer: &str) -> &'a str { } /// The `probe_failures` entries that are about the release file. +/// +/// Matches either candidate path: every failure message names the file +/// actually read (`/etc/os-release` or, on a fallback-only host, +/// `/usr/lib/os-release`), so a filter that only matched the former would +/// silently drop a release-file failure on a fallback-only host before any +/// assertion below ever saw it. fn os_release_failures(json: &serde_json::Value) -> Vec { json.get("probe_failures") .and_then(serde_json::Value::as_array) .unwrap_or_else(|| panic!("`examine --json` has no probe_failures array:\n{json:#}")) .iter() .filter_map(serde_json::Value::as_str) - .filter(|failure| failure.contains("/etc/os-release")) + .filter(|failure| failure.contains("os-release")) .map(str::to_owned) .collect() } @@ -1468,6 +1501,34 @@ async fn assert_degraded_by_os_release_alone(world: &mut E2eWorld, line: u32) { ); } +#[then( + expr = "the inspection's verdict is degraded, and its only failure says the release file could not be read" +)] +async fn assert_degraded_by_unreadable_os_release(world: &mut E2eWorld) { + assert_eq!(world.cli_rc, Some(0), "`rocm examine --json` failed"); + let json = parsed_json(world); + // The GPU is what lets the verdict be `degraded` rather than `no-amd-gpu`. + assert_eq!( + json.get("has_amd_gpu").and_then(serde_json::Value::as_bool), + Some(true), + "the planted GPU was not found:\n{json:#}" + ); + assert_eq!( + inspection_str(&json, &format!("/{VERDICT_FIELD}")), + "degraded", + "{json:#}" + ); + let failures = os_release_failures(&json); + assert_eq!(failures.len(), 1, "{json:#}"); + // Not an exact match on the OS's read-error text (e.g. "Is a directory + // (os error 21)" on Linux), which this test does not mean to pin. + assert!( + failures[0].starts_with("/etc/os-release could not be read: ") + && failures[0].ends_with("; the distro is not reported."), + "{json:#}" + ); +} + #[then("the inspection reports no distribution")] async fn assert_no_distribution(world: &mut E2eWorld) { assert_eq!(world.cli_rc, Some(0), "`rocm examine --json` failed"); From 192d61f411bf130ffbf6a18a58eefd281210246e Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 07:13:17 +0000 Subject: [PATCH 09/18] fix: narrow the WSL probe test's overclaimed parity with the Rust readers try_os_release_does_not_source_the_fallback_when_the_primary_exists_but_errors used a directory as the primary (deliberately: CI commonly runs as root, where chmod 000 is ignored, so a mode-000 fixture would be flaky depending on who runs it) but its name and docs/testing.md both claimed parity with the Rust-side hardware_root tests' permission-denied case. They are not the same failure mode: under dash, sourcing a genuinely unreadable file aborts the whole embedded script immediately, not just this function, while a directory fails to source for a different, root-safe reason. Rename to try_os_release_does_not_source_the_fallback_when_the_primary_is_not_sourceable and tighten both doc comments to state what the test actually proves (existence is not readability) and name the gap it leaves, rather than claiming parity the fixture can't back up. The underlying abort-on- unreadable-primary behavior predates this PR; fixing it is out of scope here. Signed-off-by: Jussi Elo (cherry picked from commit b069a8df514961c642ee2c31f287937e684ce448) --- crates/rocm-core/src/examine.rs | 17 ++++++++++++++++- docs/testing.md | 25 +++++++++++++++++-------- 2 files changed, 33 insertions(+), 9 deletions(-) diff --git a/crates/rocm-core/src/examine.rs b/crates/rocm-core/src/examine.rs index 59bcfe4724..713af01735 100644 --- a/crates/rocm-core/src/examine.rs +++ b/crates/rocm-core/src/examine.rs @@ -5871,9 +5871,24 @@ mod tests { /// must not fall through to the `elif` and source the fallback — that /// would silently read a file that may not describe this host, matching /// `hardware_root::read_os_release`'s own non-absence rule. + /// + /// This is deliberately a directory, not a permission-denied file: CI + /// commonly runs as root, where a `chmod 000` file is still readable, so + /// a mode-000 fixture would pass or fail depending on who runs it. A + /// directory fails to source for a different, root-safe reason ("is a + /// directory"), which is enough to prove this one claim — existence is + /// not readability — but is **not** the same failure mode as a genuinely + /// unreadable primary. Under `/bin/sh` (`dash` on Debian/Ubuntu), + /// sourcing a *permission-denied* file is a fatal shell-level error that + /// aborts the whole embedded script immediately, not just this function — + /// a materially different outcome than "`$ID` stays unset" and one this + /// test does not exercise. That abort-on-unreadable-primary behavior + /// predates the `/usr/lib/os-release` fallback this module adds; fixing + /// it is out of scope here (tracked as a possible follow-up, not a + /// blocker for the fallback itself). #[cfg(target_os = "linux")] #[test] - fn try_os_release_does_not_source_the_fallback_when_the_primary_exists_but_errors() { + fn try_os_release_does_not_source_the_fallback_when_the_primary_is_not_sourceable() { let dir = tempfile::tempdir().expect("create temp dir"); let primary = dir.path().join("primary"); let fallback = dir.path().join("fallback"); diff --git a/docs/testing.md b/docs/testing.md index e80fc3f686..972fdcf8a7 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1641,7 +1641,7 @@ cargo test -p rocm --bin rocm os_release cargo test -p rocm --bin rocm -- a_fallback_read_plans an_unreadable_file_plans_nothing_and_names_itself cargo test -p rocm-core --lib hardware_root::tests::read_os_release cargo test -p rocm-core --lib -- a_fallback_read_plans an_unreadable_file_is_reported_as_itself distro_name_names_an_unreadable_file an_unreadable_file_names_itself -cargo test -p rocm-core --lib --features e2e-test-hooks -- os_release_reads_follow_the_simulated_host_root os_release_reads_fall_back_to_usr_lib_when_etc_is_absent try_os_release_does_not_source_the_fallback_when_the_primary_exists_but_errors +cargo test -p rocm-core --lib --features e2e-test-hooks -- os_release_reads_follow_the_simulated_host_root os_release_reads_fall_back_to_usr_lib_when_etc_is_absent try_os_release_does_not_source_the_fallback_when_the_primary_is_not_sourceable ``` The parser tests that compare against `/bin/sh` itself are Linux-only. The @@ -1663,23 +1663,32 @@ host root and check that both `rocm examine` reads answer from it through the shared parser: the first at `/etc/os-release`, the second with only `/usr/lib/os-release` present, so the fallback is exercised through the real `host_path`-routed call sites, not just the helper in isolation; the feature -they need is enabled only by its own CI step. The `try_os_release_does_not_*` +they need is enabled only by its own CI step. The +`try_os_release_does_not_source_the_fallback_when_the_primary_is_not_sourceable` test runs the WSL remote probe's own shell fallback for real under `/bin/sh` -against a primary that exists but errors (a directory in its place), the same -non-absence case the Rust-side `hardware_root` tests cover for the two -in-process readers. +against a primary that exists but cannot be sourced (a directory in its +place) — proving existence is not readability, the same claim the Rust-side +`hardware_root` tests make for the two in-process readers, but **not** the +same failure mode: a genuinely permission-denied primary aborts the whole +shell probe instead of merely leaving `$ID` unset, which this test does not +exercise — see its own doc comment for why, and for the known limitation +this leaves. `rocm examine` reads the file through the simulated host root (see Simulated Host Root in [release-trust.md](release-trust.md)), so scenarios -`examine-20` to `examine-24` in +`examine-20` to `examine-25` in [examine.feature](../tests/e2e-cucumber/features/examine.feature) plant one. `examine-23` also plants a GPU in the kernel topology and puts an `lspci` listing an empty bus on `PATH`, so `status: degraded` is checked on every Linux lane, with or without a GPU. `examine-24` plants only `/usr/lib/os-release`, -with no `/etc/os-release` present, to check the `os-release(5)` fallback: +with no `/etc/os-release` present, to check the `os-release(5)` fallback. +`examine-25` plants a directory in place of `/etc/os-release` (reusing +`examine-23`'s GPU fixtures) to check the degraded verdict and failure +message a present-but-unreadable release file now gets, distinctly from +both a malformed line and an unknown distribution: ```bash -RUSTC_WRAPPER= cargo xtask e2e -- -n 'examine-2[0-4] ' +RUSTC_WRAPPER= cargo xtask e2e -- -n 'examine-2[0-5] ' ``` The install plans deliberately read the real file, so no scenario plants one From c68afd17e3defe774c01af836eeea7814a742329 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 07:20:04 +0000 Subject: [PATCH 10/18] refactor: factor the resolver closures and the unreadable-plan literal Replace the four near-identical `|p| host_path(p)`/`|p| PathBuf::from(p)` resolver closures passed to hardware_root::read_os_release with two named functions (host_path_for_str, identity_path_for_str) in hardware_root.rs. A bare reference to host_path or PathBuf::from doesn't work in their place - the borrow checker rejects the generic fn as "not general enough" over the resolved lifetime - so this needed a concrete fn(&str) -> PathBuf wrapper, not just dropping the closure. Also extract build_driver_install_plan_at's and _read's identical unreadable-os-release DriverInstallPlan literal (same field-for-field shape, differing only in the reason string) into a shared unreadable_os_release_plan helper, so a new early branch added to one can't silently fail to apply to the other. Signed-off-by: Jussi Elo (cherry picked from commit cbe194a206cf59da6f4a052dea1295126e8d0d20) --- apps/rocm/src/driver_install.rs | 57 ++++++++++++----------- apps/rocm/src/runtime_install_finalize.rs | 2 +- crates/rocm-core/src/examine.rs | 2 +- crates/rocm-core/src/hardware_root.rs | 26 +++++++++++ crates/rocm-core/src/host_gpu.rs | 2 +- crates/rocm-core/src/openmpi.rs | 2 +- 6 files changed, 60 insertions(+), 31 deletions(-) diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 4d95747ac4..0876cc50af 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -819,6 +819,29 @@ fn build_driver_install_plan( ) } +/// 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 so a new +/// early branch added to one is not silently absent from the other. +fn unreadable_os_release_plan(repo_version: String, reason: 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, + reason, + preflight_checks: Vec::new(), + commands: Vec::new(), + checks: vec!["rocm examine".to_owned()], + reboot_required: false, + } +} + /// [`build_driver_install_plan`], naming `os_release_path` instead of always /// `/etc/os-release` in an unreadable-line message. fn build_driver_install_plan_at( @@ -865,24 +888,14 @@ fn build_driver_install_plan_at( let os_release = match rocm_core::os_release::parse(os_release_text) { Ok(fields) => fields, Err(unreadable) => { - return DriverInstallPlan { - supported: false, - mutating: false, - policy: "unreadable_os_release".to_owned(), - os_id: String::new(), - version_id: String::new(), - codename: String::new(), + return unreadable_os_release_plan( repo_version, - reason: format!( + format!( "{os_release_path} {unreadable}; no driver commands were planned \ because the distro cannot be read. To fix it, {}.", unreadable.fix() ), - preflight_checks: Vec::new(), - commands: Vec::new(), - checks: vec!["rocm examine".to_owned()], - reboot_required: false, - }; + ); } }; let field = |key: &str| os_release.get(key).cloned(); @@ -1017,23 +1030,13 @@ fn build_driver_install_plan_read( if reaches_os_release_parse && let rocm_core::hardware_root::OsRelease::Unreadable { path, error } = read { - return DriverInstallPlan { - supported: false, - mutating: false, - policy: "unreadable_os_release".to_owned(), - os_id: String::new(), - version_id: String::new(), - codename: String::new(), - repo_version: resolve_shell_default_template("${ROCM_CLI_AMDGPU_VERSION:-7.2.4}"), - reason: format!( + return unreadable_os_release_plan( + resolve_shell_default_template("${ROCM_CLI_AMDGPU_VERSION:-7.2.4}"), + format!( "{path} could not be read: {error}; no driver commands were planned \ because the distro cannot be read." ), - preflight_checks: Vec::new(), - commands: Vec::new(), - checks: vec!["rocm examine".to_owned()], - reboot_required: false, - }; + ); } build_driver_install_plan_at(examine, read.path(), read.text(), dkms, escalation) } diff --git a/apps/rocm/src/runtime_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index 24b928e5a2..99b1ece446 100644 --- a/apps/rocm/src/runtime_install_finalize.rs +++ b/apps/rocm/src/runtime_install_finalize.rs @@ -158,7 +158,7 @@ pub(crate) const fn empty_as_unknown(value: &str) -> &str { /// `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(|p| PathBuf::from(p)) + 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. diff --git a/crates/rocm-core/src/examine.rs b/crates/rocm-core/src/examine.rs index 713af01735..84a57221d9 100644 --- a/crates/rocm-core/src/examine.rs +++ b/crates/rocm-core/src/examine.rs @@ -730,7 +730,7 @@ fn probe_os(e: &mut Examination) { e.kernel_cmdline = read_host_text("/proc/cmdline").trim().to_owned(); record_distro( e, - &crate::hardware_root::read_os_release(|p| crate::host_path(p)), + &crate::hardware_root::read_os_release(crate::hardware_root::host_path_for_str), ); if let Some(param) = parse_iommu_param(&e.kernel_cmdline) { e.iommu_kernel_param = param; diff --git a/crates/rocm-core/src/hardware_root.rs b/crates/rocm-core/src/hardware_root.rs index 1e6c61fdd4..872f7f8f93 100644 --- a/crates/rocm-core/src/hardware_root.rs +++ b/crates/rocm-core/src/hardware_root.rs @@ -78,6 +78,32 @@ pub fn host_path(path: impl AsRef) -> PathBuf { host_path_under(hardware_root().as_deref(), path.as_ref()) } +/// [`host_path`], fixed to `&str`. +/// +/// [`read_os_release`]'s `resolve` parameter needs a concrete +/// `Fn(&str) -> PathBuf`, which a bare reference to the generic `host_path` +/// cannot satisfy (the borrow checker rejects it as "not general enough" +/// over the resolved lifetime), so every probe that must honour a simulated +/// root passes this instead of `|p| host_path(p)`. +#[must_use] +pub fn host_path_for_str(path: &str) -> PathBuf { + host_path(path) +} + +/// [`read_os_release`]'s `resolve` parameter for a caller that must always +/// read the real machine. +/// +/// Never routed through [`host_path`], because it builds a package-manager +/// plan or install hint that runs against the real host, so a simulated +/// host root must not choose its distro (see each caller's own doc comment +/// for why). A bare `PathBuf::from` is rejected the same way a bare +/// `host_path` is (see [`host_path_for_str`]), so every such caller passes +/// this instead of `|p| PathBuf::from(p)`. +#[must_use] +pub fn identity_path_for_str(path: &str) -> PathBuf { + PathBuf::from(path) +} + #[cfg(feature = "e2e-test-hooks")] fn hardware_root() -> Option { std::env::var_os(TEST_HOST_ROOT_ENV) diff --git a/crates/rocm-core/src/host_gpu.rs b/crates/rocm-core/src/host_gpu.rs index cd66b24994..3388aafaad 100644 --- a/crates/rocm-core/src/host_gpu.rs +++ b/crates/rocm-core/src/host_gpu.rs @@ -1968,7 +1968,7 @@ pub(crate) fn detect_distro_name() -> Option { } if runtime_is_linux() { - return match hardware_root::read_os_release(|p| host_path(p)) { + return match hardware_root::read_os_release(hardware_root::host_path_for_str) { // Absent matches the pre-fallback behaviour this function has // always had: no file at all leaves the distro name unknown // entirely, rather than reporting "Linux" for a machine that diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 8ebff2c4cf..3e2768cd12 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -1004,7 +1004,7 @@ fn install_hint_for_read( /// their distribution. #[cfg(target_os = "linux")] fn real_os_release() -> crate::hardware_root::OsRelease { - crate::hardware_root::read_os_release(|p| std::path::PathBuf::from(p)) + crate::hardware_root::read_os_release(crate::hardware_root::identity_path_for_str) } const OPENMPI_MANUAL_HINT: &str = "install your distribution's OpenMPI runtime package (providing libmpi.so / libmpi_cxx.so and mpirun)"; From b6b0abdfea9539a2cae3c3a68d6043cecf782065 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 07:22:51 +0000 Subject: [PATCH 11/18] fix: non-blocking doc/comment nits and the last two /etc-only readers - docs/testing.md's "_read-suffixed functions" paragraph had the delegation backwards: they delegate to the _at functions, not to the bare-text ones (which are _at's siblings, not something _read routes through). Also drops plan_for_os_release from the list now that it's deleted, and bumps the examine-20..24 ranges to ..25. - plan_for_os_release_read's doc comment claimed the fix avoids the generic "Could not map distribution (ID=)" message; it still appends it, just with the real cause prepended. Reworded to say what actually happens. - Three install_hint doc comments (openmpi/libatomic/libnuma) said "reads /etc/os-release" without mentioning the fallback. - A test doc in host_gpu.rs said the unreadable-file case was "unchanged by this PR" when it's the opposite - new behavior - and referencing a PR goes stale the moment it merges. fix.rs and diagnose.rs's "fix-wsl-5-distro-too-old" verify: strings were the only os-release readers left in the tree without the fallback - both now check /usr/lib/os-release too. Signed-off-by: Jussi Elo (cherry picked from commit e072ebee210bd55615e2e17e8b962898eba18ff0) --- crates/rocm-core/src/diagnose.rs | 3 ++- crates/rocm-core/src/fix.rs | 2 +- crates/rocm-core/src/host_gpu.rs | 9 +++++---- crates/rocm-core/src/openmpi.rs | 19 ++++++++++++------- docs/testing.md | 11 ++++++----- 5 files changed, 26 insertions(+), 18 deletions(-) diff --git a/crates/rocm-core/src/diagnose.rs b/crates/rocm-core/src/diagnose.rs index 04ccd28bb6..b0797468a5 100644 --- a/crates/rocm-core/src/diagnose.rs +++ b/crates/rocm-core/src/diagnose.rs @@ -2306,7 +2306,8 @@ fn check_wsl_5_distro_too_old(e: &Examination, _symptom: &str) -> Diagnosis { "# wsl --install -d Ubuntu-24.04".to_owned(), ], fix_id: "fix-wsl-5-distro-too-old".to_owned(), - verify: "grep VERSION_ID /etc/os-release".to_owned(), + verify: "grep VERSION_ID /etc/os-release /usr/lib/os-release 2>/dev/null | head -1" + .to_owned(), notes: vec![ "This is a hard floor, not a recommendation: Ubuntu 22.04 ships glibc 2.35, below the glibc 2.38 / GLIBCXX_3.4.32 that every published Lemonade embeddable is linked against, so the engine cannot start there at all.".to_owned(), ], diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 1e098110e9..92a7a26e84 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -746,7 +746,7 @@ const RECIPES: &[FixRecipe] = &[ needs_sudo: false, needs_reboot: false, needs_relogin: false, - verify: "grep VERSION_ID /etc/os-release", + verify: "grep VERSION_ID /etc/os-release /usr/lib/os-release 2>/dev/null | head -1", notes: &[ "Distros install side by side, so the current one can stay until the new one is set up.", ], diff --git a/crates/rocm-core/src/host_gpu.rs b/crates/rocm-core/src/host_gpu.rs index 3388aafaad..70b55a8a36 100644 --- a/crates/rocm-core/src/host_gpu.rs +++ b/crates/rocm-core/src/host_gpu.rs @@ -4833,10 +4833,11 @@ Class Name: Display ); } - /// A file that exists but could not be read names itself and the error, - /// distinctly from a bad line it never reached and from "no file at all" - /// — which `detect_distro_name` keeps reporting as unknown, unchanged by - /// this PR (see its own doc comment). + /// A file that exists but could not be read names itself and the error — + /// new behavior; it used to be folded into "unknown" like an absent file. + /// It is distinct from a bad line it never reached, and from "no file at + /// all", which `detect_distro_name` still reports as unknown (see its own + /// doc comment) — that part is unchanged. #[test] fn distro_name_names_an_unreadable_file_instead_of_guessing_linux() { assert_eq!( diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 3e2768cd12..13f6b9eb43 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -868,10 +868,12 @@ pub fn plan_for_os_release_at( /// Names the file actually read in an unreadable-line message, and reports 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 "Could not map distribution (ID=)" — the same message an -/// actually unknown distribution gets — sending the user looking for a -/// support gap instead of a filesystem problem. +/// unreadable (permission denied, a directory in its place) would say only +/// "Could not map distribution (ID=)" — the same message an actually unknown +/// distribution gets, sending the user looking for a support gap instead of +/// a filesystem problem. The real cause is now prepended ahead of that +/// generic message, not substituted for it — `build("", "")` still produces +/// it, since nothing else identifies the distribution either. #[must_use] pub fn plan_for_os_release_read( read: &crate::hardware_root::OsRelease, @@ -1016,7 +1018,8 @@ const LIBNUMA_MANUAL_HINT: &str = /// Build a short, distro-aware hint describing how to install the OpenMPI /// runtime that vLLM requires, for embedding in user-facing error messages. /// -/// On Linux it reads `/etc/os-release` and returns the package-manager command +/// On Linux it reads `/etc/os-release` (falling back to `/usr/lib/os-release` +/// per `os-release(5)`) and returns the package-manager command /// from [`build_openmpi_install_plan`] when the distribution is recognized, /// otherwise a generic instruction. Off Linux it returns a generic message, /// since the OpenMPI path is not exercised there. @@ -1043,7 +1046,8 @@ pub fn install_hint() -> InstallHint { /// Build a short, distro-aware hint describing how to install the `libatomic` /// runtime that vLLM requires, for embedding in user-facing error messages. /// -/// On Linux it reads `/etc/os-release` and returns the package-manager command +/// On Linux it reads `/etc/os-release` (falling back to `/usr/lib/os-release` +/// per `os-release(5)`) and returns the package-manager command /// from [`build_libatomic_install_plan`] when the distribution is recognized, /// otherwise a generic instruction. Off Linux it returns a generic message. /// [`InstallHint::or`] offers an automatic install only when that plan @@ -1069,7 +1073,8 @@ pub fn libatomic_install_hint() -> InstallHint { /// Build a short, distro-aware hint describing how to install the real `libnuma` /// runtime that PyTorch requires, for embedding in user-facing error messages. /// -/// On Linux it reads `/etc/os-release` and returns the package-manager command +/// On Linux it reads `/etc/os-release` (falling back to `/usr/lib/os-release` +/// per `os-release(5)`) and returns the package-manager command /// from [`build_libnuma_install_plan`] when the distribution is recognized, /// otherwise a generic instruction. Off Linux it returns a generic message. /// [`InstallHint::or`] offers an automatic install only when that plan diff --git a/docs/testing.md b/docs/testing.md index 972fdcf8a7..32e6380e82 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1627,11 +1627,12 @@ above matches on all three: `rocm install driver` via hints via `plan_for_os_release_read`/`install_hint_for_read`, and `rocm examine`'s distro fields and distro name via `record_distro` and `distro_name_from_os_release`, which both take the whole `OsRelease` directly. -The three `_read`-suffixed functions are the one seam the real call site hands -its result to; the bare-text functions they delegate to (`plan_for_os_release`, -`install_hint_for`, `build_driver_install_plan`) are kept only for the unit -tests below, which fixture text directly and have no `OsRelease` of their -own to construct. +The three `_read`-suffixed functions are the one seam the real call site +hands its result to, and each delegates to the matching `_at` function with +the path it actually read. `install_hint_for`/`build_driver_install_plan` +are bare-text siblings of `_at` — not something `_read` delegates through — +kept only for the unit tests below, which fixture text directly and have no +`OsRelease` of their own to construct. ```bash cargo test -p rocm-core --lib os_release From 565539a7b3e3c9bceea71f8dff9ee0f758f3d6ed Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 09:35:57 +0000 Subject: [PATCH 12/18] refactor: fold repo_version resolution into unreadable_os_release_plan Both call sites resolved the same default template before calling the helper, which only ever discards it (the unreadable plan has no commands). Move the resolution inside so a future default bump can't update one call site and miss the other. Signed-off-by: Jussi Elo (cherry picked from commit db1db884f9934c153cc0a84763859b93d953941c) --- apps/rocm/src/driver_install.rs | 33 ++++++++++++++------------------- 1 file changed, 14 insertions(+), 19 deletions(-) diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 0876cc50af..9129690d20 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -823,9 +823,10 @@ fn build_driver_install_plan( /// 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 so a new -/// early branch added to one is not silently absent from the other. -fn unreadable_os_release_plan(repo_version: String, reason: String) -> DriverInstallPlan { +/// `reason`, never a distro, and differ only in it: shared here, including +/// `repo_version`'s own resolution, so a new early branch — or a bumped +/// default — added to one is not silently absent from the other. +fn unreadable_os_release_plan(reason: String) -> DriverInstallPlan { DriverInstallPlan { supported: false, mutating: false, @@ -833,7 +834,7 @@ fn unreadable_os_release_plan(repo_version: String, reason: String) -> DriverIns os_id: String::new(), version_id: String::new(), codename: String::new(), - repo_version, + repo_version: resolve_shell_default_template("${ROCM_CLI_AMDGPU_VERSION:-7.2.4}"), reason, preflight_checks: Vec::new(), commands: Vec::new(), @@ -888,14 +889,11 @@ fn build_driver_install_plan_at( let os_release = match rocm_core::os_release::parse(os_release_text) { Ok(fields) => fields, Err(unreadable) => { - return unreadable_os_release_plan( - repo_version, - format!( - "{os_release_path} {unreadable}; no driver commands were planned \ - because the distro cannot be read. To fix it, {}.", - unreadable.fix() - ), - ); + 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() + )); } }; let field = |key: &str| os_release.get(key).cloned(); @@ -1030,13 +1028,10 @@ fn build_driver_install_plan_read( if reaches_os_release_parse && let rocm_core::hardware_root::OsRelease::Unreadable { path, error } = read { - return unreadable_os_release_plan( - resolve_shell_default_template("${ROCM_CLI_AMDGPU_VERSION:-7.2.4}"), - format!( - "{path} could not be read: {error}; no driver commands were planned \ - because the distro cannot be read." - ), - ); + return unreadable_os_release_plan(format!( + "{path} could not be read: {error}; no driver commands were planned \ + because the distro cannot be read." + )); } build_driver_install_plan_at(examine, read.path(), read.text(), dkms, escalation) } From 5c78fdbf66531d002761b37f4efdf46249312e3e Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 09:36:04 +0000 Subject: [PATCH 13/18] fix: assert the exact OsRelease variant in the simulated-root test real_os_release_ignores_a_simulated_host_root compared the real-host read against an independent fs::read_to_string fallback, but collapsed both "neither file exists" and "a candidate exists but can't be read" into one None/Absent-or-Unreadable branch - exactly the distinction hardware_root::read_os_release exists to preserve. Build the expected value as the same three-way OsRelease the reader returns instead, so the test fails if the real read ever blurs Absent and Unreadable. Signed-off-by: Jussi Elo (cherry picked from commit 66e12fe986dfbb3f6eee9f47c7948ab5489432bd) --- apps/rocm/src/runtime_install_finalize.rs | 49 +++++++++++++++-------- 1 file changed, 33 insertions(+), 16 deletions(-) diff --git a/apps/rocm/src/runtime_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index 99b1ece446..e1a4f2dba9 100644 --- a/apps/rocm/src/runtime_install_finalize.rs +++ b/apps/rocm/src/runtime_install_finalize.rs @@ -2082,6 +2082,18 @@ 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` @@ -2122,32 +2134,37 @@ pub(crate) mod tests { // 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. Where - // neither candidate is cleanly readable on this box (a minimal or - // sandboxed CI image), assert only the shape (`Absent`/`Unreadable`) - // rather than exact text — this test's job is "did it ignore the - // simulated root", not "what exactly is on this machine". + // 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) => Some(("/etc/os-release", text)), + Ok(text) => ExpectedOsRelease::Found("/etc/os-release", text), Err(e) if e.kind() == std::io::ErrorKind::NotFound => { - fs::read_to_string("/usr/lib/os-release") - .ok() - .map(|text| ("/usr/lib/os-release", text)) + 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(_) => None, + Err(_) => ExpectedOsRelease::Unreadable("/etc/os-release"), }; match expected { - Some((path, text)) => { + ExpectedOsRelease::Found(path, text) => { assert_eq!((read.path(), read.text()), (path, text.as_str())); } - None => assert!( + 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::Absent - | rocm_core::hardware_root::OsRelease::Unreadable { .. } + rocm_core::hardware_root::OsRelease::Unreadable { path: p, .. } if *p == path ), - "expected Absent or Unreadable when neither candidate is cleanly \ - readable, got {read:?}" + "expected Unreadable at {path}, got {read:?}" ), } } From 6731fe89040d3f8d9d0ff30b47640b7c5d8b4358 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 09:36:07 +0000 Subject: [PATCH 14/18] fix: drop filename prefixes from the WSL distro-too-old verify grep grep across two files prints a "filename:" prefix on every match unless told not to, so adding /usr/lib/os-release as a second grep argument made the verify line's output start with "/etc/os-release:" or "/usr/lib/os-release:" ahead of VERSION_ID - cosmetic noise in output meant to be copy-pasted as-is. -h suppresses it on both candidate paths. Signed-off-by: Jussi Elo (cherry picked from commit f8bfa61097918786e78a3406a96bb23fbfced8e1) --- crates/rocm-core/src/diagnose.rs | 2 +- crates/rocm-core/src/fix.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/rocm-core/src/diagnose.rs b/crates/rocm-core/src/diagnose.rs index b0797468a5..9808aefd17 100644 --- a/crates/rocm-core/src/diagnose.rs +++ b/crates/rocm-core/src/diagnose.rs @@ -2306,7 +2306,7 @@ fn check_wsl_5_distro_too_old(e: &Examination, _symptom: &str) -> Diagnosis { "# wsl --install -d Ubuntu-24.04".to_owned(), ], fix_id: "fix-wsl-5-distro-too-old".to_owned(), - verify: "grep VERSION_ID /etc/os-release /usr/lib/os-release 2>/dev/null | head -1" + verify: "grep -h VERSION_ID /etc/os-release /usr/lib/os-release 2>/dev/null | head -1" .to_owned(), notes: vec![ "This is a hard floor, not a recommendation: Ubuntu 22.04 ships glibc 2.35, below the glibc 2.38 / GLIBCXX_3.4.32 that every published Lemonade embeddable is linked against, so the engine cannot start there at all.".to_owned(), diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 92a7a26e84..2bc634d0d4 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -746,7 +746,7 @@ const RECIPES: &[FixRecipe] = &[ needs_sudo: false, needs_reboot: false, needs_relogin: false, - verify: "grep VERSION_ID /etc/os-release /usr/lib/os-release 2>/dev/null | head -1", + verify: "grep -h VERSION_ID /etc/os-release /usr/lib/os-release 2>/dev/null | head -1", notes: &[ "Distros install side by side, so the current one can stay until the new one is set up.", ], From fce44bf40e402e97a40ff8cdbafd16a3ec5544fb Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 11:30:25 +0000 Subject: [PATCH 15/18] refactor: share the Unreadable message's path+error prefix "{path} could not be read: {error}" was hand-duplicated at all five message-building call sites (the driver plan, the OpenMPI plan and hint, examine's probe failure, and the distro name), with only the trailing clause legitimately differing per site. Factor the shared prefix into hardware_root::unreadable_prefix so a future wording change to it can't be applied to four sites and missed on the fifth. Signed-off-by: Jussi Elo --- apps/rocm/src/driver_install.rs | 4 ++-- crates/rocm-core/src/examine.rs | 3 ++- crates/rocm-core/src/hardware_root.rs | 11 +++++++++++ crates/rocm-core/src/host_gpu.rs | 2 +- crates/rocm-core/src/openmpi.rs | 6 ++++-- 5 files changed, 20 insertions(+), 6 deletions(-) diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 9129690d20..5785437b97 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -1029,8 +1029,8 @@ fn build_driver_install_plan_read( && let rocm_core::hardware_root::OsRelease::Unreadable { path, error } = read { return unreadable_os_release_plan(format!( - "{path} could not be read: {error}; no driver commands were planned \ - because the distro cannot be read." + "{}; no driver commands were planned because the distro cannot be read.", + rocm_core::hardware_root::unreadable_prefix(path, error) )); } build_driver_install_plan_at(examine, read.path(), read.text(), dkms, escalation) diff --git a/crates/rocm-core/src/examine.rs b/crates/rocm-core/src/examine.rs index 84a57221d9..bb14ee950b 100644 --- a/crates/rocm-core/src/examine.rs +++ b/crates/rocm-core/src/examine.rs @@ -758,7 +758,8 @@ fn probe_os(e: &mut Examination) { fn record_distro(e: &mut Examination, read: &crate::hardware_root::OsRelease) { if let crate::hardware_root::OsRelease::Unreadable { path, error } = read { e.probe_failures.push(format!( - "{path} could not be read: {error}; the distro is not reported." + "{}; the distro is not reported.", + crate::hardware_root::unreadable_prefix(path, error) )); return; } diff --git a/crates/rocm-core/src/hardware_root.rs b/crates/rocm-core/src/hardware_root.rs index 872f7f8f93..86a5e3d9e2 100644 --- a/crates/rocm-core/src/hardware_root.rs +++ b/crates/rocm-core/src/hardware_root.rs @@ -198,6 +198,17 @@ impl OsRelease { } } +/// The shared opening every [`OsRelease::Unreadable`] message builds on. +/// +/// Names the candidate path and the I/O error that made it unreadable. Each +/// call site appends its own clause describing what that means for it (no +/// commands planned, a probe failure, an unreported distro, ...), so only +/// this shared part can drift if changed in one place and not another. +#[must_use] +pub fn unreadable_prefix(path: &str, error: &std::io::Error) -> String { + format!("{path} could not be read: {error}") +} + /// Reads `/etc/os-release`, falling back to `/usr/lib/os-release` per /// `os-release(5)` when the former is absent. /// diff --git a/crates/rocm-core/src/host_gpu.rs b/crates/rocm-core/src/host_gpu.rs index 70b55a8a36..decd1a26ca 100644 --- a/crates/rocm-core/src/host_gpu.rs +++ b/crates/rocm-core/src/host_gpu.rs @@ -1991,7 +1991,7 @@ pub(crate) fn detect_distro_name() -> Option { /// reported as itself, distinctly from a bad line it never reached. fn distro_name_from_os_release(read: &hardware_root::OsRelease) -> String { if let hardware_root::OsRelease::Unreadable { path, error } = read { - return format!("Linux ({path} could not be read: {error})"); + return format!("Linux ({})", hardware_root::unreadable_prefix(path, error)); } match crate::os_release::parse(read.text()) { Ok(mut fields) => fields diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 13f6b9eb43..06768baed0 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -882,7 +882,8 @@ pub fn plan_for_os_release_read( if let crate::hardware_root::OsRelease::Unreadable { path, error } = read { let mut plan = build("", ""); plan.reason = format!( - "{path} could not be read: {error}, so the distribution cannot be read. {}", + "{}, so the distribution cannot be read. {}", + crate::hardware_root::unreadable_prefix(path, error), plan.reason ); return plan; @@ -990,7 +991,8 @@ fn install_hint_for_read( if let crate::hardware_root::OsRelease::Unreadable { path, error } = read { return InstallHint { text: format!( - "{manual}; {path} could not be read: {error}, so the distribution cannot be read" + "{manual}; {}, so the distribution cannot be read", + crate::hardware_root::unreadable_prefix(path, error) ), plan_installs: false, }; From 856a293324cd59ed63c3a28f86c9d3e32dbd47a8 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 11:30:34 +0000 Subject: [PATCH 16/18] fix: allow dead_code on install_hint_for_at to match its sibling install_hint_for_at's only non-test caller is install_hint_for_read, which already carries #[cfg_attr(not(target_os = "linux"), allow(dead_code))] since it has no caller at all off Linux. Give install_hint_for_at the same attribute for the same reason, instead of relying on it staying reachable through a function that is itself only conditionally alive. Signed-off-by: Jussi Elo --- crates/rocm-core/src/openmpi.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 06768baed0..0d85299376 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -943,6 +943,10 @@ fn install_hint_for(text: &str, build: InstallPlanBuilder, manual: &str) -> Inst /// [`install_hint_for`], naming `path` instead of always `/etc/os-release` in /// an unreadable-line message. +/// +/// Off Linux this has no non-test caller either — [`install_hint_for_read`], +/// its only production caller, is itself dead there for the same reason. +#[cfg_attr(not(target_os = "linux"), allow(dead_code))] fn install_hint_for_at( path: &str, text: &str, From 31881cecbc878baf60227df7e3d369c6feaacb98 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 11:30:42 +0000 Subject: [PATCH 17/18] fix: make the WSL distro-too-old verify grep existence-only grep /etc/os-release /usr/lib/os-release falls back to the second file whenever the first merely fails to match VERSION_ID (no such line, permission denied), not only when it is absent - diverging from hardware_root::read_os_release's existence-only fallback rule this PR establishes. A host where /etc/os-release exists but lacks a VERSION_ID line would silently show /usr/lib/os-release's version instead. Pick the file by existence first, then grep only that one. Signed-off-by: Jussi Elo --- crates/rocm-core/src/diagnose.rs | 2 +- crates/rocm-core/src/fix.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/rocm-core/src/diagnose.rs b/crates/rocm-core/src/diagnose.rs index 9808aefd17..b9a30185c6 100644 --- a/crates/rocm-core/src/diagnose.rs +++ b/crates/rocm-core/src/diagnose.rs @@ -2306,7 +2306,7 @@ fn check_wsl_5_distro_too_old(e: &Examination, _symptom: &str) -> Diagnosis { "# wsl --install -d Ubuntu-24.04".to_owned(), ], fix_id: "fix-wsl-5-distro-too-old".to_owned(), - verify: "grep -h VERSION_ID /etc/os-release /usr/lib/os-release 2>/dev/null | head -1" + verify: "f=/etc/os-release; [ -e \"$f\" ] || f=/usr/lib/os-release; grep VERSION_ID \"$f\" 2>/dev/null | head -1" .to_owned(), notes: vec![ "This is a hard floor, not a recommendation: Ubuntu 22.04 ships glibc 2.35, below the glibc 2.38 / GLIBCXX_3.4.32 that every published Lemonade embeddable is linked against, so the engine cannot start there at all.".to_owned(), diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 2bc634d0d4..3c7a6e89eb 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -746,7 +746,7 @@ const RECIPES: &[FixRecipe] = &[ needs_sudo: false, needs_reboot: false, needs_relogin: false, - verify: "grep -h VERSION_ID /etc/os-release /usr/lib/os-release 2>/dev/null | head -1", + verify: "f=/etc/os-release; [ -e \"$f\" ] || f=/usr/lib/os-release; grep VERSION_ID \"$f\" 2>/dev/null | head -1", notes: &[ "Distros install side by side, so the current one can stay until the new one is set up.", ], From fe42a743ccfcd760c987059cc961def93fd6d282 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 15 Oct 2026 11:30:53 +0000 Subject: [PATCH 18/18] test: cover the Windows half of reaches_os_release_parse a_wsl_host_ignores_an_unreadable_local_os_release_read only pinned the WSL half of the guard that keeps build_driver_install_plan_read's Unreadable branch from firing on a host the Linux driver install was never attempted on. Add the Windows counterpart: an Unreadable local read must still produce windows_validate_only, not unreadable_os_release. Signed-off-by: Jussi Elo --- apps/rocm/src/driver_install.rs | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 5785437b97..b5c5136160 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -2070,6 +2070,31 @@ mod tests { 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`.