diff --git a/Cargo.lock b/Cargo.lock index 785e347897..740adf8b30 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1282,7 +1282,6 @@ dependencies = [ "rand 0.10.3", "reqwest 0.13.4", "rocm-core", - "rocm-engine-protocol", "serde", "serde_json", "sha2", diff --git a/README.md b/README.md index 443a5b7613..5e9bdcb527 100644 --- a/README.md +++ b/README.md @@ -680,13 +680,51 @@ a target yourself with `--family gfx90c`: the request is refused, and no other family is substituted for it. `rocm examine` reports the same conclusion on a `rocm_support` line (see [Examine](#examine)). -These GPUs still work with the Vulkan backend, which needs no ROCm SDK. +These GPUs can still work with the Vulkan backend, which needs no ROCm SDK — +but whether they *do* depends on a Vulkan driver being installed, so `rocm +examine` looks for one rather than assuming it. It reads the Vulkan ICD +manifests (the Khronos `Drivers` registry key on Windows) and, where available, +enumerates devices with `vulkaninfo`. A software rasteriser such as lavapipe or +swiftshader does not count as a GPU driver. `rocm examine` prints that `rocm_support` line on **every** host, not only this -case, at one of three levels: ROCm/HIP-supported, Vulkan-only (the case above), -or unknown. Unknown covers both no GPU detected and a target this build's -catalog does not recognise — detection gaps rather than a verdict about the -hardware, so neither is reported as "no ROCm build". +case, at one of five levels: + +| Level | Meaning | +| --- | --- | +| ROCm/HIP-supported | A TheRock package family covers this GPU. | +| Vulkan-only | No ROCm build, **and** either a Vulkan GPU driver was found here, or the platform cannot be probed for one at all (anything other than Linux and Windows, or a summary from an older `rocm remote doctor` that predates the probe). The `rocm_support` line says which of the two it is, and only names a driver when one was actually found. | +| Vulkan-unconfirmed | No ROCm build, and the probe could not reach an answer: nothing was found, and at least one of the two sources — the ICD/registry listing or `vulkaninfo` — never answered. Either one can be the source that went unread (on Windows the registry read is a separate PowerShell call that can fail on its own), and the `vulkan:` line names which. | +| no GPU backend | No ROCm build, **and** the probe looked and found no Vulkan GPU driver. This takes `vulkaninfo`'s own answer: the ICD listing is not exhaustive on either platform, so it never denies a driver by itself. | +| unknown | No GPU detected, or a target this build's catalog does not recognize. | + +The last row is a detection gap rather than a verdict about the hardware, which +is why it is not reported as "no ROCm build". Vulkan-unconfirmed is kept +separate from "no GPU backend" for the same reason in the other direction: on +Windows the Khronos `Drivers` key is legacy and `vulkaninfo` is rarely on PATH, +so a working machine can land there, and it has not earned a confirmed "no". + +`rocm examine --json` reports the evidence behind this in a `summary.vulkan` +object (status, ICD manifests found, devices enumerated). The host summary is +flattened into the document's `summary` member, so the object is there and not +at the top level. The field is optional, so an older `rocm remote doctor` +summary that predates it reads as unknown rather than as a false "no Vulkan". + +The probe runs wherever the full host summary is gathered, not on `rocm examine` +alone: the text and JSON of `rocm examine`, the MCP and bridge snapshots, the +free-form answer, `rocm install driver` and its `--reconcile` form, and `rocmd`'s +host snapshot, MCP and sandbox paths. Each of those pays one `vulkaninfo` (or, on +Windows, one registry read) per gather. + +It does not run on the lean scope, `ExamineSummary::gather_without_driver_facts`, +which the runtime-install finalizer uses to read the GPU target: that leaves +`vulkan` as `None`, meaning "not probed", which reads as unknown rather than as a +false "no Vulkan". + +`rocm engines` and the `rocm diagnose` finding `info-20-gpu-no-rocm-support` still +speak from the gfx table alone, so they can name Vulkan on a host where `rocm +examine` would say otherwise; spawning `vulkaninfo` (and PowerShell on Windows) +was judged too expensive for a plain listing command. #### Compiler toolchain (--devel) @@ -896,7 +934,7 @@ old date is a hint to look at the driver, not a finding that it is broken. See Manage multiple side-by-side ROCm runtimes: ``` -rocm runtimes list [--json] +rocm runtimes list rocm runtimes activate [--restart-services [--yes]] rocm runtimes rollback [--restart-services [--yes]] rocm runtimes uninstall [--yes] [--dry-run] @@ -930,13 +968,6 @@ version alone, so one version can appear more than once: a `--devel` install and a plain one of the same version are two separate runtimes, as are two installs that resolved different GPU device payloads. -`list --json` prints the same listing as one JSON document on stdout for -scripts: each runtime with its key, version, mode, status and toolchain, its -`provenance` as an object with the same four facts, and `active` and -`rollback_target` flags in place of the `*` and `-` markers. Unset values, -including a provenance fact the text shows as `unrecorded`, are `null`. Fields -may be added in later releases; existing ones are not renamed or removed. - `activate` and `rollback` change which runtime the next install or server picks up. A server that is already running is not moved: it keeps serving on the runtime it started with until it is restarted. Both commands count the diff --git a/apps/rocm/src/bridge_snapshot.rs b/apps/rocm/src/bridge_snapshot.rs index a5c7b648b3..bb9745c82e 100644 --- a/apps/rocm/src/bridge_snapshot.rs +++ b/apps/rocm/src/bridge_snapshot.rs @@ -40,6 +40,7 @@ pub(crate) fn build_codex_bridge_snapshot(paths: &AppPaths) -> Result assert_eq!(parsed, json, "{args:?}"), - other => panic!("expected runtimes list, got {other:?}"), - } - } - assert!( - parse_runtimes(&["--json"]).is_err(), - "`rocm runtimes --json` must be rejected, not read as `list --json`" - ); - } - fn parse_serve(args: &[&str]) -> Result { let mut argv = vec!["rocm", "serve", "qwen"]; argv.extend_from_slice(args); diff --git a/apps/rocm/src/dash.rs b/apps/rocm/src/dash.rs index 72a3624669..c09f55f3c9 100644 --- a/apps/rocm/src/dash.rs +++ b/apps/rocm/src/dash.rs @@ -212,11 +212,9 @@ fn runtime_summaries(paths: &AppPaths, config: &RocmCliConfig) -> Vec = manifests .iter() .filter(|m| Some(m.runtime_id.as_str()) == default_id) diff --git a/apps/rocm/src/driver_plan.rs b/apps/rocm/src/driver_plan.rs index 1ef2804685..6508b4d63b 100644 --- a/apps/rocm/src/driver_plan.rs +++ b/apps/rocm/src/driver_plan.rs @@ -1252,6 +1252,7 @@ pub(crate) mod tests { detected_gfx_target: Some("gfx1201".to_owned()), compatible_therock_family: Some("gfx120X-all".to_owned()), detected_therock_family: None, + vulkan: None, driver: rocm_core::DriverSummary { policy: "linux_official_amd_dkms_wrapper".to_owned(), status: "amdgpu_missing".to_owned(), diff --git a/apps/rocm/src/engine_ipc.rs b/apps/rocm/src/engine_ipc.rs index 57978d80dd..8a7858b480 100644 --- a/apps/rocm/src/engine_ipc.rs +++ b/apps/rocm/src/engine_ipc.rs @@ -28,9 +28,8 @@ //! (`engine_request`, `engine_request_with_env_root`, //! `engine_stdio_child_request`), the `ScopedEnvVar`/ //! `with_scoped_builtin_engine_env` env-scoping helpers and the -//! `BUILTIN_ENGINE_ENV_LOCK` mutex they serialize on, `builtin_engine_handler`, -//! `builtin_engine_request`, `run_builtin_engine_stdio` with -//! `answer_builtin_engine_stdio`, and the built-in HTTP-serving path +//! `BUILTIN_ENGINE_ENV_LOCK` mutex they serialize on, `builtin_engine_request`, +//! `run_builtin_engine_stdio`, and the built-in HTTP-serving path //! (`builtin_engine_available`, `run_builtin_engine_serve_http`, //! `builtin_engine_serve_http_args`). //! @@ -291,37 +290,29 @@ fn with_scoped_builtin_engine_env( result } -/// How a built-in engine answers a decoded request. -type BuiltinEngineHandler = fn(EngineRequestEnvelope) -> EngineResponseEnvelope; - -/// The handler of the engine built into this binary under `engine`, or `None`. -/// The in-process request path, `rocm __engine-stdio` and -/// [`builtin_engine_available`] all ask it; `run_builtin_engine_serve_http` -/// keeps its own match over the same engines. -fn builtin_engine_handler(engine: &str) -> Option { - match engine { - "lemonade" => Some(rocm_engine_lemonade::builtin_handle_envelope), - "vllm" => Some(rocm_engine_vllm::builtin_handle_envelope), - "aim" => Some(rocm_engine_aim::builtin_handle_envelope), - _ => None, - } -} - fn builtin_engine_request( engine: &str, envelope: &EngineRequestEnvelope, ) -> Option { - builtin_engine_handler(engine).map(|handle| handle(envelope.clone())) + match engine { + "lemonade" => Some(rocm_engine_lemonade::builtin_handle_envelope( + envelope.clone(), + )), + "vllm" => Some(rocm_engine_vllm::builtin_handle_envelope(envelope.clone())), + "aim" => Some(rocm_engine_aim::builtin_handle_envelope(envelope.clone())), + _ => None, + } } pub(crate) fn run_builtin_engine_stdio(engine: &str) -> Result<()> { - let handle = builtin_engine_handler(engine) - .with_context(|| format!("engine `{engine}` is not built into this rocm binary"))?; let mut input = String::new(); io::stdin() .read_to_string(&mut input) .context("failed to read engine stdio request")?; - let response = answer_builtin_engine_stdio(handle, &input); + let envelope: EngineRequestEnvelope = + serde_json::from_str(&input).context("failed to parse engine stdio request")?; + let response = builtin_engine_request(engine, &envelope) + .with_context(|| format!("engine `{engine}` is not built into this rocm binary"))?; print!("{}", serde_json::to_string(&response)?); Ok(()) } @@ -604,16 +595,8 @@ where devices } -/// The answer a built-in engine's `handle` gives to the request `text` read on -/// stdin: the version is judged before the method or payload is decoded (see -/// [`rocm_engine_protocol::answer_engine_request`]), as a separately built -/// engine's `stdio` command does. -fn answer_builtin_engine_stdio(handle: BuiltinEngineHandler, text: &str) -> EngineResponseEnvelope { - rocm_engine_protocol::answer_engine_request(text, handle) -} - pub(crate) fn builtin_engine_available(engine: &str) -> bool { - builtin_engine_handler(engine).is_some() + matches!(engine, "lemonade" | "vllm" | "aim") } #[allow(clippy::too_many_arguments)] @@ -974,73 +957,6 @@ mod tests { ); } - /// Every engine built into this binary holds the engine protocol contract on - /// both of its paths: the decoded request `rocm` hands it in-process, and - /// `answer_builtin_engine_stdio`, the function `rocm __engine-stdio ` - /// (which `rocmd` runs) answers request text with. The verb's own stdin - /// reading is not run here; e2e engine-ipc-08 to -12 cover it, for `vllm` - /// only. A refusal reaches the caller through the same - /// `decode_engine_response` as a child's answer, naming the engine's code. - #[test] - fn every_built_in_engine_holds_the_protocol_contract() { - assert!(!builtin_engine_available("not-an-engine")); - assert!( - builtin_engine_request( - "not-an-engine", - &EngineRequestEnvelope::new(EngineMethod::Capabilities, serde_json::json!({})) - ) - .is_none() - ); - for engine in crate::cli::SUPPORTED_ENGINES { - assert!(builtin_engine_available(engine), "{engine}"); - let handle = builtin_engine_handler(engine).expect("built in"); - rocm_engine_protocol::engine_contract::assert_engine_holds_protocol_contract( - engine, - |text| answer_builtin_engine_stdio(handle, text), - |envelope| builtin_engine_request(engine, &envelope).expect("built in"), - ); - let mut request = EngineRequestEnvelope::new(EngineMethod::Stop, serde_json::json!({})); - request.protocol_version = Some("9.0.0".to_owned()); - let refusal = builtin_engine_request(engine, &request).expect("built in"); - assert_eq!( - decode_engine_response::(refusal) - .unwrap_err() - .to_string(), - format!( - "incompatible_protocol: this engine speaks engine protocol \ - {}; the request was made for protocol 9.0.0, which \ - it cannot serve", - rocm_engine_protocol::ENGINE_PROTOCOL_VERSION - ), - "{engine}" - ); - } - } - - /// Each built-in engine id reaches that engine's own handler: its - /// capabilities answer is the one the engine crate itself gives, and the - /// three engines' answers differ, so a swapped mapping shows. - #[test] - fn each_built_in_engine_id_reaches_its_own_engine() { - let capabilities = - || EngineRequestEnvelope::new(EngineMethod::Capabilities, serde_json::json!({})); - let own: [(&str, BuiltinEngineHandler); 3] = [ - ("lemonade", rocm_engine_lemonade::builtin_handle_envelope), - ("vllm", rocm_engine_vllm::builtin_handle_envelope), - ("aim", rocm_engine_aim::builtin_handle_envelope), - ]; - let mut answers = Vec::new(); - for (engine, handle) in own { - let mapped = builtin_engine_handler(engine).expect("built in"); - let expected = handle(capabilities()).data; - assert_eq!(mapped(capabilities()).data, expected, "{engine}"); - answers.push(expected); - } - assert_ne!(answers[0], answers[1]); - assert_ne!(answers[1], answers[2]); - assert_ne!(answers[0], answers[2]); - } - #[test] fn engine_plugin_discovery_finds_runtime_binary() -> Result<()> { let (root, paths) = test_paths("engine-plugin"); @@ -1120,7 +1036,7 @@ mod tests { const STOPPED: &str = r#"{"ok":true,"data":{"stopped":true}}"#; fn envelope(method: EngineMethod, payload: serde_json::Value) -> EngineRequestEnvelope { - EngineRequestEnvelope::new(method, payload) + EngineRequestEnvelope { method, payload } } fn stop_request() -> EngineRequestEnvelope { @@ -1167,11 +1083,7 @@ mod tests { assert_eq!(engine.argv(), ["stdio"]); assert_eq!( engine.stdin(), - format!( - "{{\"protocol_version\":\"{}\",\"method\":\"stop\",\ - \"payload\":{{\"service_id\":\"svc\"}}}}\n", - rocm_engine_protocol::ENGINE_PROTOCOL_VERSION - ) + "{\"method\":\"stop\",\"payload\":{\"service_id\":\"svc\"}}\n" ); } diff --git a/apps/rocm/src/examine_report_text.rs b/apps/rocm/src/examine_report_text.rs index 5e71bcb26b..077d0f9b4f 100644 --- a/apps/rocm/src/examine_report_text.rs +++ b/apps/rocm/src/examine_report_text.rs @@ -134,9 +134,13 @@ pub(crate) fn examine_human_report( let mut output = render_examine_plain_header(&summary); output.push_str(&summary.render_text()); append_examine_runtime_state(&mut output, paths, config)?; + // `summary` already carries the Vulkan probe result, so the support level + // here is the verified one: this is the surface other messages send people + // to when they want a real answer. let gpu_support_level = rocm_core::gpu_support_level( summary.detected_gfx_target.as_deref(), summary.compatible_therock_family.as_deref(), + summary.vulkan_status(), ); append_examine_engine_inventory( &mut output, @@ -205,7 +209,10 @@ pub(crate) fn render_engine_inventory_text_with_paths(paths: Option<&AppPaths>) render_engine_inventory_text_for_host( paths, rocm_core::default_engine_for_host(&host_gpu), - rocm_core::gpu_support_level_for_host_gpu(&host_gpu), + // No Vulkan probe on this listing path, for the reason given on + // `host_gpu_support_level`: `rocm engines` is cheap by design, and + // `rocm examine` is where the verified answer lives. + rocm_core::gpu_support_level_for_host_gpu(&host_gpu, rocm_core::VulkanStatus::Unknown), ) } @@ -299,16 +306,43 @@ fn render_engine_inventory_text_for_host( /// `Unknown` does not re-name `rocm examine` either — lemonade's own row /// already does, two lines below. /// -/// Matched exhaustively, like the notes it has to agree with, so a fourth +/// Matched exhaustively, like the notes it has to agree with, so a sixth /// support level is a compile error here instead of silently inheriting a -/// claim about ROCm. +/// claim about ROCm. That is not hypothetical: this function arrived with +/// three variants and the Vulkan probe added two more, and the compile error +/// is what forced the decision below rather than letting either new level +/// fall through to a sentence about a backend nothing had established. const fn gpu_execution_line(level: rocm_core::GpuSupportLevel) -> &'static str { match level { rocm_core::GpuSupportLevel::RocmHip => " ROCm GPU execution is required.", rocm_core::GpuSupportLevel::VulkanOnly => { " GPU execution is required; on this GPU that is the Vulkan backend, not ROCm." } - rocm_core::GpuSupportLevel::Unknown => { + // The three levels that establish no usable backend share one + // sentence, because the banner's job is to state the refusal and all + // three refuse identically. What differs between them is *why*, and + // that is the per-engine row's job two lines below — lemonade's note + // already distinguishes "could not be determined" from "no Vulkan + // driver was found", and repeating a weaker version of it up here + // would only risk the two drifting apart. + // + // Neither new level may borrow the `RocmHip` arm. `NoGpuBackend` is a + // host the catalog confirmed has no ROCm build and the probe + // confirmed has no Vulkan driver; `VulkanUnconfirmed` has the same + // confirmed absence of a ROCm build with the Vulkan half still open. + // On both, "ROCm GPU execution is required" is precisely the stale + // claim this stack exists to delete — stated directly above a row + // saying this GPU has no ROCm/HIP support. + // + // The other half is kept rather than softened: on `NoGpuBackend` it is + // tempting to read "no backend can run here" as licence to mention the + // CPU, but rocm-cli refuses CPU execution at every level and Vulkan + // counts as a GPU path rather than a fallback from one. The sentence + // that is true on all three is that a GPU is required and the CPU is + // not an alternative, which is what it says. + rocm_core::GpuSupportLevel::VulkanUnconfirmed + | rocm_core::GpuSupportLevel::NoGpuBackend + | rocm_core::GpuSupportLevel::Unknown => { " GPU execution is required; CPU execution is not supported." } } @@ -712,6 +746,7 @@ mod tests { detected_gfx_target: None, compatible_therock_family: None, detected_therock_family: None, + vulkan: None, driver: rocm_core::DriverSummary { policy: "linux_official_amd_dkms_wrapper".to_owned(), status: "amdgpu_available".to_owned(), @@ -1525,6 +1560,105 @@ mod tests { let _ = fs::remove_dir_all(root); } + /// The two support levels this change added carry new user-facing wording + /// on both renderers, and nothing exercised either of them. They are each + /// other's nearest neighbour -- both say "no ROCm/HIP" -- so each case + /// asserts what the *other* one would have said is absent; otherwise a + /// single arm doing duty for both would still pass. + #[test] + fn examine_engine_inventory_separates_an_unconfirmed_vulkan_from_no_backend_at_all() { + let (root, paths) = test_paths("examine-engine-inventory-vulkan-tiers"); + let config = RocmCliConfig::default(); + + let mut unconfirmed = String::new(); + append_examine_engine_inventory( + &mut unconfirmed, + &paths, + &config, + "lemonade", + rocm_core::GpuSupportLevel::VulkanUnconfirmed, + ); + assert!( + unconfirmed.contains("could not be determined"), + "an unprobed Vulkan path must read as unknown, not as a verdict:\n{unconfirmed}" + ); + assert!( + !unconfirmed.contains("no Vulkan driver was found"), + "`VulkanUnconfirmed` must not borrow `NoGpuBackend`'s confirmed absence:\n{unconfirmed}" + ); + assert!( + !unconfirmed.contains("so it runs on the Vulkan llama.cpp backend"), + "nor may it promise the backend `VulkanOnly` promises:\n{unconfirmed}" + ); + + let mut none = String::new(); + append_examine_engine_inventory( + &mut none, + &paths, + &config, + "lemonade", + rocm_core::GpuSupportLevel::NoGpuBackend, + ); + assert!( + none.contains("no Vulkan driver was found") + && none.contains("no GPU backend can run here"), + "a confirmed absence must say so plainly:\n{none}" + ); + assert!( + !none.contains("could not be determined"), + "`NoGpuBackend` is the probed answer, not the missing one:\n{none}" + ); + + assert_ne!( + unconfirmed, none, + "'we could not tell' and 'we looked and there is none' are different facts" + ); + let _ = fs::remove_dir_all(root); + } + + /// `rocm engines` renders the same two notes through a different renderer, + /// so it needs the same pair -- this is the counterpart to + /// `examine_engine_inventory_separates_an_unconfirmed_vulkan_from_no_backend_at_all`. + #[test] + fn engines_inventory_separates_an_unconfirmed_vulkan_from_no_backend_at_all() { + let (root, paths) = test_paths("engines-inventory-vulkan-tiers"); + + let unconfirmed = render_engine_inventory_text_for_host( + Some(&paths), + "lemonade", + rocm_core::GpuSupportLevel::VulkanUnconfirmed, + ); + assert!( + unconfirmed.contains("could not be determined") + && unconfirmed.contains("no ROCm/HIP support"), + "`rocm engines` must report the same unprobed Vulkan state examine does:\n{unconfirmed}" + ); + assert!( + !unconfirmed.contains("Lemonade server with ROCm llama.cpp backend"), + "a host with no ROCm build must not be told it has one:\n{unconfirmed}" + ); + + let none = render_engine_inventory_text_for_host( + Some(&paths), + "lemonade", + rocm_core::GpuSupportLevel::NoGpuBackend, + ); + assert!( + none.contains("no GPU backend can run here"), + "`rocm engines` must not keep promising a backend that was ruled out:\n{none}" + ); + assert!( + !none.contains("could not be determined"), + "the probed answer must not be softened into the unprobed one:\n{none}" + ); + + assert_ne!( + unconfirmed, none, + "the two levels exist precisely because they are not the same claim" + ); + let _ = fs::remove_dir_all(root); + } + /// `rocm engines` makes the same claim `rocm examine` does, through a /// different renderer, so it needs the same pair of tests: /// `examine_engine_inventory_names_vulkan_for_a_gpu_with_no_rocm_support` @@ -1625,9 +1759,17 @@ mod tests { fn engines_banner_and_engine_note_cannot_contradict_each_other() { let (root, paths) = test_paths("engines-banner-vs-note"); + // All five levels, not the three this test was written against: the + // Vulkan probe added `VulkanUnconfirmed` and `NoGpuBackend`, and both + // are hosts whose own lemonade row states there is no ROCm/HIP + // support — exactly the shape of the contradiction this test exists + // to catch, so leaving them out would leave the new levels free to + // reintroduce it. for level in [ rocm_core::GpuSupportLevel::RocmHip, rocm_core::GpuSupportLevel::VulkanOnly, + rocm_core::GpuSupportLevel::VulkanUnconfirmed, + rocm_core::GpuSupportLevel::NoGpuBackend, rocm_core::GpuSupportLevel::Unknown, ] { let output = render_engine_inventory_text_for_host(Some(&paths), "lemonade", level); @@ -1658,4 +1800,77 @@ mod tests { let _ = fs::remove_dir_all(root); } + + /// The other half of the banner, and the half nothing asserted: + /// `gpu_execution_line` tells a `VulkanOnly` host which backend it has, + /// and tells the other three that the CPU is not an alternative. Neither + /// sentence appeared anywhere outside that function, so merging the + /// `VulkanOnly` arm into the shared one below it left every test green — + /// including the ROCm-parity sweep above, which only reads the word "ROCm + /// GPU execution is required" and is satisfied by either sentence. + /// + /// The discrimination is the finding, not either sentence on its own: + /// `VulkanOnly` is the single level where the classifier established a GPU + /// backend, and "CPU execution is not supported" there is true but silent + /// about the backend this host actually has. So each level asserts its own + /// banner present *and* the other's absent, and the three no-usable-backend + /// levels are swept rather than sampled, so a future arm cannot quietly + /// pick up the Vulkan claim. + #[test] + fn engines_banner_claims_a_vulkan_backend_only_where_one_was_established() { + let (root, paths) = test_paths("engines-banner-vulkan-only"); + let banner = |level| { + render_engine_inventory_text_for_host(Some(&paths), "lemonade", level) + .lines() + .find(|line| line.contains("GPU execution is required")) + .expect("every level prints the GPU-execution banner") + .to_owned() + }; + + let vulkan_only = banner(rocm_core::GpuSupportLevel::VulkanOnly); + assert!( + vulkan_only.contains("that is the Vulkan backend, not ROCm"), + "the one level with an established GPU backend must name it:\n{vulkan_only}" + ); + assert!( + !vulkan_only.contains("CPU execution is not supported"), + "and must not borrow the sentence of the levels that have none:\n{vulkan_only}" + ); + + for level in [ + rocm_core::GpuSupportLevel::VulkanUnconfirmed, + rocm_core::GpuSupportLevel::NoGpuBackend, + rocm_core::GpuSupportLevel::Unknown, + ] { + let line = banner(level); + assert!( + !line.contains("that is the Vulkan backend, not ROCm"), + "{level:?} established no Vulkan backend and must not claim one:\n{line}" + ); + assert!( + line.contains("CPU execution is not supported"), + "but the refusal is what is invariant across them, so it is still \ + said:\n{line}" + ); + assert_ne!( + line, vulkan_only, + "{level:?} must not render the `VulkanOnly` banner" + ); + } + + // `RocmHip` is the fourth answer, and the only one that may still + // require ROCm. Without it the sweep above would pass on a banner that + // had lost that arm too. + let rocm_hip = banner(rocm_core::GpuSupportLevel::RocmHip); + assert!( + rocm_hip.contains("ROCm GPU execution is required"), + "a ROCm-capable host keeps the original claim:\n{rocm_hip}" + ); + assert_ne!( + rocm_hip, vulkan_only, + "and it is not the Vulkan sentence either" + ); + + let _ = fs::remove_dir_all(root); + } } diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index 20e2e64ce0..7c97d3450f 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -1089,6 +1089,49 @@ const fn lemonade_engine_note(level: rocm_core::GpuSupportLevel) -> &'static str rocm_core::GpuSupportLevel::RocmHip => { "default embedded Lemonade server with ROCm llama.cpp backend" } + // Looked at and inconclusive. Says the same "no ROCm/HIP" fact as the + // arm below, but stops short of its claim about Vulkan, because + // nothing here established it either way. + // + // Reached by every caller that passes a real `VulkanStatus`, which is + // `rocm examine` *and* `build_codex_bridge_snapshot` (the + // `InternalBridgeSnapshot` command and the MCP `bridge_snapshot` tool), + // which builds the level from `examine.vulkan_status()` rather than the + // cheap `host_gpu_support_level`. The MCP `engines` tool is deliberately + // NOT in that list: it goes through `host_gpu_support_level`, which + // always passes `VulkanStatus::Unknown`, so it can never land on these + // two arms. + // + // So the advice cannot be "run `rocm examine`": this very note is + // rendered *inside* that command's own output, through + // `examine_human_report` -> `append_examine_engine_inventory`, and told + // its reader to run the command they were already reading. It names the + // thing that would actually settle the question instead. + // + // The claim and the next step are `rocm_core`'s + // `VULKAN_UNCONFIRMED_CLAIM` and `VULKAN_UNCONFIRMED_NEXT_STEP`, + // spelled out here only because this is a `const fn` returning a + // `&'static str` and a constant cannot be interpolated into one. + // `the_lemonade_note_and_the_support_line_make_the_same_unconfirmed_claim` + // holds the two in step; both strings appear in the *same* `rocm + // examine` report, a few lines apart, so a divergence is visible to the + // user immediately. + // + // In particular this must not say "install a Vulkan driver" + // unconditionally: a working Windows Adrenalin machine lands in this + // level, since the Khronos key it reads is legacy there. Nor "install + // `vulkaninfo`": on a driverless Linux host that tool is already + // installed, prints "Found no drivers!" and exits 1, which is another + // of the shapes that lands here. + rocm_core::GpuSupportLevel::VulkanUnconfirmed => { + "default embedded Lemonade server; this GPU has no ROCm/HIP support, and whether a \ + Vulkan driver is present could not be determined here - run `vulkaninfo` yourself \ + to see what it reports, and install a Vulkan driver (Mesa RADV on Linux, the AMD \ + display driver on Windows) if it finds none" + } + rocm_core::GpuSupportLevel::NoGpuBackend => { + "default embedded Lemonade server; this GPU has no ROCm/HIP support and no Vulkan driver was found, so no GPU backend can run here" + } rocm_core::GpuSupportLevel::Unknown => { "default embedded Lemonade server; run `rocm examine` for this host's GPU support level, which says how to find the backend" } @@ -1101,8 +1144,21 @@ const fn lemonade_engine_note(level: rocm_core::GpuSupportLevel) -> &'static str /// The same two inputs `rocm examine` derives it from, read through /// `detect_host_gpu_summary` rather than the full examine gather — exactly what /// `render_engine_inventory_text_with_paths` (i.e. `rocm engines`) already does. +/// +/// **The Vulkan probe is deliberately not run here**, so this stays the cheap +/// probe its callers chose it for: the probe spawns `vulkaninfo` on Linux and +/// PowerShell on Windows, and `rocm engines` is a listing command that would +/// pay that on every invocation. Passing [`VulkanStatus::Unknown`] keeps these +/// surfaces answering exactly as they did before this probe existed — a +/// Vulkan-capable-by-the-table host still reads `VulkanOnly` — while `rocm +/// examine`, which already gathers the probe, is the surface that can tell a +/// host with a Vulkan driver from one without. That split is why +/// `lemonade_engine_note` sends the user to `rocm examine` for a real answer. pub(crate) fn host_gpu_support_level(paths: Option<&AppPaths>) -> rocm_core::GpuSupportLevel { - rocm_core::gpu_support_level_for_host_gpu(&rocm_core::detect_host_gpu_summary(paths)) + rocm_core::gpu_support_level_for_host_gpu( + &rocm_core::detect_host_gpu_summary(paths), + rocm_core::VulkanStatus::Unknown, + ) } fn refresh_startup_update_check_quietly() { @@ -1290,6 +1346,34 @@ pub(crate) mod tests { ); } + /// The lemonade note and `rocm examine`'s `rocm_support` line both render + /// `VulkanUnconfirmed`, and both appear in the same `rocm examine` report a + /// few lines apart. They must make the same claim about the host and offer + /// the same next step, so both are held against the constants `rocm-core` + /// defines; this note spells them out only because a `const fn` returning + /// `&'static str` cannot interpolate a constant. + /// + /// Neither may tell a host to install a Vulkan driver unconditionally: a + /// working Windows Adrenalin machine reaches this level, because the + /// Khronos registry key the probe reads is legacy there. + #[test] + fn the_lemonade_note_and_the_support_line_make_the_same_unconfirmed_claim() { + let note = super::lemonade_engine_note(rocm_core::GpuSupportLevel::VulkanUnconfirmed); + + assert!( + note.contains(rocm_core::VULKAN_UNCONFIRMED_CLAIM), + "the note must make the shared claim verbatim: {note}" + ); + assert!( + note.contains(rocm_core::VULKAN_UNCONFIRMED_NEXT_STEP), + "and offer the shared next step verbatim: {note}" + ); + assert!( + !note.contains("no Vulkan driver was found"), + "a level a working Adrenalin laptop reaches must not deny its driver: {note}" + ); + } + use std::process::ExitCode; /// `Ok(())` must map to a clean exit so `rocm`'s successful commands don't diff --git a/apps/rocm/src/runtime_registry.rs b/apps/rocm/src/runtime_registry.rs index ac6392d7b8..a939b86b83 100644 --- a/apps/rocm/src/runtime_registry.rs +++ b/apps/rocm/src/runtime_registry.rs @@ -250,30 +250,25 @@ pub(crate) struct RuntimeProvenance<'a> { pub device_target: Option<&'a str>, } -impl<'a> RuntimeProvenance<'a> { - /// Each fact as `(name, recorded value)`, in display order, with `None` for - /// a fact that was not recorded. - /// - /// The one place the names and their order are written down: - /// [`Self::fields`] shows these, and `rocm runtimes list --json` writes them - /// as its `provenance` object, with `null` for `None`. - pub(crate) const fn recorded_fields(&self) -> [(&'static str, Option<&'a str>); 4] { - [ - ("channel", self.channel), - ("source", self.source), - ("source_layout_generation", self.source_layout_generation), - ("device_target", self.device_target), - ] - } - +impl RuntimeProvenance<'_> { /// Each fact as `(name, shown value)`, in display order, with /// [`UNRECORDED_PROVENANCE`] for a fact that was not recorded. /// /// `rocm runtimes list` and `rocm examine` both print from this, so the /// names and values the two show for one runtime cannot drift apart. - pub(crate) fn fields(&self) -> [(&'static str, &'a str); 4] { - self.recorded_fields() - .map(|(name, value)| (name, value.unwrap_or(UNRECORDED_PROVENANCE))) + pub(crate) fn fields(&self) -> [(&'static str, &str); 4] { + fn shown(value: Option<&str>) -> &str { + value.unwrap_or(UNRECORDED_PROVENANCE) + } + [ + ("channel", shown(self.channel)), + ("source", shown(self.source)), + ( + "source_layout_generation", + shown(self.source_layout_generation), + ), + ("device_target", shown(self.device_target)), + ] } } @@ -773,17 +768,10 @@ pub(crate) fn select_runtime_manifest<'a>( pub(crate) fn runtime_usability_status(manifest: &InstalledRuntimeManifest) -> String { match validate_runtime_manifest_for_activation(manifest) { Ok(()) => "ready".to_owned(), - Err(error) => unusable_status_text(&error.to_string()), + Err(error) => format!("unusable ({error})"), } } -/// How the text reports name a runtime that fails the manifest check -/// activation applies, given the reason it fails it. `rocm runtimes list` -/// prints the same words from the reason it also carries in its JSON. -pub(crate) fn unusable_status_text(reason: &str) -> String { - format!("unusable ({reason})") -} - pub(crate) fn validate_runtime_manifest_for_activation( manifest: &InstalledRuntimeManifest, ) -> Result<()> { diff --git a/apps/rocm/src/runtimes_cmd.rs b/apps/rocm/src/runtimes_cmd.rs index b42621f43a..e0b3b45895 100644 --- a/apps/rocm/src/runtimes_cmd.rs +++ b/apps/rocm/src/runtimes_cmd.rs @@ -3,19 +3,17 @@ // SPDX-License-Identifier: MIT //! `rocm runtimes` command: its dispatch, activate/rollback, and the runtime -//! list, which `runtimes_listing` computes once into a `RuntimesListing` that -//! prints either as the text table or, with `--json`, as that value serialized -//! (`docs/json-output.md`). Import and adopt (and recovering the runtime -//! `rocm setup` created) live in `runtime_adopt.rs`, and uninstall in +//! list rendering. Import and adopt (and recovering the runtime `rocm setup` +//! created) live in `runtime_adopt.rs`, and uninstall in //! `runtime_uninstall.rs`. Registry selection and manifest validation live in //! `runtime_registry.rs`; the names other modules import from here //! (`current_runtime_manifest`, `select_runtime_manifest`, //! `validate_runtime_manifest_for_activation`, `runtime_usability_status`, //! and the registry path helpers) are re-exported from this module. //! -//! `runtimes(command)` is the entry point `main.rs`'s `dispatch()` calls for -//! `rocm runtimes`, imported there via -//! `use crate::runtimes_cmd::{runtimes, ...};`. +//! Mechanically relocated from `main.rs` with no behavior change — the +//! `dispatch()` call site stays byte-identical (`runtimes(command)`, +//! re-imported via `use crate::runtimes_cmd::{runtimes, ...};`). //! `RuntimesCommand` lives in `cli.rs` (part of the `Command`/`Cli` clap //! definition) and is reached via `use crate::RuntimesCommand`, a re-import in //! `main.rs`, the same way `engines_cmd.rs` reaches `EnginesCommand`. @@ -47,11 +45,9 @@ use std::fmt::Write as _; use std::fs; -use std::path::PathBuf; use anyhow::{Context, Result}; use rocm_core::{AppPaths, RocmCliConfig, require_yes_or_interactive}; -use serde::Serialize; use crate::runtime_adopt::{ AdoptRuntimeOptions, adopt_runtime_from_python_options, import_runtime_manifest, @@ -65,9 +61,7 @@ pub(crate) use crate::runtime_registry::{ runtime_manifest_path, runtime_registry_dir, runtime_usability_status, select_runtime_manifest, validate_runtime_manifest_for_activation, }; -use crate::runtime_registry::{ - RuntimeProvenance, unusable_status_text, write_active_runtime_marker, -}; +use crate::runtime_registry::{RuntimeProvenance, write_active_runtime_marker}; pub(crate) use crate::runtime_uninstall::{ InstallRootDecision, lemonade_record_report_line, should_remove_runtime_install_root, uninstall_runtime, @@ -100,7 +94,7 @@ pub(crate) fn ensure_runtime_service_restart_approved(command: &RuntimesCommand) restart_services, yes, } => runtime_services::ensure_service_restart_approved(*restart_services, *yes, "rollback"), - RuntimesCommand::List { .. } + RuntimesCommand::List | RuntimesCommand::Uninstall { .. } | RuntimesCommand::Import { .. } | RuntimesCommand::Adopt { .. } => Ok(()), @@ -110,15 +104,15 @@ pub(crate) fn ensure_runtime_service_restart_approved(command: &RuntimesCommand) pub(crate) fn runtimes(command: Option) -> Result<()> { let paths = AppPaths::discover()?; let mut config = RocmCliConfig::load(&paths)?; - let command = command.unwrap_or(RuntimesCommand::List { json: false }); + let command = command.unwrap_or(RuntimesCommand::List); // Checked before anything is written: a refused restart must leave the // previously active runtime in place, not switch the runtime and then // decline the half of the job the user actually asked for. ensure_runtime_service_restart_approved(&command)?; match command { - RuntimesCommand::List { json } => { - cli_report::print_json_or_text(json, &runtimes_listing(&paths, &config)?)?; + RuntimesCommand::List => { + print!("{}", render_runtimes_text(&paths, &config)?); } RuntimesCommand::Activate { runtime, @@ -594,497 +588,146 @@ const ACTIVE_RUNTIME_MARKER: &str = "*"; /// [`ACTIVE_RUNTIME_MARKER`]. const ROLLBACK_RUNTIME_MARKER: &str = "-"; -/// What `rocm runtimes list` reports, computed once and printed either as text -/// or, with `--json`, as this struct serialized. -/// -/// Every per-runtime fact the text shows is a field here, so the text marker -/// and the JSON `active`/`rollback_target` flags come from the same -/// computation. The text adds only presentation: the marker legend, the -/// next-step hint for an empty registry, the build date it derives from -/// `version`, the `unusable (…)` wording around `unusable_reason`, and the word -/// `unrecorded` for a provenance fact the JSON writes as `null`. The JSON -/// form is additive-only: fields may be added, but none is renamed, removed or -/// given a new meaning (see `docs/json-output.md`). -#[derive(Debug, Serialize)] -pub(crate) struct RuntimesListing { - /// `default_runtime_id` from the config, as configured; `null` when unset. - /// Not necessarily the active runtime's `runtime_id`: an `active_runtime_key` - /// that names a runtime takes precedence, and the id may differ in letter - /// case or match nothing. The text form labels it `active_runtime_id:`, as - /// `rocm examine` does. - default_runtime_id: Option, - active_runtime_key: Option, - previous_runtime_key: Option, - /// Paths are written with `to_string_lossy`, so a path that is not valid - /// UTF-8 is listed with U+FFFD in place of its bad bytes rather than - /// failing the whole document. - #[serde(serialize_with = "serialize_path_lossy")] - registry: PathBuf, - #[serde(serialize_with = "serialize_path_lossy")] - marker: PathBuf, - /// What is wrong with the configured active runtime setting, or `null`. - /// See [`active_runtime_problem`] for when it is set beside an `active` - /// runtime. - active_problem: Option, - /// Newest install first, ties broken by `runtime_key`, as the registry - /// loader sorts them (`sort_manifests_newest_install_first`). - runtimes: Vec, -} - -/// What is wrong with the configured active runtime setting. The text form -/// prints it as the `active_status:` line. -#[derive(Debug, Serialize, PartialEq, Eq)] -#[serde(tag = "kind", rename_all = "snake_case")] -enum ActiveRuntimeProblem { - /// `active_runtime_key` is set but names no registered runtime, ASCII - /// letter case ignored. Reported even when `default_runtime_id` then - /// resolves a runtime, which the listing marks `active`. - MissingManifestForKey { runtime_key: String }, - /// No `active_runtime_key`; `default_runtime_id` matches no manifest's id, - /// ASCII letter case ignored. - MissingManifestForId { runtime_id: String }, - /// No `active_runtime_key`; `default_runtime_id` matches more than one - /// manifest's id (letter case ignored), so none is active until one key is - /// activated. - AmbiguousRuntimeId { - runtime_id: String, - runtime_keys: Vec, - }, -} - -/// One registered runtime in [`RuntimesListing`]. -#[derive(Debug, Serialize)] -struct RuntimeListingEntry { - runtime_key: String, - runtime_id: String, - /// The version the manifest records; the text form adds the build date. - version: String, - format: String, - family: String, - mode: RuntimeMode, - /// Serialized as the two JSON fields `status` and `unusable_reason`. - #[serde(flatten)] - usability: RuntimeUsability, - toolchain: RuntimeToolchain, - /// The runtime `current_runtime_manifest` resolves for this config: the - /// one `rocm examine`, `rocm runtimes activate` and `rollback` treat as - /// the active runtime. - active: bool, - /// The runtime `select_runtime_manifest` resolves `previous_runtime_key` - /// to, which is the runtime `rocm runtimes rollback` selects (and then - /// refuses if it is unusable). - rollback_target: bool, - #[serde(serialize_with = "serialize_path_lossy")] - install_root: PathBuf, - /// Where the runtime came from, as its manifest recorded it - /// (`InstalledRuntimeManifest::provenance`). The text form prints it as the - /// `provenance:` line under `install_root:`; the JSON form as an object - /// with the same names, `null` where the text prints `unrecorded`. - provenance: RuntimeListingProvenance, -} - -/// An owned copy of a runtime's [`RuntimeProvenance`], so the listing can -/// outlive the manifests it was computed from. It holds the recorded values -/// (trimmed, `None` when unrecorded). The text prints them through -/// [`RuntimeProvenance::fields`], the same as `rocm examine`, and the JSON -/// writes them through [`RuntimeProvenance::recorded_fields`], so the two forms -/// take their names and order from one list. -#[derive(Debug, Clone, PartialEq, Eq)] -struct RuntimeListingProvenance { - channel: Option, - source: Option, - source_layout_generation: Option, - device_target: Option, -} - -impl RuntimeListingProvenance { - fn recorded(provenance: &RuntimeProvenance<'_>) -> Self { - Self { - channel: provenance.channel.map(str::to_owned), - source: provenance.source.map(str::to_owned), - source_layout_generation: provenance.source_layout_generation.map(str::to_owned), - device_target: provenance.device_target.map(str::to_owned), - } +pub(crate) fn render_runtimes_text(paths: &AppPaths, config: &RocmCliConfig) -> Result { + recover_setup_runtime_registration(paths, config)?; + let manifests = therock::load_runtime_manifests(paths)?; + let mut output = String::new(); + let _ = writeln!(output, "registered ROCm runtimes"); + let _ = writeln!( + output, + " active_runtime_id: {}", + config.default_runtime_id.as_deref().unwrap_or("") + ); + let _ = writeln!( + output, + " active_runtime_key: {}", + config.active_runtime_key.as_deref().unwrap_or("") + ); + let _ = writeln!( + output, + " previous_runtime_key: {}", + config.previous_runtime_key.as_deref().unwrap_or("") + ); + let _ = writeln!( + output, + " registry: {}", + runtime_registry_dir(paths).display() + ); + let _ = writeln!( + output, + " marker: {}", + active_runtime_marker_path(paths).display() + ); + if let Some(active_runtime_key) = config.active_runtime_key.as_deref() + && !manifests + .iter() + .any(|manifest| manifest.runtime_key == active_runtime_key) + { + let _ = writeln!( + output, + " active_status: missing manifest for active_runtime_key={active_runtime_key}" + ); } - - fn as_provenance(&self) -> RuntimeProvenance<'_> { - RuntimeProvenance { - channel: self.channel.as_deref(), - source: self.source.as_deref(), - source_layout_generation: self.source_layout_generation.as_deref(), - device_target: self.device_target.as_deref(), + if config.active_runtime_key.is_none() + && let Some(default_runtime_id) = config.default_runtime_id.as_deref() + { + let matches = manifests + .iter() + .filter(|manifest| manifest.runtime_id == default_runtime_id) + .collect::>(); + if matches.is_empty() { + let _ = writeln!( + output, + " active_status: missing manifest for active_runtime_id={default_runtime_id}" + ); + } else if matches.len() > 1 { + let _ = writeln!( + output, + " active_status: ambiguous runtime_id={default_runtime_id}; activate one runtime_key: {}", + runtime_keys_text(&matches) + ); } } -} - -/// One JSON object holding each fact under the name the text prints it with, -/// as a string, or `null` when it was not recorded. Not the text's -/// `unrecorded` word: a script must not read that placeholder as a value. -impl Serialize for RuntimeListingProvenance { - fn serialize(&self, serializer: S) -> Result { - use serde::ser::SerializeMap as _; - let fields = self.as_provenance().recorded_fields(); - let mut object = serializer.serialize_map(Some(fields.len()))?; - for (name, value) in fields { - object.serialize_entry(name, &value)?; - } - object.end() + if manifests.is_empty() { + let _ = writeln!(output, " installed: none"); + let _ = writeln!( + output, + " next step: rocm install sdk --channel release --format wheel" + ); + return Ok(output); } -} - -/// A path as a JSON string, through `to_string_lossy`. serde's own `Path` -/// impl fails on a path that is not valid UTF-8, which would leave -/// `rocm runtimes list --json` printing nothing for a listing the text form -/// prints (with the same replacement, through `Path::display`). -fn serialize_path_lossy( - path: &std::path::Path, - serializer: S, -) -> Result { - serializer.serialize_str(&path.to_string_lossy()) -} - -/// Whether a runtime carries the compiler toolchain. The text and the JSON -/// print the same word, the one `toolchain_state_text` gives `rocm examine`. -#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)] -#[serde(rename_all = "lowercase")] -enum RuntimeToolchain { - Included, - Excluded, -} -impl RuntimeToolchain { - const fn from_includes_devel(includes_devel: bool) -> Self { - if includes_devel { - Self::Included + let default_runtime_matches = default_runtime_id_matches(config, &manifests); + let single_default_runtime_key = + if config.active_runtime_key.is_none() && default_runtime_matches.len() == 1 { + Some(default_runtime_matches[0].runtime_key.clone()) } else { - Self::Excluded - } - } - - const fn as_str(self) -> &'static str { - toolchain_state_text(matches!(self, Self::Included)) - } -} - -#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)] -#[serde(rename_all = "kebab-case")] -enum RuntimeMode { - /// ROCm CLI installed it and may remove its folder. - Managed, - /// Imported or adopted; ROCm CLI never changes its folder. - ReadOnly, -} - -impl RuntimeMode { - const fn as_str(self) -> &'static str { - match self { - Self::Managed => "managed", - Self::ReadOnly => "read-only", - } - } -} - -/// Whether a runtime passes the manifest check that `rocm runtimes activate` -/// applies (`validate_runtime_manifest_for_activation`). Passing it does not -/// promise the activation succeeds: that can still refuse on an ambiguous -/// selector, unreadable server records or a failed config or marker write. An -/// unusable runtime always carries the reason, so the listing cannot report one -/// without saying why. -#[derive(Debug)] -enum RuntimeUsability { - Ready, - /// The human-readable message the manifest check failed with (not a - /// stable code). - Unusable { - reason: String, - }, -} - -impl RuntimeUsability { - /// The JSON `status` value. - const fn status(&self) -> &'static str { - match self { - Self::Ready => "ready", - Self::Unusable { .. } => "unusable", - } - } - - /// The JSON `unusable_reason` value: `None` exactly when ready. - fn unusable_reason(&self) -> Option<&str> { - match self { - Self::Ready => None, - Self::Unusable { reason } => Some(reason), - } - } -} - -/// Two fields, `status` (`ready` or `unusable`) and `unusable_reason` (`null` -/// when ready), flattened into each runtime's JSON object. -impl Serialize for RuntimeUsability { - fn serialize(&self, serializer: S) -> Result { - use serde::ser::SerializeStruct as _; - let mut fields = serializer.serialize_struct("RuntimeUsability", 2)?; - fields.serialize_field("status", self.status())?; - fields.serialize_field("unusable_reason", &self.unusable_reason())?; - fields.end() - } -} - -/// Recover the runtime `rocm setup` created, load the registry, and compute -/// everything `rocm runtimes list` reports, in either form. -pub(crate) fn runtimes_listing( - paths: &AppPaths, - config: &RocmCliConfig, -) -> Result { - recover_setup_runtime_registration(paths, config)?; - let manifests = therock::load_runtime_manifests(paths)?; - Ok(listing_from_manifests( - config, - manifests, - runtime_registry_dir(paths), - active_runtime_marker_path(paths), - )) -} - -/// The listing of `manifests`, in the order given, for `config`. Split from -/// the registry read so every configuration can be tested in memory, including -/// keys that differ only in letter case, which one registry folder cannot hold -/// on a case-insensitive filesystem. -/// -/// `active` and `rollback_target` are not decided by rules of the listing's -/// own: they are the runtimes the commands themselves resolve, by the same -/// functions, so the listing marks what those commands act on. -fn listing_from_manifests( - config: &RocmCliConfig, - manifests: Vec, - registry: PathBuf, - marker: PathBuf, -) -> RuntimesListing { - // Compared by position, not by key: keys can differ only in letter case, - // and the resolver's choice between such twins is part of what is listed. - let position = |resolved: &therock::InstalledRuntimeManifest| { - manifests - .iter() - .position(|manifest| std::ptr::eq(manifest, resolved)) - }; - let active_index = current_runtime_manifest(config, &manifests).and_then(position); - // `rocm runtimes rollback` selects `previous_runtime_key` this way; a value - // it refuses (no match, or ambiguous) names no rollback target. - let rollback_index = config - .previous_runtime_key - .as_deref() - .and_then(|selector| select_runtime_manifest(&manifests, selector).ok()) - .and_then(position); - let active_problem = active_runtime_problem(config, &manifests); + None + }; + drop(default_runtime_matches); - let runtimes = manifests - .into_iter() - .enumerate() - .map(|(index, manifest)| { - // The manifest check `rocm runtimes activate` applies, so "ready" - // here means the runtime passes that check, not that an activation - // is sure to succeed (see `RuntimeUsability`). - let usability = match validate_runtime_manifest_for_activation(&manifest) { - Ok(()) => RuntimeUsability::Ready, - Err(error) => RuntimeUsability::Unusable { - reason: error.to_string(), - }, - }; - let mode = if manifest.read_only { - RuntimeMode::ReadOnly - } else { - RuntimeMode::Managed - }; - // The compiler is opt-in and `rocm update` reinstalls whatever this - // says, so an install missing it should not be silent about that. - // `rocm examine` reports the same thing for the active runtime. - let toolchain = RuntimeToolchain::from_includes_devel(manifest.includes_devel()); - let provenance = RuntimeListingProvenance::recorded(&manifest.provenance()); - RuntimeListingEntry { - runtime_key: manifest.runtime_key, - runtime_id: manifest.runtime_id, - version: manifest.version, - format: manifest.format, - family: manifest.family, + let _ = writeln!(output, " installed:"); + let _ = writeln!( + output, + " legend: {ACTIVE_RUNTIME_MARKER} = active, {ROLLBACK_RUNTIME_MARKER} = rollback target" + ); + let _ = writeln!(output); + for manifest in manifests { + let active = config + .active_runtime_key + .as_deref() + .is_some_and(|runtime_key| runtime_key == manifest.runtime_key) + || single_default_runtime_key.as_deref() == Some(manifest.runtime_key.as_str()); + let rollback = config + .previous_runtime_key + .as_deref() + .is_some_and(|runtime_key| runtime_key == manifest.runtime_key); + let marker = if active { + Some(ACTIVE_RUNTIME_MARKER) + } else if rollback { + Some(ROLLBACK_RUNTIME_MARKER) + } else { + None + }; + let status = runtime_usability_status(&manifest); + let mode = if manifest.read_only { + "read-only" + } else { + "managed" + }; + // The compiler is opt-in and `rocm update` reinstalls whatever this + // says, so an install missing it should not be silent about that. + // `rocm examine` reports the same thing for the active runtime. + let toolchain = toolchain_state_text(manifest.includes_devel()); + cli_report::write_marked_row( + &mut output, + " ", + marker, + format_args!( + "{} runtime_id={} version={} format={} family={} mode={} status={} toolchain={}", + manifest.runtime_key, + manifest.runtime_id, + therock::runtime_version_display(&manifest.version), + manifest.format, + manifest.family, mode, - usability, - toolchain, - active: active_index == Some(index), - rollback_target: rollback_index == Some(index), - install_root: manifest.install_root, - provenance, - } - }) - .collect(); - - RuntimesListing { - default_runtime_id: config.default_runtime_id.clone(), - active_runtime_key: config.active_runtime_key.clone(), - previous_runtime_key: config.previous_runtime_key.clone(), - registry, - marker, - active_problem, - runtimes, - } -} - -/// What is wrong with the configured active runtime setting, by the matching -/// `current_runtime_manifest` applies. -/// -/// It reports the configuration, so it can disagree with `active` in exactly -/// one case: an `active_runtime_key` that names no runtime is reported as -/// `MissingManifestForKey` even when the resolver then falls back to -/// `default_runtime_id` and finds one, which is marked active. The commands act -/// on that runtime, so the listing marks it; the key is still dead, so the -/// listing says so. With no `active_runtime_key`, the problem comes from the -/// same `default_runtime_id_matches` the resolver falls back to, so it is set -/// exactly when nothing is active. -fn active_runtime_problem( - config: &RocmCliConfig, - manifests: &[therock::InstalledRuntimeManifest], -) -> Option { - if let Some(runtime_key) = config.active_runtime_key.as_deref() { - // The resolver's key step on its own: the same call with the default - // id it would fall back to taken away. - let mut key_only = config.clone(); - key_only.default_runtime_id = None; - return current_runtime_manifest(&key_only, manifests) - .is_none() - .then(|| ActiveRuntimeProblem::MissingManifestForKey { - runtime_key: runtime_key.to_owned(), - }); - } - let runtime_id = config.default_runtime_id.as_deref()?; - match default_runtime_id_matches(config, manifests).as_slice() { - [] => Some(ActiveRuntimeProblem::MissingManifestForId { - runtime_id: runtime_id.to_owned(), - }), - [_] => None, - matches => Some(ActiveRuntimeProblem::AmbiguousRuntimeId { - runtime_id: runtime_id.to_owned(), - runtime_keys: matches - .iter() - .map(|manifest| manifest.runtime_key.clone()) - .collect(), - }), - } -} - -impl cli_report::JsonOrText for RuntimesListing { - fn render_text(&self) -> String { - let mut output = String::new(); - let unset = |value: &Option| value.clone().unwrap_or_else(|| "".to_owned()); - let _ = writeln!(output, "registered ROCm runtimes"); - let _ = writeln!( - output, - " active_runtime_id: {}", - unset(&self.default_runtime_id) + status, + toolchain + ), ); let _ = writeln!( output, - " active_runtime_key: {}", - unset(&self.active_runtime_key) + " install_root: {}", + manifest.install_root.display() ); let _ = writeln!( output, - " previous_runtime_key: {}", - unset(&self.previous_runtime_key) - ); - let _ = writeln!(output, " registry: {}", self.registry.display()); - let _ = writeln!(output, " marker: {}", self.marker.display()); - match &self.active_problem { - None => {} - Some(ActiveRuntimeProblem::MissingManifestForKey { runtime_key }) => { - let _ = writeln!( - output, - " active_status: missing manifest for active_runtime_key={runtime_key}" - ); - } - Some(ActiveRuntimeProblem::MissingManifestForId { runtime_id }) => { - let _ = writeln!( - output, - " active_status: missing manifest for active_runtime_id={runtime_id}" - ); - } - Some(ActiveRuntimeProblem::AmbiguousRuntimeId { - runtime_id, - runtime_keys, - }) => { - let _ = writeln!( - output, - " active_status: ambiguous runtime_id={runtime_id}; activate one runtime_key: {}", - runtime_keys.join(", ") - ); - } - } - if self.runtimes.is_empty() { - let _ = writeln!(output, " installed: none"); - let _ = writeln!( - output, - " next step: rocm install sdk --channel release --format wheel" - ); - return output; - } - - let _ = writeln!(output, " installed:"); - let _ = writeln!( - output, - " legend: {ACTIVE_RUNTIME_MARKER} = active, {ROLLBACK_RUNTIME_MARKER} = rollback target" - ); - let _ = writeln!(output); - for runtime in &self.runtimes { - // Active wins when a runtime is both. `rocm runtimes activate` and - // `rollback` never record a runtime as its own rollback target, so - // only a change made outside the CLI reaches this: a hand-edited - // config, or the active runtime's registry entry deleted while the - // default id falls back to the rollback target. - let marker = if runtime.active { - Some(ACTIVE_RUNTIME_MARKER) - } else if runtime.rollback_target { - Some(ROLLBACK_RUNTIME_MARKER) - } else { - None - }; - let status = match &runtime.usability { - RuntimeUsability::Ready => runtime.usability.status().to_owned(), - RuntimeUsability::Unusable { reason } => unusable_status_text(reason), - }; - cli_report::write_marked_row( - &mut output, - " ", - marker, - format_args!( - "{} runtime_id={} version={} format={} family={} mode={} status={} toolchain={}", - runtime.runtime_key, - runtime.runtime_id, - therock::runtime_version_display(&runtime.version), - runtime.format, - runtime.family, - runtime.mode.as_str(), - status, - runtime.toolchain.as_str() - ), - ); - let _ = writeln!( - output, - " install_root: {}", - runtime.install_root.display() - ); - let _ = writeln!( - output, - " provenance: {}", - provenance_text(&runtime.provenance.as_provenance()) - ); - } - output + " provenance: {}", + provenance_text(&manifest.provenance()) + ); } -} -/// The text form of `rocm runtimes list`, for callers that want the string -/// (the chat assistant's read-only tool) rather than printing it. -pub(crate) fn render_runtimes_text(paths: &AppPaths, config: &RocmCliConfig) -> Result { - use cli_report::JsonOrText as _; - Ok(runtimes_listing(paths, config)?.render_text()) + Ok(output) } pub(crate) fn activate_runtime( @@ -2014,1381 +1657,6 @@ pub(crate) mod tests { Ok(()) } - /// What `rocm runtimes list --json` prints for `config`, as the JSON value a - /// script reads. - fn runtimes_list_json(paths: &AppPaths, config: &RocmCliConfig) -> Result { - Ok(serde_json::to_value(runtimes_listing(paths, config)?)?) - } - - /// The `runtime_key`s whose `flag` is true, in listing order. - fn runtime_keys_flagged(listing: &serde_json::Value, flag: &str) -> Vec { - listing["runtimes"] - .as_array() - .expect("runtimes is an array") - .iter() - .filter(|runtime| { - // Every runtime must carry `flag` as a boolean: read as - // `runtime[flag] == true`, a missing or renamed field would - // count as false and "nothing is flagged" would still pass. - runtime - .get(flag) - .and_then(serde_json::Value::as_bool) - .unwrap_or_else(|| panic!("a runtime has no boolean `{flag}`:\n{listing:#}")) - }) - .map(|runtime| { - runtime["runtime_key"] - .as_str() - .unwrap_or_default() - .to_owned() - }) - .collect() - } - - fn listed_runtime<'a>( - listing: &'a serde_json::Value, - runtime_key: &str, - ) -> &'a serde_json::Value { - listing["runtimes"] - .as_array() - .expect("runtimes is an array") - .iter() - .find(|runtime| runtime["runtime_key"] == runtime_key) - .unwrap_or_else(|| panic!("{runtime_key} is listed:\n{listing:#}")) - } - - #[test] - fn runtimes_list_json_with_nothing_registered_lists_nothing_and_no_active_runtime() -> Result<()> - { - let (root, paths) = test_paths("runtime-list-json-empty"); - let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; - let _ = fs::remove_dir_all(root); - - assert_eq!(listing["runtimes"], serde_json::json!([])); - for unset in [ - "default_runtime_id", - "active_runtime_key", - "previous_runtime_key", - "active_problem", - ] { - assert_null_field(&listing, unset); - } - for path in ["registry", "marker"] { - assert!( - listing.get(path).is_some_and(serde_json::Value::is_string), - "`{path}` is always a path:\n{listing:#}" - ); - } - assert!( - listing.get("next_step").is_none(), - "the next-step hint is text-only:\n{listing:#}" - ); - Ok(()) - } - - #[test] - fn runtimes_list_json_flags_the_active_runtime_and_the_rollback_target() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-active-rollback"); - for (key, version, build) in [ - ("rt-first", "7.12.0", 10), - ("rt-second", "7.13.0", 20), - ("rt-idle", "7.11.0", 5), - ] { - write_test_pip_runtime(&paths, key, "therock-release:gfx120X-all", version, build)?; - } - let config = RocmCliConfig { - active_runtime_key: Some("rt-second".to_owned()), - previous_runtime_key: Some("rt-first".to_owned()), - ..RocmCliConfig::default() - }; - let listing = runtimes_list_json(&paths, &config)?; - let _ = fs::remove_dir_all(root); - - assert_eq!(runtime_keys_flagged(&listing, "active"), ["rt-second"]); - assert_eq!( - runtime_keys_flagged(&listing, "rollback_target"), - ["rt-first"] - ); - assert_eq!(listing["active_runtime_key"], "rt-second"); - assert_eq!(listing["previous_runtime_key"], "rt-first"); - assert_null_field(&listing, "active_problem"); - let second = listed_runtime(&listing, "rt-second"); - assert_eq!(second["runtime_id"], "therock-release:gfx120X-all"); - assert_eq!(second["version"], "7.13.0"); - assert_eq!(second["format"], "wheel"); - assert_eq!(second["family"], "gfx120X-all"); - assert_eq!(second["mode"], "managed"); - assert_eq!(second["status"], "ready"); - assert_null_field(second, "unusable_reason"); - assert_eq!(second["toolchain"], "included"); - Ok(()) - } - - #[test] - fn runtimes_list_json_marks_the_one_runtime_matching_the_default_id_active() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-default-id"); - write_test_pip_runtime( - &paths, - "rt-gfx120x", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - write_test_pip_runtime( - &paths, - "rt-gfx110x", - "therock-release:gfx110X-all", - "7.13.0", - 10, - )?; - let config = RocmCliConfig { - default_runtime_id: Some("therock-release:gfx120X-all".to_owned()), - ..RocmCliConfig::default() - }; - let listing = runtimes_list_json(&paths, &config)?; - let _ = fs::remove_dir_all(root); - - assert_eq!(runtime_keys_flagged(&listing, "active"), ["rt-gfx120x"]); - assert_eq!(listing["default_runtime_id"], "therock-release:gfx120X-all"); - assert_null_field(&listing, "active_runtime_key"); - assert_null_field(&listing, "active_problem"); - Ok(()) - } - - #[test] - fn runtimes_list_json_reports_an_active_key_with_no_manifest() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-missing-key"); - write_test_pip_runtime( - &paths, - "rt-present", - "therock-release:gfx120X-all", - "7.13.0", - 10, - )?; - let config = RocmCliConfig { - active_runtime_key: Some("rt-gone".to_owned()), - ..RocmCliConfig::default() - }; - let listing = runtimes_list_json(&paths, &config)?; - let _ = fs::remove_dir_all(root); - - assert_eq!( - listing["active_problem"], - serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}) - ); - assert!(runtime_keys_flagged(&listing, "active").is_empty()); - Ok(()) - } - - #[test] - fn runtimes_list_json_reports_a_default_id_with_no_manifest() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-missing-id"); - write_test_pip_runtime( - &paths, - "rt-present", - "therock-release:gfx120X-all", - "7.13.0", - 10, - )?; - let config = RocmCliConfig { - default_runtime_id: Some("therock-release:gfx110X-all".to_owned()), - ..RocmCliConfig::default() - }; - let listing = runtimes_list_json(&paths, &config)?; - let _ = fs::remove_dir_all(root); - - assert_eq!( - listing["active_problem"], - serde_json::json!({ - "kind": "missing_manifest_for_id", - "runtime_id": "therock-release:gfx110X-all" - }) - ); - assert!(runtime_keys_flagged(&listing, "active").is_empty()); - Ok(()) - } - - #[test] - fn runtimes_list_json_reports_a_default_id_matching_two_runtimes_as_ambiguous() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-ambiguous-id"); - write_test_pip_runtime( - &paths, - "rt-newer", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - write_test_pip_runtime( - &paths, - "rt-older", - "therock-release:gfx120X-all", - "7.12.0", - 10, - )?; - let config = RocmCliConfig { - default_runtime_id: Some("therock-release:gfx120X-all".to_owned()), - ..RocmCliConfig::default() - }; - let listing = runtimes_list_json(&paths, &config)?; - let text = render_runtimes_text(&paths, &config)?; - let _ = fs::remove_dir_all(root); - - assert_eq!( - listing["active_problem"], - serde_json::json!({ - "kind": "ambiguous_runtime_id", - "runtime_id": "therock-release:gfx120X-all", - "runtime_keys": ["rt-newer", "rt-older"] - }) - ); - assert!(runtime_keys_flagged(&listing, "active").is_empty()); - // The text form prints the same problem from the same value. - assert!( - text.contains( - " active_status: ambiguous runtime_id=therock-release:gfx120X-all; \ - activate one runtime_key: rt-newer, rt-older\n" - ), - "{text}" - ); - Ok(()) - } - - /// `key` is present in `value` and `null`. Indexing a `serde_json::Value` - /// returns `null` for a missing key too, so `value[key] == Value::Null` - /// would stay green if the key were dropped from the document. - fn assert_null_field(value: &serde_json::Value, key: &str) { - assert_eq!( - value.as_object().and_then(|object| object.get(key)), - Some(&serde_json::Value::Null), - "`{key}` must be present and null:\n{value:#}" - ); - } - - /// The `runtime_key`s the text form marks with `glyph`, in listing order. - fn runtime_keys_marked(text: &str, glyph: &str) -> Vec { - text.lines() - .filter_map(|line| line.strip_prefix(&format!(" {glyph} "))) - .filter_map(|row| row.split_whitespace().next()) - .map(str::to_owned) - .collect() - } - - /// With no `active_runtime_key`, the listing matches `default_runtime_id` - /// ignoring ASCII letter case, and `active` and `active_problem` use that - /// one rule (`default_runtime_id_matches`). A default id that differs from - /// its one runtime's id only in case marks that runtime active and reports - /// no problem; `rocm config set-default-runtime` stores the id as typed, - /// so this state is one command away. Because both fields use the same - /// rule, `active_problem` never reports as missing a runtime that `active` - /// marks. - #[test] - fn runtimes_list_matches_a_default_id_differing_only_in_case_with_one_rule() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-default-id-case"); - write_test_pip_runtime( - &paths, - "rt-gfx120x", - "therock-release:gfx120X-all", - "7.13.0", - 10, - )?; - let config = RocmCliConfig { - default_runtime_id: Some("THEROCK-RELEASE:GFX120X-ALL".to_owned()), - ..RocmCliConfig::default() - }; - let listing = runtimes_list_json(&paths, &config)?; - let text = render_runtimes_text(&paths, &config)?; - let _ = fs::remove_dir_all(root); - - assert_eq!(runtime_keys_flagged(&listing, "active"), ["rt-gfx120x"]); - assert_null_field(&listing, "active_problem"); - assert_eq!( - runtime_keys_marked(&text, ACTIVE_RUNTIME_MARKER), - ["rt-gfx120x"] - ); - assert!(!text.contains("active_status:"), "{text}"); - Ok(()) - } - - /// Under the same rule, a default id matching two runtime ids that differ - /// only in letter case matches both: neither is active, and the listing - /// reports the id as ambiguous, naming both keys in listing order. The - /// runtime whose id equals the default exactly counts as one match among - /// the two, not as the winner. - #[test] - fn runtimes_list_reports_a_default_id_matching_ids_differing_only_in_case_as_ambiguous() - -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-ambiguous-id-case"); - write_test_pip_runtime( - &paths, - "rt-upper", - "therock-release:gfx120X-all", - "7.13.0", - 20, - )?; - write_test_pip_runtime( - &paths, - "rt-lower", - "therock-release:gfx120x-all", - "7.13.0", - 10, - )?; - let config = RocmCliConfig { - default_runtime_id: Some("therock-release:gfx120X-all".to_owned()), - ..RocmCliConfig::default() - }; - let listing = runtimes_list_json(&paths, &config)?; - let text = render_runtimes_text(&paths, &config)?; - let _ = fs::remove_dir_all(root); - - assert_eq!( - listing["active_problem"], - serde_json::json!({ - "kind": "ambiguous_runtime_id", - "runtime_id": "therock-release:gfx120X-all", - "runtime_keys": ["rt-upper", "rt-lower"] - }) - ); - assert!(runtime_keys_flagged(&listing, "active").is_empty()); - assert!( - text.contains( - " active_status: ambiguous runtime_id=therock-release:gfx120X-all; \ - activate one runtime_key: rt-upper, rt-lower\n" - ), - "{text}" - ); - Ok(()) - } - - // ── State matrix: what the listing marks, for every configuration ── - // - // Built in memory through `listing_from_manifests`, so keys that differ - // only in letter case are listed as they would be on a case-sensitive - // filesystem without writing them to one: on a case-insensitive one the - // second `.json` would overwrite the first. - - /// A registered runtime with just the fields the listing reads. Its - /// install root does not exist, so it is listed `unusable`, which no row - /// below depends on. - fn listed_runtime_manifest( - runtime_key: &str, - runtime_id: &str, - ) -> therock::InstalledRuntimeManifest { - serde_json::from_value(serde_json::json!({ - "runtime_key": runtime_key, - "runtime_id": runtime_id, - "channel": "release", - "format": "wheel", - "family": "gfx120X-all", - "family_source": "test", - "version": "7.13.0", - "install_root": format!("/nonexistent/rocm-list-state/{runtime_key}"), - "selected_artifact_url": "https://example.invalid/therock", - "installed_at_unix_ms": 10, - })) - .expect("a minimal runtime manifest deserializes") - } - - const ID_A: &str = "therock-release:gfx120X-all"; - const ID_B: &str = "therock-release:gfx110X-all"; - - /// Runtimes `rt-a` (id `ID_A`) and `rt-b` (id `ID_B`), in that order. - fn two_distinct_runtimes() -> Vec { - vec![ - listed_runtime_manifest("rt-a", ID_A), - listed_runtime_manifest("rt-b", ID_B), - ] - } - - /// Keys `rt-twin` and `RT-TWIN`, in that order, with distinct ids. - fn case_twin_runtimes() -> Vec { - vec![ - listed_runtime_manifest("rt-twin", ID_A), - listed_runtime_manifest("RT-TWIN", ID_B), - ] - } - - /// One row of the state matrix: a configuration, the runtimes, and what - /// the listing must say about them in both forms. - struct ListingState { - config: RocmCliConfig, - manifests: Vec, - /// The key marked `active` (JSON) and `*` (text). - active: Option<&'static str>, - /// The key flagged `rollback_target` (JSON); marked `-` in the text - /// unless it is also active. - rollback: Option<&'static str>, - /// The JSON `active_problem`. - problem: serde_json::Value, - /// The text's `active_status:` line, without its indentation. - status_line: Option<&'static str>, - } - - fn config_with( - default_runtime_id: Option<&str>, - active_runtime_key: Option<&str>, - previous_runtime_key: Option<&str>, - ) -> RocmCliConfig { - RocmCliConfig { - default_runtime_id: default_runtime_id.map(str::to_owned), - active_runtime_key: active_runtime_key.map(str::to_owned), - previous_runtime_key: previous_runtime_key.map(str::to_owned), - ..RocmCliConfig::default() - } - } - - fn assert_listing_state(state: &ListingState) -> Result<()> { - use cli_report::JsonOrText as _; - let listing = listing_from_manifests( - &state.config, - state.manifests.clone(), - PathBuf::from("registry"), - PathBuf::from("active.json"), - ); - let json = serde_json::to_value(&listing)?; - let text = listing.render_text(); - let context = format!("{json:#}\n{text}"); - - // The listing marks what the commands resolve: `current_runtime_manifest` - // for the active runtime, `select_runtime_manifest` for rollback. - let resolved_active = current_runtime_manifest(&state.config, &state.manifests) - .map(|manifest| manifest.runtime_key.as_str()); - assert_eq!(resolved_active, state.active, "resolver vs row:\n{context}"); - let resolved_rollback = state - .config - .previous_runtime_key - .as_deref() - .and_then(|selector| select_runtime_manifest(&state.manifests, selector).ok()) - .map(|manifest| manifest.runtime_key.as_str()); - assert_eq!( - resolved_rollback, state.rollback, - "resolver vs row:\n{context}" - ); - - let expected_active: Vec = state.active.iter().map(|k| (*k).to_owned()).collect(); - let expected_rollback: Vec = - state.rollback.iter().map(|k| (*k).to_owned()).collect(); - assert_eq!( - runtime_keys_flagged(&json, "active"), - expected_active, - "{context}" - ); - assert_eq!( - runtime_keys_flagged(&json, "rollback_target"), - expected_rollback, - "{context}" - ); - assert_eq!(json["active_problem"], state.problem, "{context}"); - assert_eq!( - runtime_keys_marked(&text, ACTIVE_RUNTIME_MARKER), - expected_active, - "{context}" - ); - let rollback_only: Vec = expected_rollback - .into_iter() - .filter(|key| Some(key.as_str()) != state.active) - .collect(); - assert_eq!( - runtime_keys_marked(&text, ROLLBACK_RUNTIME_MARKER), - rollback_only, - "{context}" - ); - let status_lines: Vec<&str> = text - .lines() - .map(str::trim_start) - .filter(|line| line.starts_with("active_status:")) - .collect(); - assert_eq!( - status_lines, - state.status_line.into_iter().collect::>(), - "{context}" - ); - Ok(()) - } - - fn state_no_config() -> ListingState { - ListingState { - config: RocmCliConfig::default(), - manifests: two_distinct_runtimes(), - active: None, - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - fn state_key_exact() -> ListingState { - ListingState { - config: config_with(Some(ID_B), Some("rt-b"), None), - manifests: two_distinct_runtimes(), - active: Some("rt-b"), - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - /// The default id names the other runtime, so the key alone decides. - fn state_key_in_other_case() -> ListingState { - ListingState { - config: config_with(Some(ID_B), Some("RT-A"), None), - manifests: two_distinct_runtimes(), - active: Some("rt-a"), - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - /// The one documented case where `active_problem` is set beside an - /// `active` runtime: the key is dead, the default id still resolves. - fn state_stale_key_default_resolves() -> ListingState { - ListingState { - config: config_with(Some(ID_B), Some("rt-gone"), None), - manifests: two_distinct_runtimes(), - active: Some("rt-b"), - rollback: None, - problem: serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}), - status_line: Some("active_status: missing manifest for active_runtime_key=rt-gone"), - } - } - - fn state_stale_key_default_missing() -> ListingState { - ListingState { - config: config_with(Some("therock-release:gfx90a"), Some("rt-gone"), None), - manifests: two_distinct_runtimes(), - active: None, - rollback: None, - problem: serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}), - status_line: Some("active_status: missing manifest for active_runtime_key=rt-gone"), - } - } - - fn state_stale_key_default_ambiguous() -> ListingState { - ListingState { - config: config_with(Some(ID_A), Some("rt-gone"), None), - manifests: vec![ - listed_runtime_manifest("rt-a", ID_A), - listed_runtime_manifest("rt-a2", ID_A), - ], - active: None, - rollback: None, - problem: serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}), - status_line: Some("active_status: missing manifest for active_runtime_key=rt-gone"), - } - } - - fn state_default_matches_none() -> ListingState { - ListingState { - config: config_with(Some("therock-release:gfx90a"), None, None), - manifests: two_distinct_runtimes(), - active: None, - rollback: None, - problem: serde_json::json!({ - "kind": "missing_manifest_for_id", - "runtime_id": "therock-release:gfx90a" - }), - status_line: Some( - "active_status: missing manifest for active_runtime_id=therock-release:gfx90a", - ), - } - } - - fn state_default_matches_one() -> ListingState { - ListingState { - config: config_with(Some(ID_B), None, None), - manifests: two_distinct_runtimes(), - active: Some("rt-b"), - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - fn state_default_matches_one_in_other_case() -> ListingState { - ListingState { - config: config_with(Some("THEROCK-RELEASE:GFX110X-ALL"), None, None), - manifests: two_distinct_runtimes(), - active: Some("rt-b"), - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - fn state_default_matches_two() -> ListingState { - ListingState { - config: config_with(Some(ID_A), None, None), - manifests: vec![ - listed_runtime_manifest("rt-a", ID_A), - listed_runtime_manifest("rt-a2", ID_A), - ], - active: None, - rollback: None, - problem: serde_json::json!({ - "kind": "ambiguous_runtime_id", - "runtime_id": ID_A, - "runtime_keys": ["rt-a", "rt-a2"] - }), - status_line: Some( - "active_status: ambiguous runtime_id=therock-release:gfx120X-all; \ - activate one runtime_key: rt-a, rt-a2", - ), - } - } - - /// Ids differing only in case are two matches, even though one equals the - /// default exactly. - fn state_default_matches_two_differing_in_case() -> ListingState { - ListingState { - config: config_with(Some(ID_A), None, None), - manifests: vec![ - listed_runtime_manifest("rt-a", ID_A), - listed_runtime_manifest("rt-a-lower", "therock-release:gfx120x-all"), - ], - active: None, - rollback: None, - problem: serde_json::json!({ - "kind": "ambiguous_runtime_id", - "runtime_id": ID_A, - "runtime_keys": ["rt-a", "rt-a-lower"] - }), - status_line: Some( - "active_status: ambiguous runtime_id=therock-release:gfx120X-all; \ - activate one runtime_key: rt-a, rt-a-lower", - ), - } - } - - /// Case twins: the resolver takes the first key matching in list order, - /// even when a later one equals the active key exactly, and the listing - /// marks that first one, because that is what the commands act on. - fn state_case_twins_key_names_the_second() -> ListingState { - ListingState { - config: config_with(Some(ID_B), Some("RT-TWIN"), None), - manifests: case_twin_runtimes(), - active: Some("rt-twin"), - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - fn state_case_twins_key_names_the_first() -> ListingState { - ListingState { - config: config_with(Some(ID_A), Some("rt-twin"), None), - manifests: case_twin_runtimes(), - active: Some("rt-twin"), - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - fn state_previous_key_exact() -> ListingState { - ListingState { - config: config_with(Some(ID_B), Some("rt-b"), Some("rt-a")), - manifests: two_distinct_runtimes(), - active: Some("rt-b"), - rollback: Some("rt-a"), - problem: serde_json::Value::Null, - status_line: None, - } - } - - fn state_previous_key_in_other_case() -> ListingState { - ListingState { - config: config_with(Some(ID_B), Some("rt-b"), Some("RT-A")), - manifests: two_distinct_runtimes(), - active: Some("rt-b"), - rollback: Some("rt-a"), - problem: serde_json::Value::Null, - status_line: None, - } - } - - fn state_previous_key_is_a_runtime_id() -> ListingState { - ListingState { - config: config_with(Some(ID_B), Some("rt-b"), Some(ID_A)), - manifests: two_distinct_runtimes(), - active: Some("rt-b"), - rollback: Some("rt-a"), - problem: serde_json::Value::Null, - status_line: None, - } - } - - fn state_previous_key_with_whitespace() -> ListingState { - ListingState { - config: config_with(Some(ID_B), Some("rt-b"), Some(" rt-a\n")), - manifests: two_distinct_runtimes(), - active: Some("rt-b"), - rollback: Some("rt-a"), - problem: serde_json::Value::Null, - status_line: None, - } - } - - fn state_previous_key_missing() -> ListingState { - ListingState { - config: config_with(Some(ID_B), Some("rt-b"), Some("rt-gone")), - manifests: two_distinct_runtimes(), - active: Some("rt-b"), - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - /// Matches both twins only by letter case: rollback refuses it as - /// ambiguous, so nothing is the rollback target. - fn state_previous_key_ambiguous_case_twins() -> ListingState { - ListingState { - config: config_with(None, None, Some("Rt-Twin")), - manifests: case_twin_runtimes(), - active: None, - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - /// A runtime id two runtimes share: rollback refuses it as ambiguous. - fn state_previous_key_ambiguous_runtime_id() -> ListingState { - ListingState { - config: config_with(None, None, Some(ID_A)), - manifests: vec![ - listed_runtime_manifest("rt-a", ID_A), - listed_runtime_manifest("rt-a2", ID_A), - ], - active: None, - rollback: None, - problem: serde_json::Value::Null, - status_line: None, - } - } - - /// Rollback takes an exact key over its case twin. - fn state_previous_key_names_one_case_twin_exactly() -> ListingState { - ListingState { - config: config_with(None, None, Some("RT-TWIN")), - manifests: case_twin_runtimes(), - active: None, - rollback: Some("RT-TWIN"), - problem: serde_json::Value::Null, - status_line: None, - } - } - - /// The active runtime's registry entry was deleted and the default id it - /// shared with the rollback target now resolves that one: it is both, and - /// the text marks it `*`. - fn state_stale_key_falls_back_to_the_rollback_target() -> ListingState { - ListingState { - config: config_with(Some(ID_A), Some("rt-gone"), Some("rt-a")), - manifests: two_distinct_runtimes(), - active: Some("rt-a"), - rollback: Some("rt-a"), - problem: serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}), - status_line: Some("active_status: missing manifest for active_runtime_key=rt-gone"), - } - } - - #[test] - fn listing_state_no_config() -> Result<()> { - assert_listing_state(&state_no_config()) - } - - #[test] - fn listing_state_key_exact() -> Result<()> { - assert_listing_state(&state_key_exact()) - } - - #[test] - fn listing_state_key_in_other_case() -> Result<()> { - assert_listing_state(&state_key_in_other_case()) - } - - #[test] - fn listing_state_stale_key_default_resolves() -> Result<()> { - assert_listing_state(&state_stale_key_default_resolves()) - } - - #[test] - fn listing_state_stale_key_default_missing() -> Result<()> { - assert_listing_state(&state_stale_key_default_missing()) - } - - #[test] - fn listing_state_stale_key_default_ambiguous() -> Result<()> { - assert_listing_state(&state_stale_key_default_ambiguous()) - } - - #[test] - fn listing_state_default_matches_none() -> Result<()> { - assert_listing_state(&state_default_matches_none()) - } - - #[test] - fn listing_state_default_matches_one() -> Result<()> { - assert_listing_state(&state_default_matches_one()) - } - - #[test] - fn listing_state_default_matches_one_in_other_case() -> Result<()> { - assert_listing_state(&state_default_matches_one_in_other_case()) - } - - #[test] - fn listing_state_default_matches_two() -> Result<()> { - assert_listing_state(&state_default_matches_two()) - } - - #[test] - fn listing_state_default_matches_two_differing_in_case() -> Result<()> { - assert_listing_state(&state_default_matches_two_differing_in_case()) - } - - #[test] - fn listing_state_case_twins_key_names_the_second() -> Result<()> { - assert_listing_state(&state_case_twins_key_names_the_second()) - } - - #[test] - fn listing_state_case_twins_key_names_the_first() -> Result<()> { - assert_listing_state(&state_case_twins_key_names_the_first()) - } - - #[test] - fn listing_state_previous_key_exact() -> Result<()> { - assert_listing_state(&state_previous_key_exact()) - } - - #[test] - fn listing_state_previous_key_in_other_case() -> Result<()> { - assert_listing_state(&state_previous_key_in_other_case()) - } - - #[test] - fn listing_state_previous_key_is_a_runtime_id() -> Result<()> { - assert_listing_state(&state_previous_key_is_a_runtime_id()) - } - - #[test] - fn listing_state_previous_key_with_whitespace() -> Result<()> { - assert_listing_state(&state_previous_key_with_whitespace()) - } - - #[test] - fn listing_state_previous_key_missing() -> Result<()> { - assert_listing_state(&state_previous_key_missing()) - } - - #[test] - fn listing_state_previous_key_ambiguous_case_twins() -> Result<()> { - assert_listing_state(&state_previous_key_ambiguous_case_twins()) - } - - #[test] - fn listing_state_previous_key_ambiguous_runtime_id() -> Result<()> { - assert_listing_state(&state_previous_key_ambiguous_runtime_id()) - } - - #[test] - fn listing_state_previous_key_names_one_case_twin_exactly() -> Result<()> { - assert_listing_state(&state_previous_key_names_one_case_twin_exactly()) - } - - #[test] - fn listing_state_stale_key_falls_back_to_the_rollback_target() -> Result<()> { - assert_listing_state(&state_stale_key_falls_back_to_the_rollback_target()) - } - - /// A data dir whose path is not valid UTF-8 still lists as JSON: the - /// paths are written lossily, as the text form writes them, instead of - /// failing serialization and leaving stdout empty. - #[cfg(unix)] - #[test] - fn runtimes_list_json_writes_a_non_utf8_path_lossily() -> Result<()> { - use std::os::unix::ffi::OsStrExt as _; - let data_dir = PathBuf::from(std::ffi::OsStr::from_bytes(b"/data-\xff")); - let mut runtime = listed_runtime_manifest("rt-a", ID_A); - runtime.install_root = data_dir.join("rt-a"); - let listing = listing_from_manifests( - &RocmCliConfig::default(), - vec![runtime], - data_dir.join("registry"), - data_dir.join("active.json"), - ); - let json = serde_json::to_value(&listing)?; - assert_eq!(json["registry"], "/data-\u{fffd}/registry", "{json:#}"); - assert_eq!(json["marker"], "/data-\u{fffd}/active.json", "{json:#}"); - assert_eq!( - listed_runtime(&json, "rt-a")["install_root"], - "/data-\u{fffd}/rt-a", - "{json:#}" - ); - Ok(()) - } - - /// The text prints `toolchain=` from `RuntimeToolchain::as_str`, which is - /// `toolchain_state_text`, the word `rocm examine` prints; the JSON prints - /// the serde `lowercase` rename. Both are documented as `included` and - /// `excluded`, so a change to either word fails here instead of silently - /// changing the JSON. As for the mode test below, a new variant must be - /// added to `all` as well as to the match. - #[test] - fn runtime_toolchain_text_and_json_words_agree_for_every_variant() -> Result<()> { - let all = [RuntimeToolchain::Included, RuntimeToolchain::Excluded]; - for toolchain in all { - match toolchain { - RuntimeToolchain::Included | RuntimeToolchain::Excluded => {} - } - assert_eq!( - serde_json::to_value(toolchain)?, - toolchain.as_str(), - "{toolchain:?}" - ); - } - assert_eq!( - RuntimeToolchain::from_includes_devel(true).as_str(), - "included" - ); - assert_eq!( - RuntimeToolchain::from_includes_devel(false).as_str(), - "excluded" - ); - Ok(()) - } - - /// The text prints `mode=` from `RuntimeMode::as_str` and the JSON from the - /// serde `kebab-case` rename; both are documented as the same words, so - /// every variant must agree. The exhaustive `match` turns a new variant - /// into a compile error here, which forces a look at this test, but it - /// does not add the variant to `all`: whoever adds the match arm must add - /// the variant to `all` too. - #[test] - fn runtime_mode_text_and_json_words_agree_for_every_variant() -> Result<()> { - let all = [RuntimeMode::Managed, RuntimeMode::ReadOnly]; - for mode in all { - match mode { - RuntimeMode::Managed | RuntimeMode::ReadOnly => {} - } - assert_eq!(serde_json::to_value(mode)?, mode.as_str(), "{mode:?}"); - } - Ok(()) - } - - /// The documented shape of `rocm runtimes list --json` (docs/json-output.md): - /// exactly these top-level and per-runtime keys, the registry and marker - /// paths, each runtime's own install root, and newest install first with - /// ties broken by `runtime_key`. - #[test] - fn runtimes_list_json_has_exactly_the_documented_fields_newest_install_first() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-contract"); - let mut install_roots = std::collections::BTreeMap::new(); - // Five runtimes share one install time and are planted in reverse key - // order, so the order the registry is read in cannot pass for the - // `runtime_key` tie-break by accident. - for (key, build) in [ - ("rt-old", 10), - ("rt-tie-e", 20), - ("rt-tie-d", 20), - ("rt-new", 30), - ("rt-tie-c", 20), - ("rt-tie-b", 20), - ("rt-tie-a", 20), - ] { - let manifest = write_test_pip_runtime( - &paths, - key, - "therock-release:gfx120X-all", - "7.13.0", - build, - )?; - install_roots.insert(key, manifest.install_root); - } - let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; - let _ = fs::remove_dir_all(&root); - - // Compared as sets: the key order of a `serde_json::Map` depends on - // whether its `preserve_order` feature is on, and is not documented. - let key_set = |value: &serde_json::Value| -> std::collections::BTreeSet { - value - .as_object() - .expect("an object") - .keys() - .cloned() - .collect() - }; - assert_eq!( - key_set(&listing), - std::collections::BTreeSet::from( - [ - "default_runtime_id", - "active_runtime_key", - "previous_runtime_key", - "registry", - "marker", - "active_problem", - "runtimes", - ] - .map(String::from) - ) - ); - assert_eq!( - listing["registry"], - serde_json::to_value(runtime_registry_dir(&paths))? - ); - assert_eq!( - listing["marker"], - serde_json::to_value(active_runtime_marker_path(&paths))? - ); - - let runtimes = listing["runtimes"] - .as_array() - .expect("runtimes is an array"); - let order: Vec<&str> = runtimes - .iter() - .map(|runtime| runtime["runtime_key"].as_str().unwrap_or_default()) - .collect(); - assert_eq!( - order, - [ - "rt-new", "rt-tie-a", "rt-tie-b", "rt-tie-c", "rt-tie-d", "rt-tie-e", "rt-old", - ] - ); - for runtime in runtimes { - assert_eq!( - key_set(runtime), - std::collections::BTreeSet::from( - [ - "runtime_key", - "runtime_id", - "version", - "format", - "family", - "mode", - "status", - "unusable_reason", - "toolchain", - "active", - "rollback_target", - "install_root", - "provenance", - ] - .map(String::from) - ) - ); - assert_eq!( - key_set(&runtime["provenance"]), - std::collections::BTreeSet::from( - [ - "channel", - "source", - "source_layout_generation", - "device_target", - ] - .map(String::from) - ) - ); - let key = runtime["runtime_key"].as_str().unwrap_or_default(); - assert_eq!( - runtime["install_root"], - serde_json::to_value(&install_roots[key])?, - "{key}" - ); - } - Ok(()) - } - - /// Plants the runtimes whose provenance the JSON tests read: one per way a - /// fact can be recorded or not. Returns their keys, in this order: a - /// nightly that recorded every fact, a runtime from before the layout and - /// target were recorded, an adopted one (the adoption marker is not a - /// source), a tarball install (no exact target), one whose values are - /// padded with whitespace, and one whose every value is blank. - fn plant_provenance_runtimes(paths: &AppPaths) -> Result<[String; 6]> { - let base = write_test_pip_runtime( - paths, - "release-pip-legacy", - "therock-release:gfx120X-all", - "7.13.0", - 10, - )?; - let legacy = therock::InstalledRuntimeManifest { - index_url: None, - source_layout_generation: None, - wheel_composition: None, - ..base.clone() - }; - let nightly = nightly_exact_target_manifest(base); - write_test_pip_runtime( - paths, - &nightly.runtime_key, - &nightly.runtime_id, - &nightly.version, - 20, - )?; - let adopted = therock::InstalledRuntimeManifest { - runtime_key: "adopted-release-pip".to_owned(), - index_url: None, - selected_artifact_url: crate::runtime_registry::ADOPTED_RUNTIME_ARTIFACT_URL.to_owned(), - read_only: true, - ..legacy.clone() - }; - let tarball = therock::InstalledRuntimeManifest { - runtime_key: "release-tarball-gfx120x-all-7-13-0".to_owned(), - format: "tarball".to_owned(), - selected_artifact_url: "https://example.invalid/tarball/rocm-7.13.0.tar.gz".to_owned(), - source_layout_generation: Some("multi-arch-v2".to_owned()), - ..legacy.clone() - }; - let padded = therock::InstalledRuntimeManifest { - runtime_key: "release-pip-padded".to_owned(), - channel: " release ".to_owned(), - index_url: Some(" https://example.invalid/simple ".to_owned()), - source_layout_generation: Some(" multi-arch-v2 ".to_owned()), - wheel_composition: Some(therock::WheelRuntimeComposition { - source_layout_generation: "multi-arch-v2".to_owned(), - package_specs: vec!["rocm[libraries]==7.13.0".to_owned()], - rocm_sdk_target: Some(" gfx1201 ".to_owned()), - }), - ..legacy.clone() - }; - let all_blank = therock::InstalledRuntimeManifest { - runtime_key: "release-pip-all-blank".to_owned(), - channel: String::new(), - index_url: Some(" ".to_owned()), - selected_artifact_url: String::new(), - source_layout_generation: Some(String::new()), - wheel_composition: Some(therock::WheelRuntimeComposition { - source_layout_generation: String::new(), - package_specs: vec!["rocm[libraries]==7.13.0".to_owned()], - rocm_sdk_target: Some(String::new()), - }), - ..legacy.clone() - }; - let planted = [nightly, legacy, adopted, tarball, padded, all_blank]; - for manifest in &planted { - rewrite_manifest(paths, manifest)?; - } - Ok(planted.map(|manifest| manifest.runtime_key)) - } - - /// The JSON names each runtime's provenance facts as strings, trimmed, and - /// writes `null` for one recorded nowhere or recorded blank — never the - /// text's `unrecorded` placeholder, which a script would read as a value. - /// Each object is compared whole, so a fact under the wrong name, a missing - /// one or a placeholder in place of `null` fails here. - #[test] - fn runtimes_list_json_names_recorded_provenance_and_null_for_unrecorded() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-provenance"); - let [nightly, legacy, adopted, tarball, padded, all_blank] = - plant_provenance_runtimes(&paths)?; - let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; - let _ = fs::remove_dir_all(root); - - let provenance = |key: &str| listed_runtime(&listing, key)["provenance"].clone(); - for (key, expected) in [ - ( - nightly, - serde_json::json!({ - "channel": "nightly", - "source": "https://example.invalid/whl-multi-arch", - "source_layout_generation": "next-v1", - "device_target": "gfx1201", - }), - ), - ( - legacy, - serde_json::json!({ - "channel": "release", - "source": "https://example.invalid/therock", - "source_layout_generation": null, - "device_target": null, - }), - ), - ( - adopted, - serde_json::json!({ - "channel": "release", - "source": null, - "source_layout_generation": null, - "device_target": null, - }), - ), - ( - tarball, - serde_json::json!({ - "channel": "release", - "source": "https://example.invalid/tarball/rocm-7.13.0.tar.gz", - "source_layout_generation": "multi-arch-v2", - "device_target": null, - }), - ), - ( - padded, - serde_json::json!({ - "channel": "release", - "source": "https://example.invalid/simple", - "source_layout_generation": "multi-arch-v2", - "device_target": "gfx1201", - }), - ), - ( - all_blank, - serde_json::json!({ - "channel": null, - "source": null, - "source_layout_generation": null, - "device_target": null, - }), - ), - ] { - assert_eq!(provenance(&key), expected, "{key}:\n{listing:#}"); - } - Ok(()) - } - - /// The text's `provenance:` line and the JSON's `provenance` object name - /// the same facts with the same values for every runtime, the text printing - /// `unrecorded` exactly where the JSON has `null`. Both forms are rendered - /// from one listing of the same registry and compared fact by fact, over - /// every way a fact can be recorded or not. - #[test] - fn runtimes_list_text_and_json_name_the_same_provenance() -> Result<()> { - use cli_report::JsonOrText as _; - let (root, paths) = test_paths("runtime-list-provenance-agree"); - let keys = plant_provenance_runtimes(&paths)?; - let listing = runtimes_listing(&paths, &RocmCliConfig::default())?; - let _ = fs::remove_dir_all(root); - let text = listing.render_text(); - let json = serde_json::to_value(&listing)?; - - for key in keys { - let text_pairs: Vec<(String, String)> = provenance_line(&text, &key) - .trim_start() - .strip_prefix("provenance: ") - .expect("provenance prefix") - .split(' ') - .map(|pair| pair.split_once('=').expect("name=value pair")) - .map(|(name, value)| (name.to_owned(), value.to_owned())) - .collect(); - let object = listed_runtime(&json, &key)["provenance"] - .as_object() - .unwrap_or_else(|| panic!("{key} has no provenance object:\n{json:#}")) - .clone(); - assert_eq!( - text_pairs.len(), - object.len(), - "{key}: the text and the JSON name different facts:\n{text}\n{json:#}" - ); - for (name, shown) in text_pairs { - let in_json = object - .get(&name) - .unwrap_or_else(|| panic!("{key}: the JSON has no {name}:\n{json:#}")); - let expected = match in_json { - serde_json::Value::Null => crate::runtime_registry::UNRECORDED_PROVENANCE, - serde_json::Value::String(value) => value.as_str(), - other => panic!("{key}: {name} is neither a string nor null: {other}"), - }; - assert_eq!(shown, expected, "{key}: {name}:\n{text}\n{json:#}"); - } - } - Ok(()) - } - - /// A runtime can be both the active one and the recorded rollback target - /// when the config says so (`rocm runtimes activate` and `rollback` never - /// write that, but the config file is read as it is). Both JSON flags are true; - /// the text has one marker column, and active wins it. - #[test] - fn runtimes_list_marks_a_runtime_both_active_and_rollback_target_as_active() -> Result<()> { - let (root, paths) = test_paths("runtime-list-active-and-rollback"); - write_test_pip_runtime( - &paths, - "rt-both", - "therock-release:gfx120X-all", - "7.13.0", - 10, - )?; - let config = RocmCliConfig { - active_runtime_key: Some("rt-both".to_owned()), - previous_runtime_key: Some("rt-both".to_owned()), - ..RocmCliConfig::default() - }; - let listing = runtimes_list_json(&paths, &config)?; - let text = render_runtimes_text(&paths, &config)?; - let _ = fs::remove_dir_all(root); - - assert_eq!(runtime_keys_flagged(&listing, "active"), ["rt-both"]); - assert_eq!( - runtime_keys_flagged(&listing, "rollback_target"), - ["rt-both"] - ); - assert_eq!( - runtime_keys_marked(&text, ACTIVE_RUNTIME_MARKER), - ["rt-both"] - ); - assert!( - runtime_keys_marked(&text, ROLLBACK_RUNTIME_MARKER).is_empty(), - "{text}" - ); - Ok(()) - } - - #[test] - fn runtimes_list_json_reports_a_runtime_whose_install_root_is_gone_as_unusable() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-unusable"); - let manifest = write_test_pip_runtime( - &paths, - "rt-gone", - "therock-release:gfx120X-all", - "7.13.0", - 10, - )?; - fs::remove_dir_all(&manifest.install_root)?; - let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; - let text = render_runtimes_text(&paths, &RocmCliConfig::default())?; - let _ = fs::remove_dir_all(root); - - let runtime = listed_runtime(&listing, "rt-gone"); - assert_eq!(runtime["status"], "unusable"); - let reason = runtime["unusable_reason"] - .as_str() - .expect("an unusable runtime says why"); - assert!(reason.starts_with("install root is missing: "), "{reason}"); - assert!( - text.contains(&format!("status=unusable ({reason}) toolchain=")), - "the text shows the same reason:\n{text}" - ); - Ok(()) - } - - #[test] - fn runtimes_list_json_reports_an_imported_runtime_as_read_only() -> Result<()> { - let (root, paths) = test_paths("runtime-list-json-read-only"); - let manifest = write_test_pip_runtime( - &paths, - "rt-imported", - "therock-release:gfx120X-all", - "7.13.0", - 10, - )?; - let imported = therock::InstalledRuntimeManifest { - read_only: true, - ..manifest - }; - fs::write( - runtime_manifest_path(&paths, &imported.runtime_key), - serde_json::to_vec_pretty(&imported)?, - )?; - let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; - let _ = fs::remove_dir_all(root); - - assert_eq!(listed_runtime(&listing, "rt-imported")["mode"], "read-only"); - Ok(()) - } - #[cfg(unix)] fn test_active_runtime_marker(paths: &AppPaths, runtime_key: &str) -> ActiveRuntimeMarker { ActiveRuntimeMarker { diff --git a/apps/rocm/src/therock/family.rs b/apps/rocm/src/therock/family.rs index 3afc4e153b..d52568b543 100644 --- a/apps/rocm/src/therock/family.rs +++ b/apps/rocm/src/therock/family.rs @@ -12,9 +12,10 @@ use super::source::{FamilyResolution, TheRockChannel}; use anyhow::{Result, bail}; use rocm_core::{ - AppPaths, GpuSupportLevel, VULKAN_ONLY_SUPPORT_CLAIM, detect_host_gfx_target, - detect_host_gpu_diagnostics, detect_managed_therock_family, gpu_support_level, - known_therock_families, normalize_therock_family, runtime_is_windows, + AppPaths, GpuSupportLevel, VULKAN_ONLY_SUPPORT_CLAIM, VULKAN_UNCONFIRMED_CLAIM, + VULKAN_UNCONFIRMED_NEXT_STEP, VulkanStatus, detect_host_gfx_target, + detect_host_gpu_diagnostics, detect_managed_therock_family, detect_vulkan_support, + gpu_support_level, known_therock_families, normalize_therock_family, runtime_is_windows, }; use std::fmt::Write as _; @@ -158,7 +159,15 @@ pub(super) fn resolve_family( if let Some(raw_arch) = host_arch.as_deref() && target_is_vulkan_only(raw_arch) { - let message = unsupported_host_gpu_message(raw_arch); + // The probe is paid for *here*, inside the branch that is already + // failing, and not by `target_is_vulkan_only` above: the refusal is a + // fact about the target, and only the sentence that follows it is a + // claim about this host. Keeping the two apart is what lets the gate + // stay exactly what it was while the advice stops over-promising. No + // successful resolve runs this, so `install sdk`'s hot path is + // unchanged, and `detect_host_gpu_diagnostics` on the next line already + // costs more than one `vulkaninfo` attempt. + let message = unsupported_host_gpu_message(raw_arch, detect_vulkan_support().status); let diagnostics = detect_host_gpu_diagnostics(); bail!("{message}\n\n{diagnostics}"); } @@ -191,9 +200,33 @@ pub(super) fn resolve_family( /// family covered it. On the host branch the caller has already established /// that `normalize_therock_family` answers `None`, so the extra call there is /// a no-op that costs a string compare. +/// +/// The Vulkan argument is [`rocm_core::VulkanStatus::Unknown`] — "nobody +/// looked" — and deliberately not this host's probe result. `value` may be a +/// target the user *named*, which can be a GPU that is not in this machine, so +/// a Vulkan driver found here would say nothing about it; and on the host +/// branch, probing would make `install sdk` refuse or allow based on a Vulkan +/// fact that has no bearing on whether a ROCm SDK exists. `Unknown` keeps the +/// `VulkanOnly` tier for every target the catalog confirms has no ROCm build, +/// which is exactly the set this gate refused before the probe existed — the +/// refusals are unchanged. +/// +/// This is only the *gate*, not the sentence. Whether a target has a ROCm build +/// is a fact about the catalog, and probing Vulkan to answer it would make +/// `install sdk` refuse or allow on an unrelated fact. What the refusal may +/// then *say* about Vulkan is a different question, and the two messages below +/// answer it differently: [`unsupported_host_gpu_message`] is about the GPU in +/// this machine, so it grades its claim by this host's probe, while +/// [`unsupported_requested_target_message`] is about a GPU the user named, +/// which may not be here at all, so it keeps the unconditional +/// `VULKAN_ONLY_SUPPORT_CLAIM` — there is no host whose probe would bear on it. fn target_is_vulkan_only(value: &str) -> bool { matches!( - gpu_support_level(Some(value), normalize_therock_family(value).as_deref()), + gpu_support_level( + Some(value), + normalize_therock_family(value).as_deref(), + rocm_core::VulkanStatus::Unknown, + ), GpuSupportLevel::VulkanOnly ) } @@ -202,6 +235,31 @@ fn target_is_vulkan_only(value: &str) -> bool { /// covers. It deliberately does not list `--family` values: none of them was /// built for this GPU. /// +/// **The Vulkan half of this message is graded by the probe, not asserted.** +/// It used to close, unconditionally, with "the Vulkan backend can still be +/// used - try `rocm serve --engine lemonade`", on a host nobody had +/// looked at. That is the same unearned claim the Vulkan probe exists to +/// remove, and because this branch runs only after *this machine's* GPU has +/// been detected, there is a probe result that bears on it directly: the same +/// session could have `rocm examine` saying "no Vulkan driver was found, so no +/// GPU backend can run here" while `rocm install sdk` sent the user to serve a +/// model on that backend. AGENTS.md §3 asks that a named command be able to +/// clear the condition it was printed for, and on a `NoGpuBackend` host that +/// `rocm serve` cannot. +/// +/// So `vulkan` is routed through [`gpu_support_level`] — the same classifier +/// `rocm examine`'s `rocm_support` line uses, with the same status — and the +/// closing sentence follows the level. The claims themselves come from +/// `rocm-core`'s shared constants, so this message and that line cannot drift +/// into describing one host two ways. Only `VulkanOnly` keeps the Lemonade +/// recommendation; `VulkanUnconfirmed` makes it conditional on what +/// `vulkaninfo` reports, and `NoGpuBackend` does not make it at all. +/// +/// The *refusal* is unchanged by any of this: the gate is +/// [`target_is_vulkan_only`], which does not probe. A host with no Vulkan +/// driver was refused before and is refused now; it is only told something true +/// afterwards. +/// /// The remediation pins the engine with `--engine lemonade` rather than /// suggesting a bare `rocm serve `. This branch knows the *host* has no /// ROCm build, which is not the same as knowing which engine `serve` would @@ -225,13 +283,60 @@ fn target_is_vulkan_only(value: &str) -> bool { /// `a_gfx90c_host_the_kernel_gives_no_compute_node_still_has_a_usable_gpu` /// drives both halves off one planted `/sys`, and serve-63 runs the real binary /// against that same host shape on a GPU-less lane. -fn unsupported_host_gpu_message(raw_arch: &str) -> String { +fn unsupported_host_gpu_message(raw_arch: &str, vulkan: VulkanStatus) -> String { + // The same three arguments `target_is_vulkan_only` passes, with this host's + // real status in place of `Unknown`. The caller has already established + // that the first two make the target Vulkan-only, so only the three Vulkan + // tiers are reachable here. + let level = gpu_support_level( + Some(raw_arch), + normalize_therock_family(raw_arch).as_deref(), + vulkan, + ); + let vulkan_sentence = match level { + // A device answered, a driver is installed, or the platform cannot be + // probed at all. The last of those keeps the benefit of the doubt it + // had before any probe existed — see `GpuSupportLevel::VulkanOnly`. + GpuSupportLevel::VulkanOnly => format!( + "The GPU is detected but is {VULKAN_ONLY_SUPPORT_CLAIM}. \ + Try `rocm serve --engine lemonade` - it runs on Lemonade's \ + Vulkan backend instead." + ), + // Looked at, nothing settled. The Lemonade suggestion survives, but as + // a consequence of what `vulkaninfo` reports rather than as a promise: + // this level is reached routinely by a working Adrenalin laptop, so + // withholding it entirely would be as wrong as asserting it. + GpuSupportLevel::VulkanUnconfirmed => format!( + "The GPU is detected but is not supported by ROCm, and \ + {VULKAN_UNCONFIRMED_CLAIM} - {VULKAN_UNCONFIRMED_NEXT_STEP}. \ + If it reports a device, `rocm serve --engine lemonade` runs \ + on Lemonade's Vulkan backend." + ), + // Both halves confirmed: no ROCm build, and the probe looked for a + // Vulkan driver and found none. Naming `rocm serve` here would name a + // command that cannot clear what printed it, so the only step left is + // the one that can. + GpuSupportLevel::NoGpuBackend => { + "The GPU is detected but is not supported by ROCm, and no Vulkan GPU driver was \ + found here either, so there is no GPU backend to serve a model on. Install one \ + (Mesa RADV on Linux, the AMD display driver on Windows) and re-run `rocm \ + examine` to confirm it." + .to_owned() + } + // Unreachable: the caller gated on `target_is_vulkan_only`, which asks + // `gpu_support_level` the same first two questions, so the catalog has + // already confirmed a recognized target with no ROCm build and no + // covering family. Spelled out rather than folded into a `_` so that a + // new `GpuSupportLevel` is a compile error here instead of silently + // inheriting a Vulkan claim, and worded so that if one ever did arrive + // it would assert nothing. + GpuSupportLevel::RocmHip | GpuSupportLevel::Unknown => { + "Run `rocm examine` to see what this host supports.".to_owned() + } + }; format!( "no ROCm SDK build exists for the detected GPU target `{raw_arch}`, so \ - `rocm install sdk` has nothing to install for it.\n\ - The GPU is detected but is {VULKAN_ONLY_SUPPORT_CLAIM}. \ - Try `rocm serve --engine lemonade` - it runs on Lemonade's \ - Vulkan backend instead." + `rocm install sdk` has nothing to install for it.\n{vulkan_sentence}" ) } @@ -400,17 +505,28 @@ mod tests { } } - /// Both refusals and `rocm examine`'s `rocm_support` line make the same - /// claim about a Vulkan-only GPU, so they render it from the same string. + /// Both refusals make the same claim about a Vulkan-only GPU, so they + /// render it from the same string. /// /// Asserting the constant is *in* each message is what makes it one /// claim; the wording itself is pinned word-for-word in `rocm-core` /// (`the_vulkan_only_claim_is_pinned_word_for_word`), so neither test /// alone can be satisfied by quietly rewriting the other's expectation. + /// + /// `rocm examine`'s `rocm_support` line is deliberately not in this list. + /// It grades the claim finer than three tiers, naming the device the probe + /// enumerated - see `rocm_support_line` in `rocm-core`'s + /// `host_gpu/render.rs`. + /// + /// The host-side refusal is asked here at the status where it *does* make + /// the claim. Which statuses those are is + /// `the_detected_gpu_refusal_grades_its_vulkan_claim_by_the_probe`'s + /// question; this one is only that the wording comes from the shared + /// constant and not from a second copy. #[test] fn both_install_refusals_render_the_shared_vulkan_only_claim() { for message in [ - unsupported_host_gpu_message("gfx90c"), + unsupported_host_gpu_message("gfx90c", VulkanStatus::Available), unsupported_requested_target_message("gfx90c", "--family"), ] { assert!( @@ -421,9 +537,116 @@ mod tests { } } + /// The detected-GPU refusal must say about Vulkan only what this host's + /// probe established. + /// + /// The regression this pins is a contradiction visible inside one session: + /// on a host with no AMD Vulkan driver, `rocm examine` reported "no Vulkan + /// GPU driver was found" while `rocm install sdk` closed with "the Vulkan + /// backend can still be used; try `rocm serve --engine lemonade`". + /// Both read as facts about the same machine, and the command the second + /// one named could not clear the condition it was printed for, which + /// AGENTS.md §3 requires of remediation advice. + /// + /// Every `VulkanStatus` is covered, so a status that stops being routed + /// through `gpu_support_level` fails here. `Unknown` is in the + /// claim-keeping list deliberately: a platform the probe cannot read at + /// all keeps the benefit of the doubt it had before the probe existed, + /// which is the one exception `GpuSupportLevel::VulkanOnly` documents. + #[test] + fn the_detected_gpu_refusal_grades_its_vulkan_claim_by_the_probe() { + // A device answered, a driver is installed, or nobody could look: all + // three may offer Lemonade, and all three say so with the shared claim. + for status in [ + VulkanStatus::Available, + VulkanStatus::DriverPresentDevicesUnverified, + VulkanStatus::Unknown, + ] { + let message = unsupported_host_gpu_message("gfx90c", status); + assert!( + message.contains(VULKAN_ONLY_SUPPORT_CLAIM), + "{status:?} is the tier that has earned the claim: {message}" + ); + assert!( + message.contains("rocm serve --engine lemonade"), + "{status:?}: {message}" + ); + } + + // Looked at and nothing settled. The question is open, so the message + // must say so rather than answer it in either direction, and the + // Lemonade suggestion survives only as a consequence of what + // `vulkaninfo` reports. + let unconfirmed = unsupported_host_gpu_message("gfx90c", VulkanStatus::Inconclusive); + assert!( + unconfirmed.contains(VULKAN_UNCONFIRMED_CLAIM), + "a host that was probed and showed nothing is owed the hedged claim, the same one \ + `rocm examine` gives it: {unconfirmed}" + ); + assert!( + !unconfirmed.contains(VULKAN_ONLY_SUPPORT_CLAIM), + "nothing here established a Vulkan backend: {unconfirmed}" + ); + assert!( + unconfirmed.contains("vulkaninfo"), + "the one thing that would settle it has to be named: {unconfirmed}" + ); + assert!( + unconfirmed.contains("If it reports a device, `rocm serve --engine lemonade`"), + "the serve suggestion must be conditional on the probe, not a promise: {unconfirmed}" + ); + + // Both halves confirmed. `rocm serve` cannot clear this, so it must not + // be named at all. + let absent = unsupported_host_gpu_message("gfx90c", VulkanStatus::Absent); + assert!( + !absent.contains(VULKAN_ONLY_SUPPORT_CLAIM), + "`rocm examine` tells this host no GPU backend can run here; `install sdk` must not \ + tell it the opposite in the same session: {absent}" + ); + assert!( + !absent.contains("rocm serve"), + "the probe looked and found no Vulkan driver, so serving on one is a command that \ + cannot clear the condition it is printed for (AGENTS.md §3): {absent}" + ); + assert!( + !absent.contains("lemonade") && !absent.contains("Lemonade"), + "naming the engine makes the same promise as naming the command: {absent}" + ); + assert!( + absent.contains("no Vulkan GPU driver was found"), + "the host is still owed what was established about it: {absent}" + ); + assert!( + absent.contains("Mesa RADV") && absent.contains("AMD display driver"), + "and the one step that can clear it: {absent}" + ); + + // The target and the opening sentence are the same whatever Vulkan + // reported: the refusal itself is a fact about the catalog, and only + // the sentence after it is a claim about this host. + for status in [ + VulkanStatus::Available, + VulkanStatus::DriverPresentDevicesUnverified, + VulkanStatus::Inconclusive, + VulkanStatus::Absent, + VulkanStatus::Unknown, + ] { + let message = unsupported_host_gpu_message("gfx90c", status); + assert!( + message.contains("no ROCm SDK build exists for the detected GPU target `gfx90c`"), + "{status:?}: {message}" + ); + assert!( + target_is_vulkan_only("gfx90c"), + "and the gate that printed it does not consult the probe at all" + ); + } + } + #[test] fn unsupported_gpu_error_names_the_gpu_and_does_not_suggest_families() { - let message = unsupported_host_gpu_message("gfx90c"); + let message = unsupported_host_gpu_message("gfx90c", VulkanStatus::Available); assert!(message.contains("no ROCm SDK build"), "{message}"); assert!(message.contains("`gfx90c`"), "{message}"); assert!(message.contains("Vulkan"), "{message}"); @@ -449,7 +672,7 @@ mod tests { /// every config, because an explicit `--engine` out-ranks all of it. #[test] fn unsupported_gpu_error_pins_the_engine_a_configured_default_could_override() { - let message = unsupported_host_gpu_message("gfx90c"); + let message = unsupported_host_gpu_message("gfx90c", VulkanStatus::Available); assert!( message.contains("rocm serve --engine lemonade"), @@ -498,11 +721,13 @@ mod tests { ); } - // The sibling path did look at this host, so it keeps the claim: this is - // the asymmetry, not a blanket ban on the sentence. It pins the engine - // for a different reason — see - // `unsupported_gpu_error_pins_the_engine_a_configured_default_could_override`. - let detected = unsupported_host_gpu_message("gfx90c"); + // The sibling path did look at this host, so it may make the claim when + // the probe backs it: this is the asymmetry, not a blanket ban on the + // sentence. It pins the engine for a different reason — see + // `unsupported_gpu_error_pins_the_engine_a_configured_default_could_override` + // — and which probe results earn it is + // `the_detected_gpu_refusal_grades_its_vulkan_claim_by_the_probe`'s. + let detected = unsupported_host_gpu_message("gfx90c", VulkanStatus::Available); assert!( detected.contains("rocm serve --engine lemonade"), "{detected}" diff --git a/apps/rocmd/src/engine_ipc.rs b/apps/rocmd/src/engine_ipc.rs index ae5dbba841..eda8243ac2 100644 --- a/apps/rocmd/src/engine_ipc.rs +++ b/apps/rocmd/src/engine_ipc.rs @@ -424,7 +424,10 @@ mod tests { const STOPPED: &str = r#"{"ok":true,"data":{"stopped":true}}"#; fn healthcheck_envelope() -> EngineRequestEnvelope { - EngineRequestEnvelope::new(EngineMethod::Healthcheck, json!({"service_id": SERVICE_ID})) + EngineRequestEnvelope { + method: EngineMethod::Healthcheck, + payload: json!({"service_id": SERVICE_ID}), + } } fn request(engine: &FakeEngine, paths: &AppPaths) -> Result { @@ -451,11 +454,7 @@ mod tests { assert_eq!(engine.argv(), ["__engine-stdio", "vllm"]); assert_eq!( engine.stdin(), - format!( - "{{\"protocol_version\":\"{}\",\"method\":\"healthcheck\",\ - \"payload\":{{\"service_id\":\"svc-stdio-child\"}}}}\n", - rocm_engine_protocol::ENGINE_PROTOCOL_VERSION - ) + "{\"method\":\"healthcheck\",\"payload\":{\"service_id\":\"svc-stdio-child\"}}\n" ); } @@ -537,9 +536,7 @@ mod tests { FakeEngine::new("rocmd-garbage", true, "printf 'not json'\necho oops >&2"); assert_eq!( request(&garbage, &paths).unwrap_err().to_string(), - "failed to parse engine response envelope: the engine's stdout is not JSON \ - (expected ident at line 1 column 2), starting with `not json` (an engine \ - writes only its JSON answer to stdout; logs go to stderr); stderr: oops" + "failed to parse engine response envelope; stderr: oops" ); } @@ -563,8 +560,10 @@ mod tests { let engine = FakeEngine::new("rocmd-sigpipe", false, "exit 3"); // Larger than a pipe buffer, so the write reaches the closed read end. let big = "x".repeat(1 << 20); - let envelope = - EngineRequestEnvelope::new(EngineMethod::Healthcheck, json!({ "blob": big })); + let envelope = EngineRequestEnvelope { + method: EngineMethod::Healthcheck, + payload: json!({ "blob": big }), + }; let result = engine_request_via::( engine.path(), &paths, diff --git a/crates/rocm-core/src/gfx_target.rs b/crates/rocm-core/src/gfx_target.rs index a73e36e97d..033c8a3b51 100644 --- a/crates/rocm-core/src/gfx_target.rs +++ b/crates/rocm-core/src/gfx_target.rs @@ -566,48 +566,211 @@ pub(crate) fn gfx_target_from_gc_version(major: u32, minor: u32, revision: u32) pub enum GpuSupportLevel { /// A TheRock package family covers this GPU: full ROCm/HIP support. RocmHip, - /// Recognized, confirmed to have no ROCm/HIP build, but Vulkan-based - /// engines (the default Lemonade backend) still work on it. + /// Recognized, confirmed to have no ROCm/HIP build, and a Vulkan GPU driver + /// was **found on this host**, so Vulkan-based engines (the default Lemonade + /// backend) run on it. + /// + /// One exception, and it is deliberate: [`VulkanStatus::Unknown`] — a + /// platform the probe cannot read at all, or a summary from before the probe + /// existed — also lands here, keeping the benefit of the doubt it had before + /// any probe existed rather than withholding the only path such a host has. + /// So this level means "a driver was found, **or** nobody could look"; it is + /// `render.rs` that tells the two apart in what the user reads, and it only + /// names a driver when one was actually found. + /// + /// The second half of that sentence must be evidence, never inference. + /// Deriving it from the gfx table alone — reading "no ROCm build" as + /// "Vulkan then", on a machine nobody has looked at — sends a host with no + /// Vulkan driver, or with only a software rasteriser, to a backend that + /// cannot start: every surface that renders this level tells the user to go + /// and serve a model on it. VulkanOnly, + /// Recognized, confirmed to have no ROCm/HIP build, and the Vulkan probe + /// could not reach an answer — nothing was found, and at least one of its + /// two sources never answered. Either one can be the source that went + /// unread: `vulkaninfo` missing or failing, or (on Windows, where the + /// registry read is its own PowerShell call) the driver listing. + /// + /// Deliberately NOT folded into [`Self::NoGpuBackend`]. That level renders + /// as a confirmed fact and is serialized for JSON consumers, and this state + /// has not earned it: on Windows the Khronos `Drivers` key is legacy and + /// `vulkaninfo` is rarely on PATH, so a working Adrenalin laptop — the + /// machine shape ROCMAI-550 was reported from — lands here routinely. + /// Telling it there is no GPU backend is a worse answer than the + /// unconditional Vulkan claim this level exists to replace. + /// + /// Nor is it [`Self::VulkanOnly`], which promises a backend that may not be + /// there. It is its own answer: say what was looked for, that nothing was + /// found, and how to settle it. + VulkanUnconfirmed, + /// Recognized, confirmed to have no ROCm/HIP build, **and** no Vulkan GPU + /// driver was found: this host has no GPU path at all. + /// + /// Deliberately not folded into [`Self::Unknown`]. Both halves here are + /// confirmed — the catalog establishes the missing ROCm build, and the + /// Vulkan probe looked and found nothing — whereas `Unknown` means the CLI + /// could not establish either. Collapsing them would commit, in the other + /// direction, the exact conflation this enum's `Unknown` exists to prevent: + /// a fact about the machine would be reported as a gap in what this build + /// knows, and the user would be sent to probe a question already answered. + NoGpuBackend, /// No GPU detected yet, or a gfx target this catalog doesn't recognize. Unknown, } -/// The one claim every [`GpuSupportLevel::VulkanOnly`] surface makes, written -/// once. +/// The claim every *unprobed* [`GpuSupportLevel::VulkanOnly`] surface makes, +/// written once. +/// +/// `rocm install sdk`'s two refusals (`unsupported_host_gpu_message` / +/// `unsupported_requested_target_message` in `apps/rocm/src/therock/family.rs`) +/// tell the user the same two things about a Vulkan-only GPU: ROCm will not run +/// on it, and Vulkan will. They are two different sentences around it — each +/// adds its own subject and its own next step, because what they may promise +/// differs — but the claim itself is shared, so it lives here next to the +/// classifier that decides when it is true rather than being retyped at each +/// site. +/// +/// **This constant is the claim, not the decision to make it.** Who may say it +/// is settled by whether the speaker has a host to grade it against, and the +/// three surfaces differ: /// -/// `rocm examine`'s `rocm_support` line and `rocm install sdk`'s two refusals -/// (`unsupported_host_gpu_message` / `unsupported_requested_target_message` in -/// `apps/rocm/src/therock/family.rs`) all tell the user the same two things -/// about a Vulkan-only GPU: ROCm will not run on it, and Vulkan will. They are -/// three different sentences around it — each adds its own subject and its own -/// next step, because what they may promise differs — but the claim itself is -/// shared, so it lives here next to the classifier that decides when it is -/// true rather than being retyped at each site. +/// - `unsupported_requested_target_message` says it unconditionally, and that +/// is correct: it is about a target the *user named*, which may not be the +/// GPU in this machine, so no probe of this host bears on it. It classifies +/// with [`VulkanStatus::Unknown`] for the same reason. +/// - `unsupported_host_gpu_message` is about the GPU that was *detected here*, +/// so it classifies with this host's real [`VulkanStatus`] and interpolates +/// this constant only at [`GpuSupportLevel::VulkanOnly`]. At +/// `VulkanUnconfirmed` it says [`VULKAN_UNCONFIRMED_CLAIM`] instead, and at +/// `NoGpuBackend` it says neither. Saying it unconditionally there put `rocm +/// install sdk` and `rocm examine` in flat contradiction about the same +/// machine in the same session. +/// - `rocm examine`'s `rocm_support` line does not interpolate it at all. It +/// grades the second half of the claim finer than three tiers — an +/// enumerated device is *named*, so the reader can check it rather than take +/// it — and the unconditional "can still be used" is exactly the promise this +/// work exists to stop making. See `rocm_support_line` in +/// `host_gpu/render.rs`. /// /// Deliberately just the claim, with no leading subject and no trailing -/// punctuation: a caller supplies both. Changing the wording here changes all -/// three surfaces together, which is the point. +/// punctuation: a caller supplies both. Changing the wording here changes every +/// site that makes it, which is the point. pub const VULKAN_ONLY_SUPPORT_CLAIM: &str = "not supported by ROCm; the Vulkan backend can still be used"; -/// Classify the host's GPU support level from the same two facts -/// `ExamineSummary` and `resolve_family` already compute: the detected gfx -/// target and whichever TheRock family (if any) covers it. +/// What every [`GpuSupportLevel::VulkanUnconfirmed`] surface says about the +/// host, written once. +/// +/// Two surfaces render this level — `rocm examine`'s `rocm_support` line +/// (`rocm_support_line` in `host_gpu/render.rs`) and the lemonade engine note +/// (`lemonade_engine_note` in `apps/rocm/src/main.rs`) — and they appear in the +/// *same* `rocm examine` report, a few lines apart. Sharing the claim is what +/// stops one of them denying a driver while the other says the question is +/// open. +/// +/// It states a gap in the probe, never a fact about the machine. On Windows the +/// ICD lookup reads only the legacy Khronos `Drivers` key and `vulkaninfo` is +/// rarely on PATH, so a working Adrenalin laptop lands in this level routinely; +/// anything stronger than "could not be determined" is false on that host. +pub const VULKAN_UNCONFIRMED_CLAIM: &str = + "whether a Vulkan driver is present could not be determined here"; + +/// The next step for a host at [`GpuSupportLevel::VulkanUnconfirmed`] when +/// nothing is known about its display driver. +/// +/// `vulkaninfo` comes first and the install is conditional on what it reports, +/// because the level is reached by hosts that already have a working driver. +/// An unconditional "install a Vulkan driver" is advice those hosts cannot act +/// on, and AGENTS.md §3 asks that a named command be able to clear the +/// condition it is printed for — running `vulkaninfo` can, on every host that +/// reaches here. +/// +/// Deliberately not "install `vulkaninfo`": on a driverless Linux host the tool +/// is typically already installed, prints "Found no drivers!" and exits 1, +/// which is one of the shapes that lands in this level. +pub const VULKAN_UNCONFIRMED_NEXT_STEP: &str = "run `vulkaninfo` yourself to see what it reports, and install a Vulkan driver (Mesa RADV on \ + Linux, the AMD display driver on Windows) if it finds none"; + +/// The next step for a Windows host at [`GpuSupportLevel::VulkanUnconfirmed`] +/// whose AMD display driver the summary already found. +/// +/// The Windows AMD display driver *is* the Vulkan driver on that platform — +/// Adrenalin installs the ICD — so `driver_status: amd_display_driver_detected` +/// contradicts the install advice in [`VULKAN_UNCONFIRMED_NEXT_STEP`]. Only +/// `vulkaninfo` is left to settle whether that driver exposes a device here. +/// +/// The cross-check is Windows-only on purpose. Linux's `driver_status` reports +/// the `amdgpu` kernel module, which says nothing about whether a userspace +/// Vulkan ICD such as Mesa RADV is installed, so suppressing the install advice +/// there would withhold the one step that can help. +pub const VULKAN_UNCONFIRMED_NEXT_STEP_WITH_DISPLAY_DRIVER: &str = "the AMD display driver is installed (see `driver_status`), so there is nothing to install \ + here - run `vulkaninfo` yourself to see whether it reports a device"; + +/// Classify a GPU target's support level. +/// +/// Reads the two facts `ExamineSummary` and `resolve_family` already compute — +/// the detected gfx target and whichever TheRock family (if any) covers it — +/// plus what the Vulkan probe found. /// /// Not only for a *host*: `resolve_family` also asks this of a target the user /// named with `--family` or `ROCM_CLI_THEROCK_FAMILY`, to decide whether to -/// refuse it. The two arguments are facts about a GPU target, not about this -/// machine, so that is the same question. What differs is what the caller may -/// then say — a requested target establishes nothing about the hardware here, -/// which is why the two install refusals end differently. +/// refuse it. The first two arguments are facts about a GPU target, not about +/// this machine, so that is the same question. What differs is what the caller +/// may then say — a requested target establishes nothing about the hardware +/// here, which is why the two install refusals end differently, and why they +/// pass [`VulkanStatus::Unknown`] rather than probing this host for a verdict +/// about another one. +/// +/// `vulkan` only ever decides between [`GpuSupportLevel::VulkanOnly`], +/// [`GpuSupportLevel::VulkanUnconfirmed`] and [`GpuSupportLevel::NoGpuBackend`], +/// and is consulted only once the catalog has +/// confirmed there is no ROCm build. A host with a covering family is `RocmHip` +/// whatever Vulkan reports, and an unrecognized target stays `Unknown`: finding +/// a Vulkan driver says nothing about whether ROCm would also work there, so it +/// must not be allowed to turn a detection gap into a support claim. +/// +/// [`VulkanStatus::Unknown`] — the platform could not be probed at all — keeps +/// `VulkanOnly`: withholding the one path such a host has, on the strength of a +/// probe that never ran, is a worse answer than the unconditional assumption it +/// replaces. pub fn gpu_support_level( detected_gfx_target: Option<&str>, compatible_therock_family: Option<&str>, + vulkan: crate::host_gpu::VulkanStatus, ) -> GpuSupportLevel { match (detected_gfx_target, compatible_therock_family) { (_, Some(_)) => GpuSupportLevel::RocmHip, - (Some(gfx), None) if gfx_target_has_no_rocm_build(gfx) => GpuSupportLevel::VulkanOnly, + (Some(gfx), None) if gfx_target_has_no_rocm_build(gfx) => { + // `Unknown` only — a platform the probe cannot look at, which keeps + // the benefit of the doubt. `Inconclusive` is a host that WAS + // looked at and showed nothing, and must not be promised Vulkan: it + // is the common no-driver shape, since most such hosts have no + // `vulkaninfo` either. The wording it gets is hedged rather than a + // confirmed absence — see `render.rs`. + // + // Every variant is spelled out, with no `_` and no guard. A guard + // reads well but does not count toward exhaustiveness, so the arms + // would have to end in a wildcard — and a wildcard here silently + // routes any future `VulkanStatus` to `NoGpuBackend`, which renders + // as a confirmed fact. Listing every variant makes a new one a + // compile error instead, the same discipline `render.rs` uses. + match vulkan { + // A device answered, or a driver is installed and nothing + // contradicted it. + crate::host_gpu::VulkanStatus::Available + | crate::host_gpu::VulkanStatus::DriverPresentDevicesUnverified => { + GpuSupportLevel::VulkanOnly + } + // A platform the probe cannot look at keeps the benefit of the + // doubt, as it did before any probe existed. + crate::host_gpu::VulkanStatus::Unknown => GpuSupportLevel::VulkanOnly, + // Looked at, and nothing either way. Not a confirmed absence — + // see `VulkanUnconfirmed`. + crate::host_gpu::VulkanStatus::Inconclusive => GpuSupportLevel::VulkanUnconfirmed, + // The only status that has earned a confirmed absence. + crate::host_gpu::VulkanStatus::Absent => GpuSupportLevel::NoGpuBackend, + } + } _ => GpuSupportLevel::Unknown, } } @@ -619,17 +782,27 @@ pub fn gpu_support_level( /// site that transposed them would classify a Vulkan-only host as `RocmHip` /// and still compile. `rocm engines` and the codex-bridge `engines` tool both /// derive the level from this struct, so both go through this. +/// +/// `vulkan` is passed in rather than probed here so this stays a pure function +/// of what the caller already holds: the probe runs a subprocess and reads the +/// filesystem, and burying that in a helper this cheap would make every caller +/// pay for it without saying so. #[must_use] -pub fn gpu_support_level_for_host_gpu(host_gpu: &HostGpuSummary) -> GpuSupportLevel { +pub fn gpu_support_level_for_host_gpu( + host_gpu: &HostGpuSummary, + vulkan: crate::host_gpu::VulkanStatus, +) -> GpuSupportLevel { gpu_support_level( host_gpu.gfx_target.as_deref(), host_gpu.therock_family.as_deref(), + vulkan, ) } #[cfg(test)] mod tests { use super::*; + use crate::host_gpu::VulkanStatus; #[test] fn normalize_therock_family_maps_gfx1101_to_gfx110x_all() { @@ -705,14 +878,14 @@ mod tests { ); } - /// The shared claim is user-visible text on three surfaces, so its wording - /// is pinned here rather than only asserted as "whatever the constant - /// says". + /// The shared claim is user-visible text on both `rocm install sdk` + /// refusals, so its wording is pinned here rather than only asserted as + /// "whatever the constant says". /// - /// `rocm examine`'s `rocm_support` line and both `rocm install sdk` - /// refusals now interpolate [`VULKAN_ONLY_SUPPORT_CLAIM`], which is what - /// stops them drifting — but it also means a careless edit to the constant - /// silently rewords all three at once, and their own tests would still + /// Both refusals interpolate [`VULKAN_ONLY_SUPPORT_CLAIM`] — one + /// unconditionally, one only at [`GpuSupportLevel::VulkanOnly`] — which is + /// what stops them drifting. But it also means a careless edit to the + /// constant silently rewords both at once, and their own tests would still /// pass because they assert containment of the same constant. This test is /// the one place that has to be changed deliberately. #[test] @@ -1040,7 +1213,7 @@ mod tests { therock_family: Some("gfx94X-dcgpu".to_owned()), }; assert_eq!( - gpu_support_level_for_host_gpu(&host_gpu), + gpu_support_level_for_host_gpu(&host_gpu, VulkanStatus::Available), GpuSupportLevel::RocmHip ); } @@ -1053,7 +1226,7 @@ mod tests { therock_family: None, }; assert_eq!( - gpu_support_level_for_host_gpu(&host_gpu), + gpu_support_level_for_host_gpu(&host_gpu, VulkanStatus::Available), GpuSupportLevel::VulkanOnly ); } @@ -1061,7 +1234,7 @@ mod tests { #[test] fn gpu_support_level_for_host_gpu_reads_an_undetected_summary_as_unknown() { assert_eq!( - gpu_support_level_for_host_gpu(&HostGpuSummary::default()), + gpu_support_level_for_host_gpu(&HostGpuSummary::default(), VulkanStatus::Available), GpuSupportLevel::Unknown ); } @@ -1076,35 +1249,111 @@ mod tests { #[test] fn gpu_support_level_is_rocm_hip_when_a_family_covers_it() { assert_eq!( - gpu_support_level(Some("gfx90a"), Some("gfx90a")), + gpu_support_level(Some("gfx90a"), Some("gfx90a"), VulkanStatus::Available), + GpuSupportLevel::RocmHip + ); + // A covering family wins outright: a host whose Vulkan probe found + // nothing still has ROCm, and must not be downgraded for it. + assert_eq!( + gpu_support_level(Some("gfx90a"), Some("gfx90a"), VulkanStatus::Absent), GpuSupportLevel::RocmHip ); assert_eq!( - gpu_support_level(None, Some("gfx90a")), + gpu_support_level(None, Some("gfx90a"), VulkanStatus::Absent), GpuSupportLevel::RocmHip ); // Even for a target this file's own table says has no ROCm build: the // family the caller resolved is a statement about ROCm support, and a // detected target cannot outvote it. assert_eq!( - gpu_support_level(Some("gfx90c"), Some("gfx90a")), + gpu_support_level(Some("gfx90c"), Some("gfx90a"), VulkanStatus::Absent), GpuSupportLevel::RocmHip ); } #[test] fn gpu_support_level_is_unknown_without_detection_or_for_an_unrecognized_target() { - assert_eq!(gpu_support_level(None, None), GpuSupportLevel::Unknown); assert_eq!( - gpu_support_level(Some("gfx_totally_unrecognized"), None), + gpu_support_level(None, None, VulkanStatus::Available), GpuSupportLevel::Unknown ); + // Finding a Vulkan driver says nothing about whether ROCm would work on + // an unrecognized target, so it must not promote a detection gap into a + // support claim. + assert_eq!( + gpu_support_level( + Some("gfx_totally_unrecognized"), + None, + VulkanStatus::Available + ), + GpuSupportLevel::Unknown + ); + } + + #[test] + fn gpu_support_level_is_vulkan_only_for_gfx90c_with_a_vulkan_driver() { + assert_eq!( + gpu_support_level(Some("gfx90c"), None, VulkanStatus::Available), + GpuSupportLevel::VulkanOnly + ); + // An installed driver that enumerated no device is still worth routing + // to; the level says "Vulkan", and `examine`'s own line carries how sure + // the probe was. + assert_eq!( + gpu_support_level( + Some("gfx90c"), + None, + VulkanStatus::DriverPresentDevicesUnverified + ), + GpuSupportLevel::VulkanOnly + ); + } + + /// The common no-driver host: no ICD, no device, and no `vulkaninfo` to + /// ask. It must not be promised a Vulkan path — that is the symptom this + /// change exists to remove, and it is the usual shape, since a host with no + /// driver generally has no `vulkaninfo` either. + /// + /// `Unknown` (a platform the probe cannot look at) keeps the benefit of the + /// doubt; `Inconclusive` has been looked at and showed nothing. + #[test] + fn a_probed_host_with_no_evidence_is_not_promised_vulkan() { + assert_eq!( + gpu_support_level( + Some("gfx90c"), + None, + crate::host_gpu::VulkanStatus::Inconclusive + ), + GpuSupportLevel::VulkanUnconfirmed, + "a host probed with no answer must be told neither that Vulkan runs nor \ + that it is absent — a Windows box with a working Adrenalin driver lands \ + here, since the legacy Khronos key and a missing `vulkaninfo` leave no \ + evidence to find" + ); + assert_eq!( + gpu_support_level(Some("gfx90c"), None, crate::host_gpu::VulkanStatus::Unknown), + GpuSupportLevel::VulkanOnly, + "a platform that cannot be probed keeps the benefit of the doubt" + ); + } + + #[test] + fn gpu_support_level_reports_no_gpu_backend_when_the_vulkan_probe_found_none() { + assert_eq!( + gpu_support_level(Some("gfx90c"), None, VulkanStatus::Absent), + GpuSupportLevel::NoGpuBackend, + "a confirmed-absent Vulkan driver must not read as a usable Vulkan path" + ); } + /// A platform the probe cannot read is not a platform without Vulkan. + /// Withholding the only path such a host has, on the strength of a probe + /// that never ran, would be a worse answer than the assumption this change + /// replaces. #[test] - fn gpu_support_level_is_vulkan_only_for_gfx90c() { + fn gpu_support_level_keeps_vulkan_when_the_probe_could_not_run() { assert_eq!( - gpu_support_level(Some("gfx90c"), None), + gpu_support_level(Some("gfx90c"), None, VulkanStatus::Unknown), GpuSupportLevel::VulkanOnly ); } diff --git a/crates/rocm-core/src/host_gpu.rs b/crates/rocm-core/src/host_gpu.rs index 55c356e57e..40f8b574a5 100644 --- a/crates/rocm-core/src/host_gpu.rs +++ b/crates/rocm-core/src/host_gpu.rs @@ -54,6 +54,7 @@ mod gpu_visibility; pub(crate) mod linux; mod os_facts; mod render; +mod vulkan; mod windows_inventory; mod wsl; @@ -73,6 +74,11 @@ pub(crate) use linux::detect_linux_sysfs_gfx_target; pub use linux::is_amdgpu_device; #[cfg(any(target_os = "linux", test))] pub(crate) use linux::{KfdGpuNode, kfd_gpu_nodes_in}; +pub use vulkan::{ + VulkanDevice, VulkanEvidence, VulkanStatus, VulkanSupport, amd_icd_driver_label, + classify_vulkan_support, detect_vulkan_support, icd_driver_label, icd_is_gpu_driver, + parse_vulkaninfo_summary, parse_windows_vulkan_icd_listing, windows_icds_from_capture, +}; pub(crate) use windows_inventory::detect_windows_amd_driver_info; #[cfg(test)] use windows_inventory::parse_windows_examine_inventory; @@ -134,6 +140,15 @@ pub struct ExamineSummary { pub compatible_therock_family: Option, #[serde(default)] pub detected_therock_family: Option, + /// What the Vulkan probe found, when it could run. + /// + /// `#[serde(default)]` is load-bearing in the *reverse* direction: `rocm + /// remote doctor` deserializes summaries produced by other hosts, which may + /// be running a build from before this field existed. `None` means "not + /// probed", which [`ExamineSummary::vulkan_status`] maps to + /// [`VulkanStatus::Unknown`] — never to "no Vulkan". + #[serde(default)] + pub vulkan: Option, pub driver: DriverSummary, pub legacy_rocm: LegacyRocmSummary, #[serde(default)] @@ -247,17 +262,29 @@ impl ExamineSummary { Self::gather_scoped(true, Some(&examination.kernel_release)) } - /// The host summary without the Windows driver version and date, for a - /// caller that reads neither. On an AMD Windows host that skips the - /// PowerShell video-controller query `gather` adds for them; the GPU - /// target, CPU, RAM and every other field are the same. + /// The host summary without the probes that spawn a process purely to + /// describe the host, for a caller that reads none of their fields: the + /// Windows driver version and date, and the Vulkan probe. + /// + /// On an AMD Windows host that skips the PowerShell video-controller query + /// `gather` adds for the driver facts, and on every platform it skips the + /// `vulkaninfo` (or Windows registry) read behind [`vulkan`](Self::vulkan), + /// which is left `None` — "not probed", which + /// [`vulkan_status`](Self::vulkan_status) maps to [`VulkanStatus::Unknown`] + /// and never to "no Vulkan". The GPU target, CPU, RAM and every other field + /// are the same. pub fn gather_without_driver_facts() -> Result { Self::gather_scoped(false, None) } - fn gather_scoped(driver_facts: bool, examined_kernel: Option<&str>) -> Result { + /// `host_probes` buys the fields that cost a spawned process to describe + /// the host — the Windows driver facts and the Vulkan probe. It is not a + /// detail of either one: a caller that wants neither must pay for neither, + /// which is what [`gather_without_driver_facts`](Self::gather_without_driver_facts) + /// is for. + fn gather_scoped(host_probes: bool, examined_kernel: Option<&str>) -> Result { let paths = AppPaths::discover()?; - let windows_inventory = if driver_facts { + let windows_inventory = if host_probes { detect_windows_examine_inventory_with_driver_facts() } else { detect_windows_examine_inventory() @@ -295,6 +322,7 @@ impl ExamineSummary { detected_gfx_target, compatible_therock_family, detected_therock_family, + vulkan: host_probes.then(detect_vulkan_support), driver: detect_driver_summary_with_windows_inventory( windows_inventory.as_ref(), wsl.as_ref(), @@ -445,6 +473,16 @@ pub fn detect_gpu_driver_version() -> Option { None } +/// The [`DriverSummary::status`] word for a Windows host whose AMD display +/// driver was read. +/// +/// Written once because it is also a *fact about the Vulkan driver*: on Windows +/// the display driver installs the Vulkan ICD, so `render.rs` cross-checks this +/// word before advising an unconfirmed-Vulkan host to install one. Only +/// [`windows_driver_summary`] produces it, which is what makes matching on it a +/// Windows-only test. +pub(super) const AMD_DISPLAY_DRIVER_DETECTED: &str = "amd_display_driver_detected"; + fn windows_driver_summary( detail: Option, windows: Option, @@ -452,7 +490,7 @@ fn windows_driver_summary( DriverSummary { policy: "windows_validate_only".to_owned(), status: if detail.is_some() { - "amd_display_driver_detected".to_owned() + AMD_DISPLAY_DRIVER_DETECTED.to_owned() } else { "not_detected".to_owned() }, @@ -767,6 +805,7 @@ mod tests { detected_gfx_target: None, compatible_therock_family: None, detected_therock_family: None, + vulkan: None, driver: windows_driver_summary( Some("AMD Radeon(TM) Graphics driver 30.0.13014.8".to_owned()), info, @@ -842,11 +881,12 @@ mod tests { } } - /// `gather_without_driver_facts` is `gather` minus the driver version and - /// date: the GPU target a caller reads is the same, and it never carries a - /// driver record the full summary lacks. That it starts no PowerShell query - /// for them is the `the_startup_paths_do_not_start_the_driver_fact_query` - /// test, which counts the sources the same scope runs. + /// `gather_without_driver_facts` is `gather` minus the fields that cost a + /// spawned process: the GPU target a caller reads is the same, and it never + /// carries a driver record the full summary lacks. That it starts no + /// PowerShell query for them is the + /// `the_startup_paths_do_not_start_the_driver_fact_query` test, which counts + /// the sources the same scope runs. #[test] fn the_summary_without_driver_facts_keeps_the_gpu_target() { let full = ExamineSummary::gather().expect("full summary"); @@ -865,6 +905,29 @@ mod tests { ); } + /// The lean scope must not run the Vulkan probe. This is the assertion, not + /// a timing measurement: the probe spawns `vulkaninfo` on Linux and starts + /// PowerShell on Windows, and the whole point of this scope is that a caller + /// reading only the GPU target does not pay for a process it will not read. + /// + /// Restoring `vulkan: Some(detect_vulkan_support())` in `gather_scoped` + /// fails this. `None` is not a loss of information: it is the "not probed" + /// value the field documents, which `vulkan_status` reports as `Unknown` + /// rather than as an absence of Vulkan. + #[test] + fn the_summary_without_driver_facts_does_not_probe_vulkan() { + let lean = ExamineSummary::gather_without_driver_facts().expect("lean summary"); + assert_eq!( + lean.vulkan, None, + "the lean scope probed Vulkan; it must stay out of the cheap paths" + ); + assert_eq!( + lean.vulkan_status(), + VulkanStatus::Unknown, + "an unprobed host must read as Unknown, never as having no Vulkan" + ); + } + /// The runtime check stays at the call site; what it feeds is decided here, /// so it is covered on every platform. Replacing the driver info with `None` /// in this function fails this test. diff --git a/crates/rocm-core/src/host_gpu/render.rs b/crates/rocm-core/src/host_gpu/render.rs index 125c9f3846..929e2e77f6 100644 --- a/crates/rocm-core/src/host_gpu/render.rs +++ b/crates/rocm-core/src/host_gpu/render.rs @@ -6,18 +6,112 @@ use super::ExamineSummary; use super::os_facts::format_gib_value; -use crate::gfx_target::{GpuSupportLevel, VULKAN_ONLY_SUPPORT_CLAIM, gpu_support_level}; +use super::vulkan::VulkanStatus; +use crate::gfx_target::{GpuSupportLevel, gpu_support_level}; impl ExamineSummary { + /// What the Vulkan probe found, or [`VulkanStatus::Unknown`] when this + /// summary carries no probe result — an older host's JSON read back by + /// `rocm remote doctor`, or a caller that built the struct by hand. + /// + /// Public because the `rocm` binary classifies its own support level from a + /// summary it already gathered, and must read the probe result the same way + /// this module does rather than reaching into the field and inventing its + /// own `None` handling. + #[must_use] + pub fn vulkan_status(&self) -> VulkanStatus { + self.vulkan + .as_ref() + .map_or(VulkanStatus::Unknown, |vulkan| vulkan.status) + } + + /// The `vulkan` line: the status, and the evidence behind it. + fn vulkan_line(&self) -> String { + let Some(vulkan) = self.vulkan.as_ref() else { + return "".to_owned(); + }; + // `VulkanStatus::as_str`, not a second table here: this word and the + // one `--json` prints are the same status, and a local mapping lets the + // two renderings of one report drift apart silently. + let status = vulkan.status.as_str(); + vulkan.detail.as_deref().map_or_else( + || status.to_owned(), + |detail| format!("{status} ({detail})"), + ) + } + + /// Whether this summary's own evidence already contradicts "install a + /// Vulkan driver". + /// + /// `DriverSummary::status` only ever reads `AMD_DISPLAY_DRIVER_DETECTED` + /// on Windows — `windows_driver_summary` is the sole producer of that word + /// — so matching on it *is* the Windows cross-check, with no second read + /// of `os` to keep in step with it. On that platform the display driver + /// carries the Vulkan ICD, so its presence contradicts that advice: the + /// report would print `driver_status: amd_display_driver_detected` a few + /// lines above a sentence telling the reader to go and install what it + /// names. + /// + /// The cross-check is Windows-only for that reason, and not by accident: + /// Linux's `driver_status` reports the `amdgpu` kernel module, which says + /// nothing about whether a userspace ICD such as Mesa RADV is installed, + /// so suppressing the install advice there would withhold the one step + /// that can help. + /// + /// One predicate rather than a test spelled out in each arm that gives + /// install advice. Two arms now need it — `VulkanUnconfirmed` and + /// `NoGpuBackend` — and the second one shipped without it precisely + /// because the first one's check lived inside that first one's `match` + /// arm. Each arm's own test pins its half: + /// `examine_render_does_not_tell_a_windows_host_to_install_the_driver_it_has` + /// and + /// `examine_render_does_not_tell_a_no_backend_windows_host_to_install_the_driver_it_has`. + fn install_advice_is_contradicted_by_the_driver(&self) -> bool { + self.driver.status == super::AMD_DISPLAY_DRIVER_DETECTED + } + + /// What a [`GpuSupportLevel::VulkanUnconfirmed`] host is told to do next. + fn vulkan_unconfirmed_next_step(&self) -> &'static str { + if self.install_advice_is_contradicted_by_the_driver() { + crate::gfx_target::VULKAN_UNCONFIRMED_NEXT_STEP_WITH_DISPLAY_DRIVER + } else { + crate::gfx_target::VULKAN_UNCONFIRMED_NEXT_STEP + } + } + + /// What a [`GpuSupportLevel::NoGpuBackend`] host is told to do next. + /// + /// The unconditional branch is the whole story on a host with nothing + /// installed: both halves of the level are established facts, there is + /// nothing left to go and find out, and installing a driver is the one + /// thing that can clear it. + /// + /// The other branch is a Windows host that already has the driver that + /// sentence names. Its probe answered — `VulkanStatus::Absent` is never + /// reached without `vulkaninfo`'s answer behind it — so "run `vulkaninfo`" + /// is not left either, the way it is under `VulkanUnconfirmed`. What is + /// left is the display driver itself: it is installed and is exposing no + /// Vulkan GPU device here, which a repair or update of that driver can + /// change and a fresh install cannot. + fn no_gpu_backend_next_step(&self) -> &'static str { + if self.install_advice_is_contradicted_by_the_driver() { + "the AMD display driver is installed (see `driver_status`) but is exposing no Vulkan \ + GPU device here, so repairing or updating it is the step that could open one" + } else { + "install one (Mesa RADV on Linux, the AMD display driver on Windows) to run models on \ + this GPU" + } + } + /// The `rocm_support` line of the examine text. /// /// ROCMAI-550 asks `rocm examine` to "report the support level with one /// line of what the user can do", so every level gets a line — including - /// the ones where the answer is "this build cannot tell". The earlier draft - /// printed only the `VulkanOnly` line, which made this report unable to - /// answer the very question the other surfaces send people here to ask: - /// `lemonade_engine_note` in `apps/rocm/src/main.rs` tells an `Unknown` - /// host to run `rocm examine`, and silence there is not an answer. + /// the ones where the answer is "this build cannot tell". Printing only the + /// `VulkanOnly` line leaves this report unable to answer the very question + /// the other surfaces send people here to ask: `lemonade_engine_note` in + /// `apps/rocm/src/main.rs` tells an `Unknown` host to run `rocm examine`, + /// and silence there is not an answer. /// /// Without the `VulkanOnly` line specifically, /// `compatible_therock_family: ` reads like a probe failure when @@ -34,14 +128,95 @@ impl ExamineSummary { /// blank line. fn rocm_support_line(&self) -> String { let detected = self.detected_gfx_target.as_deref(); - match gpu_support_level(detected, self.compatible_therock_family.as_deref()) { + let vulkan = self.vulkan_status(); + match gpu_support_level(detected, self.compatible_therock_family.as_deref(), vulkan) { // `VulkanOnly` is only ever returned for a detected target, so the // fallback below is unreachable; it keeps the arm total without a // panic path. + // + // The claim is graded by what the probe actually established. An + // enumerated device is named, because naming it is what lets the + // reader check the claim rather than take it; an installed-but- + // unenumerated driver says so instead of borrowing the stronger + // sentence; and a platform that could not be probed admits it. All + // three still point at the same command, because all three are + // hosts worth trying. GpuSupportLevel::VulkanOnly => format!( - " rocm_support: GPU detected ({}) but {VULKAN_ONLY_SUPPORT_CLAIM} - \ - serve on it with `rocm serve --engine lemonade`\n", - detected.unwrap_or_default() + " rocm_support: GPU detected ({}) but not supported by ROCm; {} - serve on it \ + with `rocm serve --engine lemonade`\n", + detected.unwrap_or_default(), + match vulkan { + VulkanStatus::Available => self.vulkan.as_ref().map_or_else( + || "the Vulkan backend can be used".to_owned(), + |support| support.driver_label().map_or_else( + || "the Vulkan backend can be used".to_owned(), + |driver| format!("the Vulkan backend can be used ({driver})"), + ), + ), + VulkanStatus::DriverPresentDevicesUnverified => + "a Vulkan driver is installed, so the Vulkan backend is expected to work" + .to_owned(), + VulkanStatus::Unknown => + "Vulkan was not probed on this platform, so the Vulkan backend is \ + unconfirmed" + .to_owned(), + // Unreachable: `gpu_support_level` routes `Inconclusive` to + // `VulkanUnconfirmed` and `Absent` to `NoGpuBackend`, so + // neither can arrive under `VulkanOnly`. Kept spelled out + // rather than folded into a `_` so that adding a + // `VulkanStatus` stays a compile error here, and worded + // hedged rather than promising so that a future routing + // change cannot silently resurrect the claim this level + // exists to stop making. + VulkanStatus::Inconclusive | VulkanStatus::Absent => + "the Vulkan backend is unconfirmed".to_owned(), + } + ), + // Looked at and nothing settled either way. Says the probe could + // not determine it and how to settle it, rather than promising a + // backend or declaring one absent — neither of which the evidence + // supports. See `GpuSupportLevel::VulkanUnconfirmed`. + // + // The claim comes from `VULKAN_UNCONFIRMED_CLAIM` because + // `lemonade_engine_note` renders the same level a few lines further + // down the same report; one constant is what keeps the two from + // contradicting each other. + // + // The next step is cross-checked against `driver.status`, the one + // other fact on this summary that bears on it. On Windows the AMD + // display driver *is* the Vulkan driver, so a host that already has + // it must not be told to install one — the exact misdirection this + // level exists to avoid, reached through its own advice. The + // cross-check is Windows-only: Linux's `driver_status` reports the + // `amdgpu` kernel module, which says nothing about whether a + // userspace ICD is installed. + GpuSupportLevel::VulkanUnconfirmed => format!( + " rocm_support: GPU detected ({}) but not supported by ROCm; {} - {}\n", + detected.unwrap_or_default(), + crate::gfx_target::VULKAN_UNCONFIRMED_CLAIM, + self.vulkan_unconfirmed_next_step(), + ), + // Both halves are established facts: the catalog confirmed there is + // no ROCm build, and the probe looked for a Vulkan driver and found + // none. Unlike `VulkanUnconfirmed` above, there is nothing left to + // go and find out on this host. Only `Absent` reaches this level — + // `gpu_support_level` routes the probed-but-inconclusive host to + // `VulkanUnconfirmed` precisely so that this sentence is never said + // to one. + // + // The next step is cross-checked against `driver.status` for the + // same reason `VulkanUnconfirmed`'s is, and through the same + // predicate: a Windows host whose report already says + // `driver_status: amd_display_driver_detected` must not be told, a + // few lines below, to install the driver it is showing. The + // confirmed absence itself is unaffected — the probe did look and + // did find no Vulkan GPU device — only what the host can do about + // it differs. + GpuSupportLevel::NoGpuBackend => format!( + " rocm_support: GPU detected ({}) but not supported by ROCm, and no Vulkan GPU \ + driver was found - {}\n", + detected.unwrap_or_default(), + self.no_gpu_backend_next_step(), ), // The covering family is the fact; it is already printed on its own // line above, so this one says what it means rather than repeating @@ -201,7 +376,7 @@ impl ExamineSummary { "false (this run's output is captured, so the CLI will not prompt)" }; format!( - "rocm examine\n os: {}\n arch: {}\n kernel: {}\n distro: {}\n cpu: {}\n system_ram: {}\n interactive_terminal: {}\n default_engine: {}\n detected_gfx_target: {}\n compatible_therock_family: {}\n{} detected_therock_family: {}\n driver_policy: {}\n driver_status: {}\n driver_detail: {}\n{} legacy_rocm_status: {}\n legacy_rocm_paths: {}\n legacy_rocm_version: {}\n legacy_rocm_detail: {}\n legacy_rocm_guidance: {}\n wsl: {}\n wsl_dxg_device: {}\n wsl_dxcore: {}\n wsl_librocdxg: {}\n wsl_rocdxg_dids: {}\n wsl_ldconfig_librocdxg: {}\n wsl_librocdxg_on_ld_library_path: {}\n wsl_librocdxg_beside_runtime: {}\n wsl_global_rocminfo: {}\n wsl_cargo: {}\n wsl_detail: {}\n{} managed_runtimes: {}\n managed_services: {}\n model_cache_entries: {}\n config_dir: {}\n data_dir: {}\n cache_dir: {}\n", + "rocm examine\n os: {}\n arch: {}\n kernel: {}\n distro: {}\n cpu: {}\n system_ram: {}\n interactive_terminal: {}\n default_engine: {}\n detected_gfx_target: {}\n compatible_therock_family: {}\n{} detected_therock_family: {}\n vulkan: {}\n driver_policy: {}\n driver_status: {}\n driver_detail: {}\n{} legacy_rocm_status: {}\n legacy_rocm_paths: {}\n legacy_rocm_version: {}\n legacy_rocm_detail: {}\n legacy_rocm_guidance: {}\n wsl: {}\n wsl_dxg_device: {}\n wsl_dxcore: {}\n wsl_librocdxg: {}\n wsl_rocdxg_dids: {}\n wsl_ldconfig_librocdxg: {}\n wsl_librocdxg_on_ld_library_path: {}\n wsl_librocdxg_beside_runtime: {}\n wsl_global_rocminfo: {}\n wsl_cargo: {}\n wsl_detail: {}\n{} managed_runtimes: {}\n managed_services: {}\n model_cache_entries: {}\n config_dir: {}\n data_dir: {}\n cache_dir: {}\n", self.os, self.arch, self.kernel.as_deref().unwrap_or(""), @@ -219,6 +394,7 @@ impl ExamineSummary { self.detected_therock_family .as_deref() .unwrap_or(""), + self.vulkan_line(), self.driver.policy, self.driver.status, self.driver.detail.as_deref().unwrap_or(""), @@ -282,8 +458,8 @@ mod tests { use super::*; use crate::LegacyRocmSummary; use crate::gfx_target::normalize_therock_family; - use crate::host_gpu::DriverSummary; use crate::host_gpu::tests::windows_summary_with_driver; + use crate::host_gpu::{DriverSummary, VulkanDevice, VulkanSupport}; use std::path::PathBuf; #[test] @@ -300,6 +476,7 @@ mod tests { detected_gfx_target: None, compatible_therock_family: Some("gfx120X-all".to_owned()), detected_therock_family: None, + vulkan: None, driver: DriverSummary { policy: "windows_validate_only".to_owned(), status: "amd_display_driver_detected".to_owned(), @@ -380,6 +557,7 @@ mod tests { detected_gfx_target: detected_gfx_target.map(str::to_owned), compatible_therock_family: compatible_therock_family.map(str::to_owned), detected_therock_family: None, + vulkan: None, driver: DriverSummary { policy: "windows_validate_only".to_owned(), status: "amd_display_driver_detected".to_owned(), @@ -403,12 +581,41 @@ mod tests { } } + /// A gfx90c summary carrying the given Vulkan evidence. + /// + /// gfx90c is detected from its PCI ID but has no ROCm package family, so it + /// is the target that reaches the Vulkan-graded arms at all. + fn gfx90c_summary_with_vulkan(vulkan: Option) -> ExamineSummary { + let family = normalize_therock_family("gfx90c"); + let mut summary = examine_summary_with_gpu(Some("gfx90c"), family.as_deref()); + summary.vulkan = vulkan; + summary + } + + fn vulkan_support(status: VulkanStatus, detail: &str) -> Option { + Some(VulkanSupport { + status, + detail: Some(detail.to_owned()), + devices: vec![VulkanDevice { + name: "AMD Radeon Graphics (RADV RENOIR)".to_owned(), + driver_name: Some("radv".to_owned()), + vendor_id: Some("0x1002".to_owned()), + device_type: Some("PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU".to_owned()), + ..VulkanDevice::default() + }], + ..VulkanSupport::default() + }) + } + #[test] fn examine_render_says_a_gpu_without_a_rocm_family_is_unsupported() { - // gfx90c is detected from its PCI ID but has no ROCm package family. - let family = normalize_therock_family("gfx90c"); - let summary = examine_summary_with_gpu(Some("gfx90c"), family.as_deref()); + let summary = gfx90c_summary_with_vulkan(vulkan_support( + VulkanStatus::Available, + "AMD Radeon Graphics (RADV RENOIR) through radv", + )); + let rendered = summary.render_text(); + assert!( rendered.contains("detected_gfx_target: gfx90c"), "{rendered}" @@ -418,15 +625,19 @@ mod tests { "{rendered}" ); assert!( - rendered.contains("the Vulkan backend can still be used"), - "{rendered}" + rendered.contains("the Vulkan backend can be used (radv)"), + "a confirmed device must be named, so the claim can be checked: {rendered}" + ); + assert!( + rendered.contains("vulkan: available"), + "the evidence line must carry the verdict too: {rendered}" ); // AGENTS.md §3: advice naming a command is asserted together with the - // behaviour. Saying the Vulkan backend "can still be used" without - // naming how to use it leaves the user where they started, so the - // command is part of the claim, not decoration — without this - // assertion the recommendation could be deleted or garbled and this - // test would still pass. + // behaviour. Saying the Vulkan backend "can be used" without naming + // how to use it leaves the user where they started, so the command is + // part of the claim, not decoration — without this assertion the + // recommendation could be deleted or garbled and this test would still + // pass. // // That the named command *parses* (the subcommand exists and accepts // `--engine lemonade`) is proved mechanically rather than here: @@ -441,16 +652,314 @@ mod tests { ); } + /// The defect this guards against: promising "the Vulkan backend can still + /// be used" on every gfx90c host, from the gfx table alone. That sends a + /// Renoir laptop with no Vulkan driver installed to serve a model on a + /// backend that cannot start — and under the GPU-required policy there is + /// nothing for it to fall back to. + #[test] + fn examine_render_does_not_promise_vulkan_on_a_host_that_has_none() { + let mut summary = gfx90c_summary_with_vulkan(Some(VulkanSupport { + status: VulkanStatus::Absent, + detail: Some("no Vulkan driver found".to_owned()), + ..VulkanSupport::default() + })); + // The shared fixture is a Windows host carrying + // `AMD_DISPLAY_DRIVER_DETECTED`, which is the one state where "install + // one" is the wrong advice (see + // `examine_render_does_not_tell_a_no_backend_windows_host_to_install_the_driver_it_has`). + // This test is about the host that genuinely has nothing, so it plants + // that host rather than asserting the install sentence on a summary + // whose own `driver_status` line contradicts it. + summary.os = "linux".to_owned(); + summary.driver = DriverSummary { + policy: "amdgpu_dkms".to_owned(), + status: "amdgpu_module_loaded".to_owned(), + detail: None, + windows: None, + }; + + let rendered = summary.render_text(); + + assert!( + !rendered.contains("the Vulkan backend can be used"), + "a host with no Vulkan driver must not be promised one: {rendered}" + ); + assert!( + rendered.contains("no Vulkan GPU driver was found"), + "{rendered}" + ); + assert!( + rendered.contains("install one"), + "the advice must be able to clear the condition it is printed for: {rendered}" + ); + assert!(rendered.contains("vulkan: absent"), "{rendered}"); + } + + /// An installed driver that enumerated no device is a weaker claim than a + /// device that answered, and says so rather than borrowing the stronger + /// sentence. + #[test] + fn examine_render_separates_an_installed_driver_from_a_confirmed_device() { + let summary = gfx90c_summary_with_vulkan(Some(VulkanSupport { + status: VulkanStatus::DriverPresentDevicesUnverified, + detail: Some("Mesa RADV is installed, but no device was enumerated".to_owned()), + ..VulkanSupport::default() + })); + + let rendered = summary.render_text(); + + assert!( + rendered.contains("a Vulkan driver is installed, so the Vulkan backend is expected"), + "{rendered}" + ); + assert!( + rendered.contains("vulkan: driver_present_devices_unverified"), + "{rendered}" + ); + } + + /// A summary with no probe result at all — an older host's JSON read back + /// through `rocm remote doctor` — must not read as "no Vulkan". It keeps + /// the Vulkan advice, because withholding the only path such a host has on + /// the strength of a probe that never ran would be worse than the + /// assumption this change replaces. + #[test] + fn examine_render_treats_an_unprobed_summary_as_unconfirmed_not_absent() { + let summary = gfx90c_summary_with_vulkan(None); + + let rendered = summary.render_text(); + + assert!(rendered.contains("vulkan: "), "{rendered}"); + assert!( + rendered.contains("the Vulkan backend is unconfirmed"), + "{rendered}" + ); + assert!( + !rendered.contains("no Vulkan GPU driver was found"), + "an unprobed host is not a host without Vulkan: {rendered}" + ); + assert!( + rendered.contains("rocm serve --engine lemonade"), + "it is still worth trying, so the command stays: {rendered}" + ); + } + + /// The motivating case, and the one nothing rendered: a host that **was** + /// probed and showed nothing either way — no ICD, no enumerated device, and + /// no `vulkaninfo` to ask. On Windows the Khronos `Drivers` key is legacy + /// and `vulkaninfo` is rarely on PATH, so a working Adrenalin laptop (the + /// machine ROCMAI-550 was reported from) lands here. + /// + /// `gfx_target.rs` pins that the classifier turns this into + /// `VulkanUnconfirmed`; this pins what the user actually reads, which is the + /// half that can go wrong on its own. Both directions are asserted: it must + /// not promise a backend, and it must not declare one absent either. + #[test] + fn examine_render_hedges_a_host_that_was_probed_and_showed_nothing() { + // Built directly rather than through `vulkan_support`, which plants an + // AMD device: an enumerated device is the one thing this state cannot + // have, and a fixture that contradicts its own status proves nothing. + let summary = gfx90c_summary_with_vulkan(Some(VulkanSupport { + status: VulkanStatus::Inconclusive, + detail: Some( + "no installed Vulkan driver was listed, and `vulkaninfo` could not confirm \ + anything either (not installed, or it failed to run), so nothing here shows \ + whether a driver is present" + .to_owned(), + ), + ..VulkanSupport::default() + })); + + let rendered = summary.render_text(); + + assert!( + rendered.contains(crate::gfx_target::VULKAN_UNCONFIRMED_CLAIM), + "it must say the probe could not settle it: {rendered}" + ); + assert!( + !rendered.contains("the Vulkan backend can be used"), + "nothing here established a Vulkan path: {rendered}" + ); + assert!( + !rendered.contains("and no Vulkan GPU driver was found - install one"), + "and nothing established its absence either, so the confirmed-absence \ + sentence must not be used: {rendered}" + ); + assert!(rendered.contains("vulkan: inconclusive"), "{rendered}"); + } + + /// The Windows machine this level exists for: the Khronos `Drivers` key it + /// reads is legacy and `vulkaninfo` is rarely on PATH, so an **Adrenalin + /// laptop with a working Vulkan driver** lands in `VulkanUnconfirmed`. + /// Telling it to install the AMD display driver is advice it has already + /// taken, and nothing it does can clear the state. + /// + /// `driver_status` is the summary's own evidence against that advice, and + /// on Windows the display driver carries the Vulkan ICD, so its presence is + /// decisive. The line must say so instead, and still name the one step that + /// can settle the question. + #[test] + fn examine_render_does_not_tell_a_windows_host_to_install_the_driver_it_has() { + let mut summary = gfx90c_summary_with_vulkan(Some(VulkanSupport { + status: VulkanStatus::Inconclusive, + detail: Some("the legacy Khronos key listed nothing".to_owned()), + ..VulkanSupport::default() + })); + summary.os = "windows".to_owned(); + summary.driver = DriverSummary { + policy: "windows_validate_only".to_owned(), + status: super::super::AMD_DISPLAY_DRIVER_DETECTED.to_owned(), + detail: Some("AMD display driver 31.0.21925.1001".to_owned()), + windows: None, + }; + + let rendered = summary.render_text(); + let support = rendered + .lines() + .find(|line| line.contains("rocm_support:")) + .expect("every host gets a support line"); + + assert!( + !support.contains("install a Vulkan driver"), + "this host already has the driver that would be installed: {support}" + ); + assert!( + support.contains("the AMD display driver is installed"), + "and it is owed the reason that advice does not apply: {support}" + ); + assert!( + support.contains("run `vulkaninfo`"), + "the one step that can still settle it must stay: {support}" + ); + assert!( + support.contains(crate::gfx_target::VULKAN_UNCONFIRMED_CLAIM), + "the claim is the same on both platforms; only the next step differs: {support}" + ); + + // The Linux shape of the same status, which is what makes the two halves + // a discrimination rather than one assertion twice. `driver` has to be + // overwritten explicitly: the shared fixture is a Windows host and + // already carries `AMD_DISPLAY_DRIVER_DETECTED`, so reusing it unchanged + // would re-enter the branch above and assert nothing about Linux. + // + // There `driver_status` reports the `amdgpu` kernel module, which says + // nothing about whether a userspace ICD such as Mesa RADV is installed, + // so the install advice is the true one and must survive. + let mut linux = gfx90c_summary_with_vulkan(Some(VulkanSupport { + status: VulkanStatus::Inconclusive, + detail: Some("no ICD manifest was found".to_owned()), + ..VulkanSupport::default() + })); + linux.os = "linux".to_owned(); + linux.driver = DriverSummary { + policy: "amdgpu_dkms".to_owned(), + status: "amdgpu_module_loaded".to_owned(), + detail: None, + windows: None, + }; + let linux = linux.render_text(); + assert!( + linux.contains(crate::gfx_target::VULKAN_UNCONFIRMED_NEXT_STEP), + "a host with no display-driver evidence still gets the install step: {linux}" + ); + assert!( + !linux.contains("the AMD display driver is installed"), + "and must not be told about a Windows driver it cannot have: {linux}" + ); + } + + /// The same misdirection one level down, and the one the + /// `VulkanUnconfirmed` cross-check above did not stop: a Windows host whose + /// report prints `driver_status: amd_display_driver_detected` must not be + /// told, a few lines higher in the same output, to install the AMD display + /// driver. + /// + /// `NoGpuBackend` keeps the confirmed absence — the probe did look and did + /// find no Vulkan GPU device, and that is not in question here — but the + /// *advice* has to be one the host can act on, and "install the driver you + /// are already showing" is not. `vulkaninfo` is not offered as the next + /// step either, unlike under `VulkanUnconfirmed`: reaching `Absent` takes + /// `vulkaninfo`'s own answer, so that question is already settled. + /// + /// Both directions are asserted, against the two hosts that differ only in + /// `driver_status`, so an arm that dropped the cross-check again fails here + /// rather than passing on the Linux half alone. + #[test] + fn examine_render_does_not_tell_a_no_backend_windows_host_to_install_the_driver_it_has() { + let absent = || { + Some(VulkanSupport { + status: VulkanStatus::Absent, + detail: Some("no Vulkan driver found".to_owned()), + ..VulkanSupport::default() + }) + }; + // The shared fixture is already a Windows host carrying + // `AMD_DISPLAY_DRIVER_DETECTED` — the exact summary this arm shipped + // being rendered against, and the reason the omission was invisible. + let windows = gfx90c_summary_with_vulkan(absent()); + assert_eq!( + windows.driver.status, + super::super::AMD_DISPLAY_DRIVER_DETECTED, + "this test is only a discrimination while the fixture it reuses is the \ + display-driver host" + ); + let windows = windows.render_text(); + let support = windows + .lines() + .find(|line| line.contains("rocm_support:")) + .expect("every host gets a support line"); + + assert!( + windows.contains("driver_status: amd_display_driver_detected"), + "the contradiction this guards against is between two lines of one report: {windows}" + ); + assert!( + !support.contains("install one"), + "this host already has the driver that sentence names: {support}" + ); + assert!( + support.contains("repairing or updating it"), + "and it is owed the step that can actually open a GPU path: {support}" + ); + assert!( + support.contains("no Vulkan GPU driver was found"), + "the confirmed absence itself is unchanged; only the advice is: {support}" + ); + assert!( + !support.contains("run `vulkaninfo`"), + "`Absent` already has `vulkaninfo`'s answer behind it, so there is nothing \ + left to ask it: {support}" + ); + + // The Linux shape of the same status: `driver_status` there reports the + // `amdgpu` kernel module, which says nothing about a userspace ICD, so + // the install advice is true and must survive. + let mut linux = gfx90c_summary_with_vulkan(absent()); + linux.os = "linux".to_owned(); + linux.driver = DriverSummary { + policy: "amdgpu_dkms".to_owned(), + status: "amdgpu_module_loaded".to_owned(), + detail: None, + windows: None, + }; + let linux = linux.render_text(); + assert!( + linux.contains("install one (Mesa RADV on Linux, the AMD display driver on Windows)"), + "a host with no display-driver evidence still gets the install step: {linux}" + ); + assert!( + !linux.contains("repairing or updating it"), + "and must not be told about a Windows driver it cannot have: {linux}" + ); + } + /// An unmapped target must not be *claimed* unsupported, even though every /// host now gets a `rocm_support` line. /// - /// This replaces `examine_render_omits_the_support_note_for_supported_or_missing_gpus`, - /// which asserted the line was absent for supported, missing and unmapped - /// GPUs. ROCMAI-550 deliberately reverses the absence: silence could not - /// answer the question `lemonade_engine_note` sends users here to ask. The - /// half of that test worth keeping is the discrimination it protected — - /// "no ROCm build" is a fact about gfx90c, and a gap in this catalog is not - /// the same claim about gfx803. + /// Every host gets the line, so what this protects is the discrimination + /// rather than the silence: "no ROCm build" is a fact about gfx90c, and a + /// gap in this catalog is not the same claim about gfx803. #[test] fn examine_render_never_claims_an_unmapped_target_is_unsupported() { for (gfx, family) in [ @@ -594,6 +1103,7 @@ mod tests { detected_gfx_target: None, compatible_therock_family: None, detected_therock_family: None, + vulkan: None, driver: DriverSummary { policy: "linux_official_amd_dkms_wrapper".to_owned(), status: "amdgpu_available".to_owned(), @@ -649,6 +1159,7 @@ mod tests { detected_gfx_target: None, compatible_therock_family: None, detected_therock_family: None, + vulkan: None, driver: DriverSummary { policy: "linux_official_amd_dkms_wrapper".to_owned(), status: "amdgpu_available".to_owned(), @@ -749,7 +1260,7 @@ mod tests { .find(|l| l.trim_start().starts_with("rocm_support:")) .expect("every host gets a support line"); assert_eq!( - gpu_support_level(None, None), + gpu_support_level(None, None, VulkanStatus::Unknown), GpuSupportLevel::Unknown, "precondition: nothing detected is the Unknown tier" ); diff --git a/crates/rocm-core/src/host_gpu/vulkan.rs b/crates/rocm-core/src/host_gpu/vulkan.rs new file mode 100644 index 0000000000..08c40dd5d1 --- /dev/null +++ b/crates/rocm-core/src/host_gpu/vulkan.rs @@ -0,0 +1,1832 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Whether this host can run a model through Vulkan. +//! +//! The CLI has always *asserted* this for a GPU with no ROCm build -- `examine` +//! told a gfx90c user "the Vulkan backend can still be used" without ever +//! looking. This probe is what makes that sentence evidence rather than a +//! promise, and it is what lets a host outside the ROCm compatibility matrix be +//! described by what it can do instead of only by what it cannot. +//! +//! Two sources, in increasing order of strength: +//! +//! 1. An **installable driver**: an ICD manifest on Linux (`/usr/share/vulkan/ +//! icd.d` and friends), or the Khronos registry key on Windows. This proves a +//! driver is *installed*, not that a device enumerates. +//! 2. An **enumerated device**: `vulkaninfo --summary`, when it is on PATH. +//! This proves a device actually answers. +//! +//! The two are kept apart by [`VulkanStatus`] rather than collapsed, because +//! collapsing them would replace one unverified promise with another. +//! +//! **A software rasteriser is not a GPU.** Mesa's lavapipe (`lvp_icd.*.json`, +//! `PHYSICAL_DEVICE_TYPE_CPU`) presents a complete Vulkan implementation that +//! runs entirely on the CPU. Counting it here would route a user onto CPU +//! execution while reporting a GPU path -- precisely the silent CPU fallback +//! `AGENTS.md` §6 forbids -- so it is recognised in order to be excluded, and +//! named in `detail` so the exclusion is visible rather than mysterious. + +use super::capture::capture_optional_command; +#[cfg(target_os = "linux")] +use crate::host_path; +use serde::{Deserialize, Serialize}; + +/// The directories a Linux Vulkan loader reads ICD manifests from. +/// +/// Read through [`host_path`] so a simulated host root can plant them, which is +/// what lets the no-GPU CI lane cover this probe at all. +#[cfg(target_os = "linux")] +const LINUX_ICD_DIRS: [&str; 4] = [ + "/usr/share/vulkan/icd.d", + "/usr/local/share/vulkan/icd.d", + "/etc/vulkan/icd.d", + "/usr/lib/x86_64-linux-gnu/vulkan/icd.d", +]; + +/// How sure the CLI is that a model can run through Vulkan here. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum VulkanStatus { + /// A Vulkan device answered and it is a real GPU. + Available, + /// A driver is installed, but no AMD device was confirmed behind it. + /// Likely to work; not established. + /// + /// Three hosts land here and they are not owed the same sentence, which is + /// why `classify_vulkan_support` builds the detail from `devices` and + /// `enumerated` rather than from the status alone: `vulkaninfo` was not on + /// PATH to ask; it ran and listed nothing; or it ran and listed only + /// non-AMD hardware. + DriverPresentDevicesUnverified, + /// The probe looked and found no GPU Vulkan driver. A software rasteriser + /// alone lands here, not in [`Self::Available`]. + /// + /// `vulkaninfo` must have *answered* on every path that reaches this + /// status, and `absent_always_has_vulkaninfos_answer_behind_it` holds that + /// against every combination of evidence. It is the only source strong + /// enough to rule a GPU path out on its own: neither the Linux ICD + /// directory list nor the Windows Khronos key is exhaustive, so "no GPU + /// manifest was listed" never denies a driver by itself. Where nothing at + /// all was found, the ICD listing must have answered too, because an empty + /// `icds` is also what a PowerShell read that failed or timed out produces. + /// + /// In practice that means a `vulkaninfo` that exits 0 having listed no + /// device, or one that listed only software devices with no GPU manifest + /// beside them. A real driverless Linux host does not take this path: there + /// `vulkaninfo` fails to create an instance and exits non-zero, which + /// [`vulkan_devices_from_capture`] reads as a source that did not answer, + /// landing such a host in [`Self::Inconclusive`]. That is deliberate — see + /// [`vulkan_devices_from_capture`] for why a failing probe must not be + /// promoted to a confirmed absence — but it does make confirmed absence + /// narrower than "no driver is installed", and it is why the scenario + /// covering this status plants the exit-0 shape rather than reproducing a + /// driverless host. + Absent, + /// The probe came away with nothing either way: no ICD manifest *that + /// names a GPU driver*, no enumerated device, and at least one of the two + /// sources that never answered — `vulkaninfo` missing or failing, or (on + /// Windows) a registry listing that could not be run. + /// + /// `icds` is therefore not necessarily empty here, and the first clause is + /// written that way deliberately. A host whose only manifest is a software + /// rasteriser — `lvp_icd.x86_64.json` and nothing else — has found no GPU + /// driver, but it has not *ruled one out* either: the ICD search is not + /// exhaustive (a fixed directory list on Linux that ignores + /// `VK_ICD_FILENAMES`/`VK_DRIVER_FILES`, the legacy Khronos key alone on + /// Windows), so "lavapipe is the only manifest I can see" leaves a GPU + /// driver this probe never reads perfectly possible. Without `vulkaninfo`'s + /// answer behind it that host lands here rather than in [`Self::Absent`], + /// which is what + /// `a_lavapipe_only_install_is_not_a_confirmed_absence_until_vulkaninfo_answers` + /// holds. + /// + /// Distinct from [`Self::Unknown`], which is a platform that cannot be + /// probed at all. The difference decides what the host is told: an + /// unprobed platform keeps the benefit of the doubt, while this one has + /// been looked at and nothing was found, so it must not be promised a + /// Vulkan path — but neither may it be told a driver is definitely absent, + /// since the sources that came back empty are not exhaustive. + Inconclusive, + /// The probe could not look (an unsupported platform). + /// + /// The default: a value nobody has filled in is one nobody has probed, and + /// defaulting to `Absent` would let an unset field read as a fact about the + /// machine. + #[default] + Unknown, +} + +impl VulkanStatus { + /// The one spelling of this status, shared by the `vulkan:` text line and + /// the `--json` document. + /// + /// Byte-identical to what `#[serde(rename_all = "snake_case")]` writes, so + /// the two forms of the same report cannot disagree about what the probe + /// found; `the_status_word_is_the_one_serde_writes` holds that. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Available => "available", + Self::DriverPresentDevicesUnverified => "driver_present_devices_unverified", + Self::Absent => "absent", + Self::Inconclusive => "inconclusive", + Self::Unknown => "unknown", + } + } +} + +/// What one evidence source came back with: whether the lookup **answered**, +/// and what it found. +/// +/// The classification turns on the first half, so the two halves travel +/// together and an empty `Vec` can never be read as an answer by accident. The +/// two sources are different instantiations — `VulkanEvidence` for ICD +/// manifests, `VulkanEvidence` for enumerated devices — so +/// handing [`classify_vulkan_support`] one in the other's place is a type error +/// rather than a silent flip between `Inconclusive` and `Absent`. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct VulkanEvidence { + found: Vec, + answered: bool, +} + +impl VulkanEvidence { + /// The lookup ran and this is what it saw. An empty list from here is a + /// real "nothing is installed", which is the only thing that can earn + /// [`VulkanStatus::Absent`]. + #[must_use] + pub const fn answered(found: Vec) -> Self { + Self { + found, + answered: true, + } + } + + /// The lookup did not answer — the tool is missing, exited non-zero, timed + /// out, or this platform has nothing to read. Nothing it "found" could be + /// evidence, so it carries no findings at all. + #[must_use] + pub const fn unanswered() -> Self { + Self { + found: Vec::new(), + answered: false, + } + } + + /// Whether this source answered at all, as opposed to finding nothing. + #[must_use] + pub const fn did_answer(&self) -> bool { + self.answered + } + + #[must_use] + pub fn found(&self) -> &[T] { + &self.found + } + + /// The findings, for a caller that is done asking whether they are + /// evidence. + #[must_use] + pub fn into_found(self) -> Vec { + self.found + } +} + +impl Default for VulkanEvidence { + /// An unfilled source is one nobody asked, for the same reason + /// [`VulkanStatus`] defaults to `Unknown`. + fn default() -> Self { + Self::unanswered() + } +} + +/// One physical device as `vulkaninfo --summary` reported it. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct VulkanDevice { + pub name: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub driver_name: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub driver_id: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub api_version: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub vendor_id: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub device_id: Option, + /// The raw `deviceType`, e.g. `PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU`. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub device_type: Option, +} + +impl VulkanDevice { + /// AMD's PCI vendor id, as `vulkaninfo` prints it. + const AMD_VENDOR_ID: &'static str = "0x1002"; + + #[must_use] + pub fn is_amd(&self) -> bool { + self.vendor_id + .as_deref() + .is_some_and(|id| id.eq_ignore_ascii_case(Self::AMD_VENDOR_ID)) + } + + /// Whether this device is real hardware rather than a software rasteriser. + /// + /// A missing `deviceType` reads as hardware: the field is optional in the + /// summary output, and treating an unreported type as CPU would discard a + /// working GPU. Lavapipe always reports its type, so the only entries this + /// lets through unverified are ones that named no type at all. + #[must_use] + pub fn is_hardware(&self) -> bool { + !self + .device_type + .as_deref() + .is_some_and(|kind| kind.to_ascii_uppercase().contains("TYPE_CPU")) + } +} + +/// What the host offers for Vulkan, and the evidence behind it. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct VulkanSupport { + pub status: VulkanStatus, + /// The ICD manifests or registry entries found, as the loader names them. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub icds: Vec, + /// The devices `vulkaninfo` enumerated, when it was available. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub devices: Vec, + /// A one-line human summary, including why anything was excluded. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub detail: Option, +} + +impl VulkanSupport { + /// The driver this host would use, for the `examine` line. + /// + /// Prefers what a device actually reported (`AMD proprietary driver`, + /// `radv`) over what an ICD filename implies, because the filename is a + /// guess about a vendor and the device's own `driverName` is not. + #[must_use] + pub fn driver_label(&self) -> Option { + self.devices + .iter() + .find(|device| device.is_amd() && device.is_hardware()) + .and_then(|device| device.driver_name.clone()) + .or_else(|| { + // Restricted to AMD-branded manifests, because whatever this + // fallback names is read as the driver behind an AMD Vulkan + // path. It runs whenever no AMD hardware device supplied a + // `driverName` of its own — either because none was confirmed + // at all, or because the one that was confirmed went unnamed — + // so the manifest it picks must not be allowed to attribute + // that path to another vendor. "Not a known software + // rasteriser" is too weak a + // filter for that job — `detect_icds` sorts alphabetically on + // Linux, so on a dual-vendor host carrying both + // `nvidia_icd.json` and `radeon_icd.x86_64.json` the NVIDIA + // manifest wins the `find_map`, and a confirmed AMD Vulkan path + // is attributed to NVIDIA's driver. + // + // Narrowing to AMD subsumes that weaker filter's + // software-rasteriser exclusion (lavapipe and SwiftShader are + // not AMD labels), so "a software rasteriser never counts as a + // GPU path" still holds in the one place the user actually + // reads a driver name. + self.icds + .iter() + .find_map(|icd| amd_icd_driver_label(icd)) + .map(str::to_owned) + }) + } +} + +/// The driver an ICD manifest's file name implies, or `None` when the name is +/// not one this table knows. +/// +/// Deliberately includes the software rasterisers so a caller can *exclude* +/// them by name; [`icd_is_gpu_driver`] is the predicate that does so. +#[must_use] +pub fn icd_driver_label(icd: &str) -> Option<&'static str> { + let name = icd + .rsplit(['/', '\\']) + .next() + .unwrap_or(icd) + .to_ascii_lowercase(); + if name.starts_with("radeon_icd") { + return Some("Mesa RADV"); + } + if name.starts_with("amd_icd") || name.starts_with("amdvlk") { + return Some("AMDVLK"); + } + if name.starts_with("lvp_icd") { + return Some("Mesa lavapipe (software)"); + } + if name.starts_with("vk_swiftshader") { + return Some("SwiftShader (software)"); + } + if name.starts_with("nvidia_icd") { + return Some("NVIDIA"); + } + if name.starts_with("intel_icd") || name.starts_with("intel_hasvk") { + return Some("Intel"); + } + None +} + +/// The driver an ICD manifest's file name implies **when that driver is AMD's**, +/// and `None` for every other vendor (software rasterisers included — none of +/// them is AMD). +/// +/// The vendor test lives here, beside the one table that maps a file name to a +/// label, rather than being spelled out at each call site: a caller that must +/// not name another vendor's driver asks this instead of re-deriving which +/// prefixes are AMD's. It reads the label rather than the file name for the same +/// reason [`icd_is_gpu_driver`] does — one table, one place to extend. +#[must_use] +pub fn amd_icd_driver_label(icd: &str) -> Option<&'static str> { + icd_driver_label(icd).filter(|label| matches!(*label, "Mesa RADV" | "AMDVLK")) +} + +/// Whether an ICD manifest names a driver that runs on a GPU. +/// +/// An unrecognised manifest counts as a GPU driver: a vendor the table does not +/// list yet is far more likely to be real hardware than a new software +/// rasteriser, and the cost of the two errors is not symmetric -- missing a +/// working GPU path sends the user to CPU, while admitting an unknown one is +/// corrected by the device enumeration that follows. +#[must_use] +pub fn icd_is_gpu_driver(icd: &str) -> bool { + !icd_driver_label(icd).is_some_and(|label| label.contains("(software)")) +} + +/// Parse `vulkaninfo --summary` output into its physical devices. +/// +/// Tolerates the loader warnings `vulkaninfo` prints to stdout before the +/// report, and the `Instance Extensions` / `Instance Layers` sections ahead of +/// `Devices:` -- only `GPUn:` blocks and their indented `key = value` lines are +/// read. +#[must_use] +pub fn parse_vulkaninfo_summary(output: &str) -> Vec { + let mut devices = Vec::new(); + let mut current: Option = None; + for line in output.lines() { + let trimmed = line.trim(); + if trimmed.starts_with("GPU") && trimmed.ends_with(':') { + if let Some(device) = current.take() { + devices.push(device); + } + current = Some(VulkanDevice::default()); + continue; + } + let Some(device) = current.as_mut() else { + continue; + }; + let Some((key, value)) = trimmed.split_once('=') else { + // A non-indented, non-`key = value` line ends the block: the + // summary's device section is the last thing printed, but a caller + // may hand us trailing output. + if !trimmed.is_empty() && !line.starts_with([' ', '\t']) { + devices.push(current.take().unwrap_or_default()); + } + continue; + }; + let value = value.trim().to_owned(); + if value.is_empty() { + continue; + } + match key.trim() { + "deviceName" => device.name = value, + "driverName" => device.driver_name = Some(value), + "driverID" => device.driver_id = Some(value), + "apiVersion" => device.api_version = Some(value), + "vendorID" => device.vendor_id = Some(value), + "deviceID" => device.device_id = Some(value), + "deviceType" => device.device_type = Some(value), + _ => {} + } + } + if let Some(device) = current.take() { + devices.push(device); + } + devices.retain(|device| !device.name.is_empty()); + devices +} + +/// The ICD manifest paths listed under the Windows Khronos registry key, as +/// [`WINDOWS_VULKAN_ICD_SCRIPT`] prints them (one `ICD\t` row each). +#[must_use] +pub fn parse_windows_vulkan_icd_listing(output: &str) -> Vec { + output + .lines() + .filter_map(|line| line.trim().strip_prefix("ICD\t")) + .map(str::trim) + .filter(|path| !path.is_empty()) + .map(str::to_owned) + .collect() +} + +/// Enumerate both Khronos ICD keys. The WOW6432Node key carries the 32-bit +/// drivers; a 64-bit-only install lists nothing there, which is not an error. +#[cfg(any(windows, test))] +pub(super) const WINDOWS_VULKAN_ICD_SCRIPT: &str = r#"foreach ($key in 'HKLM:\SOFTWARE\Khronos\Vulkan\Drivers','HKLM:\SOFTWARE\WOW6432Node\Khronos\Vulkan\Drivers') { if (Test-Path $key) { foreach ($name in (Get-Item $key).GetValueNames()) { "ICD`t$name" } } }"#; + +/// Every Vulkan ICD manifest this host's loader would read, as the ICD-side +/// [`VulkanEvidence`]. +/// +/// On Linux the lookup is a read of a fixed list of manifest directories, and +/// there is no step in it that can fail in a way distinguishable from an honest +/// "nothing is installed here": a directory that does not exist is exactly what +/// a host with no Vulkan driver looks like. So this source always answers. +#[cfg(target_os = "linux")] +fn detect_icds() -> VulkanEvidence { + let mut icds = Vec::new(); + for dir in LINUX_ICD_DIRS { + let Ok(entries) = std::fs::read_dir(host_path(dir)) else { + continue; + }; + for entry in entries.flatten() { + let path = entry.path(); + if path.extension().is_some_and(|ext| ext == "json") + && let Some(name) = path.file_name().and_then(|name| name.to_str()) + { + icds.push(name.to_owned()); + } + } + } + icds.sort(); + icds.dedup(); + VulkanEvidence::answered(icds) +} + +/// On Windows the lookup is a PowerShell read of the Khronos registry keys, and +/// that genuinely can fail: `capture_optional_command` yields `None` for a +/// missing `powershell`, a non-zero exit **and** a timeout alike. That `None` +/// must stay distinct from the empty `Vec` an empty registry key produces, +/// otherwise a flaky PowerShell on a host with a working AMD driver reads +/// identically to a host with no driver at all — the conflation the device +/// side's "did it answer" exists to prevent. +/// +/// Everything this does beyond starting the process lives in +/// [`windows_icds_through`], which is compiled and tested on every platform. +#[cfg(windows)] +fn detect_icds() -> VulkanEvidence { + windows_icds_through(capture_optional_command) +} + +/// The Windows ICD lookup with the subprocess as an argument: which program is +/// run, with which arguments, and what its capture is turned into. +/// +/// Split out from [`detect_icds`] so that the whole of the Windows registry +/// path except the `CreateProcess` call itself can be driven from a Linux lane. +/// The argv is the part that had no test at all: `windows_icds_from_capture` +/// was tested over hand-written captures, but nothing checked that the capture +/// handed to it came from PowerShell running +/// [`WINDOWS_VULKAN_ICD_SCRIPT`] — so dropping `-Command`, or pointing the +/// lookup at a program that is not on a stock Windows install, would have +/// compiled and shipped, failing only on real hardware as a silent +/// [`VulkanStatus::Inconclusive`]. `the_windows_registry_lookup_runs_the_khronos_script_through_powershell` +/// pins it. +/// +/// `-NonInteractive` and `-NoProfile` are not decoration: a profile that +/// prompts turns this probe into a 1.5 s timeout on every `examine`, and a +/// timeout is one of the `None`s that must not read as an empty registry key. +#[cfg(any(windows, test))] +fn windows_icds_through( + capture: impl FnOnce(&str, &[&str]) -> Option, +) -> VulkanEvidence { + windows_icds_from_capture(capture( + "powershell", + &[ + "-NoLogo", + "-NoProfile", + "-NonInteractive", + "-Command", + WINDOWS_VULKAN_ICD_SCRIPT, + ], + )) +} + +/// Nothing here can be read on a platform that is neither Linux nor Windows, so +/// this source never answers. The classifier never sees it today — +/// `vulkan_is_probeable()` is false there and returns [`VulkanStatus::Unknown`] +/// first — but it must not claim a lookup happened where none exists. +#[cfg(not(any(target_os = "linux", windows)))] +const fn detect_icds() -> VulkanEvidence { + VulkanEvidence::unanswered() +} + +/// The pure half of the Windows [`detect_icds`]: the manifests the capture +/// named, and whether PowerShell actually **answered**. +/// +/// Compiled on every platform, not just Windows, so the Linux lanes can test +/// the failure path at all. `Some` means the script exited 0 and its stdout is +/// in hand, so an empty list from it is a real "the key holds no ICD"; `None` +/// is the un-run lookup that must not be reported as one. +/// +/// **What is and is not covered**, stated exactly, because an overstated claim +/// here is what leaves a gap nobody goes looking for. This function and the +/// argv around it ([`windows_icds_through`]) are unit-tested on every platform. +/// The one step no test executes is starting the PowerShell process: no test in +/// this repository runs `detect_icds` on Windows, so CI's +/// `windows-build-and-test` job *compiles* that call and never runs it. What +/// could still break there and nowhere else is the behaviour of PowerShell +/// itself on a real host — the script's output encoding, a policy that blocks +/// it, a cold start slower than `OPTIONAL_COMMAND_TIMEOUT`. Each of those +/// arrives as a `None`, which this function routes to the hedged +/// [`VulkanStatus::Inconclusive`] rather than to a claim about the machine, so +/// the untested step cannot produce a false statement — only a less useful one. +#[must_use] +pub fn windows_icds_from_capture(captured: Option) -> VulkanEvidence { + captured.map_or_else(VulkanEvidence::unanswered, |output| { + VulkanEvidence::answered(parse_windows_vulkan_icd_listing(&output)) + }) +} + +/// The devices `vulkaninfo --summary` reports, or an empty list when the tool +/// is not installed. Absence of the tool is not absence of a driver, which is +/// why this cannot decide [`VulkanStatus`] on its own. +fn detect_vulkan_devices() -> VulkanEvidence { + vulkan_devices_from_capture(capture_optional_command("vulkaninfo", &["--summary"])) +} + +/// The pure half of [`detect_vulkan_devices`]: the devices the capture named, +/// and whether `vulkaninfo` actually **answered**. +/// +/// The classification turns on "could we ask" versus "we asked and nothing was +/// there", and the second half of that is what `did_answer` carries. Answering +/// is deliberately *not* "the binary exists": `capture_optional_command` yields +/// `Some` only for an exit-0 run, so a `vulkaninfo` that exits non-zero, times +/// out, or is too old to know `--summary` arrives here as a source that +/// answered nothing — none of which is a host that was looked at and found +/// empty. +/// +/// Mere presence on `PATH` is the wrong test, in the direction that matters: on +/// a host whose ICD sits outside the fixed search directories, a failing +/// `vulkaninfo` would then produce a *confirmed* `Absent` and tell the user "no +/// Vulkan GPU driver was found - install one", which is the unearned claim this +/// probe exists to stop making. +fn vulkan_devices_from_capture(captured: Option) -> VulkanEvidence { + captured.map_or_else(VulkanEvidence::unanswered, |output| { + VulkanEvidence::answered(parse_vulkaninfo_summary(&output)) + }) +} + +/// Whether this platform's Vulkan surfaces can be read at all. +const fn vulkan_is_probeable() -> bool { + cfg!(any(target_os = "linux", windows)) +} + +/// What this host offers for Vulkan. +#[must_use] +pub fn detect_vulkan_support() -> VulkanSupport { + classify_vulkan_support( + detect_icds(), + detect_vulkan_devices(), + vulkan_is_probeable(), + ) +} + +/// The pure decision behind [`detect_vulkan_support`], split out so every +/// combination of evidence can be tested without a Vulkan install. +/// +/// Each source arrives as a [`VulkanEvidence`] carrying its own "did this +/// answer at all", which is what keeps "could not look" apart from "looked and +/// found nothing". Both must have answered before an empty result may be +/// reported as a confirmed absence. +#[must_use] +pub fn classify_vulkan_support( + icd_evidence: VulkanEvidence, + device_evidence: VulkanEvidence, + probeable: bool, +) -> VulkanSupport { + let icds_listed = icd_evidence.did_answer(); + let enumerated = device_evidence.did_answer(); + let icds = icd_evidence.into_found(); + let devices = device_evidence.into_found(); + if !probeable { + return VulkanSupport { + status: VulkanStatus::Unknown, + icds, + devices, + detail: Some("Vulkan support is not probed on this platform".to_owned()), + }; + } + + let amd_gpu = devices + .iter() + .find(|device| device.is_amd() && device.is_hardware()); + if let Some(device) = amd_gpu { + let driver = device.driver_name.as_deref().unwrap_or("an unnamed driver"); + return VulkanSupport { + detail: Some(format!("{} through {driver}", device.name)), + status: VulkanStatus::Available, + icds, + devices, + }; + } + + // An enumeration of nothing but software devices denies a GPU path only + // while no GPU driver manifest contradicts it. A host carrying + // `radeon_icd.x86_64.json` whose `vulkaninfo` lists only `llvmpipe` is the + // ordinary shape of a permission problem (no `render` group), not of a + // missing driver — and "no Vulkan GPU driver was found - install one" is + // then both false and unactionable, since the driver it names is already + // installed and printed in `icds` of the same report. The ICD evidence is + // therefore consulted *before* this early return, not after it: such a host + // falls through to the driver-present-devices-unverified arm at the end, + // which names the software-only enumeration as the reason nothing was + // confirmed. + let software_only = !devices.is_empty() && devices.iter().all(|device| !device.is_hardware()); + let gpu_icds: Vec<&String> = icds.iter().filter(|icd| icd_is_gpu_driver(icd)).collect(); + if software_only && gpu_icds.is_empty() { + return VulkanSupport { + status: VulkanStatus::Absent, + detail: Some( + "only a software (CPU) Vulkan device was found; that is not a GPU path".to_owned(), + ), + icds, + devices, + }; + } + + if gpu_icds.is_empty() { + // Nothing found at all, and nothing that could have found it: the ICD + // search is not exhaustive (a fixed directory list on Linux that + // ignores `VK_ICD_FILENAMES`/`VK_DRIVER_FILES`; only the legacy + // Khronos key on Windows), so without `vulkaninfo` to ask, an empty + // result is a gap in the probe rather than a fact about the host. + // `Absent` renders as "no Vulkan GPU driver was found - install one", + // which would then be told to a host that has one. + // + // `enumerated` is "the tool answered", not "the tool returned devices" + // and not "the tool is installed": a host genuinely without a driver + // runs `vulkaninfo` successfully and gets an empty device list, and + // that is a real answer. A `vulkaninfo` that exits non-zero, times out, + // or is too old for `--summary` is not — it answered nothing, so it + // cannot be the evidence that turns an empty result into a confirmed + // absence. + // + // `icds_listed` is the same question asked of the other source, and it + // is why an empty `icds` alone proves nothing: on Windows the listing is + // a PowerShell registry read that can be missing, fail or time out, and + // all three arrive here as the same empty `Vec` a genuinely empty + // registry key produces. Both sources must have answered before an empty + // result may be called an absence. + if icds.is_empty() && devices.is_empty() && !(icds_listed && enumerated) { + // Which source went unread decides the sentence: a host is owed the + // reason nothing could be concluded about it, and "a Vulkan driver + // is absent" is a claim no single source here may make. + // + // None of the three denies a driver, the arm where the manifest + // lookup *did* answer included. On Windows that lookup reads only + // the legacy Khronos key, which a current Adrenalin install leaves + // empty, so "no manifest was listed" is routinely true of a machine + // with a perfectly good Vulkan driver. + let detail = match (icds_listed, enumerated) { + // The lookup ran and found no manifest; only `vulkaninfo` is + // missing. (`(true, true)` cannot reach here — it is the + // confirmed absence handled below.) + (true, _) => { + "no installed Vulkan driver was listed, and `vulkaninfo` could not confirm \ + anything either (not installed, or it failed to run), so nothing here shows \ + whether a driver is present" + } + (false, true) => { + "`vulkaninfo` ran and listed no device, but the installed Vulkan drivers could \ + not be listed on this host, so nothing here confirms a driver is absent" + } + (false, false) => { + "the installed Vulkan drivers could not be listed on this host, and \ + `vulkaninfo` could not confirm anything either (not installed, or it failed \ + to run), so nothing here shows whether a driver is present" + } + }; + return VulkanSupport { + status: VulkanStatus::Inconclusive, + detail: Some(detail.to_owned()), + icds, + devices, + }; + } + // A device that enumerated is proof a driver answered, so neither the + // status nor the detail may deny one here, even though no ICD manifest + // was read: the ICD search is not exhaustive, and `vulkaninfo` can see + // a driver it misses. `Absent` is the status that renders the "install + // one" advice, so it must not be used; what was actually established — + // hardware answered, none of it AMD — is the same evidentiary state as + // an installed driver that enumerated nothing for us. + if !devices.is_empty() { + return VulkanSupport { + status: VulkanStatus::DriverPresentDevicesUnverified, + detail: Some( + "Vulkan devices were enumerated, but none of them is an AMD GPU".to_owned(), + ), + icds, + devices, + }; + } + // Two different hosts are left, and only one of them has answered + // enough to be denied a driver. + // + // `icds.is_empty()` here means both sources answered: the guard above + // returned otherwise. That is the empty-everything confirmed absence. + // + // A non-empty `icds` at this point is a software-rasteriser manifest + // and nothing else, and that fact arrives from the *weaker* source. The + // ICD search is documented as non-exhaustive — a fixed directory list + // that ignores `VK_ICD_FILENAMES`/`VK_DRIVER_FILES` on Linux, the + // legacy Khronos key alone on Windows — so "lavapipe is the only + // manifest I can see" does not exclude a GPU driver whose manifest sits + // somewhere this probe never reads. `vulkaninfo` is the source that + // would have seen it, and when it never answered nothing here has ruled + // a GPU path out. Routed to `Inconclusive` for the same reason as the + // guard above, so that every `Absent` this function returns has + // `vulkaninfo`'s answer behind it. + if !icds.is_empty() && !enumerated { + return VulkanSupport { + status: VulkanStatus::Inconclusive, + detail: Some( + "only a software (CPU) Vulkan driver was listed, and `vulkaninfo` could not \ + confirm anything either (not installed, or it failed to run), so nothing here \ + rules out a GPU driver this probe cannot see" + .to_owned(), + ), + icds, + devices, + }; + } + let detail = if icds.is_empty() { + "no Vulkan driver found".to_owned() + } else { + "only a software (CPU) Vulkan driver is installed; that is not a GPU path".to_owned() + }; + return VulkanSupport { + status: VulkanStatus::Absent, + detail: Some(detail), + icds, + devices, + }; + } + + // An AMD manifest wins over any other vendor's, for the same reason + // `driver_label` restricts its fallback: this sentence is the justification + // the host is handed for being offered a Vulkan path for its AMD GPU, and on + // a dual-vendor box the alphabetical sort would otherwise open it with + // "NVIDIA is installed". A non-AMD label is still used when it is the only + // one there, because the status beside it claims nothing about AMD — it says + // a driver is installed and no AMD device was confirmed. + let named = gpu_icds + .iter() + .find_map(|icd| amd_icd_driver_label(icd)) + .or_else(|| gpu_icds.iter().find_map(|icd| icd_driver_label(icd))) + .map_or_else( + || "a Vulkan driver is installed".to_owned(), + |label| format!("{label} is installed"), + ); + // Four different hosts reach this status and they are not owed the same + // sentence. + // + // `software_only` is the one that would otherwise be described wrongly by + // the arm below it: saying "none of the devices it enumerated is an AMD + // GPU" of a host that enumerated nothing but `llvmpipe` is true and + // useless, because it reads as "your other vendor's card answered" rather + // than "no GPU answered at all". It is also the arm that must not say a + // driver is absent — a GPU manifest is installed and named in `icds` — so + // it names the exclusion and the likeliest cause instead. + // + // A non-empty `devices` otherwise means `vulkaninfo` answered and the + // hardware it listed simply was not AMD — saying no device was enumerated + // there is false, and it is the shape an NVIDIA box with an AMD iGPU + // disabled lands in. + // + // An empty `devices` splits on `enumerated`, the same evidence the + // `gpu_icds.is_empty()` arm above already branches on. `enumerated == true` + // means `vulkaninfo` ran, exited 0 and listed nothing — the answer is in + // hand, so telling that user to "install `vulkaninfo` to confirm" sends + // them after a tool that is already installed and has already answered + // (the common cause is a permission problem, e.g. not being in the + // `render` group, not a missing tool). Only `enumerated == false` is the + // case where the tool is genuinely missing or failed to run, and only + // there is that advice true. + let detail = if software_only { + format!( + "{named}, but `vulkaninfo` enumerated only a software (CPU) Vulkan device, which is \ + not a GPU path, so nothing confirms the driver can reach a GPU here (on Linux, check \ + that your user is in the `render` group)" + ) + } else if !devices.is_empty() { + format!("{named}, but none of the devices it enumerated is an AMD GPU") + } else if enumerated { + format!( + "{named}, but `vulkaninfo` ran and listed no device, so nothing confirms it can \ + reach a GPU here (on Linux, check that your user is in the `render` group)" + ) + } else { + format!("{named}, but no device was enumerated (install `vulkaninfo` to confirm)") + }; + VulkanSupport { + status: VulkanStatus::DriverPresentDevicesUnverified, + detail: Some(detail), + icds, + devices, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// The `vulkan:` text line and the `--json` document are two renderings of + /// one status, so they must spell it the same way. Holding `as_str` against + /// what serde writes is what makes that true by construction rather than by + /// two hand-maintained tables. + #[test] + fn the_status_word_is_the_one_serde_writes() { + for status in [ + VulkanStatus::Available, + VulkanStatus::DriverPresentDevicesUnverified, + VulkanStatus::Absent, + VulkanStatus::Inconclusive, + VulkanStatus::Unknown, + ] { + let json = serde_json::to_string(&status).expect("a status always serializes"); + assert_eq!( + json, + format!("\"{}\"", status.as_str()), + "the text line and the JSON must name {status:?} identically" + ); + } + } + + /// The real `vulkaninfo --summary` output from a Ryzen 7 4700U (gfx90c, + /// Renoir) on Windows 11 with Adrenalin 31.0.21925.1001 -- the machine + /// ROCMAI-517 is about. Note the loader warnings ahead of the report and + /// the instance sections before `Devices:`; both must be skipped. + const RENOIR_WINDOWS_SUMMARY: &str = "\ +WARNING: [Loader Message] Code 0 : windows_read_data_files_in_registry: Registry lookup failed to get layer manifest files. +========== +VULKANINFO +========== + +Vulkan Instance Version: 1.3.301 + + +Instance Extensions: count = 13 +------------------------------- +VK_EXT_debug_report : extension revision 10 +VK_KHR_surface : extension revision 25 + +Instance Layers: count = 1 +-------------------------- +VK_LAYER_AMD_switchable_graphics AMD switchable graphics layer 1.3.260 version 1 + +Devices: +======== +GPU0: +\tapiVersion = 1.3.260 +\tdriverVersion = 2.0.279 +\tvendorID = 0x1002 +\tdeviceID = 0x1636 +\tdeviceType = PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU +\tdeviceName = AMD Radeon(TM) Graphics +\tdriverID = DRIVER_ID_AMD_PROPRIETARY +\tdriverName = AMD proprietary driver +\tdriverInfo = 26.5.2 (AMD proprietary shader compiler) +\tconformanceVersion = 1.3.3.1 +"; + + #[test] + fn the_renoir_igpu_is_read_out_of_a_real_vulkaninfo_summary() { + let devices = parse_vulkaninfo_summary(RENOIR_WINDOWS_SUMMARY); + + assert_eq!(devices.len(), 1, "{devices:?}"); + let gpu = &devices[0]; + assert_eq!(gpu.name, "AMD Radeon(TM) Graphics"); + assert_eq!(gpu.vendor_id.as_deref(), Some("0x1002")); + // The same device id the gfx-target table maps to gfx90c. + assert_eq!(gpu.device_id.as_deref(), Some("0x1636")); + assert_eq!(gpu.driver_name.as_deref(), Some("AMD proprietary driver")); + assert_eq!(gpu.driver_id.as_deref(), Some("DRIVER_ID_AMD_PROPRIETARY")); + assert_eq!(gpu.api_version.as_deref(), Some("1.3.260")); + assert!(gpu.is_amd(), "vendor 0x1002 is AMD"); + assert!(gpu.is_hardware(), "an integrated GPU is hardware"); + } + + #[test] + fn a_real_renoir_host_reports_vulkan_available_and_names_its_driver() { + let devices = parse_vulkaninfo_summary(RENOIR_WINDOWS_SUMMARY); + + let support = classify_vulkan_support( + VulkanEvidence::answered(Vec::new()), + VulkanEvidence::answered(devices), + true, + ); + + assert_eq!(support.status, VulkanStatus::Available); + assert_eq!( + crate::gfx_target::gpu_support_level(Some("gfx90c"), None, support.status), + crate::gfx_target::GpuSupportLevel::VulkanOnly, + "a confirmed AMD device is the one thing that earns this GPU a Vulkan path" + ); + assert_eq!( + support.driver_label().as_deref(), + Some("AMD proprietary driver"), + "the device's own driverName must win over any ICD filename guess" + ); + } + + /// The defect this guards against: lavapipe is a complete Vulkan + /// implementation that runs on the CPU. Reporting it as a usable Vulkan + /// path would route a GPU-required launch onto CPU execution while telling + /// the user a GPU path was chosen -- the silent CPU fallback AGENTS.md §6 + /// forbids, reached through a backend rather than a policy bug. + #[test] + fn a_software_rasteriser_is_never_a_usable_vulkan_path() { + let lavapipe = "\ +GPU0: +\tapiVersion = 1.3.255 +\tvendorID = 0x10005 +\tdeviceType = PHYSICAL_DEVICE_TYPE_CPU +\tdeviceName = llvmpipe (LLVM 15.0.7, 256 bits) +\tdriverName = llvmpipe +"; + let devices = parse_vulkaninfo_summary(lavapipe); + assert_eq!(devices.len(), 1); + assert!(!devices[0].is_hardware()); + + let support = classify_vulkan_support( + VulkanEvidence::answered(vec!["lvp_icd.x86_64.json".to_owned()]), + VulkanEvidence::answered(devices), + true, + ); + + assert_eq!( + support.status, + VulkanStatus::Absent, + "a CPU rasteriser must not read as a Vulkan GPU path: {support:?}" + ); + assert_eq!( + crate::gfx_target::gpu_support_level(Some("gfx90c"), None, support.status), + crate::gfx_target::GpuSupportLevel::NoGpuBackend, + "and the level the user is shown must not offer one either: {support:?}" + ); + assert!( + support + .detail + .as_deref() + .is_some_and(|detail| detail.contains("not a GPU path")), + "{support:?}" + ); + } + + #[test] + fn a_lavapipe_only_install_is_absent_even_before_any_device_is_enumerated() { + let support = classify_vulkan_support( + VulkanEvidence::answered(vec!["lvp_icd.x86_64.json".to_owned()]), + VulkanEvidence::answered(Vec::new()), + true, + ); + + assert_eq!(support.status, VulkanStatus::Absent); + assert!(!icd_is_gpu_driver("lvp_icd.x86_64.json")); + assert!(icd_is_gpu_driver("radeon_icd.x86_64.json")); + } + + /// The same lavapipe-only manifest list as the test above, with the one + /// difference that decides whether anything was actually established: + /// `vulkaninfo` never answered. + /// + /// The ICD search is documented as non-exhaustive — a fixed directory list + /// that ignores `VK_ICD_FILENAMES`/`VK_DRIVER_FILES` on Linux, the legacy + /// Khronos key alone on Windows — so "lavapipe is the only manifest I can + /// see" rules out nothing on its own; a proprietary AMD ICD sitting in a + /// directory this probe never reads looks identical. `vulkaninfo` is the + /// source that would have seen it, and here it was not there to ask. + /// + /// Asserted as a pair against the answered case, because the status is the + /// whole finding: an isolated assertion that this is `Inconclusive` would + /// still pass if the sibling were quietly weakened to match it, and the + /// point is that the two hosts earn different answers. + #[test] + fn a_lavapipe_only_install_is_not_a_confirmed_absence_until_vulkaninfo_answers() { + let unasked = classify_vulkan_support( + VulkanEvidence::answered(vec!["lvp_icd.x86_64.json".to_owned()]), + VulkanEvidence::unanswered(), + true, + ); + + assert_eq!( + unasked.status, + VulkanStatus::Inconclusive, + "no source here has looked where a GPU manifest could still be: {unasked:?}" + ); + assert_eq!( + crate::gfx_target::gpu_support_level(Some("gfx90c"), None, unasked.status), + crate::gfx_target::GpuSupportLevel::VulkanUnconfirmed, + "and the level must not render the confirmed-absence advice: {unasked:?}" + ); + assert!( + unasked + .detail + .as_deref() + .is_some_and(|detail| detail.contains("`vulkaninfo` could not confirm")), + "the host is owed which source went unread: {unasked:?}" + ); + + let asked = classify_vulkan_support( + VulkanEvidence::answered(vec!["lvp_icd.x86_64.json".to_owned()]), + VulkanEvidence::answered(Vec::new()), + true, + ); + assert_eq!( + asked.status, + VulkanStatus::Absent, + "while the same manifest list with `vulkaninfo`'s answer behind it has \ + earned the confirmed absence: {asked:?}" + ); + } + + /// `VulkanStatus::Absent` renders as "no Vulkan GPU driver was found - + /// install one", a confirmed fact, so its documented precondition is worth + /// holding mechanically rather than arm by arm: `vulkaninfo` must have + /// answered on every path that reaches it. + /// + /// Swept over every combination of the two sources' answers against a + /// representative set of findings, so a future arm that denies a driver on + /// the ICD listing alone fails here even if it is added somewhere none of + /// the hand-written cases look. + #[test] + fn absent_always_has_vulkaninfos_answer_behind_it() { + let lavapipe = VulkanDevice { + name: "llvmpipe (LLVM 15.0.7, 256 bits)".to_owned(), + driver_name: Some("llvmpipe".to_owned()), + vendor_id: Some("0x10005".to_owned()), + device_type: Some("PHYSICAL_DEVICE_TYPE_CPU".to_owned()), + ..VulkanDevice::default() + }; + let icd_sets: [Vec; 3] = [ + Vec::new(), + vec!["lvp_icd.x86_64.json".to_owned()], + vec!["radeon_icd.x86_64.json".to_owned()], + ]; + let device_sets: [Vec; 2] = [Vec::new(), vec![lavapipe]]; + + for icds in &icd_sets { + for devices in &device_sets { + for icds_listed in [false, true] { + for enumerated in [false, true] { + // An unanswered source has nothing to report, which is + // what `VulkanEvidence::unanswered` encodes; pairing a + // "did not answer" with findings would test a state the + // constructors cannot build. + let icd_evidence = if icds_listed { + VulkanEvidence::answered(icds.clone()) + } else if icds.is_empty() { + VulkanEvidence::unanswered() + } else { + continue; + }; + let device_evidence = if enumerated { + VulkanEvidence::answered(devices.clone()) + } else if devices.is_empty() { + VulkanEvidence::unanswered() + } else { + continue; + }; + + let support = classify_vulkan_support(icd_evidence, device_evidence, true); + + assert!( + support.status != VulkanStatus::Absent || enumerated, + "a confirmed absence without `vulkaninfo`'s answer, from \ + icds={icds:?} devices={devices:?} icds_listed={icds_listed} \ + enumerated={enumerated}: {support:?}" + ); + } + } + } + } + } + + /// The `render`-group host, and the combination neither layer covered: a + /// real GPU driver manifest is installed and `vulkaninfo` enumerates only + /// `llvmpipe`. + /// + /// Telling this host "no Vulkan GPU driver was found - install one" is both + /// false and unactionable — `radeon_icd.x86_64.json` is printed in the + /// `icds` field of the same report — so the device evidence may not deny a + /// driver the ICD evidence is holding. What was actually established is + /// that a driver is installed and nothing confirmed it can reach a GPU, + /// which is exactly `DriverPresentDevicesUnverified`. + /// + /// Held against the software-ICD host beside it, because the two differ + /// only in which manifest is planted: folding the ICD check back out of the + /// `software_only` early return would turn this half into `Absent` while + /// the other half kept passing. + #[test] + fn a_software_only_enumeration_does_not_deny_an_installed_gpu_driver() { + let lavapipe = VulkanDevice { + name: "llvmpipe (LLVM 15.0.7, 256 bits)".to_owned(), + driver_name: Some("llvmpipe".to_owned()), + vendor_id: Some("0x10005".to_owned()), + device_type: Some("PHYSICAL_DEVICE_TYPE_CPU".to_owned()), + ..VulkanDevice::default() + }; + + let with_gpu_driver = classify_vulkan_support( + VulkanEvidence::answered(vec!["radeon_icd.x86_64.json".to_owned()]), + VulkanEvidence::answered(vec![lavapipe.clone()]), + true, + ); + + assert_eq!( + with_gpu_driver.status, + VulkanStatus::DriverPresentDevicesUnverified, + "an installed GPU driver is not absent just because the enumeration was \ + software-only: {with_gpu_driver:?}" + ); + let detail = with_gpu_driver + .detail + .as_deref() + .expect("every classification carries a detail"); + assert!( + detail.contains("Mesa RADV is installed"), + "the driver the report names in `icds` must be named here too: {detail}" + ); + assert!( + detail.contains("software (CPU) Vulkan device"), + "and the reason nothing was confirmed must be the software-only \ + enumeration, not a vendor mismatch: {detail}" + ); + assert!( + detail.contains("`render` group"), + "the likeliest cause is the one step that can clear it: {detail}" + ); + assert_eq!( + crate::gfx_target::gpu_support_level(Some("gfx90c"), None, with_gpu_driver.status), + crate::gfx_target::GpuSupportLevel::VulkanOnly, + "so the user must not reach the level that renders \"install one\": \ + {with_gpu_driver:?}" + ); + + // The same enumeration with only a software manifest beside it: nothing + // contradicts the devices, so this one keeps the confirmed absence. + let software_throughout = classify_vulkan_support( + VulkanEvidence::answered(vec!["lvp_icd.x86_64.json".to_owned()]), + VulkanEvidence::answered(vec![lavapipe]), + true, + ); + assert_eq!( + software_throughout.status, + VulkanStatus::Absent, + "a software rasteriser top to bottom is still not a GPU path: \ + {software_throughout:?}" + ); + } + + /// Both halves of this test reach the same *status*; what they must not + /// share is the *sentence*. A host whose `vulkaninfo` has already run and + /// listed nothing must not be told to "install `vulkaninfo` to confirm" — + /// that advice can never clear the state it is printed for. Asserting the + /// two texts differ, rather than asserting each in isolation, is what keeps + /// the advice tied to the evidence. + #[test] + fn an_installed_driver_with_no_enumerated_device_stays_unverified() { + let asked = classify_vulkan_support( + VulkanEvidence::answered(vec!["radeon_icd.x86_64.json".to_owned()]), + VulkanEvidence::answered(Vec::new()), + true, + ); + + assert_eq!(asked.status, VulkanStatus::DriverPresentDevicesUnverified); + assert_eq!( + crate::gfx_target::gpu_support_level(Some("gfx90c"), None, asked.status), + crate::gfx_target::GpuSupportLevel::VulkanOnly, + "an installed GPU driver is still worth routing to" + ); + assert_eq!(asked.driver_label().as_deref(), Some("Mesa RADV")); + let asked_detail = asked.detail.clone().expect("a detail is always set here"); + assert!( + asked_detail.contains("listed no device"), + "the gap must be stated, not papered over: {asked:?}" + ); + assert!( + !asked_detail.contains("install `vulkaninfo`"), + "`vulkaninfo` already ran and already answered; telling this user to install it \ + sends them after a tool they have: {asked:?}" + ); + + // Same ICD, same (empty) device list, but nothing asked: here the tool + // really may be missing, so the install advice is the true one. + let unasked = classify_vulkan_support( + VulkanEvidence::answered(vec!["radeon_icd.x86_64.json".to_owned()]), + VulkanEvidence::unanswered(), + true, + ); + + assert_eq!(unasked.status, VulkanStatus::DriverPresentDevicesUnverified); + let unasked_detail = unasked.detail.clone().expect("a detail is always set here"); + assert!( + unasked_detail.contains("install `vulkaninfo` to confirm"), + "with nothing having looked, the tool is what would settle it: {unasked:?}" + ); + assert_ne!( + asked_detail, unasked_detail, + "`enumerated` is the difference between 'nothing looked' and 'something looked \ + and found nothing'; the two must not be told the same thing" + ); + } + + /// No ICD and no enumerated device is an absence of evidence, not evidence + /// of absence — neither source is exhaustive (the Linux ICD search ignores + /// `VK_ICD_FILENAMES`, the Windows one reads only the legacy registry key, + /// and `vulkaninfo` is often not installed). `Absent` renders as a + /// confirmed "no Vulkan GPU driver was found - install one", so a host with + /// a working driver would be told to install one it already has. + #[test] + fn no_evidence_either_way_is_not_reported_as_a_confirmed_absence() { + // `vulkaninfo` absent: nothing could have found a driver, so nothing + // may claim there is none. + let unasked = classify_vulkan_support( + VulkanEvidence::answered(Vec::new()), + VulkanEvidence::unanswered(), + true, + ); + assert_eq!( + unasked.status, + VulkanStatus::Inconclusive, + "with no ICD and no way to enumerate, absence is unproven — but the \ + host WAS looked at, which `Unknown` (an unprobed platform) does not say" + ); + assert!( + unasked + .detail + .as_deref() + .is_some_and(|detail| detail.contains("not installed")), + "the detail must name the missing tool: {unasked:?}" + ); + + // `vulkaninfo` present and it found nothing: that IS the answer, and + // it is the shape a host genuinely without a driver takes. + let nothing = classify_vulkan_support( + VulkanEvidence::answered(Vec::new()), + VulkanEvidence::answered(Vec::new()), + true, + ); + assert_eq!( + nothing.status, + VulkanStatus::Absent, + "a probe that could look and found nothing is a real absence" + ); + assert!(nothing.driver_label().is_none()); + + // What `Absent` is now reserved for: something WAS found and ruled out. + let software_only = classify_vulkan_support( + VulkanEvidence::answered(vec!["lvp_icd.x86_64.json".to_owned()]), + VulkanEvidence::answered(Vec::new()), + true, + ); + assert_eq!(software_only.status, VulkanStatus::Absent); + + // macOS and friends: no evidence either way, which must not read as + // "no Vulkan" any more than it reads as "Vulkan works". + // An unprobeable platform is the one place a source goes unanswered + // without a failure: the `cfg` stub there has nothing it could read. + let unprobeable = classify_vulkan_support( + VulkanEvidence::unanswered(), + VulkanEvidence::unanswered(), + false, + ); + assert_eq!(unprobeable.status, VulkanStatus::Unknown); + assert_eq!( + crate::gfx_target::gpu_support_level(Some("gfx90c"), None, unprobeable.status), + crate::gfx_target::GpuSupportLevel::VulkanOnly, + "a platform nobody could look at keeps the benefit of the doubt, which is \ + what tells `Unknown` apart from `Inconclusive`" + ); + } + + #[test] + fn an_unknown_vendors_icd_is_assumed_to_be_hardware() { + // A vendor the table does not list yet must not be mistaken for a + // software rasteriser; the device enumeration corrects it if wrong. + assert!(icd_is_gpu_driver("some_new_vendor_icd.x86_64.json")); + assert_eq!(icd_driver_label("some_new_vendor_icd.x86_64.json"), None); + + let support = classify_vulkan_support( + VulkanEvidence::answered(vec!["some_new_vendor_icd.x86_64.json".to_owned()]), + VulkanEvidence::answered(Vec::new()), + true, + ); + assert_eq!(support.status, VulkanStatus::DriverPresentDevicesUnverified); + } + + #[test] + fn a_discrete_amd_card_is_preferred_over_a_software_device_in_the_same_report() { + let mixed = "\ +GPU0: +\tvendorID = 0x10005 +\tdeviceType = PHYSICAL_DEVICE_TYPE_CPU +\tdeviceName = llvmpipe +\tdriverName = llvmpipe +GPU1: +\tvendorID = 0x1002 +\tdeviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU +\tdeviceName = AMD Radeon RX 7900 XTX +\tdriverName = radv +"; + let support = classify_vulkan_support( + VulkanEvidence::answered(Vec::new()), + VulkanEvidence::answered(parse_vulkaninfo_summary(mixed)), + true, + ); + + assert_eq!(support.status, VulkanStatus::Available); + assert_eq!(support.driver_label().as_deref(), Some("radv")); + assert!( + support + .detail + .as_deref() + .is_some_and(|detail| detail.contains("AMD Radeon RX 7900 XTX")), + "{support:?}" + ); + } + + /// Pins a **known limitation**, not a desired behavior: an enumeration that + /// returned only non-AMD hardware is not treated as evidence against an AMD + /// Vulkan path, so such a host is still routed to `VulkanOnly` and told to + /// serve a model. The name has to say that rather than imply the opposite, + /// and the routing is asserted alongside the status so the limitation is + /// visible here: if it is ever tightened, this test fails and has to be + /// rewritten deliberately. + #[test] + fn a_non_amd_only_enumeration_is_still_routed_to_vulkan_today() { + let nvidia = "\ +GPU0: +\tvendorID = 0x10de +\tdeviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU +\tdeviceName = NVIDIA GeForce GTX 1050 Ti +\tdriverName = NVIDIA +"; + let support = classify_vulkan_support( + VulkanEvidence::answered(vec!["nvidia_icd.json".to_owned()]), + VulkanEvidence::answered(parse_vulkaninfo_summary(nvidia)), + true, + ); + + // The driver is installed and is not software, so the status stops short + // of "available" while still routing this host to Vulkan. + assert_eq!(support.status, VulkanStatus::DriverPresentDevicesUnverified); + assert_eq!( + crate::gfx_target::gpu_support_level(Some("gfx90c"), None, support.status), + crate::gfx_target::GpuSupportLevel::VulkanOnly, + "today a non-AMD-only enumeration still promises this host a Vulkan path; \ + this is the documented limitation, and changing it must break this test" + ); + } + + /// The distinction the whole classification rests on, at the seam where it + /// is actually decided. + /// + /// `capture_optional_command` collapses "not installed", "exited non-zero", + /// "timed out" and "too old for `--summary`" into one `None`, and **none** + /// of those is a host that was looked at. Presence on `PATH` is therefore + /// not the test: were it, a failing `vulkaninfo` on a host whose ICD sits + /// outside the fixed search directories would produce a confirmed `Absent` + /// and tell the user to install a driver they already have. + #[test] + fn only_a_vulkaninfo_that_answered_counts_as_having_looked() { + let devices = vulkan_devices_from_capture(None); + assert!( + !devices.did_answer() && devices.found().is_empty(), + "a run that produced no output did not look at this host" + ); + assert_eq!( + classify_vulkan_support(VulkanEvidence::answered(Vec::new()), devices, true).status, + VulkanStatus::Inconclusive, + "so it must not be reported as a confirmed absence" + ); + + // The genuine "looked and found none": exit 0, empty device list. + let devices = vulkan_devices_from_capture(Some("Devices:\n=======\n".to_owned())); + assert!( + devices.did_answer() && devices.found().is_empty(), + "an empty answer is still an answer" + ); + assert_eq!( + classify_vulkan_support(VulkanEvidence::answered(Vec::new()), devices, true).status, + VulkanStatus::Absent, + "and that one has earned the confirmed absence" + ); + } + + /// A device that enumerated is proof a driver answered, so the report must + /// not deny one just because no ICD manifest was read: the ICD search is a + /// fixed directory list that `vulkaninfo` can see past. "No Vulkan driver + /// found" is false on exactly this host. + #[test] + fn an_enumerated_non_amd_device_is_not_reported_as_a_missing_driver() { + let nvidia = "\ +GPU0: +\tvendorID = 0x10de +\tdeviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU +\tdeviceName = NVIDIA GeForce GTX 1050 Ti +\tdriverName = NVIDIA +"; + // No ICD manifest at all: the one shape in which a denial of the driver + // could slip past the enumeration above. + let support = classify_vulkan_support( + VulkanEvidence::answered(Vec::new()), + VulkanEvidence::answered(parse_vulkaninfo_summary(nvidia)), + true, + ); + + let detail = support.detail.as_deref().unwrap_or_default(); + assert!( + !detail.contains("no Vulkan driver found"), + "a driver answered with a device, so it cannot be reported missing: {support:?}" + ); + assert!( + detail.contains("none of them is an AMD GPU"), + "the report should say what was established: {support:?}" + ); + + // The status and the rendered line, not just the detail. Asserting only + // the detail is what let the two disagree: the text said devices were + // enumerated while `Absent` rendered "install one" right beside it. + assert_eq!( + support.status, + VulkanStatus::DriverPresentDevicesUnverified, + "a driver that answered is not an absent one: {support:?}" + ); + assert_eq!( + crate::gfx_target::gpu_support_level(Some("gfx90c"), None, support.status), + crate::gfx_target::GpuSupportLevel::VulkanOnly, + "and it must not route to the confirmed-absence level" + ); + } + + #[test] + fn the_windows_registry_listing_is_read_into_icd_paths() { + let output = "ICD\tC:\\Windows\\System32\\DriverStore\\FileRepository\\u0397342.inf_amd64_x\\amdvlk64.json\nICD\tC:\\Windows\\SysWOW64\\amdvlk32.json\n"; + + let icds = parse_windows_vulkan_icd_listing(output); + + assert_eq!(icds.len(), 2, "{icds:?}"); + assert!(icds[0].ends_with("amdvlk64.json")); + assert_eq!(icd_driver_label(&icds[0]), Some("AMDVLK")); + assert!( + icd_is_gpu_driver(&icds[0]), + "a Windows path separator must not defeat the filename table" + ); + } + + /// Both Khronos keys must be queried. A 32-bit AMDVLK registration lives + /// only under `WOW6432Node`, so reading the 64-bit key alone would report + /// "no Vulkan driver" on a host that has one. + #[test] + fn the_windows_icd_query_reads_both_the_native_and_the_wow6432_key() { + assert!( + WINDOWS_VULKAN_ICD_SCRIPT.contains(r"HKLM:\SOFTWARE\Khronos\Vulkan\Drivers"), + "{WINDOWS_VULKAN_ICD_SCRIPT}" + ); + assert!( + WINDOWS_VULKAN_ICD_SCRIPT + .contains(r"HKLM:\SOFTWARE\WOW6432Node\Khronos\Vulkan\Drivers"), + "{WINDOWS_VULKAN_ICD_SCRIPT}" + ); + // A missing key is ordinary on a host with no Vulkan at all, so the + // script must test for it rather than let PowerShell error out. + assert!( + WINDOWS_VULKAN_ICD_SCRIPT.contains("Test-Path"), + "{WINDOWS_VULKAN_ICD_SCRIPT}" + ); + // The rows the parser consumes. + assert!( + WINDOWS_VULKAN_ICD_SCRIPT.contains("\"ICD`t$name\""), + "{WINDOWS_VULKAN_ICD_SCRIPT}" + ); + } + + #[test] + fn an_empty_registry_key_yields_no_icds_rather_than_a_blank_entry() { + assert!(parse_windows_vulkan_icd_listing("").is_empty()); + assert!(parse_windows_vulkan_icd_listing("ICD\t\n").is_empty()); + assert!(parse_windows_vulkan_icd_listing("unrelated output\n").is_empty()); + } + + #[test] + fn a_vulkaninfo_report_with_no_devices_yields_none() { + assert!(parse_vulkaninfo_summary("Vulkan Instance Version: 1.3.301\n").is_empty()); + assert!(parse_vulkaninfo_summary("").is_empty()); + } + + /// The ICD side of "could not look" versus "looked and found nothing" — the + /// same distinction `enumerated` draws for `vulkaninfo`, which the ICD + /// source had no signal for. + /// + /// On Windows the listing is a PowerShell registry read, and + /// `capture_optional_command` reports a missing binary, a non-zero exit and + /// a timeout as one `None`, which `unwrap_or_default()` then turned into the + /// very empty `Vec` an empty Khronos key produces. Asserting that the two + /// details *differ*, rather than asserting each alone, is what keeps the + /// claim tied to the evidence: collapsing them back together has to fail + /// here. + #[test] + fn a_failed_icd_lookup_is_not_reported_as_a_host_without_a_driver() { + // Nothing read the registry, and `vulkaninfo` did not answer either. + let unread = classify_vulkan_support( + VulkanEvidence::unanswered(), + VulkanEvidence::unanswered(), + true, + ); + // Same host, except the lookup ran and genuinely found no manifest. + let read = classify_vulkan_support( + VulkanEvidence::answered(Vec::new()), + VulkanEvidence::unanswered(), + true, + ); + + assert_eq!(unread.status, VulkanStatus::Inconclusive); + assert_eq!(read.status, VulkanStatus::Inconclusive); + let unread_detail = unread.detail.clone().expect("a detail is always set here"); + let read_detail = read.detail.clone().expect("a detail is always set here"); + assert!( + !unread_detail.contains("no Vulkan driver was found"), + "the driver list was never read, so nothing here may report it empty: {unread:?}" + ); + assert!( + unread_detail.contains("could not be listed"), + "the host is owed the reason nothing could be concluded about it: {unread:?}" + ); + assert!( + read_detail.contains("no installed Vulkan driver was listed"), + "a lookup that ran and came back empty is entitled to say what it saw: {read:?}" + ); + assert!( + !read_detail.contains("no Vulkan driver was found"), + "but it may not deny the driver itself: on Windows this lookup reads only the legacy \ + Khronos key, which a current Adrenalin install leaves empty, so an empty list is \ + routinely true of a machine with a working Vulkan driver: {read:?}" + ); + assert_ne!( + unread_detail, read_detail, + "`icds_listed` is the difference between a lookup that never ran and one that ran \ + and came back empty; a host whose PowerShell failed must not be told what a host \ + with a genuinely empty registry key is told" + ); + + // `Absent` is the confirmed claim, and it takes *both* sources having + // answered. A `vulkaninfo` that ran and listed nothing is not enough on + // its own while the driver list went unread. + let only_vulkaninfo_answered = classify_vulkan_support( + VulkanEvidence::unanswered(), + VulkanEvidence::answered(Vec::new()), + true, + ); + assert_eq!( + only_vulkaninfo_answered.status, + VulkanStatus::Inconclusive, + "one source of two is not an exhaustive look: {only_vulkaninfo_answered:?}" + ); + assert!( + only_vulkaninfo_answered + .detail + .as_deref() + .is_some_and(|detail| detail.contains("could not be listed")), + "{only_vulkaninfo_answered:?}" + ); + assert_eq!( + classify_vulkan_support( + VulkanEvidence::answered(Vec::new()), + VulkanEvidence::answered(Vec::new()), + true + ) + .status, + VulkanStatus::Absent, + "both sources answered and both came back empty: that one has earned the claim" + ); + } + + /// The Windows registry lookup, driven from a Linux lane through the one + /// seam `detect_icds` leaves: the subprocess as an argument. + /// + /// This is the half that had no test. `windows_icds_from_capture` was + /// exercised over captures written by hand, which says nothing about where + /// a real capture comes from — the program name, the flags, and the script + /// were only ever read by a human. Asserting the argv *here*, against the + /// same `WINDOWS_VULKAN_ICD_SCRIPT` the parser's own test reads, is what + /// ties the two halves together: an argv that no longer runs the script, + /// or runs it interactively, fails here rather than on a user's machine as + /// a permanently inconclusive Vulkan line. + /// + /// What it still does not reach is `CreateProcess` itself, and no test in + /// this repository does — see `windows_icds_from_capture` for exactly what + /// that leaves uncovered and why the residue is bounded. + #[test] + fn the_windows_registry_lookup_runs_the_khronos_script_through_powershell() { + let mut argv = None; + let icds = windows_icds_through(|program, args| { + argv = Some(( + program.to_owned(), + args.iter().map(|arg| (*arg).to_owned()).collect::>(), + )); + // What a real AMD Adrenalin host prints: both the 64-bit and the + // 32-bit registration, one `ICD` row each. + Some( + "ICD\tC:\\Windows\\System32\\DriverStore\\FileRepository\\u0397342.inf_amd64_x\\amdvlk64.json\n\ + ICD\tC:\\Windows\\SysWOW64\\amdvlk32.json\n" + .to_owned(), + ) + }); + + let (program, args) = argv.expect("the lookup must actually run a command"); + assert_eq!( + program, "powershell", + "the program has to be the one a stock Windows install has" + ); + assert_eq!( + args.last().map(String::as_str), + Some(WINDOWS_VULKAN_ICD_SCRIPT), + "the script that is run must be the one the parser's test reads, or the two halves \ + can drift apart while each looks right: {args:?}" + ); + assert!( + args.iter().any(|arg| arg == "-Command"), + "without it PowerShell treats the script as a file name: {args:?}" + ); + assert!( + args.iter().any(|arg| arg == "-NonInteractive") + && args.iter().any(|arg| arg == "-NoProfile"), + "a profile that prompts turns this probe into a 1.5s timeout on every `examine`, and \ + a timeout reads as `Inconclusive`: {args:?}" + ); + + // End to end: the capture became evidence that answered, and the + // classifier made the right thing of it. + assert!(icds.did_answer()); + assert_eq!(icds.found().len(), 2, "{icds:?}"); + assert_eq!(amd_icd_driver_label(&icds.found()[0]), Some("AMDVLK")); + let support = classify_vulkan_support(icds, VulkanEvidence::unanswered(), true); + assert_eq!( + support.status, + VulkanStatus::DriverPresentDevicesUnverified, + "a registry that named an AMD driver has an installed driver behind it, even with no \ + `vulkaninfo` to enumerate a device: {support:?}" + ); + + // The other end of the same wiring: a PowerShell that never answered + // must come out of the whole path as "could not look", not as a host + // with an empty registry key. + let unread = windows_icds_through(|_program, _args| None); + assert!( + !unread.did_answer() && unread.found().is_empty(), + "{unread:?}" + ); + assert_eq!( + classify_vulkan_support(unread, VulkanEvidence::unanswered(), true).status, + VulkanStatus::Inconclusive + ); + } + + /// The capture-to-evidence half on its own: what each shape of PowerShell + /// output becomes. The failure and timeout paths all arrive here as one + /// `None`, so this is where they are covered; the test above covers the + /// argv that produces it. + #[test] + fn a_powershell_that_never_answered_is_not_an_empty_registry_key() { + // Missing `powershell`, a non-zero exit, or a timeout: all one `None`. + let icds = windows_icds_from_capture(None); + assert!( + icds.found().is_empty() && !icds.did_answer(), + "a run that produced no output did not read the registry" + ); + assert_eq!( + classify_vulkan_support(icds, VulkanEvidence::unanswered(), true).status, + VulkanStatus::Inconclusive, + "so it must not be reported as a confirmed absence" + ); + + // Exit 0 with no `ICD` row: the key really is empty, and that answer is + // what a host with no Vulkan driver installed looks like. + let icds = windows_icds_from_capture(Some(String::new())); + assert!( + icds.found().is_empty() && icds.did_answer(), + "an empty answer is still an answer" + ); + assert_eq!( + classify_vulkan_support(icds, VulkanEvidence::answered(Vec::new()), true).status, + VulkanStatus::Absent, + "and that one has earned the confirmed absence" + ); + + let icds = windows_icds_from_capture(Some( + "ICD\tC:\\Windows\\System32\\amdvlk64.json\n".to_owned(), + )); + assert!(icds.did_answer()); + assert_eq!(icds.found().len(), 1, "{icds:?}"); + assert_eq!(amd_icd_driver_label(&icds.found()[0]), Some("AMDVLK")); + } + + /// A confirmed AMD Vulkan path must never be attributed to another vendor's + /// driver. `detect_icds` sorts alphabetically on Linux, so on a host with + /// both manifests installed `nvidia_icd.json` comes first: any fallback + /// looser than "AMD only" names NVIDIA as the driver behind an AMD device + /// the probe has already confirmed. + #[test] + fn a_dual_vendor_host_names_the_amd_driver_behind_a_confirmed_amd_device() { + // The AMD entry omits the optional `driverName`, which is the only + // reason the ICD fallback runs at all. + let dual_vendor = "\ +GPU0: +\tvendorID = 0x10de +\tdeviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU +\tdeviceName = NVIDIA GeForce GTX 1050 Ti +\tdriverName = NVIDIA +GPU1: +\tvendorID = 0x1002 +\tdeviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU +\tdeviceName = AMD Radeon RX 7900 XTX +"; + let devices = parse_vulkaninfo_summary(dual_vendor); + assert_eq!(devices.len(), 2, "{devices:?}"); + assert!( + devices[1].is_amd() && devices[1].driver_name.is_none(), + "{devices:?}" + ); + + let support = classify_vulkan_support( + // Alphabetical, as `detect_icds` returns them on Linux. + VulkanEvidence::answered(vec![ + "nvidia_icd.json".to_owned(), + "radeon_icd.x86_64.json".to_owned(), + ]), + VulkanEvidence::answered(devices), + true, + ); + + assert_eq!(support.status, VulkanStatus::Available); + assert_eq!( + support.driver_label().as_deref(), + Some("Mesa RADV"), + "the confirmed device is AMD's, so only an AMD manifest may name its driver: \ + {support:?}" + ); + + // The sibling instance: the sentence that justifies offering a host a + // Vulkan path when no AMD device was confirmed at all. + let unconfirmed = classify_vulkan_support( + VulkanEvidence::answered(vec![ + "nvidia_icd.json".to_owned(), + "radeon_icd.x86_64.json".to_owned(), + ]), + VulkanEvidence::unanswered(), + true, + ); + let unconfirmed_detail = unconfirmed.detail.as_deref().unwrap_or_default(); + assert!( + unconfirmed_detail.starts_with("Mesa RADV is installed"), + "the AMD manifest must open the sentence an AMD GPU is routed on: {unconfirmed:?}" + ); + assert!(!unconfirmed_detail.contains("NVIDIA"), "{unconfirmed:?}"); + + // A host where NVIDIA genuinely is all there is still gets named it: + // that status claims nothing about AMD. But `driver_label` — which only + // ever speaks for a confirmed AMD device — must stay silent. + let nvidia_only = classify_vulkan_support( + VulkanEvidence::answered(vec!["nvidia_icd.json".to_owned()]), + VulkanEvidence::unanswered(), + true, + ); + assert!( + nvidia_only + .detail + .as_deref() + .is_some_and(|detail| detail.starts_with("NVIDIA is installed")), + "naming the only driver there is remains correct: {nvidia_only:?}" + ); + assert_eq!( + nvidia_only.driver_label(), + None, + "no AMD device, no AMD manifest: there is no AMD driver to name: {nvidia_only:?}" + ); + + assert_eq!( + amd_icd_driver_label("radeon_icd.x86_64.json"), + Some("Mesa RADV") + ); + assert_eq!(amd_icd_driver_label("amdvlk64.json"), Some("AMDVLK")); + assert_eq!(amd_icd_driver_label("amd_icd64.json"), Some("AMDVLK")); + assert_eq!(amd_icd_driver_label("nvidia_icd.json"), None); + assert_eq!(amd_icd_driver_label("intel_icd.x86_64.json"), None); + assert_eq!( + amd_icd_driver_label("lvp_icd.x86_64.json"), + None, + "a software rasteriser is never an AMD GPU driver, so the AMD-only test still \ + excludes one" + ); + assert_eq!(amd_icd_driver_label("some_new_vendor_icd.json"), None); + } +} diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index f990b62c68..d8b5669192 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -137,7 +137,9 @@ pub use fix::{ list_recipes as list_fix_recipes, }; pub use gfx_target::{ - GpuSupportLevel, VULKAN_ONLY_SUPPORT_CLAIM, gpu_support_level, gpu_support_level_for_host_gpu, + GpuSupportLevel, VULKAN_ONLY_SUPPORT_CLAIM, VULKAN_UNCONFIRMED_CLAIM, + VULKAN_UNCONFIRMED_NEXT_STEP, VULKAN_UNCONFIRMED_NEXT_STEP_WITH_DISPLAY_DRIVER, + gpu_support_level, gpu_support_level_for_host_gpu, }; pub use gfx_target::{ extract_first_gfx_token, gfx_target_has_no_rocm_build, known_therock_families, @@ -146,10 +148,11 @@ pub use gfx_target::{ pub use hardware_root::host_path; pub use host_gpu::ldconfig_cache; pub use host_gpu::{ - DriverSummary, ExamineSummary, HostGpuSummary, WSL_ROCDXG_READY, WindowsGpuListing, - WslHostDriverProbe, WslSummary, default_engine_for_host, default_engine_for_platform, - detect_gpu_driver_version, detect_host_gfx_target, detect_host_gpu_diagnostics, - detect_host_gpu_summary, detect_system_ram_gib, has_usable_amd_gpu, is_amdgpu_device, + DriverSummary, ExamineSummary, HostGpuSummary, VulkanDevice, VulkanEvidence, VulkanStatus, + VulkanSupport, WSL_ROCDXG_READY, WindowsGpuListing, WslHostDriverProbe, WslSummary, + default_engine_for_host, default_engine_for_platform, detect_gpu_driver_version, + detect_host_gfx_target, detect_host_gpu_diagnostics, detect_host_gpu_summary, + detect_system_ram_gib, detect_vulkan_support, has_usable_amd_gpu, is_amdgpu_device, is_wsl_host, pinned_gpu_name, preferred_serve_engine_for_host_gpu_summary, usable_amd_gpu_indices, windows_amd_gpu_listing, }; diff --git a/crates/rocm-engine-protocol/Cargo.toml b/crates/rocm-engine-protocol/Cargo.toml index 31af67a769..d9f9fa82b4 100644 --- a/crates/rocm-engine-protocol/Cargo.toml +++ b/crates/rocm-engine-protocol/Cargo.toml @@ -11,10 +11,8 @@ publish.workspace = true workspace = true [features] -# Compiles the test-only modules into the test builds that turn it on (`rocm`, -# `rocmd`, and the `lemonade`, `vllm` and `aim` engines): `fake_engine`, a -# stand-in engine child (Unix only), and `engine_contract`, the shared engine -# protocol contract check. Never enabled in a release build. +# Compiles `fake_engine`, a stand-in engine child for tests, into the `rocm` and +# `rocmd` test builds. Never enabled in a release build. test-support = [] [dependencies] diff --git a/crates/rocm-engine-protocol/src/fake_engine.rs b/crates/rocm-engine-protocol/src/fake_engine.rs index d8ed29d004..dc90a42449 100644 --- a/crates/rocm-engine-protocol/src/fake_engine.rs +++ b/crates/rocm-engine-protocol/src/fake_engine.rs @@ -5,15 +5,13 @@ //! A stand-in engine child for tests. //! //! It is a `/bin/sh` script that records how it was launched (arguments, -//! environment, stdin, and the environment and request of each of its runs) into a -//! scratch directory and then runs a caller-supplied +//! environment, stdin) into a scratch directory and then runs a caller-supplied //! body, so a test can assert what an engine IPC client put on the child's //! command line, environment and stdin, and shape what comes back (a response //! envelope, a crash, stderr output). //! -//! Test-only: compiled for this crate's own tests and for every test build -//! that turns on the `test-support` feature (`rocm`, `rocmd`, and the three -//! engine crates, which turn it on for `engine_contract`), so the two engine +//! Test-only: compiled for this crate's own tests and for the `rocm` and +//! `rocmd` test builds through the `test-support` feature, so the two engine //! IPC callers are exercised against the same fake rather than each growing a //! private one. Unix-only, because the fake is a shell script; the pure parts //! of the client are tested on every platform without it. @@ -61,14 +59,14 @@ impl FakeEngine { fs::create_dir_all(&dir).expect("create the fake engine's scratch directory"); let script = dir.join("engine.sh"); let read_stdin = if reads_stdin { - "cat > \"$dir/stdin\"\ncat \"$dir/stdin\" >> \"$dir/requests\"\n" + "cat > \"$dir/stdin\"\n" } else { "" }; rocm_core::fake_executable::write_fake_executable( &script, format!( - "#!/bin/sh\ndir={}\nprintf '%s\\n' \"$@\" > \"$dir/argv\"\nenv > \"$dir/env\"\nrun=0\nwhile [ -e \"$dir/env.$run\" ]; do run=$((run + 1)); done\nenv > \"$dir/env.$run\"\nprintf '%s\\n' \"$@\" > \"$dir/argv.$run\"\n{read_stdin}{body}\n", + "#!/bin/sh\ndir={}\nprintf '%s\\n' \"$@\" > \"$dir/argv\"\nenv > \"$dir/env\"\n{read_stdin}{body}\n", shell_quote(&dir.to_string_lossy()) ), ) @@ -90,79 +88,25 @@ impl FakeEngine { &self.script } - /// The arguments the fake was started with the last time it was run, one - /// per entry. + /// The arguments the fake was started with, one per entry. pub fn argv(&self) -> Vec { - Self::lines_of(&self.dir.join("argv")) - } - - /// The arguments the fake was started with the `run`-th time it was run - /// (0 is the first), one per entry. - pub fn argv_of_run(&self, run: usize) -> Vec { - Self::lines_of(&self.dir.join(format!("argv.{run}"))) - } - - fn lines_of(file: &Path) -> Vec { - fs::read_to_string(file) - .unwrap_or_else(|error| { - panic!( - "the fake engine recorded no arguments at {}: {error}", - file.display() - ) - }) + fs::read_to_string(self.dir.join("argv")) + .expect("the fake engine never recorded its arguments") .lines() .map(str::to_owned) .collect() } - /// Every request the fake read, one per time it was run, oldest first. A - /// fake that was never run (or never read its stdin) has an empty list. - pub fn requests(&self) -> Vec { - fs::read_to_string(self.dir.join("requests")) - .unwrap_or_default() - .lines() - .map(|line| { - serde_json::from_str(line) - .unwrap_or_else(|error| panic!("a request is not JSON ({error}): {line:?}")) - }) - .collect() - } - - /// The `method` of every request the fake read, oldest first. - pub fn methods(&self) -> Vec { - self.requests() - .iter() - .map(|request| request["method"].as_str().unwrap_or_default().to_owned()) - .collect() - } - - /// Everything the fake read from its stdin the last time it was run, - /// verbatim. + /// Everything the fake read from its stdin, verbatim. pub fn stdin(&self) -> String { fs::read_to_string(self.dir.join("stdin")).expect("the fake engine never read its stdin") } - /// The value of `key` in the fake's environment the last time it was run, - /// if it was set. + /// The value of `key` in the fake's environment, if it was set. pub fn env(&self, key: &str) -> Option { - Self::env_in(&self.dir.join("env"), key) - } - - /// The value of `key` in the fake's environment the `run`-th time it was - /// started (0 is the first), if it was set. - pub fn env_of_run(&self, run: usize, key: &str) -> Option { - Self::env_in(&self.dir.join(format!("env.{run}")), key) - } - - fn env_in(file: &Path, key: &str) -> Option { let prefix = format!("{key}="); - fs::read_to_string(file) - .unwrap_or_else(|error| { - panic!( - "the fake engine recorded no environment at {}: {error}", - file.display() - ) - }) + fs::read_to_string(self.dir.join("env")) + .expect("the fake engine never recorded its environment") .lines() .find_map(|line| line.strip_prefix(&prefix).map(str::to_owned)) } diff --git a/crates/rocm-engine-protocol/src/lib.rs b/crates/rocm-engine-protocol/src/lib.rs index 18533ad1fd..04b42910ed 100644 --- a/crates/rocm-engine-protocol/src/lib.rs +++ b/crates/rocm-engine-protocol/src/lib.rs @@ -5,14 +5,6 @@ #[cfg(all(unix, any(test, feature = "test-support")))] pub mod fake_engine; -mod protocol_version; -#[cfg(any(test, feature = "test-support"))] -pub use protocol_version::engine_contract; -pub use protocol_version::{ - INCOMPATIBLE_PROTOCOL_CODE, INVALID_PAYLOAD_CODE, INVALID_REQUEST_CODE, - PRE_VERSIONING_PROTOCOL, ProtocolMismatch, UNKNOWN_METHOD_CODE, answer_engine_request, - engine_protocol_compatible, incompatible_request_response, -}; mod stdio_client; pub use stdio_client::{ ENGINE_PROGRESS_STDERR_ENV, EngineStdioOptions, decode_engine_response, @@ -26,11 +18,6 @@ use std::collections::BTreeMap; use std::fs; use std::path::{Path, PathBuf}; -/// The version of the engine stdio protocol this build speaks. -/// -/// It is carried in every request and answer as `protocol_version`. See the -/// `protocol_version` module for what a missing field means, the compatibility -/// rule and when to raise it. pub const ENGINE_PROTOCOL_VERSION: &str = "0.1.0"; pub const ENGINE_RECIPE_CONTRACT_VERSION: &str = "0.1.0"; pub const ENGINE_PLUGIN_BINARY_PREFIX: &str = "rocm-engine-"; @@ -282,61 +269,6 @@ pub enum EngineMethod { Logs, } -impl EngineMethod { - /// Every method, in declaration order. `every_method_is_in_all` holds this - /// list to the enum's derived decoder, so a new method that is not added - /// here fails a test rather than slipping past every loop over it. - pub const ALL: [Self; 9] = [ - Self::Detect, - Self::Install, - Self::Capabilities, - Self::ResolveModel, - Self::Launch, - Self::Healthcheck, - Self::Endpoint, - Self::Stop, - Self::Logs, - ]; - - /// The method's name on the wire (`install`, `resolve_model`, ...). - #[must_use] - pub const fn name(&self) -> &'static str { - match self { - Self::Detect => "detect", - Self::Install => "install", - Self::Capabilities => "capabilities", - Self::ResolveModel => "resolve_model", - Self::Launch => "launch", - Self::Healthcheck => "healthcheck", - Self::Endpoint => "endpoint", - Self::Stop => "stop", - Self::Logs => "logs", - } - } - - /// Whether the client checks the engine's protocol version before sending - /// this request: the methods that install or start something (a runtime, a - /// server), which must never reach an engine that would misread them. The - /// others are answered in the engine's protocol and that answer's version is - /// checked instead. - /// - /// `stop` changes state too, and is left out on purpose: it starts no extra - /// child for a check first, so a stop is never held behind one. An engine - /// that checks the version refuses a `stop` made for a protocol it cannot - /// serve, before reading its payload. An engine from before the field ignores - /// the version and acts on the `stop`; its answer names no version and reads - /// as `0.1.0`, so the client accepts it while this release's protocol is - /// `0.1.x` and refuses it once the protocol is past that. When the engine's - /// answer is an error or is refused, the stop paths in `rocm` and `rocmd` - /// still signal the server's recorded processes themselves; only for an - /// engine whose stop alone can confirm it (`aim`) does that leave the stop - /// unconfirmed. - #[must_use] - pub const fn requires_protocol_handshake(&self) -> bool { - matches!(self, Self::Install | Self::Launch) - } -} - #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] #[serde(rename_all = "snake_case")] pub enum DevicePolicy { @@ -430,28 +362,11 @@ pub fn launch_gpu_indices(selection: Option<&GpuSelection>) -> Vec { #[derive(Debug, Clone, Serialize, Deserialize)] pub struct EngineRequestEnvelope { - /// The protocol the request was written in; absent means - /// [`PRE_VERSIONING_PROTOCOL`]. - #[serde(default, skip_serializing_if = "Option::is_none")] - pub protocol_version: Option, pub method: EngineMethod, #[serde(default)] pub payload: Value, } -impl EngineRequestEnvelope { - /// A request for `method` with `payload`, written in this build's - /// [`ENGINE_PROTOCOL_VERSION`]. - #[must_use] - pub fn new(method: EngineMethod, payload: Value) -> Self { - Self { - protocol_version: Some(ENGINE_PROTOCOL_VERSION.to_owned()), - method, - payload, - } - } -} - #[derive(Debug, Clone, Serialize, Deserialize)] pub struct EngineErrorDetail { pub code: String, @@ -460,10 +375,6 @@ pub struct EngineErrorDetail { #[derive(Debug, Clone, Serialize, Deserialize)] pub struct EngineResponseEnvelope { - /// The protocol the answer was written in; absent means - /// [`PRE_VERSIONING_PROTOCOL`]. - #[serde(default, skip_serializing_if = "Option::is_none")] - pub protocol_version: Option, pub ok: bool, #[serde(skip_serializing_if = "Option::is_none")] pub data: Option, @@ -477,7 +388,6 @@ impl EngineResponseEnvelope { T: Serialize, { Self { - protocol_version: Some(ENGINE_PROTOCOL_VERSION.to_owned()), ok: true, data: Some(serde_json::to_value(data).expect("serializable response")), error: None, @@ -486,7 +396,6 @@ impl EngineResponseEnvelope { pub fn failure(code: impl Into, message: impl Into) -> Self { Self { - protocol_version: Some(ENGINE_PROTOCOL_VERSION.to_owned()), ok: false, data: None, error: Some(EngineErrorDetail { @@ -1162,131 +1071,14 @@ mod tests { #[test] fn request_roundtrip_preserves_method() { - let envelope = EngineRequestEnvelope::new( - EngineMethod::Detect, - serde_json::json!({ "runtime_id": "therock-release" }), - ); + let envelope = EngineRequestEnvelope { + method: EngineMethod::Detect, + payload: serde_json::json!({ "runtime_id": "therock-release" }), + }; let serialized = serde_json::to_string(&envelope).unwrap(); let parsed: EngineRequestEnvelope = serde_json::from_str(&serialized).unwrap(); assert_eq!(parsed.method, EngineMethod::Detect); - assert_eq!( - parsed.protocol_version.as_deref(), - Some(ENGINE_PROTOCOL_VERSION) - ); - } - - /// Every message this build writes names the protocol it was written in, - /// and a message from before the field existed still reads, with no version. - #[test] - fn envelopes_carry_this_builds_protocol_version_and_tolerate_its_absence() { - let request = serde_json::to_value(EngineRequestEnvelope::new( - EngineMethod::Stop, - serde_json::json!({}), - )) - .unwrap(); - assert_eq!(request["protocol_version"], ENGINE_PROTOCOL_VERSION); - let success = serde_json::to_value(EngineResponseEnvelope::success(1)).unwrap(); - assert_eq!(success["protocol_version"], ENGINE_PROTOCOL_VERSION); - let failure = serde_json::to_value(EngineResponseEnvelope::failure("c", "m")).unwrap(); - assert_eq!(failure["protocol_version"], ENGINE_PROTOCOL_VERSION); - - let legacy_request: EngineRequestEnvelope = - serde_json::from_str(r#"{"method":"stop","payload":{}}"#).unwrap(); - assert_eq!(legacy_request.protocol_version, None); - let legacy_response: EngineResponseEnvelope = - serde_json::from_str(r#"{"ok":true,"data":{}}"#).unwrap(); - assert_eq!(legacy_response.protocol_version, None); - - // And a message with no version is written without the field, as one - // from before it was. - let mut request = EngineRequestEnvelope::new(EngineMethod::Stop, serde_json::json!({})); - request.protocol_version = None; - let request = serde_json::to_value(request).unwrap(); - assert!(request.get("protocol_version").is_none(), "{request}"); - let mut response = EngineResponseEnvelope::success(1); - response.protocol_version = None; - let response = serde_json::to_value(response).unwrap(); - assert!(response.get("protocol_version").is_none(), "{response}"); - } - - /// `EngineMethod::ALL` lists every variant, checked against the enum's own - /// derive: decoding a name that is not a method fails with the full list of - /// method names serde knows, so a variant added to the enum and not to - /// `ALL` fails here. - #[test] - fn every_method_is_in_all() { - let error = serde_json::from_value::(serde_json::json!("not-a-method")) - .unwrap_err() - .to_string(); - let known: Vec<&str> = error - .split_once("expected one of ") - .unwrap_or_else(|| panic!("unexpected serde error: {error}")) - .1 - .split(", ") - .map(|name| name.trim_matches('`')) - .collect(); - let listed: Vec<&str> = EngineMethod::ALL.iter().map(EngineMethod::name).collect(); - assert_eq!(listed, known); - } - - /// Each method is put on one side of the protocol check by hand: the match - /// is exhaustive, so a new method does not compile here until someone - /// decides whether the client checks the engine's protocol before sending it. - #[test] - fn every_method_is_placed_on_one_side_of_the_protocol_check() { - for method in EngineMethod::ALL { - let checked_first = match method { - EngineMethod::Install | EngineMethod::Launch => true, - EngineMethod::Detect - | EngineMethod::Capabilities - | EngineMethod::ResolveModel - | EngineMethod::Healthcheck - | EngineMethod::Endpoint - | EngineMethod::Stop - | EngineMethod::Logs => false, - }; - assert_eq!( - method.requires_protocol_handshake(), - checked_first, - "{method:?}" - ); - } - } - - #[test] - fn error_codes_have_their_wire_spellings() { - assert_eq!(INCOMPATIBLE_PROTOCOL_CODE, "incompatible_protocol"); - assert_eq!(UNKNOWN_METHOD_CODE, "unknown_method"); - assert_eq!(INVALID_REQUEST_CODE, "invalid_request"); - assert_eq!(INVALID_PAYLOAD_CODE, "invalid_payload"); - } - - /// A field this build does not know, as a newer protocol on the same minor - /// may add, is ignored in both envelopes rather than refused. - #[test] - fn envelopes_ignore_a_field_they_do_not_know() { - let request: EngineRequestEnvelope = serde_json::from_str( - r#"{"protocol_version":"0.1.9","method":"stop","payload":{},"hint":"new"}"#, - ) - .unwrap(); - assert_eq!(request.method, EngineMethod::Stop); - let response: EngineResponseEnvelope = serde_json::from_str( - r#"{"protocol_version":"0.1.9","ok":true,"data":{"stopped":true},"hint":"new"}"#, - ) - .unwrap(); - assert!(response.ok); - assert_eq!(response.data, Some(serde_json::json!({"stopped": true}))); - } - - #[test] - fn method_names_match_the_wire_spelling() { - for method in EngineMethod::ALL { - assert_eq!( - serde_json::to_value(&method).unwrap(), - serde_json::json!(method.name()) - ); - } } #[test] diff --git a/crates/rocm-engine-protocol/src/protocol_version.rs b/crates/rocm-engine-protocol/src/protocol_version.rs deleted file mode 100644 index e706663077..0000000000 --- a/crates/rocm-engine-protocol/src/protocol_version.rs +++ /dev/null @@ -1,775 +0,0 @@ -// Copyright © Advanced Micro Devices, Inc., or its affiliates. -// -// SPDX-License-Identifier: MIT - -//! Which engine protocol a request or an answer was written in, and whether -//! the other side can use it. -//! -//! Every request and every answer carries `protocol_version`, the -//! [`ENGINE_PROTOCOL_VERSION`] of the side that wrote it, as a -//! `MAJOR.MINOR.PATCH` string. A message without one was written before the -//! field existed and is read as [`PRE_VERSIONING_PROTOCOL`] (`0.1.0`), so an -//! engine or a daemon from an earlier release keeps working with this one. -//! -//! Two versions are compatible by the caret rule: while the major is `0`, the -//! major and the minor must both match (`0.1.0` and `0.1.9` are, `0.1.0` and -//! `0.2.0` are not); from `1.0.0` on, the major alone must match. The patch -//! never decides, in either direction. A `MAJOR.MINOR.PATCH` version here is -//! three dot-separated plain decimal numbers, each without a leading zero -//! (`0` itself aside) and fitting in 64 bits. Anything else cannot be compared -//! with anything, and is treated as incompatible and reported as unreadable -//! rather than as a different version. -//! -//! [`ENGINE_PROTOCOL_VERSION`] `0.1.0` is the baseline: it is the release that -//! introduced the field, and it speaks the same format as the messages written -//! before it, which is why a missing field and `0.1.0` mean the same thing. -//! -//! Rules for raising [`ENGINE_PROTOCOL_VERSION`] from there. They are this -//! protocol's own: the recipe hint's `ENGINE_RECIPE_CONTRACT_VERSION` is -//! compared as an exact string, and the `rocm fix` catalog keeps its number on -//! an addition, so neither is the model here. -//! - An **addition** an older peer can ignore — a new optional field, a new -//! method only an engine ever offers — raises the patch, which every peer on -//! the same minor (major, from `1.0.0`) still accepts. -//! - A **new method a client may send** raises the minor while the major is -//! `0`, and the major after that: an older engine cannot decode it and would -//! answer `unknown_method` (see [`answer_engine_request`]). The exception is a -//! method the client sends only to an engine whose capabilities say it has it. -//! - A **removal or a type change** — a field dropped, renamed, made required or -//! given another type — raises the minor while the major is `0`, and the major -//! from `1.0.0` on, so that a peer that would misread the message refuses it -//! instead of guessing. -//! -//! An engine reads a request's version before anything else in it, its method -//! included, and refuses a request it cannot serve with an error answer whose -//! code is [`INCOMPATIBLE_PROTOCOL_CODE`] ([`answer_engine_request`] for a -//! request read from stdin, [`incompatible_request_response`] for one already -//! decoded). The client checks the version of an answer that is a single JSON -//! object before anything else in it, and before an `install` or a `launch` -//! it first asks the engine for its capabilities and checks the version of -//! that answer, so a request that installs or starts something is never sent -//! to an engine that cannot read it. - -use serde_json::Value; - -use crate::{ENGINE_PROTOCOL_VERSION, EngineMethod, EngineRequestEnvelope, EngineResponseEnvelope}; - -/// The version a request or an answer without `protocol_version` was written -/// in: the format from before the field existed. -pub const PRE_VERSIONING_PROTOCOL: &str = "0.1.0"; - -/// The error code an engine answers with when a request was made for a -/// protocol it cannot serve. -pub const INCOMPATIBLE_PROTOCOL_CODE: &str = "incompatible_protocol"; - -/// The error code an engine answers with when a request in a protocol it can -/// serve names a method it does not have. -pub const UNKNOWN_METHOD_CODE: &str = "unknown_method"; - -/// The error code an engine answers with when what it was sent is not a -/// request envelope at all. -pub const INVALID_REQUEST_CODE: &str = "invalid_request"; - -/// The error code an engine answers with when a request's payload does not -/// decode as that method's request. -pub const INVALID_PAYLOAD_CODE: &str = "invalid_payload"; - -/// Why two engine protocol versions cannot be used together. -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum ProtocolMismatch { - /// Both versions are readable, and the caret rule says they differ. - Incompatible { ours: String, theirs: String }, - /// The other side's version is not a `MAJOR.MINOR.PATCH` version. - Unreadable { ours: String, theirs: String }, -} - -/// `version` as its three numbers, or `None` when it is not exactly -/// `MAJOR.MINOR.PATCH` as the module documentation defines it. -fn parse_version(version: &str) -> Option<(u64, u64, u64)> { - let mut parts = version.split('.'); - let mut number = || { - let part = parts.next()?; - if part.is_empty() - || !part.bytes().all(|byte| byte.is_ascii_digit()) - || (part.len() > 1 && part.starts_with('0')) - { - return None; - } - part.parse::().ok() - }; - let parsed = (number()?, number()?, number()?); - if parts.next().is_some() { - return None; - } - Some(parsed) -} - -/// Whether a side that speaks `ours` can use a peer that speaks `theirs`. -/// -/// The rule is the caret rule in the module documentation. `None` is a message -/// written before the field existed, read as [`PRE_VERSIONING_PROTOCOL`]. -/// -/// `ours` is this build's own constant; should it ever fail to parse, nothing -/// is compatible with it, which a test of [`ENGINE_PROTOCOL_VERSION`] rules out. -pub fn engine_protocol_compatible( - ours: &str, - theirs: Option<&str>, -) -> Result<(), ProtocolMismatch> { - let theirs = theirs.unwrap_or(PRE_VERSIONING_PROTOCOL); - let Some(their_version) = parse_version(theirs) else { - return Err(ProtocolMismatch::Unreadable { - ours: ours.to_owned(), - theirs: theirs.to_owned(), - }); - }; - let compatible = parse_version(ours).is_some_and(|our_version| { - if our_version.0 == 0 || their_version.0 == 0 { - our_version.0 == their_version.0 && our_version.1 == their_version.1 - } else { - our_version.0 == their_version.0 - } - }); - if compatible { - Ok(()) - } else { - Err(ProtocolMismatch::Incompatible { - ours: ours.to_owned(), - theirs: theirs.to_owned(), - }) - } -} - -/// The answer an engine gives instead of serving `request` when the request -/// was made for a protocol this build cannot serve, or `None` when it can. -/// -/// Each engine calls this before it decodes the payload, so a request whose -/// payload means something else in another protocol is never acted on. A -/// request read from text goes through [`answer_engine_request`], which judges -/// the version before the method is even decoded. -#[must_use] -pub fn incompatible_request_response( - request: &EngineRequestEnvelope, -) -> Option { - refusal_for(request.protocol_version.as_deref()) -} - -/// The `incompatible_protocol` answer to a request that named `theirs`, or -/// `None` when this build can serve it. -fn refusal_for(theirs: Option<&str>) -> Option { - let mismatch = engine_protocol_compatible(ENGINE_PROTOCOL_VERSION, theirs).err()?; - let message = match &mismatch { - ProtocolMismatch::Incompatible { ours, theirs } => format!( - "this engine speaks engine protocol {ours}; the request was made for protocol \ - {theirs}, which it cannot serve" - ), - ProtocolMismatch::Unreadable { ours, theirs } => format!( - "this engine speaks engine protocol {ours}; the request named protocol version \ - {theirs:?}, which is not a MAJOR.MINOR.PATCH version, so it cannot be served" - ), - }; - Some(EngineResponseEnvelope::failure( - INCOMPATIBLE_PROTOCOL_CODE, - message, - )) -} - -/// The `protocol_version` a JSON object names, read without decoding the -/// rest of it: `None` when it is absent or `null`, the string itself, or, for -/// any other type, its JSON text (which is never a readable version). Both -/// sides use it to judge a message's version before decoding the message. -pub(crate) fn raw_protocol_version(value: &Value) -> Option { - match value.get("protocol_version") { - None | Some(Value::Null) => None, - Some(Value::String(version)) => Some(version.clone()), - Some(other) => Some(other.to_string()), - } -} - -/// Answer the request an engine read from its stdin, as `text`: judge its -/// `protocol_version` first, then decode the rest and hand it to `handle`. -/// -/// The version is read from the request as plain JSON before the envelope is -/// decoded, so a request made for another protocol is refused with -/// [`INCOMPATIBLE_PROTOCOL_CODE`] whatever its method is (a later protocol may -/// add methods this build cannot decode) and whatever type its version has (a -/// version that is present and neither a string nor `null` is unreadable, like -/// one that is not `MAJOR.MINOR.PATCH`; `null` is read like a missing version, -/// as [`PRE_VERSIONING_PROTOCOL`]). A request this build can serve that names a -/// method it does not have is answered with [`UNKNOWN_METHOD_CODE`], and text -/// that is not a request envelope at all, including JSON that is not an object, -/// with [`INVALID_REQUEST_CODE`]. Every outcome is an answer envelope. Input -/// that cannot be read as text (not valid UTF-8) never reaches this function: -/// the engine's stdio command fails reading it, and there is no answer. -pub fn answer_engine_request( - text: &str, - handle: impl FnOnce(EngineRequestEnvelope) -> EngineResponseEnvelope, -) -> EngineResponseEnvelope { - let value: Value = match serde_json::from_str(text) { - Ok(value) => value, - Err(error) => { - return EngineResponseEnvelope::failure( - INVALID_REQUEST_CODE, - format!("the request is not JSON: {error}"), - ); - } - }; - // A derived struct also decodes from a JSON array of its fields in order, - // which no client writes; an array has no `protocol_version` to judge, so - // reading one by position would serve a request whose version was never - // checked. - if !value.is_object() { - return EngineResponseEnvelope::failure( - INVALID_REQUEST_CODE, - "the request is not an engine request envelope: it is not a JSON object", - ); - } - let version = raw_protocol_version(&value); - if let Some(refusal) = refusal_for(version.as_deref()) { - return refusal; - } - if let Some(Value::String(method)) = value.get("method") - && serde_json::from_value::(Value::String(method.clone())).is_err() - { - return EngineResponseEnvelope::failure( - UNKNOWN_METHOD_CODE, - format!( - "this engine (engine protocol {ENGINE_PROTOCOL_VERSION}) has no method {method:?}" - ), - ); - } - match serde_json::from_value::(value) { - Ok(request) => handle(request), - Err(error) => EngineResponseEnvelope::failure( - INVALID_REQUEST_CODE, - format!("the request is not an engine request envelope: {error}"), - ), - } -} - -/// The protocol contract every engine holds, as one shared check. -/// -/// Each engine's tests run it, so the three first-party engines (and `rocm`'s -/// built-in stdio verb) are held to the same list rather than to three -/// hand-copied ones. -#[cfg(any(test, feature = "test-support"))] -pub mod engine_contract { - use super::{ - ENGINE_PROTOCOL_VERSION, EngineMethod, EngineRequestEnvelope, EngineResponseEnvelope, - INCOMPATIBLE_PROTOCOL_CODE, INVALID_PAYLOAD_CODE, INVALID_REQUEST_CODE, - UNKNOWN_METHOD_CODE, - }; - - fn code(answer: &EngineResponseEnvelope) -> Option<&str> { - answer.error.as_ref().map(|error| error.code.as_str()) - } - - /// The first version the documented bump rule makes incompatible with - /// `version`: the next minor while the major is `0`, the next major after. - pub(super) fn breaking_successor(version: &str) -> String { - let (major, minor, _) = - super::parse_version(version).expect("a protocol version is MAJOR.MINOR.PATCH"); - if major == 0 { - format!("0.{}.0", minor + 1) - } else { - format!("{}.0.0", major + 1) - } - } - - #[track_caller] - fn assert_refused(engine: &str, request: &str, answer: &EngineResponseEnvelope, code_: &str) { - assert!(!answer.ok, "{engine}: {request} was served"); - assert_eq!( - code(answer), - Some(code_), - "{engine}: {request}: {:?}", - answer.error - ); - assert_eq!( - answer.protocol_version.as_deref(), - Some(ENGINE_PROTOCOL_VERSION), - "{engine}: {request}: the answer must name this build's protocol" - ); - } - - /// Check `engine` against the contract, through `answer_text` (what its - /// stdio command does with the text it read) and `handle` (its decoded - /// envelope handler, which `rocm` calls in-process): - /// - a request for an incompatible or unreadable protocol is refused with - /// `incompatible_protocol` for every method on both paths, and, on the - /// stdio path, for a method this build does not know and for a version - /// that is not a string; - /// - a compatible request naming an unknown method is `unknown_method`, and - /// text that is not a request envelope is `invalid_request`; - /// - `capabilities` in this protocol, and with no version at all, is served, - /// and an `install` or `launch` with an empty payload reaches the engine's - /// own decoding (`invalid_payload`), with this build's version on every - /// answer. - #[track_caller] - pub fn assert_engine_holds_protocol_contract( - engine: &str, - answer_text: impl Fn(&str) -> EngineResponseEnvelope, - handle: impl Fn(EngineRequestEnvelope) -> EngineResponseEnvelope, - ) { - let breaking = breaking_successor(ENGINE_PROTOCOL_VERSION); - let breaking_text = format!("{breaking:?}"); - for theirs in [breaking_text.as_str(), r#""banana""#, "2", "[0,1,0]"] { - for method in EngineMethod::ALL - .iter() - .map(EngineMethod::name) - .chain(["frobnicate"]) - { - let request = format!( - r#"{{"protocol_version":{theirs},"method":"{method}","payload":{{}}}}"# - ); - assert_refused( - engine, - &request, - &answer_text(&request), - INCOMPATIBLE_PROTOCOL_CODE, - ); - } - } - for method in EngineMethod::ALL { - for theirs in [breaking.as_str(), "banana"] { - let mut request = EngineRequestEnvelope::new(method.clone(), serde_json::json!({})); - request.protocol_version = Some(theirs.to_owned()); - let label = format!("decoded {method:?} for {theirs}"); - assert_refused(engine, &label, &handle(request), INCOMPATIBLE_PROTOCOL_CODE); - } - } - - let unknown = format!( - r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","method":"frobnicate","payload":{{}}}}"# - ); - assert_refused( - engine, - &unknown, - &answer_text(&unknown), - UNKNOWN_METHOD_CODE, - ); - let no_method = format!(r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}"}}"#); - let by_position = format!(r#"["{ENGINE_PROTOCOL_VERSION}","capabilities",{{}}]"#); - for garbage in ["not json", no_method.as_str(), "[]", by_position.as_str()] { - assert_refused(engine, garbage, &answer_text(garbage), INVALID_REQUEST_CODE); - } - - let current = format!( - r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","method":"capabilities"}}"# - ); - let mut served = vec![current.as_str()]; - // A request with no version is one written before the field existed, - // `0.1.0`; it is served only while this build can serve that. - if super::engine_protocol_compatible(ENGINE_PROTOCOL_VERSION, None).is_ok() { - served.push(r#"{"method":"capabilities","payload":{}}"#); - } - for request in served { - let answer = answer_text(request); - assert!(answer.ok, "{engine}: {request}: {:?}", answer.error); - assert_eq!( - answer.protocol_version.as_deref(), - Some(ENGINE_PROTOCOL_VERSION), - "{engine}: {request}: a served answer must name this build's protocol" - ); - } - for method in [EngineMethod::Install, EngineMethod::Launch] { - let label = format!("decoded {method:?} with an empty payload"); - let answer = handle(EngineRequestEnvelope::new(method, serde_json::json!({}))); - assert_refused(engine, &label, &answer, INVALID_PAYLOAD_CODE); - } - } -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::EngineMethod; - use serde_json::json; - - /// The compatibility rule as a table, from this build's own version. - /// Runs on every platform, Windows included. - #[test] - fn the_caret_rule_from_this_builds_version() { - assert_eq!( - ENGINE_PROTOCOL_VERSION, "0.1.0", - "the table below is written for 0.1.0" - ); - let incompatible = |theirs: &str| ProtocolMismatch::Incompatible { - ours: "0.1.0".to_owned(), - theirs: theirs.to_owned(), - }; - let unreadable = |theirs: &str| ProtocolMismatch::Unreadable { - ours: "0.1.0".to_owned(), - theirs: theirs.to_owned(), - }; - let table: &[(Option<&str>, Result<(), ProtocolMismatch>)] = &[ - (None, Ok(())), - (Some("0.1.0"), Ok(())), - (Some("0.1.9"), Ok(())), - (Some("0.2.0"), Err(incompatible("0.2.0"))), - (Some("0.0.1"), Err(incompatible("0.0.1"))), - (Some("1.0.0"), Err(incompatible("1.0.0"))), - (Some("9.0.0"), Err(incompatible("9.0.0"))), - (Some(""), Err(unreadable(""))), - (Some("banana"), Err(unreadable("banana"))), - (Some("1.2"), Err(unreadable("1.2"))), - (Some("1.2.3.4"), Err(unreadable("1.2.3.4"))), - (Some("0.1.0-rc1"), Err(unreadable("0.1.0-rc1"))), - (Some("v0.1.0"), Err(unreadable("v0.1.0"))), - (Some("0..1"), Err(unreadable("0..1"))), - (Some("+0.1.0"), Err(unreadable("+0.1.0"))), - (Some("0.+1.0"), Err(unreadable("0.+1.0"))), - (Some("0.01.0"), Err(unreadable("0.01.0"))), - (Some("00.1.0"), Err(unreadable("00.1.0"))), - ( - Some("99999999999999999999.0.0"), - Err(unreadable("99999999999999999999.0.0")), - ), - ]; - for (theirs, expected) in table { - assert_eq!( - &engine_protocol_compatible(ENGINE_PROTOCOL_VERSION, *theirs), - expected, - "theirs: {theirs:?}" - ); - } - } - - /// From `1.0.0` on, only the major decides. - #[test] - fn past_one_the_major_alone_decides() { - assert_eq!(engine_protocol_compatible("1.2.0", Some("1.9.4")), Ok(())); - assert_eq!(engine_protocol_compatible("1.2.0", Some("1.0.0")), Ok(())); - assert!(engine_protocol_compatible("1.2.0", Some("2.0.0")).is_err()); - assert!(engine_protocol_compatible("1.2.0", Some("0.2.0")).is_err()); - // A peer that sends nothing is 0.1.0, which a 1.x side cannot use. - assert!(engine_protocol_compatible("1.0.0", None).is_err()); - } - - #[test] - fn this_builds_version_is_readable() { - assert!(parse_version(ENGINE_PROTOCOL_VERSION).is_some()); - assert!(parse_version(PRE_VERSIONING_PROTOCOL).is_some()); - } - - #[test] - fn a_request_this_engine_can_serve_gets_no_refusal() { - for version in [None, Some(ENGINE_PROTOCOL_VERSION), Some("0.1.7")] { - let mut request = EngineRequestEnvelope::new(EngineMethod::Stop, json!({})); - request.protocol_version = version.map(str::to_owned); - assert!( - incompatible_request_response(&request).is_none(), - "{version:?}" - ); - } - } - - #[test] - fn a_request_for_another_protocol_is_refused_naming_both_versions() { - let mut request = EngineRequestEnvelope::new(EngineMethod::Install, json!({})); - request.protocol_version = Some("0.2.0".to_owned()); - let response = incompatible_request_response(&request).expect("refused"); - assert!(!response.ok); - assert_eq!( - response.protocol_version.as_deref(), - Some(ENGINE_PROTOCOL_VERSION) - ); - let error = response.error.expect("an error"); - assert_eq!(error.code, INCOMPATIBLE_PROTOCOL_CODE); - assert_eq!( - error.message, - format!( - "this engine speaks engine protocol {ENGINE_PROTOCOL_VERSION}; the request was made for protocol 0.2.0, \ - which it cannot serve" - ) - ); - - request.protocol_version = Some("banana".to_owned()); - let error = incompatible_request_response(&request) - .expect("refused") - .error - .expect("an error"); - assert_eq!(error.code, INCOMPATIBLE_PROTOCOL_CODE); - assert_eq!( - error.message, - format!( - "this engine speaks engine protocol {ENGINE_PROTOCOL_VERSION}; the request named protocol version \ - \"banana\", which is not a MAJOR.MINOR.PATCH version, so it cannot be served" - ) - ); - } - - /// The handler a request reaches once its version and method are judged: - /// it serves `capabilities` and rejects every other payload, the shape of - /// a first-party engine for the cases the contract check sends. - fn toy_engine(request: EngineRequestEnvelope) -> EngineResponseEnvelope { - if let Some(refusal) = incompatible_request_response(&request) { - return refusal; - } - match request.method { - EngineMethod::Capabilities => EngineResponseEnvelope::success(json!({})), - _ => EngineResponseEnvelope::failure(INVALID_PAYLOAD_CODE, "toy"), - } - } - - /// A request is judged by its version before its method: one for another - /// protocol is refused even when its method or its version's type is one - /// this build cannot decode, and each other way a request can be unusable - /// still gets an answer that says so. - #[test] - fn a_request_is_judged_by_its_version_before_its_method() { - let answer = |text: &str| answer_engine_request(text, toy_engine); - let error = |text: &str| answer(text).error.expect("an error answer"); - - let refused = error(r#"{"protocol_version":"0.2.0","method":"frobnicate"}"#); - assert_eq!(refused.code, INCOMPATIBLE_PROTOCOL_CODE); - assert_eq!( - refused.message, - format!( - "this engine speaks engine protocol {ENGINE_PROTOCOL_VERSION}; the request was made for protocol 0.2.0, \ - which it cannot serve" - ) - ); - let not_a_string = error(r#"{"protocol_version":2,"method":"stop","payload":{}}"#); - assert_eq!(not_a_string.code, INCOMPATIBLE_PROTOCOL_CODE); - assert_eq!( - not_a_string.message, - format!( - "this engine speaks engine protocol {ENGINE_PROTOCOL_VERSION}; the request named protocol version \ - \"2\", which is not a MAJOR.MINOR.PATCH version, so it cannot be served" - ) - ); - - let unknown = error(&format!( - r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","method":"frobnicate"}}"# - )); - assert_eq!(unknown.code, UNKNOWN_METHOD_CODE); - assert_eq!( - unknown.message, - format!( - "this engine (engine protocol {ENGINE_PROTOCOL_VERSION}) has no method \"frobnicate\"" - ) - ); - assert_eq!( - error(r#"{"method":"frobnicate"}"#).code, - UNKNOWN_METHOD_CODE - ); - - let not_json = error("not json"); - assert_eq!(not_json.code, INVALID_REQUEST_CODE); - assert_eq!( - not_json.message, - "the request is not JSON: expected ident at line 1 column 2" - ); - let no_method = error(&format!( - r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}"}}"# - )); - assert_eq!(no_method.code, INVALID_REQUEST_CODE); - assert_eq!( - no_method.message, - "the request is not an engine request envelope: missing field `method`" - ); - - assert!(answer(r#"{"method":"capabilities"}"#).ok); - // A newer request on the same minor, with a field this build does not - // know, is served. - assert!(answer(r#"{"protocol_version":"0.1.9","method":"capabilities","hint":"new"}"#).ok); - assert!(answer(r#"{"protocol_version":null,"method":"capabilities"}"#).ok); - } - - /// The shared contract check passes an engine that holds the contract, - /// so a red result in an engine's own test is that engine's. - #[test] - fn the_contract_check_passes_an_engine_that_holds_it() { - engine_contract::assert_engine_holds_protocol_contract( - "toy", - |text| answer_engine_request(text, toy_engine), - toy_engine, - ); - } - - /// An engine that serves a request whatever protocol it names breaks the - /// contract, and the shared check says so: a check that passed any engine - /// would make every engine's contract test meaningless. - #[test] - #[should_panic(expected = "was served")] - fn the_contract_check_fails_an_engine_that_ignores_the_version() { - fn careless(request: EngineRequestEnvelope) -> EngineResponseEnvelope { - match request.method { - EngineMethod::Install | EngineMethod::Launch => { - EngineResponseEnvelope::failure(INVALID_PAYLOAD_CODE, "toy") - } - _ => EngineResponseEnvelope::success(json!({})), - } - } - engine_contract::assert_engine_holds_protocol_contract( - "careless", - |text| match serde_json::from_str::(text) { - Ok(request) => careless(request), - Err(_) => EngineResponseEnvelope::failure(INVALID_REQUEST_CODE, "toy"), - }, - careless, - ); - } - - /// An engine whose decoded path refuses but whose stdio path does not read - /// the version first fails the check too. - #[test] - #[should_panic(expected = "incompatible_protocol")] - fn the_contract_check_fails_an_engine_whose_stdio_skips_the_version() { - engine_contract::assert_engine_holds_protocol_contract( - "stdio-skips-version", - |text| match serde_json::from_str::(text) { - Ok(mut request) => { - request.protocol_version = None; - toy_engine(request) - } - Err(_) => EngineResponseEnvelope::failure(INVALID_REQUEST_CODE, "toy"), - }, - toy_engine, - ); - } - - /// The version the contract check uses as "incompatible" is the first one - /// the bump rule makes so, for both branches of the rule, and it is - /// incompatible with this build's. - #[test] - fn the_contract_checks_breaking_version_is_the_next_incompatible_one() { - assert_eq!(engine_contract::breaking_successor("0.1.0"), "0.2.0"); - assert_eq!(engine_contract::breaking_successor("0.3.7"), "0.4.0"); - assert_eq!(engine_contract::breaking_successor("1.4.2"), "2.0.0"); - assert_eq!(engine_contract::breaking_successor("2.0.0"), "3.0.0"); - let breaking = engine_contract::breaking_successor(ENGINE_PROTOCOL_VERSION); - assert!(engine_protocol_compatible(ENGINE_PROTOCOL_VERSION, Some(&breaking)).is_err()); - } - - /// The panic message of `check`, or `None` when it did not panic. - fn panic_message(check: impl FnOnce() + std::panic::UnwindSafe) -> Option { - let payload = std::panic::catch_unwind(check).err()?; - Some( - payload - .downcast_ref::() - .cloned() - .or_else(|| { - payload - .downcast_ref::<&str>() - .map(|text| (*text).to_owned()) - }) - .unwrap_or_default(), - ) - } - - /// Six rules of the shared contract check, each failing an engine that - /// breaks that rule alone: a refusal names this build's protocol; a served - /// answer names it; an unknown method in another protocol is refused for - /// the protocol on the stdio path; the decoded path refuses another - /// protocol; a request with no version is served; an empty-payload install - /// reaches the engine's own decoding. Every toy below is the conforming toy - /// with one of these wrong, and the check must panic naming it. The check's - /// other rules have no toy here. - #[test] - fn the_contract_check_fails_an_engine_that_breaks_any_one_rule() { - type Answer = fn(&str) -> EngineResponseEnvelope; - type Handle = fn(EngineRequestEnvelope) -> EngineResponseEnvelope; - fn conforming_text(text: &str) -> EngineResponseEnvelope { - answer_engine_request(text, toy_engine) - } - fn unversioned(mut answer: EngineResponseEnvelope) -> EngineResponseEnvelope { - answer.protocol_version = None; - answer - } - // Rule: a refusal names this build's protocol. - fn refuses_unversioned(text: &str) -> EngineResponseEnvelope { - let answer = conforming_text(text); - if answer.ok { - answer - } else { - unversioned(answer) - } - } - // Rule: a served answer names this build's protocol. - fn serves_unversioned(text: &str) -> EngineResponseEnvelope { - let answer = conforming_text(text); - if answer.ok { - unversioned(answer) - } else { - answer - } - } - // Rule: an unknown method in another protocol is refused for the - // protocol, not for the method. - fn method_before_version(text: &str) -> EngineResponseEnvelope { - if text.contains(r#""method":"frobnicate""#) { - return EngineResponseEnvelope::failure(UNKNOWN_METHOD_CODE, "toy"); - } - conforming_text(text) - } - // Rule: the decoded path refuses another protocol too. - fn decoded_ignores_version(request: EngineRequestEnvelope) -> EngineResponseEnvelope { - let mut request = request; - request.protocol_version = None; - toy_engine(request) - } - // Rule: a request with no version is served as `0.1.0`. - fn refuses_unversioned_requests(text: &str) -> EngineResponseEnvelope { - let value: serde_json::Value = serde_json::from_str(text).unwrap_or_default(); - if value.get("method").is_some() && value.get("protocol_version").is_none() { - return refusal_for(Some("banana")).expect("refused"); - } - conforming_text(text) - } - // Rule: an install or launch with an empty payload reaches the - // engine's own decoding. - fn installs_anything(request: EngineRequestEnvelope) -> EngineResponseEnvelope { - if let Some(refusal) = incompatible_request_response(&request) { - return refusal; - } - EngineResponseEnvelope::success(json!({})) - } - let breaking = engine_contract::breaking_successor(ENGINE_PROTOCOL_VERSION); - let cases: [(&str, Answer, Handle, String); 6] = [ - ( - "refusal-version", - refuses_unversioned, - toy_engine, - "the answer must name this build's protocol".to_owned(), - ), - ( - "served-version", - serves_unversioned, - toy_engine, - "a served answer must name this build's protocol".to_owned(), - ), - ( - "method-first", - method_before_version, - toy_engine, - format!(r#"{{"protocol_version":"{breaking}","method":"frobnicate""#), - ), - ( - "decoded-version", - conforming_text, - decoded_ignores_version, - format!("decoded Detect for {breaking}: "), - ), - ( - "legacy-request", - refuses_unversioned_requests, - toy_engine, - r#"{"method":"capabilities","payload":{}}"#.to_owned(), - ), - ( - "empty-install", - conforming_text, - installs_anything, - "decoded Install with an empty payload was served".to_owned(), - ), - ]; - for (label, answer_text, handle, expected) in cases { - let message = panic_message(|| { - engine_contract::assert_engine_holds_protocol_contract(label, answer_text, handle); - }) - .unwrap_or_else(|| panic!("{label}: the check passed an engine that breaks it")); - assert!(message.contains(&expected), "{label}: {message}"); - } - } -} diff --git a/crates/rocm-engine-protocol/src/stdio_client.rs b/crates/rocm-engine-protocol/src/stdio_client.rs index 7b30df2d9a..cc8d31bf21 100644 --- a/crates/rocm-engine-protocol/src/stdio_client.rs +++ b/crates/rocm-engine-protocol/src/stdio_client.rs @@ -4,9 +4,7 @@ //! The client side of the engine stdio protocol: run an engine as a child //! process, send it one [`EngineRequestEnvelope`] on stdin as a single line of -//! JSON, and read one [`EngineResponseEnvelope`] back from stdout. Each child -//! serves one request; an `install` or a `launch` starts two, one after the -//! other: the `capabilities` check described below, then the request itself. +//! JSON, and read one [`EngineResponseEnvelope`] back from stdout. //! //! `rocm` and `rocmd` both talk to engines this way and share this one //! implementation. They differ in *which* process they start (`rocm` runs the @@ -18,29 +16,8 @@ //! unusable answer is reported as, and decoding the response. The few things //! the callers want differently are the fields of [`EngineStdioOptions`]. //! -//! It is also where the engine protocol version is enforced on the client side -//! (the rule is in the `protocol_version` module). An answer's -//! `protocol_version` is checked before anything else in it: by -//! [`decode_engine_response`] for an answer that decodes as an envelope, and -//! from the raw JSON object for one that does not, before its shape is. A -//! stdout that is not a single JSON object has no version to check and is -//! reported as unreadable. [`run_engine_stdio`], before an `install` or a -//! `launch`, first sends a -//! `capabilities` request through the same path and does not send the real one -//! unless that answer is in a protocol this build can use. The other methods are -//! sent once, as they are. -//! -//! The whole of an engine's stdout must be its one answer: an engine writes -//! only its JSON answer to stdout and its logs to stderr. Output that is not -//! exactly one envelope is refused, never salvaged, and the error says what was -//! wrong with it: nothing printed; other output before or after an answer, -//! which it quotes; or JSON that is not an envelope, or not JSON, quoting the -//! start of stdout. -//! //! The request and the child's lifetime are not bounded by a timeout: an engine -//! install legitimately runs for minutes, and no caller has ever set one. That -//! holds for the `capabilities` child that goes before an `install` or a -//! `launch` too, so those requests wait, unbounded, on two children in turn. +//! install legitimately runs for minutes, and no caller has ever set one. //! //! Nor is the wait for the pipes after the child has exited, and that is a known //! limit rather than an oversight. The answer is read to the end of the child's @@ -48,26 +25,23 @@ //! grandchild holding either pipe open makes the request wait for that grandchild //! to exit. Both clients this one replaces behaved the same way (`rocm` read //! stdout to the end then joined its stderr thread; `rocmd` used -//! `wait_with_output`). The `capabilities` check before an `install` or a -//! `launch` is a second child exposed to the same wait, so an engine that -//! leaves a grandchild holding a pipe can hang the check as well as the -//! request; the daemon is long lived and a hung request holds its caller. -//! Bounding it exactly would mean reading both pipes on their own threads, -//! waiting for the child itself without a limit and for the pipes only up to a -//! deadline after it exits, and choosing what to report when the deadline -//! passes (an answer already complete? a partial one?). That is a timeout -//! policy for an engine contract nothing here sets, so it is left to be decided -//! on its own. The one wait this client adds itself, for the stderr of a child -//! whose request could not be written, is bounded by `EXITED_STDERR_GRACE`. +//! `wait_with_output`), so nothing new is exposed to it, but the daemon is long +//! lived and a hung request holds its caller. Bounding it exactly would mean +//! reading both pipes on their own threads, waiting for the child itself without a +//! limit and for the pipes only up to a deadline after it exits, and choosing what +//! to report when the deadline passes (an answer already complete? a partial +//! one?). That is a timeout policy for an engine contract nothing here sets, so +//! this change leaves it to be decided on its own. The one wait this client adds +//! itself, for the stderr of a child whose request could not be written, is +//! bounded by `EXITED_STDERR_GRACE`. //! //! A request that cannot be written is the other place the answer-wins rule does //! not apply: if the engine answered and exited without draining a request larger //! than a pipe buffer, the write fails, the child is killed and its stdout is //! never read, so the error carries its stderr and not its answer. Every engine //! here (`lemonade`, `vllm`, `aim`, and the `rocm __engine-stdio` verb that serves -//! the built-in ones, once it has accepted the engine name) reads stdin to the end -//! before it answers, so reaching this needs an engine that breaks the -//! protocol. Decoding such an answer would mean +//! the built-in ones) reads stdin to the end before it answers, so reaching this +//! needs an engine that breaks the protocol. Decoding such an answer would mean //! waiting, up to a deadline, for the child to finish printing it and to exit //! before deciding it is complete, and an engine that has stopped reading is no //! engine to wait for, so it is left as a documented limit. @@ -95,7 +69,7 @@ //! thread, so an engine that fills it before draining a large request cannot //! deadlock the write. -use std::ffi::{OsStr, OsString}; +use std::ffi::OsStr; use std::io::{self, Read, Write}; use std::path::Path; use std::process::{Child, Command, ExitStatus, Stdio}; @@ -110,8 +84,7 @@ use serde::Serialize; use serde::de::DeserializeOwned; use crate::{ - ENDPOINT_API_KEY_FILE_ENV, ENGINE_PROTOCOL_VERSION, EngineMethod, EngineRequestEnvelope, - EngineResponseEnvelope, ProtocolMismatch, engine_protocol_compatible, + ENDPOINT_API_KEY_FILE_ENV, EngineMethod, EngineRequestEnvelope, EngineResponseEnvelope, }; /// Set to `1` on an engine child whose caller wants its progress lines on @@ -151,8 +124,8 @@ pub struct EngineStdioOptions<'a> { /// shown in the error when the request fails. pub forward_stderr: bool, /// Say, on this process's stderr, when the child answered and then exited - /// with a failing status. The answer is read either way (and then judged - /// like any other); this only leaves a trace of the status, which the caller would otherwise never see. For a + /// with a failing status. The answer is used either way; this only leaves a + /// trace of the status, which the caller would otherwise never see. For a /// daemon, whose stderr is its log; a terminal user has no use for it. pub note_failing_exit_after_answer: bool, } @@ -162,10 +135,11 @@ pub fn engine_request_envelope( method: EngineMethod, request: &T, ) -> Result { - Ok(EngineRequestEnvelope::new( + Ok(EngineRequestEnvelope { method, - serde_json::to_value(request).context("failed to encode engine request payload")?, - )) + payload: serde_json::to_value(request) + .context("failed to encode engine request payload")?, + }) } /// The command [`run_engine_stdio`] runs: `program` with `args`, all three @@ -213,20 +187,9 @@ where /// non-zero is read as that envelope, which says more than the status does. The /// same holds for a success envelope (`ok: true`): a child that answers /// successfully and then exits non-zero is reported as the success it answered, -/// and the failing exit is not an error, because the answer is what the caller -/// asked for; it is only noted on this process's stderr when the caller sets -/// `note_failing_exit_after_answer`. -/// Every other failure names what went wrong and carries the child's stderr, -/// with one exception: when the capabilities check below refuses the request -/// on that child's answer (a protocol mismatch or an error answer), the error -/// carries neither the check child's stderr nor, for a mismatch, its exit -/// status, as [`check_protocol_before`] documents. -/// -/// For a method that installs or starts something -/// ([`EngineMethod::requires_protocol_handshake`]), the engine is first asked -/// for its capabilities, as a request of its own, and `envelope` is sent only -/// when that answer is in a compatible protocol and is not an error; otherwise -/// the error says `envelope` was not sent, and why. +/// and the failing exit is not reported or logged anywhere, by design, because +/// the answer is what the caller asked for. +/// Every other failure names what went wrong and carries the child's stderr. pub fn run_engine_stdio( program: &Path, args: I, @@ -261,110 +224,6 @@ where I: IntoIterator, S: AsRef, { - let args: Vec = args - .into_iter() - .map(|arg| arg.as_ref().to_owned()) - .collect(); - if envelope.method.requires_protocol_handshake() { - check_protocol_before(program, &args, options, &envelope.method)?; - } - exchange(program, &args, options, envelope, forward) -} - -/// Before a request that installs or starts something (see -/// [`EngineMethod::requires_protocol_handshake`]), ask the engine for its -/// capabilities, through the same path, and check the protocol it answers in. -/// The request itself is sent only when that answer is in a protocol this -/// build can use; otherwise the error says it was not sent, and why. -/// -/// Nothing is cached: an engine can be replaced between two requests, and the -/// extra child is small next to the install or launch it guards. The -/// capabilities child runs with [`handshake_options`]; its stderr is not -/// forwarded (it is in the error when asking for its capabilities fails, and -/// nowhere when the check fails on its answer), and it sends an empty -/// object as its payload, so an engine that decodes every payload as an object -/// still answers it. -fn check_protocol_before( - program: &Path, - args: &[OsString], - options: &EngineStdioOptions<'_>, - method: &EngineMethod, -) -> Result<()> { - let refused = format!("the {} request was not sent to the engine", method.name()); - let capabilities = - EngineRequestEnvelope::new(EngineMethod::Capabilities, serde_json::json!({})); - let answer = exchange( - program, - args, - &handshake_options(options), - &capabilities, - None::, - ) - .map_err(|error| match error.downcast::() { - Ok(AnswerInOtherProtocol { mismatch, .. }) => handshake_mismatch(&refused, mismatch), - Err(error) => anyhow::anyhow!( - "{refused}: its protocol could not be checked against this release's \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) because asking for its capabilities \ - failed: {error:#}" - ), - })?; - if let Err(mismatch) = - engine_protocol_compatible(ENGINE_PROTOCOL_VERSION, answer.protocol_version.as_deref()) - { - return Err(handshake_mismatch(&refused, mismatch)); - } - if !answer.ok { - bail!( - "{refused}: its protocol could not be checked against this release's \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) because it refused the capabilities \ - request: {}", - engine_error_text(answer.error) - ); - } - Ok(()) -} - -/// The error for a capabilities answer in a protocol this build cannot use: -/// the request named by `refused` was not sent, and why. The same words whether -/// the answer decoded as an envelope or was judged from its raw object. -fn handshake_mismatch(refused: &str, mismatch: ProtocolMismatch) -> anyhow::Error { - match mismatch { - ProtocolMismatch::Incompatible { ours, theirs } => anyhow::anyhow!( - "{refused}: the engine speaks engine protocol {theirs}, which this release \ - (engine protocol {ours}) cannot use" - ), - ProtocolMismatch::Unreadable { ours, theirs } => anyhow::anyhow!( - "{refused}: the engine named its protocol version {theirs:?}, which is not a \ - MAJOR.MINOR.PATCH version, so this release (engine protocol {ours}) cannot tell \ - whether it can use it" - ), - } -} - -/// The options the capabilities child of [`check_protocol_before`] runs with: -/// the real request's environment (app paths, engine environments root, the -/// endpoint key file and whether an inherited one is withheld), so the engine -/// that is checked is the one the request will reach, without the request for -/// progress, which is the install's, and without the note on a failing exit, -/// since the check reports its own outcome. -const fn handshake_options<'a>(options: &EngineStdioOptions<'a>) -> EngineStdioOptions<'a> { - EngineStdioOptions { - request_progress: false, - note_failing_exit_after_answer: false, - ..*options - } -} - -/// One request and its answer: start the child, write `envelope`, read what it -/// printed. [`run_engine_stdio_forwarding`] is this plus the protocol check that -/// goes before a request that installs or starts something. -fn exchange( - program: &Path, - args: &[OsString], - options: &EngineStdioOptions<'_>, - envelope: &EngineRequestEnvelope, - forward: Option, -) -> Result { let mut child = engine_stdio_command(program, args, options) .spawn() .with_context(|| format!("failed to spawn engine stdio process {}", program.display()))?; @@ -425,17 +284,9 @@ fn exchange( } bail!("{exited}: {stderr}"); } - let answer = parse_answer(&stdout).ok_or_else(|| { - match incompatible_object(ENGINE_PROTOCOL_VERSION, &stdout) { - Some(mismatch) => anyhow::Error::new(AnswerInOtherProtocol { - mismatch, - exited: (!status.success()).then(|| exit_note(status)), - stderr: stderr.clone(), - }), - None => anyhow::anyhow!(unparseable_answer_message(status, &stdout, &stderr)), - } - }); - // The note says an answer was read, so it is only made for an answer that + let answer = serde_json::from_slice(&stdout) + .with_context(|| unparseable_answer_message(status, &stderr)); + // The note says the answer was used, so it is only made for an answer that // parsed; an unparseable one is reported by the error above, with the status. if answer.is_ok() && !status.success() && options.note_failing_exit_after_answer { note_failing_exit_after_answer(&mut io::stderr(), status); @@ -449,7 +300,7 @@ fn exchange( /// in `rocm` (SIGPIPE at its default action) nor panic it, as `eprintln!` would. fn note_failing_exit_after_answer(sink: &mut impl Write, status: ExitStatus) { let note = format!( - "{} after printing its answer; the answer was read\n", + "{} after printing its answer; the answer was used\n", exit_note(status) ); forward_best_effort(sink, note.as_bytes()); @@ -475,237 +326,18 @@ fn exit_note(status: ExitStatus) -> String { /// The error for an answer that is not a response envelope. A child that also /// exited with a failing status says so, because that is often why the answer is -/// cut short; then what was wrong with what it printed ([`unreadable_stdout`]); -/// the stderr it wrote follows when there is any. -fn unparseable_answer_message(status: ExitStatus, stdout: &[u8], stderr: &str) -> String { +/// cut short; the stderr it wrote follows when there is any. +fn unparseable_answer_message(status: ExitStatus, stderr: &str) -> String { let mut message = "failed to parse engine response envelope".to_owned(); if !status.success() { message = format!("{message} ({})", exit_note(status)); } - message = format!("{message}: {}", unreadable_stdout(stdout)); if !stderr.is_empty() { message = format!("{message}; stderr: {stderr}"); } message } -/// The answer envelope `stdout` holds, when the whole of it is one: a single -/// JSON object that decodes as an envelope. -fn parse_answer(stdout: &[u8]) -> Option { - answer_from_value(serde_json::from_slice(stdout).ok()?) -} - -/// An answer that does not decode as an envelope and names a protocol this -/// build cannot use. Its message is the one for any answer in such a protocol, -/// followed by the child's failing exit status and its stderr when there are -/// any, as for every other unusable answer; the type lets the protocol check -/// before an install or launch report the mismatch alone. -#[derive(Debug)] -struct AnswerInOtherProtocol { - mismatch: ProtocolMismatch, - /// The failing exit, when the child did not exit cleanly. - exited: Option, - /// What the child wrote to stderr, trimmed; empty for none. - stderr: String, -} - -impl std::fmt::Display for AnswerInOtherProtocol { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.write_str(&incompatible_answer_message(&self.mismatch))?; - if let Some(exited) = &self.exited { - write!(f, " ({exited})")?; - } - if !self.stderr.is_empty() { - write!(f, "; stderr: {}", self.stderr)?; - } - Ok(()) - } -} - -impl std::error::Error for AnswerInOtherProtocol {} - -/// The protocol mismatch of a stdout that is one JSON object naming a protocol -/// this build cannot use, or `None`. Used for an object that does not decode -/// as an envelope, so its version is judged from the raw object before the -/// shape of the rest is: an answer in another protocol may have another shape, -/// and the mismatch is what has to be fixed. -fn incompatible_object(ours: &str, stdout: &[u8]) -> Option { - let value: serde_json::Value = serde_json::from_slice(stdout).ok()?; - if !value.is_object() { - return None; - } - let theirs = crate::protocol_version::raw_protocol_version(&value); - engine_protocol_compatible(ours, theirs.as_deref()).err() -} - -/// `value` as an answer envelope, when it is a JSON object that decodes as one. -/// A derived struct also decodes from a JSON array of its fields in order -/// (`[null,true,null,null]`), which no engine writes, so anything but an -/// object is refused rather than read by position. -fn answer_from_value(value: serde_json::Value) -> Option { - if !value.is_object() { - return None; - } - serde_json::from_value(value).ok() -} - -/// What an engine's stdout must hold, said wherever it held something else. -const STDOUT_RULE: &str = "an engine writes only its JSON answer to stdout; logs go to stderr"; - -/// How much of an engine's output an error quotes: the first non-blank line of -/// an unreadable stdout, or a decoder's message about it (which can quote a -/// value the engine wrote in full), cut to this many characters. -const STDOUT_EXCERPT_CHARS: usize = 120; - -/// How many pieces of stdout (a line of text, or one whole top-level JSON -/// value however many lines it spans) [`answer_among_other_output`] reads, so a -/// large unreadable stdout costs a bounded amount of work to describe. -const STDOUT_SEARCH_PIECES: usize = 256; - -/// Where the other output is, in a stdout that holds an answer and something -/// else, with an excerpt of that other output. -#[derive(Debug, PartialEq, Eq)] -enum OtherOutput { - BeforeAnswer(String), - AfterAnswer(String), -} - -/// What is wrong with a stdout that does not parse as one response envelope, -/// for the error that reports it. -/// -/// The whole of stdout must be the answer, so nothing here salvages one: an -/// answer found among other output is still refused, and only named as the -/// reason. The cases, in the order they are told apart: -/// - nothing (or only whitespace) was printed; -/// - a top-level envelope is there, but so is other output before or after it -/// (a log line on the wrong stream), which is what the error quotes; -/// - the whole of it is one JSON value, but not an envelope; -/// - it is not JSON. -fn unreadable_stdout(stdout: &[u8]) -> String { - if stdout.iter().all(u8::is_ascii_whitespace) { - return "the engine printed no answer on stdout".to_owned(); - } - match answer_among_other_output(stdout) { - Some(OtherOutput::BeforeAnswer(other)) => { - return format!( - "the engine wrote other output to stdout before its answer, starting with \ - `{other}` ({STDOUT_RULE})" - ); - } - Some(OtherOutput::AfterAnswer(other)) => { - return format!( - "the engine wrote other output to stdout after its answer, starting with \ - `{other}` ({STDOUT_RULE})" - ); - } - None => {} - } - let excerpt = stdout_excerpt(stdout); - match serde_json::from_slice::(stdout) { - Ok(value) => { - let reason = if value.is_object() { - serde_json::from_slice::(stdout) - .err() - .map_or_else(String::new, |error| { - format!(" ({})", bounded(&error.to_string())) - }) - } else { - " (an answer is a JSON object)".to_owned() - }; - format!( - "the engine's stdout is JSON but not an answer envelope{reason}, starting with \ - `{excerpt}` ({STDOUT_RULE})" - ) - } - Err(error) => format!( - "the engine's stdout is not JSON ({}), starting with `{excerpt}` \ - ({STDOUT_RULE})", - bounded(&error.to_string()) - ), - } -} - -/// The other output beside a response envelope in `stdout`, when the envelope -/// is a top-level value there and something else is too, or `None`. -/// -/// `stdout` is read as a sequence of pieces: wherever (after whitespace) a `{` -/// or `[` starts a whole JSON value, that value, however many lines it spans, -/// since engines pretty-print their answer; anything else, a line of text. Only -/// a top-level object can be the answer, so an envelope nested inside another -/// value is never mistaken for one. At most [`STDOUT_SEARCH_PIECES`] pieces -/// are read. -fn answer_among_other_output(stdout: &[u8]) -> Option { - let mut position = 0; - let mut answered = false; - let mut first_other: Option = None; - for _ in 0..STDOUT_SEARCH_PIECES { - position += stdout[position..] - .iter() - .take_while(|byte| byte.is_ascii_whitespace()) - .count(); - let rest = &stdout[position..]; - if rest.is_empty() { - return None; - } - if answered { - return Some(OtherOutput::AfterAnswer(stdout_excerpt(rest))); - } - if matches!(rest[0], b'{' | b'[') { - let mut values = - serde_json::Deserializer::from_slice(rest).into_iter::(); - if let Some(Ok(value)) = values.next() { - let is_answer = answer_from_value(value).is_some(); - if is_answer { - if let Some(start) = first_other { - return Some(OtherOutput::BeforeAnswer(stdout_excerpt(&stdout[start..]))); - } - answered = true; - } else { - first_other.get_or_insert(position); - } - position += values.byte_offset(); - continue; - } - } - first_other.get_or_insert(position); - match rest.iter().position(|byte| *byte == b'\n') { - Some(newline) => position += newline + 1, - None => return None, - } - } - None -} - -/// The first non-blank line of `stdout`, [`bounded`]. -fn stdout_excerpt(stdout: &[u8]) -> String { - let text = String::from_utf8_lossy(stdout); - let line = text - .lines() - .map(str::trim) - .find(|line| !line.is_empty()) - .unwrap_or_default(); - bounded(line) -} - -/// `text` cut to [`STDOUT_EXCERPT_CHARS`] characters, with `...` marking a -/// cut, and with control characters (`char::is_control`) escaped. Other -/// characters, such as Unicode format characters, are quoted as they are. -fn bounded(text: &str) -> String { - let mut excerpt = String::new(); - for (index, ch) in text.chars().enumerate() { - if index == STDOUT_EXCERPT_CHARS { - excerpt.push_str("..."); - break; - } - if ch.is_control() { - excerpt.extend(ch.escape_default()); - } else { - excerpt.push(ch); - } - } - excerpt -} - /// `pipe` of `child`, or an error that also kills and reaps the child: a child /// whose request cannot be sent must not be left running, as on every other /// failure path. Unreachable while the command pipes all three streams, which is @@ -1004,55 +636,21 @@ fn forward_best_effort(sink: &mut impl Write, bytes: &[u8]) { /// Turn an engine's answer into the response type the caller asked for: the /// engine's own error when it reported one, otherwise the decoded `data`. -/// -/// The protocol the answer was written in is checked first, before `ok`: an -/// answer in a protocol this build cannot use is refused whatever it says, -/// and so is an engine's own error in such a protocol, because its meaning -/// cannot be trusted either and the mismatch is the thing to fix. pub fn decode_engine_response(envelope: EngineResponseEnvelope) -> Result where R: DeserializeOwned, { - if let Err(mismatch) = engine_protocol_compatible( - ENGINE_PROTOCOL_VERSION, - envelope.protocol_version.as_deref(), - ) { - bail!("{}", incompatible_answer_message(&mismatch)); - } if !envelope.ok { - bail!("{}", engine_error_text(envelope.error)); + let error = envelope.error.map_or_else( + || "unknown engine error".to_owned(), + |value| format!("{}: {}", value.code, value.message), + ); + bail!("{error}"); } let data = envelope .data .context("engine response envelope did not contain data")?; - serde_json::from_value(data).map_err(|error| { - anyhow::anyhow!( - "failed to decode engine response payload: {}", - bounded(&error.to_string()) - ) - }) -} - -/// The error for an answer in a protocol this build cannot use. -fn incompatible_answer_message(mismatch: &ProtocolMismatch) -> String { - match mismatch { - ProtocolMismatch::Incompatible { ours, theirs } => format!( - "engine answered in engine protocol {theirs}, which this release \ - (engine protocol {ours}) cannot use" - ), - ProtocolMismatch::Unreadable { ours, theirs } => format!( - "engine answered with protocol version {theirs:?}, which is not a \ - MAJOR.MINOR.PATCH version this release (engine protocol {ours}) can read" - ), - } -} - -/// An engine's own error, as `code: message`. -fn engine_error_text(error: Option) -> String { - error.map_or_else( - || "unknown engine error".to_owned(), - |value| format!("{}: {}", value.code, value.message), - ) + serde_json::from_value(data).context("failed to decode engine response payload") } #[cfg(test)] @@ -1241,16 +839,13 @@ mod tests { assert_eq!(envelope.payload, json!({"service_id": "svc"})); assert_eq!( serde_json::to_string(&envelope).unwrap(), - format!( - r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","method":"stop","payload":{{"service_id":"svc"}}}}"# - ) + r#"{"method":"stop","payload":{"service_id":"svc"}}"# ); } #[test] fn decode_engine_response_reports_each_way_an_answer_can_be_unusable() { let failed = EngineResponseEnvelope { - protocol_version: None, ok: false, data: None, error: Some(EngineErrorDetail { @@ -1262,7 +857,6 @@ mod tests { assert_eq!(error.to_string(), "stop_failed: it broke"); let unexplained = EngineResponseEnvelope { - protocol_version: None, ok: false, data: None, error: None, @@ -1271,7 +865,6 @@ mod tests { assert_eq!(error.to_string(), "unknown engine error"); let empty = EngineResponseEnvelope { - protocol_version: None, ok: true, data: None, error: None, @@ -1286,341 +879,7 @@ mod tests { let error = decode_engine_response::(wrong_shape).unwrap_err(); assert_eq!( error.to_string(), - "failed to decode engine response payload: \ - invalid type: string \"yes\", expected a boolean" - ); - } - - /// An answer, as a client reads it, from an engine that wrote it in - /// `version` (`None`: before the field existed). - fn answer_in(version: Option<&str>, ok: bool) -> EngineResponseEnvelope { - let mut answer = if ok { - EngineResponseEnvelope::success(json!({"stopped": true, "graceful": true})) - } else { - EngineResponseEnvelope::failure("incompatible_protocol", "the engine's own refusal") - }; - answer.protocol_version = version.map(str::to_owned); - answer - } - - /// The answer's protocol is checked before anything else in it: a success - /// with perfectly good data is refused when it is in a protocol this - /// release cannot use, and an engine's own error in such a protocol is - /// reported as the mismatch, which is what has to be fixed. - #[test] - fn an_answer_in_an_incompatible_protocol_is_refused_whatever_it_says() { - for ok in [true, false] { - let error = - decode_engine_response::(answer_in(Some("9.0.0"), ok)).unwrap_err(); - assert_eq!( - error.to_string(), - format!( - "engine answered in engine protocol 9.0.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ), - "ok: {ok}" - ); - let error = - decode_engine_response::(answer_in(Some("0.2.0"), ok)).unwrap_err(); - assert_eq!( - error.to_string(), - format!( - "engine answered in engine protocol 0.2.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ), - "ok: {ok}" - ); - let error = - decode_engine_response::(answer_in(Some("banana"), ok)).unwrap_err(); - assert_eq!( - error.to_string(), - format!( - "engine answered with protocol version \"banana\", which is not a \ - MAJOR.MINOR.PATCH version this release (engine protocol \ - {ENGINE_PROTOCOL_VERSION}) can read" - ), - "ok: {ok}" - ); - } - } - - /// The same answer in this protocol, in a newer one with only additions, - /// or from an engine older than the field, is read as answered. - #[test] - fn an_answer_in_a_compatible_or_unnamed_protocol_is_read() { - for version in [Some(ENGINE_PROTOCOL_VERSION), Some("0.1.9"), None] { - let decoded = decode_engine_response::(answer_in(version, true)) - .unwrap_or_else(|error| panic!("{version:?}: {error:#}")); - assert!(decoded.stopped, "{version:?}"); - let error = - decode_engine_response::(answer_in(version, false)).unwrap_err(); - assert_eq!( - error.to_string(), - "incompatible_protocol: the engine's own refusal", - "{version:?}" - ); - } - } - - /// An object that is not a valid envelope is judged by the protocol it - /// names first: in another protocol, or with a version that is not text, - /// the error is the mismatch and not the stdout rule; in this protocol (or - /// none), the shape of the object is what is reported. - #[test] - fn a_malformed_answer_is_judged_by_its_protocol_before_its_shape() { - let incompatible = format!( - "engine answered in engine protocol 9.0.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ); - for stdout in [ - r#"{"protocol_version":"9.0.0","ok":"yes"}"#, - r#"{"protocol_version":"9.0.0","status":"ok"}"#, - r#"{"protocol_version":"9.0.0","ok":false,"error":"boom"}"#, - ] { - assert_eq!( - incompatible_object(ENGINE_PROTOCOL_VERSION, stdout.as_bytes()) - .map(|mismatch| incompatible_answer_message(&mismatch)) - .as_deref(), - Some(incompatible.as_str()), - "{stdout}" - ); - } - assert_eq!( - incompatible_object( - ENGINE_PROTOCOL_VERSION, - br#"{"protocol_version":9,"ok":true,"data":{}}"# - ) - .map(|mismatch| incompatible_answer_message(&mismatch)) - .as_deref(), - Some( - format!( - "engine answered with protocol version \"9\", which is not a \ - MAJOR.MINOR.PATCH version this release (engine protocol \ - {ENGINE_PROTOCOL_VERSION}) can read" - ) - .as_str() - ) - ); - // An array is not an object, so it is not judged at all: read as an - // absent version it would be `0.1.0`, which a `0.2.0` build cannot use. - assert_eq!(incompatible_object("0.2.0", b"[null,true,null,null]"), None); - assert!(incompatible_object("0.2.0", br#"{"ok":true}"#).is_some()); - let current = format!(r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","ok":"yes"}}"#); - for compatible in [current.as_str(), r#"{"ok":"yes"}"#] { - assert_eq!( - incompatible_object(ENGINE_PROTOCOL_VERSION, compatible.as_bytes()), - None - ); - assert!( - unreadable_stdout(compatible.as_bytes()) - .starts_with("the engine's stdout is JSON but not an answer envelope"), - "{compatible}" - ); - } - } - - /// Each way a stdout can fail to be one envelope is told apart, and none of - /// them is salvaged. - #[test] - fn an_unreadable_stdout_is_described_by_what_is_wrong_with_it() { - const RULE: &str = "(an engine writes only its JSON answer to stdout; logs go to stderr)"; - let envelope = format!( - r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","ok":true,"data":{{"stopped":true}}}}"# - ); - let cases: Vec<(String, String)> = vec![ - ( - String::new(), - "the engine printed no answer on stdout".to_owned(), - ), - ( - " \n\t\n".to_owned(), - "the engine printed no answer on stdout".to_owned(), - ), - ( - format!("INFO loading model\n{envelope}\n"), - format!( - "the engine wrote other output to stdout before its answer, starting \ - with `INFO loading model` {RULE}" - ), - ), - ( - // Several pieces before the answer: the first is quoted. - format!("first\nsecond\n{envelope}\n"), - format!( - "the engine wrote other output to stdout before its answer, starting \ - with `first` {RULE}" - ), - ), - ( - // A line of text, then a JSON value that is not an answer, then - // the answer: the line comes first and is quoted. - format!("loading\n{{\"progress\":1}}\n{envelope}\n"), - format!( - "the engine wrote other output to stdout before its answer, starting \ - with `loading` {RULE}" - ), - ), - ( - // A JSON value that is not an answer, then a line of text, then - // the answer: the JSON value comes first and is quoted. - format!("{{\"progress\":1}}\nloading\n{envelope}\n"), - format!( - "the engine wrote other output to stdout before its answer, starting \ - with `{{\"progress\":1}}` {RULE}" - ), - ), - ( - format!("{envelope}\ndone\n"), - format!( - "the engine wrote other output to stdout after its answer, starting \ - with `done` {RULE}" - ), - ), - ( - format!("{envelope}{envelope}"), - format!( - "the engine wrote other output to stdout after its answer, starting \ - with `{envelope}` {RULE}" - ), - ), - ( - "[\n {\"ok\": true}\n]\n".to_owned(), - format!( - "the engine's stdout is JSON but not an answer envelope (an answer is a \ - JSON object), starting with `[` {RULE}" - ), - ), - ( - // The fields of an envelope in order, which a derived struct - // would decode by position: not an answer, however it reads. - "[null,true,null,null]".to_owned(), - format!( - "the engine's stdout is JSON but not an answer envelope (an answer is a \ - JSON object), starting with `[null,true,null,null]` {RULE}" - ), - ), - ( - format!("[null,true,null,null]\n{envelope}\n"), - format!( - "the engine wrote other output to stdout before its answer, starting \ - with `[null,true,null,null]` {RULE}" - ), - ), - ( - "progress\n{\"result\":\n{\"ok\": true}\n}\n".to_owned(), - format!( - "the engine's stdout is not JSON (expected value at line 1 column 1), \ - starting with `progress` {RULE}" - ), - ), - ( - "loading {model}\n {\n \"ok\": true,\n \"data\": {}\n }\n".to_owned(), - format!( - "the engine wrote other output to stdout before its answer, starting \ - with `loading {{model}}` {RULE}" - ), - ), - ( - r#"{"status":"ok"}"#.to_owned(), - format!( - "the engine's stdout is JSON but not an answer envelope (missing field `ok` \ - at line 1 column 15), starting with `{{\"status\":\"ok\"}}` {RULE}" - ), - ), - ( - "not json".to_owned(), - format!( - "the engine's stdout is not JSON (expected ident at line 1 column 2), \ - starting with `not json` {RULE}" - ), - ), - ( - "\u{1b}[31mred\u{7}\n".to_owned(), - format!( - "the engine's stdout is not JSON (expected value at line 1 column 1), \ - starting with `\\u{{1b}}[31mred\\u{{7}}` {RULE}" - ), - ), - ]; - for (stdout, expected) in cases { - assert_eq!(unreadable_stdout(stdout.as_bytes()), expected, "{stdout:?}"); - } - - // A decoder's message can quote what the engine wrote in full; the - // error quotes it bounded, like the excerpt beside it. - let long = format!(r#"{{"ok":false,"error":"{}"}}"#, "x".repeat(10_000)); - let message = unreadable_stdout(long.as_bytes()); - assert!(message.len() < 600, "{} bytes: {message}", message.len()); - assert!( - message.starts_with( - "the engine's stdout is JSON but not an answer envelope (invalid type: string \"x" - ), - "{message}" - ); - let excerpt: String = long.chars().take(STDOUT_EXCERPT_CHARS).collect(); - assert!(message.contains(&format!("`{excerpt}...`")), "{message}"); - let payload = EngineResponseEnvelope::success(json!({"stopped": "x".repeat(10_000)})); - let error = decode_engine_response::(payload) - .unwrap_err() - .to_string(); - assert!(error.len() < 300, "{} bytes: {error}", error.len()); - assert!( - error.starts_with("failed to decode engine response payload: invalid type: string \"x"), - "{error}" - ); - assert!(error.ends_with("..."), "{error}"); - } - - /// The search for an answer among other output reads a bounded number of - /// pieces: an answer just inside the bound is found and named, one just - /// past it is not looked for, and the stdout is described as a whole. - #[test] - fn an_answer_past_the_search_bound_is_not_looked_for() { - let envelope = r#"{"ok":true,"data":{}}"#; - let inside = format!("{}{envelope}\n", "log\n".repeat(STDOUT_SEARCH_PIECES - 1)); - assert_eq!( - answer_among_other_output(inside.as_bytes()), - Some(OtherOutput::BeforeAnswer("log".to_owned())) - ); - let past = format!("{}{envelope}\n", "log\n".repeat(STDOUT_SEARCH_PIECES)); - assert_eq!(answer_among_other_output(past.as_bytes()), None); - assert!( - unreadable_stdout(past.as_bytes()).starts_with("the engine's stdout is not JSON"), - "{}", - unreadable_stdout(past.as_bytes()) - ); - } - - /// The quoted part of an unreadable stdout is its first non-blank line, - /// bounded, so a megabyte of output does not become a megabyte of error. - #[test] - fn the_stdout_excerpt_is_the_first_line_and_bounded() { - assert_eq!(stdout_excerpt(b"\n\n first \nsecond"), "first"); - let long = "x".repeat(500); - let excerpt = stdout_excerpt(long.as_bytes()); - assert_eq!(excerpt, format!("{}...", "x".repeat(STDOUT_EXCERPT_CHARS))); - let exact = "y".repeat(STDOUT_EXCERPT_CHARS); - assert_eq!(stdout_excerpt(exact.as_bytes()), exact); - } - - /// The cut is made in characters, not bytes, so a multi-byte character that - /// straddles the byte position of the cut is kept whole or left out whole, - /// and a control character in a decoder's message is escaped. - #[test] - fn bounded_cuts_in_characters_and_escapes_control_characters() { - for wide in ['\u{e9}', '\u{20ac}', '\u{1f600}'] { - // One ASCII character, then wide ones: in bytes, the cut falls - // inside a wide character; in characters, it falls between two. - let text: String = std::iter::once('a') - .chain(std::iter::repeat_n(wide, STDOUT_EXCERPT_CHARS)) - .collect(); - let kept: String = text.chars().take(STDOUT_EXCERPT_CHARS).collect(); - assert_eq!(bounded(&text), format!("{kept}..."), "{}", wide.len_utf8()); - assert_eq!(kept.chars().count(), STDOUT_EXCERPT_CHARS); - } - assert_eq!( - bounded("invalid type: string \"a\u{1b}[31mb\", expected a boolean"), - "invalid type: string \"a\\u{1b}[31mb\", expected a boolean" + "failed to decode engine response payload" ); } @@ -1905,64 +1164,6 @@ mod tests { assert_eq!(collected, b"still kept\n"); } - /// The capabilities child gets the request's environment and nothing that - /// is the request's own: not its progress request, and not the note on a - /// failing exit, which is about an answer the caller uses. Pure, so it runs - /// on every platform. - #[test] - fn the_check_keeps_the_requests_environment_and_drops_its_progress_and_note() { - let paths = AppPaths { - config_dir: "/c".into(), - data_dir: "/d".into(), - cache_dir: "/k".into(), - }; - let options = EngineStdioOptions { - app_paths: Some(&paths), - env_root: Some(Path::new("/envs")), - endpoint_key_file: Some(Path::new("/keys/k")), - withhold_inherited_key_file: true, - request_progress: true, - forward_stderr: true, - note_failing_exit_after_answer: true, - }; - let check = handshake_options(&options); - assert!( - check - .app_paths - .is_some_and(|kept| std::ptr::eq(kept, std::ptr::addr_of!(paths))) - ); - assert_eq!(check.env_root, options.env_root); - assert_eq!(check.endpoint_key_file, options.endpoint_key_file); - assert!(check.withhold_inherited_key_file); - assert!(!check.request_progress); - assert!(!check.note_failing_exit_after_answer); - } - - /// Withholding an inherited key file holds for the check as well: a - /// third-party engine is not handed a credential path by the request - /// that comes first. - #[test] - fn the_check_withholds_an_inherited_key_file_as_the_request_does() { - let options = EngineStdioOptions { - withhold_inherited_key_file: true, - ..EngineStdioOptions::default() - }; - let command = engine_stdio_command( - Path::new("/an/engine"), - ["stdio"], - &handshake_options(&options), - ); - let key = std::ffi::OsStr::new(ENDPOINT_API_KEY_FILE_ENV); - assert_eq!( - command - .get_envs() - .find(|(name, _)| *name == key) - .map(|(_, value)| value), - Some(None), - "the check must clear an inherited key file, as the request does" - ); - } - #[cfg(unix)] mod child { use super::*; @@ -1992,10 +1193,7 @@ mod tests { assert_eq!(engine.argv(), ["stdio"]); assert_eq!( engine.stdin(), - format!( - "{{\"protocol_version\":\"{ENGINE_PROTOCOL_VERSION}\",\"method\":\"stop\",\ - \"payload\":{{\"service_id\":\"svc\"}}}}\n" - ) + "{\"method\":\"stop\",\"payload\":{\"service_id\":\"svc\"}}\n" ); } @@ -2083,7 +1281,7 @@ mod tests { /// answer, so a caller that asks for it (the daemon) gets a note on this /// process's stderr, and one that does not (the CLI) gets nothing. Run in /// a re-executed test binary so the parent can read that stderr; the - /// decision itself is unchanged: the answer is read. + /// decision itself is unchanged: the answer is used. #[test] fn a_failing_exit_after_an_answer_is_noted_only_when_asked_for() { if let Some(arm) = std::env::var_os("ROCM_TEST_CLIENT_NOTE_ARM") { @@ -2108,14 +1306,14 @@ mod tests { .unwrap(); assert!(output.status.success(), "{arm}: {:?}", output.status); let stderr = String::from_utf8_lossy(&output.stderr); - let note = "engine stdio process exited with code 7 after printing its answer; the answer was read"; + let note = "engine stdio process exited with code 7 after printing its answer; the answer was used"; assert_eq!(stderr.contains(note), expected, "{arm}:\n{stderr}"); } } /// The note is only made for an answer that parsed: a child that prints /// something unreadable and fails is reported by the error (with its - /// status), and must not also log that "the answer was read". Both cases + /// status), and must not also log that "the answer was used". Both cases /// assert the outcome and the stderr together, in a re-executed binary. #[test] fn the_note_is_made_only_for_an_answer_that_parsed() { @@ -2138,10 +1336,7 @@ mod tests { assert_eq!( outcome.unwrap_err().to_string(), "failed to parse engine response envelope \ - (engine stdio process exited with code 7): the engine's stdout \ - is not JSON (expected ident at line 1 column 2), starting with \ - `not json` (an engine writes only its JSON answer to stdout; logs \ - go to stderr)" + (engine stdio process exited with code 7)" ); } return; @@ -2159,7 +1354,7 @@ mod tests { assert!(output.status.success(), "{arm}: {:?}", output.status); let stderr = String::from_utf8_lossy(&output.stderr); assert_eq!( - stderr.contains("the answer was read"), + stderr.contains("the answer was used"), expected, "{arm}:\n{stderr}" ); @@ -2286,18 +1481,14 @@ mod tests { let error = run(&engine, &EngineStdioOptions::default()).unwrap_err(); assert_eq!( error.to_string(), - "failed to parse engine response envelope: the engine's stdout is not JSON (expected ident at line 1 column 2), \ - starting with `not json` (an engine writes only its JSON answer to stdout; \ - logs go to stderr); stderr: oops" + "failed to parse engine response envelope; stderr: oops" ); let silent = FakeEngine::new("client-garbage-quiet", true, "printf 'not json'"); let error = run(&silent, &EngineStdioOptions::default()).unwrap_err(); assert_eq!( error.to_string(), - "failed to parse engine response envelope: the engine's stdout is not JSON (expected ident at line 1 column 2), \ - starting with `not json` (an engine writes only its JSON answer to stdout; \ - logs go to stderr)" + "failed to parse engine response envelope" ); } @@ -2322,10 +1513,7 @@ mod tests { assert_eq!( error.to_string(), "failed to parse engine response envelope \ - (engine stdio process was terminated by signal 9): the engine's stdout is \ - not JSON (EOF while parsing an object at line 1 column 5), starting with \ - `{\"ok\"` (an engine writes only its JSON answer to stdout; logs go to \ - stderr)" + (engine stdio process was terminated by signal 9)" ); } @@ -2346,9 +1534,7 @@ mod tests { assert_eq!( error.to_string(), "failed to parse engine response envelope \ - (engine stdio process exited with code 4): the engine's stdout is not JSON (expected ident at line 1 column 2), \ - starting with `not json` (an engine writes only its JSON answer to stdout; \ - logs go to stderr); stderr: oops" + (engine stdio process exited with code 4); stderr: oops" ); let silent = FakeEngine::new( @@ -2360,18 +1546,14 @@ mod tests { assert_eq!( error.to_string(), "failed to parse engine response envelope \ - (engine stdio process exited with code 5): the engine's stdout is not JSON (expected ident at line 1 column 2), \ - starting with `not json` (an engine writes only its JSON answer to stdout; \ - logs go to stderr)" + (engine stdio process exited with code 5)" ); let clean = FakeEngine::new("client-garbage-clean", true, "printf 'not json'\nexit 0"); let error = run(&clean, &EngineStdioOptions::default()).unwrap_err(); assert_eq!( error.to_string(), - "failed to parse engine response envelope: the engine's stdout is not JSON (expected ident at line 1 column 2), \ - starting with `not json` (an engine writes only its JSON answer to stdout; \ - logs go to stderr)" + "failed to parse engine response envelope" ); } @@ -2866,525 +2048,5 @@ mod tests { ); assert!(status.success(), "{status:?}"); } - - /// What a well-behaved engine answers an `install` with, in this protocol. - fn installed() -> String { - format!( - r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","ok":true,"data":{{"installed":true}}}}"# - ) - } - - /// A fake engine that answers `capabilities` by running - /// `capabilities_body` (shell; it must exit) and anything else with - /// [`installed`]. - fn engine_answering_capabilities_with(label: &str, capabilities_body: &str) -> FakeEngine { - let installed = installed(); - FakeEngine::new( - label, - true, - &format!( - "if grep -q '\"method\":\"capabilities\"' \"$dir/stdin\"; then\n\ - {capabilities_body}\n\ - fi\n\ - printf '%s' '{installed}'" - ), - ) - } - - /// Only the install's own stderr reaches this process's stderr: the - /// capabilities child that goes first is not forwarded, even when the - /// caller asks for the install's stderr. The test binary re-executes - /// itself so the parent can read the stderr the arm writes. - #[test] - fn the_checks_stderr_is_not_forwarded_and_the_requests_is() { - const CHECK_LINE: &str = "capabilities child stderr line"; - const INSTALL_LINE: &str = "install child stderr line"; - if std::env::var_os("ROCM_TEST_CLIENT_CHECK_STDERR").is_some() { - let engine = engine_answering_capabilities_with( - "check-stderr", - &format!( - "echo '{CHECK_LINE}' >&2\nprintf '%s' '{}'\nexit 0", - installed() - ), - ); - let body = std::fs::read_to_string(engine.path()).unwrap(); - let body = body.replacen("fi\n", &format!("fi\necho '{INSTALL_LINE}' >&2\n"), 1); - rocm_core::fake_executable::write_fake_executable(engine.path(), body).unwrap(); - let options = EngineStdioOptions { - forward_stderr: true, - ..EngineStdioOptions::default() - }; - let envelope = - engine_request_envelope(EngineMethod::Install, &json!({"runtime_id": "r"})) - .unwrap(); - run_engine_stdio(engine.path(), ["stdio"], &options, &envelope).unwrap(); - assert_eq!(engine.methods(), ["capabilities", "install"]); - return; - } - let output = Command::new(std::env::current_exe().unwrap()) - .args([ - "stdio_client::tests::child::the_checks_stderr_is_not_forwarded_and_the_requests_is", - "--exact", - "--nocapture", - ]) - .env("ROCM_TEST_CLIENT_CHECK_STDERR", "1") - .output() - .unwrap(); - let stderr = String::from_utf8_lossy(&output.stderr); - assert!(output.status.success(), "{:?}\n{stderr}", output.status); - assert!(stderr.contains(INSTALL_LINE), "{stderr}"); - assert!(!stderr.contains(CHECK_LINE), "{stderr}"); - } - - fn send(engine: &FakeEngine, method: EngineMethod) -> Result { - let envelope = engine_request_envelope(method, &json!({"runtime_id": "r"})).unwrap(); - decode_engine_response(run_engine_stdio( - engine.path(), - ["stdio"], - &EngineStdioOptions::default(), - &envelope, - )?) - } - - /// The capabilities answer that lets the request through: this - /// protocol, a newer one with only additions, or none at all (an engine - /// older than the field). Each time the engine is run twice, the - /// capabilities request first, and the install or launch reaches it. - #[test] - fn a_compatible_engine_is_checked_and_then_sent_the_request() { - let same = format!( - r#"{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","ok":true,"data":{{}}}}"# - ); - for (row, capabilities) in [ - ("same", same.as_str()), - ( - "additive", - r#"{"protocol_version":"0.1.9","ok":true,"data":{}}"#, - ), - ("legacy", r#"{"ok":true,"data":{}}"#), - ] { - for method in [EngineMethod::Install, EngineMethod::Launch] { - let engine = engine_answering_capabilities_with( - &format!("handshake-ok-{row}"), - &format!("printf '%s' '{capabilities}'\nexit 0"), - ); - let answer = send(&engine, method.clone()) - .unwrap_or_else(|error| panic!("{row} {method:?}: {error:#}")); - assert_eq!(answer, json!({"installed": true}), "{row}"); - assert_eq!( - engine.methods(), - ["capabilities", method.name()], - "{row}: the request must follow the check" - ); - assert_eq!( - engine.requests()[0]["protocol_version"], - ENGINE_PROTOCOL_VERSION, - "{row}: the check is itself a versioned request" - ); - assert_eq!( - engine.requests()[0]["payload"], - json!({}), - "{row}: the check sends an empty object, which any engine decodes" - ); - } - } - } - - /// The capabilities child runs on the real request's environment, so the - /// engine checked is the one the request reaches (same app roots, same - /// engine environments root, same endpoint key file), but it is not asked - /// for the install's progress. - #[test] - fn the_check_runs_on_the_requests_environment_without_its_progress() { - let engine = engine_answering_capabilities_with( - "handshake-env", - "printf '%s' '{\"ok\":true,\"data\":{}}'\nexit 0", - ); - let paths = AppPaths { - config_dir: "/c".into(), - data_dir: "/d".into(), - cache_dir: "/k".into(), - }; - let options = EngineStdioOptions { - app_paths: Some(&paths), - env_root: Some(Path::new("/envs")), - endpoint_key_file: Some(Path::new("/keys/k")), - withhold_inherited_key_file: true, - request_progress: true, - forward_stderr: false, - note_failing_exit_after_answer: false, - }; - let envelope = - engine_request_envelope(EngineMethod::Install, &json!({"runtime_id": "r"})) - .unwrap(); - run_engine_stdio(engine.path(), ["stdio"], &options, &envelope).unwrap(); - assert_eq!(engine.methods(), ["capabilities", "install"]); - assert_eq!( - engine.argv_of_run(0), - ["stdio"], - "the check gets the request's args" - ); - assert_eq!(engine.argv_of_run(1), ["stdio"]); - for key in [ - "ROCM_CLI_CONFIG_DIR", - "ROCM_CLI_DATA_DIR", - "ROCM_CLI_CACHE_DIR", - "ROCM_CLI_ENGINE_ENVS_ROOT", - "ROCM_SERVE_API_KEY_FILE", - ] { - assert!( - engine.env_of_run(1, key).is_some(), - "{key} must reach the request" - ); - assert_eq!( - engine.env_of_run(0, key), - engine.env_of_run(1, key), - "{key}: the check must run where the request does" - ); - } - assert_eq!( - engine.env_of_run(1, ENGINE_PROGRESS_STDERR_ENV).as_deref(), - Some("1") - ); - assert_eq!(engine.env_of_run(0, ENGINE_PROGRESS_STDERR_ENV), None); - } - - /// Every way the check can fail stops the request before it is sent: - /// the error says it was not sent and why, naming both versions where - /// the engine named one, and the engine was only ever asked for its - /// capabilities. - #[test] - fn a_handshaked_request_is_not_sent_when_the_check_fails() { - const NOT_SENT: &str = "the install request was not sent to the engine"; - let unchecked = format!( - "the install request was not sent to the engine: its protocol could not be \ - checked against this release's (engine protocol {ENGINE_PROTOCOL_VERSION}) because" - ); - let rows: [(&str, String, String); 11] = [ - ( - "incompatible", - r#"printf '%s' '{"protocol_version":"9.0.0","ok":true,"data":{}}'"#.to_owned(), - format!( - "{NOT_SENT}: the engine speaks engine protocol 9.0.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ), - ), - ( - "incompatible-refusal", - r#"printf '%s' '{"protocol_version":"0.2.0","ok":false,"error":{"code":"incompatible_protocol","message":"no"}}'"# - .to_owned(), - format!( - "{NOT_SENT}: the engine speaks engine protocol 0.2.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ), - ), - ( - "unreadable-version", - r#"printf '%s' '{"protocol_version":"banana","ok":true,"data":{}}'"#.to_owned(), - format!( - "{NOT_SENT}: the engine named its protocol version \"banana\", which is \ - not a MAJOR.MINOR.PATCH version, so this release (engine protocol {ENGINE_PROTOCOL_VERSION}) \ - cannot tell whether it can use it" - ), - ), - ( - "incompatible-malformed", - r#"printf '%s' '{"protocol_version":"9.0.0","status":"ok"}'"#.to_owned(), - format!( - "{NOT_SENT}: the engine speaks engine protocol 9.0.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ), - ), - ( - // The check's refusal on its answer carries no exit note - // and no stderr, even when the child failed and wrote some. - "incompatible-malformed-failing", - r#"printf '%s' '{"protocol_version":"9.0.0","status":"ok"}' -echo oops >&2 -exit 1"# - .to_owned(), - format!( - "{NOT_SENT}: the engine speaks engine protocol 9.0.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ), - ), - ( - "unreadable-not-text", - r#"printf '%s' '{"protocol_version":9,"ok":true,"data":{}}'"#.to_owned(), - format!( - "{NOT_SENT}: the engine named its protocol version \"9\", which is \ - not a MAJOR.MINOR.PATCH version, so this release (engine protocol {ENGINE_PROTOCOL_VERSION}) \ - cannot tell whether it can use it" - ), - ), - ( - "refused", - format!( - r#"printf '%s' '{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","ok":false,"error":{{"code":"broken","message":"no capabilities today"}}}}'"# - ), - format!( - "{unchecked} it refused the capabilities request: broken: no capabilities \ - today" - ), - ), - ( - "crashed", - "echo 'engine exploded' >&2\nexit 3".to_owned(), - format!( - "{unchecked} asking for its capabilities failed: engine stdio process \ - exited with code 3: engine exploded" - ), - ), - ( - "silent", - "exit 0".to_owned(), - format!( - "{unchecked} asking for its capabilities failed: failed to parse engine \ - response envelope: the engine printed no answer on stdout" - ), - ), - ( - "contaminated", - format!( - r#"echo 'INFO starting' -printf '%s' '{{"protocol_version":"{ENGINE_PROTOCOL_VERSION}","ok":true,"data":{{}}}}'"# - ), - format!( - "{unchecked} asking for its capabilities failed: failed to parse engine \ - response envelope: the engine wrote other output to stdout before its \ - answer, starting with `INFO starting` (an engine writes only its JSON \ - answer to stdout; logs go to stderr)" - ), - ), - ( - "not-json", - "printf 'not json'".to_owned(), - format!( - "{unchecked} asking for its capabilities failed: failed to parse engine \ - response envelope: the engine's stdout is not JSON (expected ident at \ - line 1 column 2), starting with `not json` (an engine writes only its \ - JSON answer to stdout; logs go to stderr)" - ), - ), - ]; - for (row, capabilities_body, expected) in rows { - let engine = engine_answering_capabilities_with( - &format!("handshake-refused-{row}"), - &format!("{capabilities_body}\nexit 0"), - ); - let error = send(&engine, EngineMethod::Install).unwrap_err(); - assert_eq!(format!("{error:#}"), expected, "{row}"); - assert_eq!( - engine.methods(), - ["capabilities"], - "{row}: the install must never reach the engine" - ); - } - - // A refused launch is named as a launch. - let engine = engine_answering_capabilities_with( - "handshake-refused-launch", - r#"printf '%s' '{"protocol_version":"9.0.0","ok":true,"data":{}}' -exit 0"#, - ); - let error = send(&engine, EngineMethod::Launch).unwrap_err(); - assert_eq!( - format!("{error:#}"), - format!( - "the launch request was not sent to the engine: the engine speaks engine \ - protocol 9.0.0, which this release (engine protocol {ENGINE_PROTOCOL_VERSION}) \ - cannot use" - ) - ); - assert_eq!(engine.methods(), ["capabilities"]); - - // An engine that cannot be started at all: the cause the OS gave is in - // the error, not only the client's own context line. - let missing = std::env::temp_dir().join("rocm-no-such-engine-binary"); - let envelope = - engine_request_envelope(EngineMethod::Install, &json!({"runtime_id": "r"})) - .unwrap(); - let error = run_engine_stdio( - &missing, - ["stdio"], - &EngineStdioOptions::default(), - &envelope, - ) - .unwrap_err() - .to_string(); - assert!( - error.starts_with("the install request was not sent to the engine: its protocol"), - "{error}" - ); - assert!( - error.contains(&format!( - "failed to spawn engine stdio process {}: ", - missing.display() - )) && error.contains("os error"), - "{error}" - ); - } - - /// The client's own reading of stdout reports a malformed answer in - /// another protocol as the mismatch, not as output that breaks the - /// stdout rule. - #[test] - fn a_malformed_answer_in_another_protocol_is_reported_as_the_mismatch() { - let engine = FakeEngine::answering( - "malformed-incompatible", - r#"{"protocol_version":"9.0.0","status":"ok"}"#, - 0, - ); - let error = run(&engine, &EngineStdioOptions::default()) - .unwrap_err() - .to_string(); - assert_eq!( - error, - format!( - "engine answered in engine protocol 9.0.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ) - ); - assert!(!error.contains("logs go to stderr"), "{error}"); - - // A child that also failed and complained on stderr: the error - // carries both, as for any other unusable answer. - let failing = FakeEngine::new( - "malformed-incompatible-failing", - true, - "printf '%s' '{\"protocol_version\":\"9.0.0\",\"status\":\"ok\"}'\n\ - echo 'engine exploded' >&2\nexit 1", - ); - let error = run(&failing, &EngineStdioOptions::default()) - .unwrap_err() - .to_string(); - assert_eq!( - error, - format!( - "engine answered in engine protocol 9.0.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use \ - (engine stdio process exited with code 1); stderr: engine exploded" - ) - ); - } - - /// The requests that are not checked first (`stop` included) are sent as they are, - /// once, and their answer's version is what is checked. - #[test] - fn a_request_without_a_handshake_is_sent_once() { - for method in [ - EngineMethod::Stop, - EngineMethod::Healthcheck, - EngineMethod::Detect, - EngineMethod::ResolveModel, - EngineMethod::Endpoint, - EngineMethod::Logs, - EngineMethod::Capabilities, - ] { - let engine = FakeEngine::answering("no-handshake", &installed(), 0); - send(&engine, method.clone()).unwrap(); - assert_eq!(engine.methods(), [method.name()], "{method:?}"); - } - let engine = FakeEngine::answering( - "no-handshake-incompatible", - r#"{"protocol_version":"9.0.0","ok":true,"data":{"stopped":true}}"#, - 0, - ); - let error = send(&engine, EngineMethod::Stop).unwrap_err(); - assert_eq!( - error.to_string(), - format!( - "engine answered in engine protocol 9.0.0, which this release \ - (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ) - ); - assert_eq!(engine.methods(), ["stop"]); - } - - /// What an engine leaves on stdout besides its answer makes the answer - /// unreadable, and the error says so; a pretty-printed answer over many - /// lines is still one answer. - #[test] - fn output_besides_the_answer_on_stdout_is_refused_and_named() { - let rule = "(an engine writes only its JSON answer to stdout; logs go to stderr)"; - let logged = FakeEngine::new( - "contaminated-before", - true, - &format!("echo 'INFO loading model'\nprintf '%s' '{STOPPED}'"), - ); - assert_eq!( - run(&logged, &EngineStdioOptions::default()) - .unwrap_err() - .to_string(), - format!( - "failed to parse engine response envelope: the engine wrote other output to \ - stdout before its answer, starting with `INFO loading model` {rule}" - ) - ); - - let trailing = FakeEngine::new( - "contaminated-after", - true, - &format!("printf '%s\\n' '{STOPPED}'\necho done >&1\necho oops >&2"), - ); - assert_eq!( - run(&trailing, &EngineStdioOptions::default()) - .unwrap_err() - .to_string(), - format!( - "failed to parse engine response envelope: the engine wrote other output to \ - stdout after its answer, starting with `done` {rule}; stderr: oops" - ) - ); - - let by_position = FakeEngine::answering( - "envelope-by-position", - r#"[null,true,{"stopped":true},null]"#, - 0, - ); - assert_eq!( - run(&by_position, &EngineStdioOptions::default()) - .unwrap_err() - .to_string(), - format!( - "failed to parse engine response envelope: the engine's stdout is JSON but \ - not an answer envelope (an answer is a JSON object), starting with \ - `[null,true,{{\"stopped\":true}},null]` {rule}" - ), - "an array of the envelope's fields is not an answer" - ); - - let not_an_envelope = FakeEngine::answering("not-an-envelope", r#"{"status":"ok"}"#, 0); - assert_eq!( - run(¬_an_envelope, &EngineStdioOptions::default()) - .unwrap_err() - .to_string(), - format!( - "failed to parse engine response envelope: the engine's stdout is JSON but \ - not an answer envelope (missing field `ok` at line 1 column 15), starting \ - with `{{\"status\":\"ok\"}}` {rule}" - ) - ); - - let empty = FakeEngine::new("empty-stdout", true, "exit 0"); - assert_eq!( - run(&empty, &EngineStdioOptions::default()) - .unwrap_err() - .to_string(), - "failed to parse engine response envelope: the engine printed no answer on stdout" - ); - - let pretty = FakeEngine::new( - "pretty-printed", - true, - &format!( - "printf '{{\\n \"protocol_version\": \"{ENGINE_PROTOCOL_VERSION}\",\\n \"ok\": true,\\n \"data\": {{\\n \"stopped\": true\\n }}\\n}}\\n'" - ), - ); - assert_eq!( - run(&pretty, &EngineStdioOptions::default()).unwrap(), - json!({"stopped": true}) - ); - } } } diff --git a/crates/rocm-engine-protocol/tests/protocol_properties.rs b/crates/rocm-engine-protocol/tests/protocol_properties.rs index 846bd8504c..8aa54b9971 100644 --- a/crates/rocm-engine-protocol/tests/protocol_properties.rs +++ b/crates/rocm-engine-protocol/tests/protocol_properties.rs @@ -22,9 +22,8 @@ use rocm_engine_protocol::{ DetectResponse, DevicePolicy, EngineCapabilities, EngineDeviceAvailability, EngineMethod, EngineRecipeEndpointHint, EngineRecipeHint, EngineRecipeUnsupportedCombinationHint, EngineRequestEnvelope, EngineResponseEnvelope, GpuSelection, HealthcheckResponse, - LaunchRequest, LogsRequest, LogsResponse, PRE_VERSIONING_PROTOCOL, ResolveModelRequest, - engine_id_from_plugin_binary_name, engine_protocol_compatible, gpu_indices_to_csv, - is_public_bind_host, launch_gpu_indices, + LaunchRequest, LogsRequest, LogsResponse, ResolveModelRequest, + engine_id_from_plugin_binary_name, gpu_indices_to_csv, is_public_bind_host, launch_gpu_indices, }; use std::collections::BTreeMap; @@ -925,81 +924,10 @@ fn request_and_detect_documents_have_their_documented_wire_shape() { fn failure_envelope_has_its_documented_wire_shape() { assert_eq!( serde_json::to_value(EngineResponseEnvelope::failure("c", "m")).expect("encode"), - serde_json::json!({ - "protocol_version": rocm_engine_protocol::ENGINE_PROTOCOL_VERSION, - "ok": false, - "error": { "code": "c", "message": "m" } - }) + serde_json::json!({ "ok": false, "error": { "code": "c", "message": "m" } }) ); } -/// What a protocol version is, generated: readable `MAJOR.MINOR.PATCH` -/// versions, near misses, and arbitrary text. -fn protocol_version_strategy() -> impl Strategy { - prop_oneof![ - (0_u64..4, 0_u64..4, 0_u64..20).prop_map(|(a, b, c)| format!("{a}.{b}.{c}")), - (0_u64..4, 0_u64..4).prop_map(|(a, b)| format!("{a}.{b}")), - "[ -~]{0,12}", - ] -} - -proptest! { - #![proptest_config(ProptestConfig { - cases: proptest_cases(512), - ..ProptestConfig::default() - })] - - /// The version field survives a round trip in both envelopes, whatever it - /// holds, so the reader judges what the writer wrote. - #[test] - fn protocol_version_roundtrips_in_both_envelopes( - version in prop::option::of(protocol_version_strategy()), - ) { - let mut request = EngineRequestEnvelope::new(EngineMethod::Stop, serde_json::json!({})); - request.protocol_version = version.clone(); - let decoded: EngineRequestEnvelope = - serde_json::from_str(&serde_json::to_string(&request).expect("encode")) - .expect("decode"); - prop_assert_eq!(&decoded.protocol_version, &version); - - let mut response = EngineResponseEnvelope::success(1); - response.protocol_version = version.clone(); - let decoded: EngineResponseEnvelope = - serde_json::from_str(&serde_json::to_string(&response).expect("encode")) - .expect("decode"); - prop_assert_eq!(&decoded.protocol_version, &version); - } - - /// A missing version is judged exactly as `0.1.0`, the format from before - /// the field existed, against any version this side might speak. - #[test] - fn a_missing_version_is_read_as_the_pre_versioning_protocol( - ours in protocol_version_strategy(), - ) { - prop_assert_eq!( - engine_protocol_compatible(&ours, None).is_ok(), - engine_protocol_compatible(&ours, Some("0.1.0")).is_ok() - ); - prop_assert_eq!(PRE_VERSIONING_PROTOCOL, "0.1.0"); - } - - /// Every readable version is compatible with itself, and the rule is - /// symmetric between two readable versions. - #[test] - fn compatibility_is_reflexive_and_symmetric( - a in (0_u64..4, 0_u64..4, 0_u64..20), - b in (0_u64..4, 0_u64..4, 0_u64..20), - ) { - let a = format!("{}.{}.{}", a.0, a.1, a.2); - let b = format!("{}.{}.{}", b.0, b.1, b.2); - prop_assert!(engine_protocol_compatible(&a, Some(&a)).is_ok()); - prop_assert_eq!( - engine_protocol_compatible(&a, Some(&b)).is_ok(), - engine_protocol_compatible(&b, Some(&a)).is_ok() - ); - } -} - /// The plugin binary naming rule, positively: the `rocm-engine-` prefix with /// an optional `.exe` in either case yields the id, and anything else none. #[test] diff --git a/docs/architecture.md b/docs/architecture.md index e7311e833c..42dedaec9e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -69,7 +69,7 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an | [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) | The WSL2 rocDXG driver plan, which installs the digest-pinned `rocdxg-roct` package or refuses when the download cannot be authenticated. | domain | | [`endpoint_keys.rs`](../apps/rocm/src/endpoint_keys.rs) | Per-service inference-endpoint API keys, stored in owner-only files under the services directory, keyed by service id. | relocation | | [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.rs) | Which runtime an engine installs into and where its environment lives (`engine_manages_own_runtime`, `env_root_for_engine_install`), shared by the engine and SDK install paths. | relocation | -| [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs) | Locating an engine's plugin binary, the engine request entry points (answering from the in-process built-in handler, or running the resolved engine binary with `stdio`), and the in-process built-in engine path, including `rocm __engine-stdio `, which reads its request through the shared `answer_engine_request` so the version is judged before the method. `engine_stdio_child_request` hands the child to the stdio client `rocm` shares with `rocmd`, [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs), and chooses what `rocm` asks of it: the app paths and engine environments root for the child, progress for an install, and the child's stderr forwarded to the terminal. | relocation | +| [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs) | Locating an engine's plugin binary, the engine request entry points (answering from the in-process built-in handler, or running the resolved engine binary with `stdio`), and the in-process built-in engine path. `engine_stdio_child_request` hands the child to the stdio client `rocm` shares with `rocmd`, [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs), and chooses what `rocm` asks of it: the app paths and engine environments root for the child, progress for an install, and the child's stderr forwarded to the terminal. | relocation | | [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs) | Which runtime a `serve` or `engines install` resolves to (`resolve_engine_selection`), the argv and `ROCM_CLI_*` env of a managed child (over [`AppPaths::env_vars`](../crates/rocm-core/src/paths.rs)), and HTTP readiness polling of a launched service. | relocation | | [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs) | `rocm engines` (`engines`), the readiness check `serve` runs for self-managed engines, and the environment root of a running service. | relocation | | [`examine_cmd.rs`](../apps/rocm/src/examine_cmd.rs) | `rocm examine` (`examine`): the human report, or with `--json` the examination plus a summary of what only the CLI knows. | relocation | @@ -108,7 +108,7 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an | [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) | The installed-runtime registry: the manifest model, where manifests live, writing and loading them, selection and activation validation, and the active-runtime marker with the atomic writer activation, rollback and uninstall use (a failed activation's restore writes or removes it directly, and `rocm config set-default-runtime`/`clear-default-runtime` remove it), and the recorded provenance (`RuntimeProvenance`) that the runtime list and `rocm examine` both print. | domain | | [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) | Reconciling running local servers with a runtime being activated or rolled back: classifying each, the report, and moving stale ones with `--restart-services`. | domain | | [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs) | `rocm runtimes uninstall`: planning, revalidating after the prompt, and applying the removal of a registered runtime, including dropping it as the active or rollback runtime in the config and the active-runtime marker and clearing a Lemonade record inside its folder. | domain | -| [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) | `rocm runtimes` (`runtimes`): activation and rollback, which write the active-runtime marker through `runtime_registry.rs`, and the runtime list (`runtimes_listing`, printed as text or `--json` through `JsonOrText`). | relocation | +| [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) | `rocm runtimes` (`runtimes`): activation and rollback, which write the active-runtime marker through `runtime_registry.rs`, and the runtime list. | relocation | | [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) | `rocm serve` (`serve`): engine selection (`select_serve_engine`), the AIM pre-flight, and the GPU and device notes folded into the summary. | relocation | | [`serve_port.rs`](../apps/rocm/src/serve_port.rs) | The `rocm serve` port policy: turns an automatic or explicit `--port` request into one leased port before any manifest, log, key or child exists. | domain | | [`serve_recipe.rs`](../apps/rocm/src/serve_recipe.rs) | The pure transforms `serve()` applies to an engine's launch recipe hint: the catalog mapping, then `--tool-call-parser`, `--gpu-memory-utilization`, generation defaults and `--engine-env`. | relocation | @@ -323,6 +323,7 @@ The library every first-party app and engine crate depends on. It holds host exa | [`host_gpu/linux.rs`](../crates/rocm-core/src/host_gpu/linux.rs) | Linux sysfs, KFD and DRM probes: the KFD topology, the DRM ip-discovery gfx target, the amdgpu device and driver version, the primary GPU name. | domain | | [`host_gpu/os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) | Kernel version, distro name, installed RAM, and the CPU model and vendor for the host summary. One reader returns the CPU model and vendor together for both the summary and `Examination::probe`: Linux from `/proc/cpuinfo`, Windows from the CPU row of the system inventory. `detect_kernel_version` is now the only `uname -r` reader; [`examine/host_env.rs`](../crates/rocm-core/src/examine/host_env.rs)'s `probe_os` calls it for the examination's `kernel_release`. | domain | | [`host_gpu/render.rs`](../crates/rocm-core/src/host_gpu/render.rs) | The `rocm examine` text rendering of an `ExamineSummary`. | domain | +| [`host_gpu/vulkan.rs`](../crates/rocm-core/src/host_gpu/vulkan.rs) | Whether a model can run through Vulkan on this host: ICD manifests, the Windows Khronos registry and `vulkaninfo --summary`, classified into `VulkanStatus`. Each source arrives as a `VulkanEvidence` carrying whether it *answered* (`did_answer()`) apart from what it found, so an empty list can never be read as an answer by accident. `Absent` is reserved for a probe that was able to look and ruled a GPU path out: a `vulkaninfo` that ran and reported nothing (what `examine-57` plants), a software-only ICD list that `vulkaninfo` did not contradict, or an enumeration of only software devices with no GPU manifest beside it. `vulkaninfo` must have answered on every one of those paths, since neither the Linux directory list nor the Windows Khronos key is exhaustive enough to deny a driver alone; where nothing at all was found the driver listing must have answered too, because an empty list is also what a Windows `powershell` that is missing, fails or times out produces. Anything short of that is `Inconclusive`, which reaches the user as the `VulkanUnconfirmed` support level rather than a confirmed absence, with a detail naming which source went unread — claiming absence there would tell a host with a working driver to install one. A software rasteriser never counts as a GPU path, but neither does it deny one that an ICD manifest asserts: a software-only enumeration alongside `radeon_icd.x86_64.json`, the ordinary shape of a missing `render`-group membership, is `DriverPresentDevicesUnverified`. An enumeration that returned only non-AMD hardware is reported as such rather than as a missing driver, but is still routed to the `VulkanOnly` level — a known limitation. | domain | | [`host_gpu/windows_inventory.rs`](../crates/rocm-core/src/host_gpu/windows_inventory.rs) | The Windows display-adapter inventory: the PowerShell queries, their parsers, and assembling one inventory from several sources, including the system query whose CPU row the CPU reader in [`os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) takes. | domain | | [`host_gpu/wsl.rs`](../crates/rocm-core/src/host_gpu/wsl.rs) | WSL detection and the Windows host driver as seen from the guest: the WSL2 signals, the librocdxg chain and the host-driver probes. | domain | | [`jsonl_store.rs`](../crates/rocm-core/src/jsonl_store.rs) | The generic append-only JSONL store engine: sibling `.lock` file, single-line appends, torn-tail repair, size rotation and tail-first reads. | domain | @@ -614,10 +615,9 @@ A contract surface: verify all impacted engines after any protocol change here ( | File | Responsibility | Class | | --- | --- | --- | -| [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs) | The protocol contract: protocol versions (`ENGINE_PROTOCOL_VERSION`), the request/response envelopes with their `protocol_version` field and `EngineRequestEnvelope::new` that stamps it, the per-method types and `EngineMethod::requires_protocol_handshake`, device and GPU-selection policy, engine-plugin discovery, the endpoint API key file carrier shared by `rocm` and `rocmd` (including `remove_endpoint_key_files`, which also removes leftover staged copies of a key), and `optional_arg`, the `flag value` argument helper both binaries build child command lines with. | flat | -| [`fake_engine.rs`](../crates/rocm-engine-protocol/src/fake_engine.rs) | Test-only, behind the `test-support` feature that the `rocm`, `rocmd`, `lemonade`, `vllm` and `aim` dev-dependencies turn on: a shell-script stand-in for an engine child that records its argv, environment, stdin, and the environment and request of each of its runs, and answers (or crashes) as a test asks, so both callers' tests run against the same fake. | flat | -| [`protocol_version.rs`](../crates/rocm-engine-protocol/src/protocol_version.rs) | The engine protocol version rule: hand-parsed `MAJOR.MINOR.PATCH`, a missing version read as `0.1.0`, the caret compatibility rule (`engine_protocol_compatible`, `ProtocolMismatch`), the bump policy, `incompatible_request_response` (the `incompatible_protocol` refusal for a decoded request), `answer_engine_request` (an engine's reading of request text: the version judged before the method, then `unknown_method` or `invalid_request` for the other unusable requests), and, behind the `test-support` feature, `engine_contract`, the one protocol check every engine's tests run. | flat | -| [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs) | The client side of the engine stdio protocol, the one implementation `rocm` and `rocmd` both run an engine child through: the request line, the child's environment (`EngineStdioOptions`: app paths, engine environments root, endpoint key file, whether to withhold an inherited key file from a child that is handed none, progress request), stderr handling (kept for the error, optionally forwarded as it arrives), the SIGPIPE guard around the write and around each forward of the child's stderr, killing and reaping the child when its request cannot be written (the error then carries what it wrote to stderr) or its answer cannot be read, what a failing exit status or an unusable answer is reported as (an empty stdout, other output before or after a top-level answer, quoting that output, JSON that is not an envelope, or not JSON, quoting the start of stdout), the protocol check before an `install` or a `launch` (a `capabilities` request first, on the request's environment without its progress request, and the request is not sent unless its answer is in a compatible protocol; `rocm` answers its built-in engines in-process without it, and no shipped command sends an install or launch to an engine binary today), and `decode_engine_response`, which checks the answer's protocol before anything else in it (an object that does not decode as an envelope has its protocol judged from the raw JSON before its shape is). It sets no timeout, and does not bound the wait for the child's pipes after it exits (a grandchild holding one makes the request wait); its module comment states that limit. Each caller still chooses which program to run: `rocm` the resolved engine binary with `stdio` (or the built-in handler, with no child), `rocmd` the `rocm` executable with `__engine-stdio `. It adds no wire format; the envelope types are the ones in [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs), and the version rule is [`protocol_version.rs`](../crates/rocm-engine-protocol/src/protocol_version.rs). | flat | +| [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs) | The protocol contract: protocol versions, the request/response envelopes and per-method types, device and GPU-selection policy, engine-plugin discovery, the endpoint API key file carrier shared by `rocm` and `rocmd` (including `remove_endpoint_key_files`, which also removes leftover staged copies of a key), and `optional_arg`, the `flag value` argument helper both binaries build child command lines with. | flat | +| [`fake_engine.rs`](../crates/rocm-engine-protocol/src/fake_engine.rs) | Test-only, behind the `test-support` feature the `rocm` and `rocmd` dev-dependencies turn on: a shell-script stand-in for an engine child that records its argv, environment and stdin and answers (or crashes) as a test asks, so both callers' tests run against the same fake. | flat | +| [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs) | The client side of the engine stdio protocol, the one implementation `rocm` and `rocmd` both run an engine child through: the request line, the child's environment (`EngineStdioOptions`: app paths, engine environments root, endpoint key file, whether to withhold an inherited key file from a child that is handed none, progress request), stderr handling (kept for the error, optionally forwarded as it arrives), the SIGPIPE guard around the write and around each forward of the child's stderr, killing and reaping the child when its request cannot be written (the error then carries what it wrote to stderr) or its answer cannot be read, what a failing exit status or an unusable answer is reported as, and `decode_engine_response`. It sets no timeout, and does not bound the wait for the child's pipes after it exits (a grandchild holding one makes the request wait); its module comment states that limit. Each caller still chooses which program to run: `rocm` the resolved engine binary with `stdio` (or the built-in handler, with no child), `rocmd` the `rocm` executable with `__engine-stdio `. It adds no wire format; the envelope types are the ones in [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs). | flat | ### `crates/rocm-deps` @@ -658,7 +658,7 @@ The Lemonade engine adapter (`rocm-engine-lemonade`): installs the embeddable Le | File | Responsibility | Class | | --- | --- | --- | -| [`lib.rs`](../engines/lemonade/src/lib.rs) | Crate root: CLI and envelope dispatch (the `stdio` request read through the shared `answer_engine_request`, and a request for an incompatible engine protocol refused before its payload is read), the service-lifecycle orchestration that calls across the modules, and the crate-root re-exports `apps/rocm` uses. | flat | +| [`lib.rs`](../engines/lemonade/src/lib.rs) | Crate root: CLI and envelope dispatch, the service-lifecycle orchestration that calls across the modules, and the crate-root re-exports `apps/rocm` uses. | flat | | [`main.rs`](../engines/lemonade/src/main.rs) | The `rocm-engine-lemonade` binary's entry point; it only calls `rocm_engine_lemonade::run_cli()`. | flat | | [`archive_cache.rs`](../engines/lemonade/src/archive_cache.rs) | The cached embeddable-archive layer: SHA-256 verification, verified publication into the cache, and the per-archive lock `ensure_cached_archive` returns as an `ArchiveCacheGuard` to hold while using the bytes. | domain | | [`archive_extract.rs`](../engines/lemonade/src/archive_extract.rs) | The hardened in-process tar.gz and zip extractor for the embeddable archive, and the containment-checked `copy_tree` into the runtime directory. | domain | @@ -691,7 +691,7 @@ The vLLM engine adapter (`rocm-engine-vllm`): installs vLLM into a managed TheRo | File | Responsibility | Class | | --- | --- | --- | -| [`lib.rs`](../engines/vllm/src/lib.rs) | Crate root: CLI and envelope dispatch (the `stdio` request read through the shared `answer_engine_request`, and a request for an incompatible engine protocol refused before its payload is read) and the few items shared across the modules, including `verified_torchaudio_release` for the `rocm` binary, a `pub fn` here that delegates to the `pub(crate)` one in [`wheel_builds.rs`](../engines/vllm/src/wheel_builds.rs) (it is not a `pub use`). | flat | +| [`lib.rs`](../engines/vllm/src/lib.rs) | Crate root: CLI and envelope dispatch and the few items shared across the modules, including `verified_torchaudio_release` for the `rocm` binary, a `pub fn` here that delegates to the `pub(crate)` one in [`wheel_builds.rs`](../engines/vllm/src/wheel_builds.rs) (it is not a `pub use`). | flat | | [`main.rs`](../engines/vllm/src/main.rs) | The `rocm-engine-vllm` binary's entry point; it only calls `rocm_engine_vllm::run_cli()`. | flat | | [`discover_builds.rs`](../engines/vllm/src/discover_builds.rs) | The ROCm 10.x discovery table (`VLLM_ROCM_DISCOVER_BUILD_TABLE`, one row per supported `major.minor` line), its lookup and the series matcher. | domain | | [`endpoint_auth.rs`](../engines/vllm/src/endpoint_auth.rs) | The endpoint-key middleware for a keyed launch: writes [`rocm_cli_vllm_auth.py`](../engines/vllm/src/rocm_cli_vllm_auth.py) (compiled in with `include_str!`) under the engine's data directory, prepends that directory to the server's `PYTHONPATH` and passes `--middleware rocm_cli_vllm_auth.RequireEndpointApiKey`, which requires the bearer key on every HTTP and WebSocket route except `GET`/`HEAD /health` and CORS preflights. `VLLM_API_KEY` alone covers only a fixed set of path prefixes. | domain | @@ -716,7 +716,7 @@ The AIM engine adapter (`rocm-engine-aim`) runs models as Docker containers inst | File | Responsibility | Class | | --- | --- | --- | -| [`lib.rs`](../engines/aim/src/lib.rs) | Crate root: CLI and envelope dispatch (the `stdio` request read through the shared `answer_engine_request`, and a request for an incompatible engine protocol refused before its payload is read), including the `builtin_*` entry points the `rocm` binary calls in-process, the detect and capabilities responses, and the items shared across the modules. | flat | +| [`lib.rs`](../engines/aim/src/lib.rs) | Crate root: CLI and envelope dispatch, including the `builtin_*` entry points the `rocm` binary calls in-process, the detect and capabilities responses, and the items shared across the modules. | flat | | [`main.rs`](../engines/aim/src/main.rs) | The `rocm-engine-aim` binary's entry point; it only calls `rocm_engine_aim::run_cli()`. | flat | | [`docker.rs`](../engines/aim/src/docker.rs) | A thin wrapper around the `docker` CLI binary, with no Docker API client, and `container_name`, a service's deterministic Docker-safe container name. | flat | | [`install.rs`](../engines/aim/src/install.rs) | Install for an engine whose images are self-contained: only a check that Docker is present and reachable. | flat | @@ -871,11 +871,11 @@ Gherkin `.feature` files under `features/` backed by Rust step functions that dr | [`tests/e2e/model_catalog_steps.rs`](../tests/e2e-cucumber/tests/e2e/model_catalog_steps.rs) | Steps for [`model_catalog.feature`](../tests/e2e-cucumber/features/model_catalog.feature): the verbose catalog's AIM entry, its Docker-unavailable flag and its staleness warning. | flat | | [`tests/e2e/planner_steps.rs`](../tests/e2e-cucumber/tests/e2e/planner_steps.rs) | Steps for the planning-assistant scenarios in [`chat.feature`](../tests/e2e-cucumber/features/chat.feature), with a scripted mock proving a request is handed over once and its plan is the one shown. | flat | | [`tests/e2e/remote_steps.rs`](../tests/e2e-cucumber/tests/e2e/remote_steps.rs) | Steps for [`remote.feature`](../tests/e2e-cucumber/features/remote.feature): `rocm remote` against the `fake-tailscale` stand-in and a status document the step writes. | flat | -| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, listing planted nightly wheel, older and adopted runtimes with their provenance in the text and in the JSON, and `runtimes list` as text and as `--json`, including the JSON for a runtime whose folder was deleted and for an active key whose registry entry was, a default runtime set in other letter case through `rocm config set-default-runtime`, an active key edited to other letter case or to a key no runtime has, checked against the active runtime `rocm examine --json` reports, a check that the text markers and JSON flags agree, and a `--json` list that fails on a registry entry it cannot read and prints nothing on stdout. | flat | +| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, and listing planted nightly wheel, older and adopted runtimes with their provenance. | flat | | [`tests/e2e/runtime_side_by_side_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_side_by_side_steps.rs) | Steps for the side-by-side scenarios in [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` list, activate and uninstall over managed wheel runtimes planted as installs from before and after the ROCm 10 layout leave them, comparing their install records byte for byte. | flat | | [`tests/e2e/runtime_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_steps.rs) | Steps for [`runtime_setup.feature`](../tests/e2e-cucumber/features/runtime_setup.feature): SDK install previews and installs, runtime folders reached through a link, and the managed runtime they leave active. | flat | | [`tests/e2e/service_cleanup_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_cleanup_steps.rs) | Steps for [`service_record_cleanup.feature`](../tests/e2e-cucumber/features/service_record_cleanup.feature): `rocm services remove` and `prune` over planted service records, asserting on the files that survive, and [`service_record_unqueryable.feature`](../tests/e2e-cucumber/features/service_record_unqueryable.feature): a record whose process cannot be queried (the `e2e-test-hooks` build reads `ROCM_E2E_UNQUERYABLE_PIDS`) is stopped as unverified, refused by `remove`, and cleared by `remove --force` only when no recorded process is confirmed running. | flat | -| [`tests/e2e/service_stop_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_stop_steps.rs) | Steps for [`service_stop.feature`](../tests/e2e-cucumber/features/service_stop.feature) and [`engine_ipc.feature`](../tests/e2e-cucumber/features/engine_ipc.feature): `rocm services stop` and the daemon's `stop_server` tool against a planted service record, and how the daemon reads what an engine child prints (an answer before a failing exit, an unreadable answer, one in an incompatible or a compatible engine protocol, one with a log line before it on stdout), with a stand-in `rocm` staged beside a copy of `rocmd`, and how the real `rocm __engine-stdio vllm` answers requests it cannot serve (another engine protocol, a version that is not text, a method it does not have, input that is not a request); and the confirmed stop against a real recorded process, a recorded PID that now belongs to a different process, and a parent that has started a child. | flat | +| [`tests/e2e/service_stop_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_stop_steps.rs) | Steps for [`service_stop.feature`](../tests/e2e-cucumber/features/service_stop.feature) and [`engine_ipc.feature`](../tests/e2e-cucumber/features/engine_ipc.feature): `rocm services stop` and the daemon's `stop_server` tool against a planted service record, and how the daemon reads what an engine child prints, with a stand-in `rocm` staged beside a copy of `rocmd`; and the confirmed stop against a real recorded process, a recorded PID that now belongs to a different process, and a parent that has started a child. | flat | | [`tests/e2e/service_unknown_id_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_unknown_id_steps.rs) | Steps for [`service_unknown_id.feature`](../tests/e2e-cucumber/features/service_unknown_id.feature): commands that name a local server with no record, checked against the listing they point to. | flat | | [`tests/e2e/serving_steps.rs`](../tests/e2e-cucumber/tests/e2e/serving_steps.rs) | Steps for [`model_serving.feature`](../tests/e2e-cucumber/features/model_serving.feature) and the serve steps other features reuse: `rocm serve` on each engine, ports, managed services and inference. | flat | | [`tests/e2e/skill_steps.rs`](../tests/e2e-cucumber/tests/e2e/skill_steps.rs) | Steps for [`rocm_doctor_skill.feature`](../tests/e2e-cucumber/features/rocm_doctor_skill.feature): drive `rocm` through the sequence the rocm-doctor skill prescribes and check its literal claims. | flat | diff --git a/docs/engine-plugins.md b/docs/engine-plugins.md index 0aa8c759a0..eae236c131 100644 --- a/docs/engine-plugins.md +++ b/docs/engine-plugins.md @@ -32,100 +32,6 @@ The `lemonade` adapter uses Lemonade embeddable and prefers Lemonade's `llamacpp:rocm` backend, falling back to `llamacpp:vulkan` when ROCm is unsupported. rocm-cli does not use a CPU fallback for this path. -## The stdio protocol contract - -An adapter run as `rocm-engine- stdio` (and `rocm __engine-stdio -`, which serves the built-in ones) reads one JSON request envelope on -stdin, to its end, and writes one JSON response envelope on stdout. The client -that sends it is [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs), -shared by `rocm` and `rocmd`; the version rule is in -[`protocol_version.rs`](../crates/rocm-engine-protocol/src/protocol_version.rs). - -**Every envelope names its protocol.** Requests and responses carry -`protocol_version`, the `MAJOR.MINOR.PATCH` version of the engine protocol the -side that wrote it speaks (`ENGINE_PROTOCOL_VERSION`, `0.1.0` today; `rocm -examine` prints it as `protocol:`). `0.1.0` is the baseline: the release that -introduced the field speaks the same format as the messages written before it. -So an envelope without the field is read as `0.1.0`, and an adapter or a daemon -from an earlier release keeps working with this one. - -**Compatibility is the caret rule.** While the major is `0`, two versions are -compatible when their major and minor match (`0.1.0` and `0.1.9` are, `0.1.0` -and `0.2.0` are not); from `1.0.0` on, when their major matches. The patch never -decides. A version must be three dot-separated plain decimal numbers, each -without a leading zero (`0` itself aside) and fitting in 64 bits; anything else -is unreadable and incompatible with everything. - -**When the version is raised.** - -- An addition an older peer can ignore (a new optional field, a new method - that only an engine ever offers) raises the patch. -- A new method a client may send raises the minor while the major is `0`, and - the major after that, because an older engine cannot decode it. The exception - is a method the client sends only to engines whose capabilities say they have - it. -- A removal or a type change (a field dropped, renamed, made required or given - another type) raises the minor while the major is `0`, and the major after - that. - -**What each side does with a mismatch.** - -- An adapter reads the request's version before anything else in it, its method - included. A request it cannot serve, including one whose `protocol_version` - is present and neither a string nor `null`, gets an error envelope with code - `incompatible_protocol`, whatever its method, and nothing else happens. A - `protocol_version` of `null` is read like a missing one, as `0.1.0`. A - request in a protocol it can serve that names a method it does not have gets - `unknown_method`, and input that is not a request envelope (including JSON - that is not an object) gets `invalid_request`. Each of these is an answer on - stdout. Input that is not valid UTF-8 is not read as a request: the adapter - exits with an error and prints no answer. -- The client checks a response's version before anything else in it, `ok` - and the shape of the rest included, whenever stdout is a single JSON object. - An answer in a protocol it cannot use is an error that names both versions, - even when it reports success or does not otherwise decode. -- Before an `install` or a `launch`, the requests that install or start - something, the client first sends `capabilities` (with an empty object as its - payload) through the same path, on the same environment minus the request - for progress, and checks the version of that answer. The `install` or - `launch` is sent only when that answer is in a compatible protocol and is not - an error; otherwise the error says the request was not sent and why (the - engine's version, or the reason its capabilities could not be read). Nothing - is cached: each such request checks again. The check is made by the shared - client, for an engine binary it runs: `rocm` answers its built-in engines in - its own process, with no check, and no shipped command sends an install or - launch to an engine outside it today. The other methods are sent as they are - and only their answer is checked. `stop` is one of them on purpose: it starts - no extra child for a check first, so a stop is never held behind one. An - adapter that checks the version refuses a `stop` made for a protocol it - cannot serve, before reading its payload. An adapter from before the field - ignores the version and acts on the `stop`; its answer names no version and - reads as `0.1.0`, so the client accepts it while this release's protocol is - `0.1.x` and refuses it once the protocol is past that. When the daemon stops - a server and the engine's answer is refused, the report carries that error - as the engine's result; the daemon - still signals the server's recorded processes itself, so for a `vllm` server - the stop completes, while for an `aim` server, whose stop only the engine can - confirm, it is left unconfirmed. - -**Stdout holds only the answer.** The whole of stdout must parse as one -response envelope, a JSON object, pretty-printed over many lines or not. Anything else there, -such as a log line before the answer, makes the answer unreadable, and the -error says so, quoting the other output (or, when there is no answer at all, -the start of stdout). The rule for an adapter is to write its logs and progress -to stderr, which the client collects and shows when a request fails. The -first-party adapters do not hold it everywhere yet. Known cases where a child -process they start can write to the adapter's stdout: - -- `aim` runs `docker pull` with inherited stdout when it starts a container. -- `lemonade` runs its llama.cpp backend install with inherited stdout. When - it is given no log file, the Lemonade server it starts, the Lemonade CLI it - runs to pull or load a model, and a packaged `llama-server` it runs directly - on a GGUF file all inherit stdout too. -- `vllm` leaves the server's stdout inherited when it is given no log file. - -These are known and not yet changed. - ## Lemonade backend alignment on engine install Lemonade's `resources/backend_versions.json` pins which ROCm SDK version its diff --git a/docs/host-probing.md b/docs/host-probing.md index e6b6b3342f..6981426164 100644 --- a/docs/host-probing.md +++ b/docs/host-probing.md @@ -188,6 +188,32 @@ Proposal: the summary stack's inventory survives and `probe_gpus_windows` builds Hosts: this pair is native Windows only; on WSL `gpus[]` is already empty (see the host table), so rebuilding it from the inventory changes nothing there. The characterisation test covers an inventory that answers with one AMD adapter, with an AMD and an NVIDIA adapter, with an NVIDIA adapter only, with no adapter, that fails, and that times out, because `None` in the summary and an empty `gpus[]` with a `probe_failures` entry in the examination are different answers to "no adapter" and "could not ask", and the convergence must keep that distinction. +## Vulkan support + +Verdict: not a duplicate — only the summary stack reads it — but it is a spawned process on a path that several commands reach, so it belongs in this note. + +`detect_vulkan_support` in [vulkan.rs](../crates/rocm-core/src/host_gpu/vulkan.rs) answers two questions: which ICD manifests the loader would find, and which devices actually enumerate. + +| | Linux | Windows | +|---|---|---| +| ICDs | the manifest directories, read from the filesystem | `powershell` over the Khronos `Drivers` registry keys | +| Devices | `vulkaninfo --summary` | `vulkaninfo --summary` as well — there is no registry source for devices — but it is rarely on PATH, so this source usually does not answer at all | +| Timeout | 1.5 s (`OPTIONAL_COMMAND_TIMEOUT`), per candidate spelling | the same 1.5 s, which a cold PowerShell start can exceed | +| Failure | `None` from `capture_optional_command`, which does not distinguish "not installed" from "timed out" | the same | +| Lookup ran? | always true: reading directories that may not exist is still a lookup | `false` whenever `powershell` is missing, exits non-zero or times out | + +The two sources do not return a bare list. Each arrives as a `VulkanEvidence` — `VulkanEvidence` for the ICD manifests, `VulkanEvidence` for the enumerated devices — whose `did_answer()` is whether that source *answered* at all, as opposed to answering with nothing. The last row of the table is the ICD side of that; `vulkan_devices_from_capture` is the `vulkaninfo` side, mapping a `None` capture to `VulkanEvidence::unanswered()`. The two monomorphizations are distinct types, so passing one source's evidence where the other belongs is a compile error rather than a silent status flip. `classify_vulkan_support` reads them as the local bindings `icds_listed` and `enumerated`. + +What it does with them: `vulkaninfo` must have answered before any empty-or-software result may be reported as a confirmed `VulkanStatus::Absent`, because neither the Linux directory list nor the Windows Khronos key is exhaustive and so neither can deny a driver on its own. Where nothing at all was found, the ICD listing must have answered too — an empty `icds` is also what a PowerShell read that failed or timed out produces. Anything short of that is `Inconclusive`. On a platform that is neither Linux nor Windows both flags are `false` — there is nothing to read there — though the classifier never consults them, since `vulkan_is_probeable()` returns `Unknown` first. + +A driver the ICD listing *did* find is also evidence in the other direction: a host carrying `radeon_icd.x86_64.json` whose `vulkaninfo` enumerates only `llvmpipe` (the ordinary shape of a missing `render`-group membership) is `DriverPresentDevicesUnverified`, not `Absent`. Denying the driver there would print "no Vulkan GPU driver was found - install one" beside the `icds` field naming the driver that is already installed. + +Who pays it. The probe runs once per full gather, so every caller of `ExamineSummary::gather` pays one: the text and JSON of `rocm examine`, the MCP and bridge snapshots, the free-form answer, `rocm install driver` and its `--reconcile` form, and `rocmd`'s host snapshot, MCP and sandbox paths. It is deliberately *not* run by the lean scope, `gather_without_driver_facts`, which the runtime-install finalizer uses to read the GPU target and nothing else; that scope leaves `vulkan` as `None` and `vulkan_status` reports `Unknown`. `the_summary_without_driver_facts_does_not_probe_vulkan` pins that, so restoring an unconditional probe fails a test rather than quietly adding a process to the install path. + +What a user can see: on a Windows host whose PowerShell start is slower than 1.5 s, the probe times out and the host reads Vulkan-unconfirmed rather than Vulkan-capable. It is no longer told the *same thing* as a host with a genuinely empty registry key, which is what `icds_listed` buys: the timed-out host is told the driver list could not be read, never that no driver was found, and it can no longer reach `Absent` at all. The collapse that remains is inside `capture_optional_command`, which still cannot say *which* failure it was ("not installed" and "timed out" are one `None`), so the sentence names the possibilities rather than the cause. `windows_icds_from_capture` is the pure seam where that `None` is turned into "did not answer", and it is unit-tested on every platform. + +What the Windows ICD path's tests do and do not reach, stated exactly, because an overstated coverage claim is what leaves a gap nobody goes looking for. `windows_icds_through` takes the subprocess as an argument, so the program name, the flags and the script handed to PowerShell — and what the resulting capture becomes, all the way through `classify_vulkan_support` — are driven from every lane by `the_windows_registry_lookup_runs_the_khronos_script_through_powershell`. The one step no test in this repository executes is starting the process: nothing calls `detect_icds` on Windows, so the `windows-build-and-test` job *compiles* that call without ever running it. What that leaves uncovered is PowerShell's own behaviour on a real host — the script's output encoding, an execution policy that blocks it, a cold start past the 1.5 s timeout. All three arrive as a `None`, which the seam routes to `Inconclusive`, so the untested step can make the answer less useful but not false. + ## Marketing name to gfx target Verdict: confirmed duplicate, but not equivalent. The two cover different names. diff --git a/docs/json-output.md b/docs/json-output.md deleted file mode 100644 index f35214b089..0000000000 --- a/docs/json-output.md +++ /dev/null @@ -1,211 +0,0 @@ - - -# JSON output - -Which `rocm` commands print JSON with `--json`, the rules they follow, and the -commands that do not have it yet. - -## Rules - -- **Text is the default.** `--json` is opt-in per command; leaving it out never - changes the text a person reads. -- **JSON goes to stdout, and only JSON.** With `--json`, stdout holds one JSON - document and nothing else, so a script can parse all of it. Diagnostics, - progress and warnings go to stderr. A command that has no single document to - print is listed below as unsupported rather than given a `--json` that mixes - the two. - - One known exception, tracked as a follow-up: the startup update check that - runs before most commands can print a progress line on stdout ahead of the - document, such as `Python from PATH is not usable for this ROCm install`. - It runs at most once per check interval, and prints only when the runtime it - checks is a wheel install whose recorded Python is not usable and a Python - it finds instead (on `PATH`, or a saved managed one) does not fit. Setting - `ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK` turns the check off, and with it the - line. -- **Errors are not JSON today.** A command that fails with `--json` prints its - error to stderr, prints nothing on stdout, and exits 1, unless the command - documents its own code, as `rocm fix` does. Command lines the argument parser - rejects (an unknown flag, such as `--json` on a command without one, or a - missing argument) exit 2 with a usage message on stderr, before the command - runs. A script tells success from failure by the exit code, not by parsing an - error document. A JSON error shape belongs to the shared envelope below. The - one refusal printed as JSON today is `rocm diagnose --report --json` - declining to prepare a report: that is the command working, so it exits 0 - and prints `refusal_envelope` from - [report.rs](../crates/rocm-core/src/report.rs) (`schema`, `refused`, - `explanation`, `architecture_matrix`). -- **Documented fields do not change silently.** A field may be added. Renaming - or removing one, or giving it a new meaning, needs a versioned transition: - publish the new shape under a new version and keep the old one readable while - callers move. -- **Two shapes are frozen contracts** that other tools are built against: - - `rocm examine --json` — the Examination document the diagnosis tooling - reads. `examination_top_level_keys_match_examine_py_contract` in - [examine.rs](../crates/rocm-core/src/examine.rs) fails if a top-level field - is added, removed or renamed. - - `rocm fix --json` — the fix catalog, carrying `contract_version` - (`CATALOG_CONTRACT_VERSION` in - [manifest.rs](../crates/rocm-core/src/fix/manifest.rs), 1 today). The - rocm-doctor skill states the version it needs, and scenario `skill-07` - holds the two equal. -- **New commands print through the shared helper.** A command whose output is - one value implements `JsonOrText` and calls `print_json_or_text` in - [cli_report.rs](../apps/rocm/src/cli_report.rs), which writes pretty JSON plus - one newline, or the text, and nothing else. - -## Which commands have `--json` - -| Command | Today | Decision | Proven by | -|---|---|---|---| -| `rocm examine` | supported; pretty JSON | supported, frozen | `examine-07`, `examine-08`; `examination_top_level_keys_match_examine_py_contract` | -| `rocm diagnose` | supported; pretty JSON (`DiagnoseOutput` through `JsonOrText`); with `--report`, the prepared report or its refusal | supported | `diagnose-02`, `diagnose-03` | -| `rocm fix` | the catalog only: `--json` is refused with a fix id; `contract_version` 1 | catalog supported, frozen; a JSON result for applying one fix waits for the envelope | `skill-07` | -| `rocm update` | supported for the check; one compact JSON line, not pretty, and refused with `--apply` and `--dry-run` | supported; the compact form is a known difference from the others | `update-02`, `update-03` | -| `rocm storage report` | supported; pretty JSON through `JsonOrText` | supported | `json_or_text_impl_renders_the_report_and_serializes_it` | -| `rocm services list` | supported; pretty JSON. `rocm remote` reads it back over its control channel | supported | `services_json_round_trips_and_applies_the_same_liveness_filter_as_the_table`; exercised indirectly by `remote-15` (`@requires-docker`), whose `rocm remote` reads it back | -| `rocm runtimes list` | supported; pretty JSON through `JsonOrText` | supported, additive-only, no version field yet | `runtime-lifecycle-23` to `runtime-lifecycle-31` and `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first`; what each covers is in [testing.md](testing.md#runtime-selection-and-activation) | -| `rocm runtimes activate`, `rollback`, `uninstall`, `import`, `adopt` | none | follow-up: they change state, so they need the envelope's result and refusal shapes | — | -| `rocm services logs` | none | intentionally unsupported: streamed text, and `-f` never ends | — | -| `rocm services stop`, `restart`, `remove`, `prune` | none | follow-up: needs the envelope, including the refusal path | — | -| `rocm install sdk`, `rocm install driver` | none | follow-up: long-running with progress; needs the envelope and an audit that progress stays off stdout | — | -| `rocm uninstall` | none (`--dry-run` prints the plan as text) | follow-up | — | -| `rocm daemon --status` | none | follow-up; a one-shot snapshot, so a good next command | — | -| `rocm daemon` | none | intentionally unsupported: it runs until stopped | — | - -Commands not in the table (for example `rocm engines list`, `rocm config show`, -`rocm automations list`, `rocm comfyui status`, `rocm setup status`, -`rocm version`) have no `--json` and no decision recorded yet. - -## `rocm runtimes list --json` - -The same listing as the text form, as one object: - -| Field | Value | -|---|---| -| `default_runtime_id` | the configured default runtime id as written in the config, or `null`. The text form labels it `active_runtime_id:`. Not necessarily the active runtime's `runtime_id`: an `active_runtime_key` that names a runtime takes precedence, and the id may differ from its runtime's in letter case or match no runtime at all. Read each runtime's `active` flag to see which one is in use | -| `active_runtime_key` | the configured active runtime key, or `null` | -| `previous_runtime_key` | the configured rollback key, or `null` | -| `registry`, `marker` | paths of the runtime registry folder and the active-runtime marker | -| `active_problem` | `null`, or what is wrong with the configured active runtime, as described under [which runtimes are marked](#which-runtimes-are-marked): `{"kind": "missing_manifest_for_key", "runtime_key"}`, `{"kind": "missing_manifest_for_id", "runtime_id"}`, or `{"kind": "ambiguous_runtime_id", "runtime_id", "runtime_keys": [...]}` | -| `runtimes` | one object per registered runtime, newest install first, ties broken by `runtime_key` | - -Each runtime carries `runtime_key`, `runtime_id`, `version` (as recorded; the -text adds the build date), `format`, `family`, `mode` (`managed` or -`read-only`), `status` (`ready` when the runtime passes the manifest check -that activation applies, `unusable` when it fails it; `ready` does not promise -that an activation succeeds), `unusable_reason` (`null` when ready, otherwise -why the runtime fails that check: text for a person, not a code to match on), -`toolchain` (`included` or `excluded`, the words `rocm examine` uses), `active`, -`rollback_target`, `install_root` and `provenance`. `active` and `rollback_target` are the facts the text marks with -`*` and `-`; a runtime that is both is shown as `*` in the text. The text's -next-step hint for an empty registry is not part of the JSON. - -`provenance` is an object with the four facts the text prints on the runtime's -`provenance:` line, under the same names: `channel`, `source` (the package -index, else the downloaded archive), `source_layout_generation` and -`device_target`. Each is the value the manifest recorded, trimmed, or `null` -where the text prints `unrecorded`: a fact recorded nowhere or recorded blank, -the source of an adopted runtime, the exact target of a tarball or family-wide -install. A script reads `null` as "not recorded"; nothing is guessed from other -facts. - -`registry`, `marker` and `install_root` are strings. A path that is not valid -UTF-8 is written with each invalid sequence replaced by U+FFFD, as the text -form prints it, so such a path cannot be passed back to the filesystem from the -JSON as it stands. - -### Which runtimes are marked - -`active` marks the runtime that `rocm examine`, `rocm runtimes activate`, -`rocm runtimes rollback`, `rocm runtimes uninstall` and `rocm update` treat as -the active one: the listing asks the resolver they use -(`current_runtime_manifest` in -[runtime_registry.rs](../apps/rocm/src/runtime_registry.rs)) rather than -applying rules of its own. That resolver takes the first runtime in list order -whose key matches `active_runtime_key` with ASCII letter case ignored; when -`active_runtime_key` is unset or names no runtime, it takes the one runtime -whose id matches `default_runtime_id`, letter case ignored, and nothing when -that matches none or several. - -`rollback_target` marks the runtime `rocm runtimes rollback` selects: -`previous_runtime_key` resolved the way rollback resolves it -(`select_runtime_manifest`, same file), which ignores surrounding whitespace, -takes an exact key first, then the one key differing only in letter case, then -the one runtime whose id matches. When that selection fails (the value names -nothing, or matches several runtimes), no runtime is the rollback target. A -selected runtime whose `status` is `unusable` is still marked; rollback then -refuses it at the manifest check. - -`active_problem` reports the configuration, by the same matching: - -- `missing_manifest_for_key` when `active_runtime_key` is set and no runtime's - key matches it, letter case ignored. This is the one case where a problem is - reported beside an `active` runtime: when `default_runtime_id` still resolves - one runtime, the commands fall back to it and the listing marks it active, - while `active_problem` still says the configured key names nothing. This - happens when the active runtime's registry entry is deleted outside the CLI - while another registered runtime has the same id (activation records the - active runtime's id as `default_runtime_id`, and installs of one channel and - family share an id). -- With no `active_runtime_key`: `missing_manifest_for_id` when - `default_runtime_id` matches no runtime's id, `ambiguous_runtime_id` when it - matches several (ids differing only in letter case count as several), and - `null` when it matches one, which is then the active runtime. `rocm config - set-default-runtime` reaches this state: it stores the id as typed, clears - `active_runtime_key` and `previous_runtime_key`, and tries to remove the - active-runtime marker file (best effort: a failed removal is ignored). - -Two runtimes can have keys that differ only in letter case on a -case-sensitive filesystem, since `rocm runtimes import` and -`rocm runtimes adopt --runtime-key` store keys as given. For such a pair the -resolver takes the first in list order even when `active_runtime_key` equals -the other exactly, and the listing marks that first one, because it is the one -those commands act on. Each registry entry is a file named `.json`, so on -a case-insensitive filesystem (the default on Windows volumes, and on drvfs -mounts under WSL) the second key names the first one's file: the command -refuses it, or with `--replace` overwrites the first runtime's entry, and this -state cannot occur. - -Not every surface resolves the active runtime this way. Known differences: - -- The runtime manager in `rocm dash` matches exactly: `active_runtime_key` - equal to a runtime's key, or with no `active_runtime_key` the single runtime - whose id equals `default_runtime_id`, and `previous_runtime_key` equal to a - runtime's key. It shows nothing active where the listing marks a runtime - through letter case or through the default-id fallback after a dead key, - shows no rollback target for a `previous_runtime_key` in other letter case, - with surrounding whitespace or given as a runtime id. Of two keys differing - only in letter case it marks the one equal to `active_runtime_key`, where the - listing marks the first in list order, and of two ids differing only in case - it marks the one equal to `default_runtime_id`, where the listing reports - `ambiguous_runtime_id`. -- `rocm setup status` looks `active_runtime_key` up ignoring letter case but - does not fall back to `default_runtime_id`. -- `rocm engines install` without `--runtime-id`, for an engine that runs on the - ROCm runtime, resolves `active_runtime_key` (or, when it is unset, - `default_runtime_id`) the way rollback resolves a key: a dead key fails the - install instead of falling back, and a key matching case twins only by letter - case is refused as ambiguous. - -The shape is additive-only: fields may be added, none will be renamed or -removed without a versioned transition. It carries no version field yet; one -arrives with the envelope if that is adopted. - -## Open decision: a shared envelope - -Every command above prints its own top-level value (an object, or for -`rocm services list` an array). The mutating commands that -are still follow-ups need more than a value: whether the action ran, was -refused or failed, and why, in a shape a script can rely on across commands. A -shared envelope (for example a version, an outcome, the command's result and an -error object) would give them that. - -It is not adopted. Wrapping the existing outputs in it would change documented -shapes, including the two frozen contracts, so it can only arrive alongside -them, under a versioned transition, and the decision belongs with the first -mutating command that needs it. diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 26db54be83..cd7270bba1 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -125,26 +125,6 @@ Expected result: lines. - The active runtime is ready, or the output gives one clear next command. -Then read the same listing as JSON: - -```powershell -rocm runtimes list --json | python -m json.tool -``` - -Expected result: - -- `python -m json.tool` accepts the output and prints it back. Only stdout - enters the pipeline (stderr still shows on the console), so this checks that - stdout holds the document alone; a parse error means something else, such as - a banner, progress or hint line, reached stdout. -- The runtime the text form marks `*` has `"active": true`, and it is the only - one; the runtime marked `-`, if any, has `"rollback_target": true`. -- The runtime marked active is the one `rocm examine` reports: its - `install_root` is the `active_runtime_root` that `rocm examine` prints. -- Each runtime's `provenance` object names the same `channel`, `source`, - `source_layout_generation` and `device_target` as its `provenance:` line in - the text, with `null` where the text shows `unrecorded`. - Optional: an unreadable settings file. Copy `config.json` from the config directory aside, cut the original off part-way through, and run `rocm version` without `ROCM_CLI_DATA_DIR` set. Expected result: @@ -343,12 +323,45 @@ checks, which cannot be made anywhere else: - `rocm examine` shows `detected_gfx_target: gfx90c` with an empty `compatible_therock_family`, plus a `rocm_support` line saying the GPU is - detected but not supported by ROCm and that the Vulkan backend can still be - used. A `` target, or a missing `rocm_support` line, means detection - regressed. That line is printed on **every** host, at one of three levels — - ROCm/HIP-supported, Vulkan-only (this case), or unknown — so on a supported - card or a machine with no GPU it must still be there, saying the level that - host's hardware implies rather than being absent. + detected but not supported by ROCm. A `` target, or a missing + `rocm_support` line, means detection regressed. That line is printed on + **every** host, at one of five levels — ROCm/HIP-supported, Vulkan-only, + Vulkan-unconfirmed, no-GPU-backend, or unknown — so on a supported card or a + machine with no GPU it must still be there, saying the level that host's + hardware implies rather than being absent. + + Which of the three middle levels this machine gets is **not** decided by the + gfx table: `rocm examine` probes for a Vulkan driver, so the answer depends on + what is installed. This is the check that cannot be made in CI, because no + lane has this silicon. Walk it in both directions: + + - With the AMD display driver (Windows) or Mesa RADV (Linux) installed, the + line says models can still run through Vulkan and **names the driver**, and + `rocm examine --json` shows `summary.vulkan.status` as `available` with the + device under `summary.vulkan.devices`. Then actually run + `rocm serve --engine lemonade` — the point of the claim is that it + is true, and this is the only place it can be confirmed against real + hardware. + - With the driver removed but `vulkaninfo` still installed, expect the + *could-not-confirm* wording on Linux rather than a confirmed absence, and it + must **not** still name a driver. This is the known gap recorded on + examine-57, measured rather than assumed: a real `vulkaninfo` with no + reachable driver prints "Found no drivers!" and exits **1**, and the probe + counts only an exit-0 run as having answered, so the host is classed + inconclusive. Telling "no drivers" apart from "the tool is broken" needs the + loader's own message, which the shared capture discards. Seeing "could not + confirm" here is correct, not a regression. + - With neither installed, the line says the check could not be made — the same + level as the bullet above — and tells you to install a Vulkan driver, while + pointing at running `vulkaninfo` yourself to see what it reports. It must + **not** say the driver is absent, and it must **not** tell you to *install* + `vulkaninfo`: on the host above, that tool is already there, so that advice + could never clear the state. The absence claim is the Windows-laptop case + ROCMAI-550 came from, and declaring absence there is the regression + `VulkanUnconfirmed` exists to prevent. + + A software rasteriser (`lavapipe`, `swiftshader`) must never be reported as a + GPU path in any of the three. - A plain `rocm install sdk`, with no `--family`, gives the same refusal with the wording for a *detected* GPU rather than a requested one. - `rocm diagnose` reports `info-20-gpu-no-rocm-support`, naming `gfx90c` and diff --git a/docs/testing.md b/docs/testing.md index a27abd3590..acf0743db1 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -335,77 +335,6 @@ stderr. `an_unparseable_answer_from_a_failing_child_names_the_exit_status` pins the three cases against the fake, and `engine-ipc-02` below shows the same message in a `stop_server` report next to what the stop did. -That error also says what is wrong with what the child printed, because "failed -to parse" alone sends the reader to the engine's source: it printed nothing on -stdout, or other output before or after its answer (a log line on the wrong -stream), or JSON that is not an envelope, or something that is not JSON. The -first says only that nothing was printed. The second quotes the other output, -and the last two the start of stdout (one line, bounded, control characters -escaped); those three also state the rule an engine breaks: only its JSON -answer goes to stdout, its logs go to stderr. -Nothing is salvaged from such output. Only a top-level JSON object counts as the -answer, so a pretty-printed answer over many lines is still one answer, and an -envelope inside an array or another object is not mistaken for one. -`an_unreadable_stdout_is_described_by_what_is_wrong_with_it` covers the -classification on every platform, `an_answer_past_the_search_bound_is_not_looked_for` -the bound on how much of stdout the search reads, and -`output_besides_the_answer_on_stdout_is_refused_and_named` runs the same cases -through the fake. - -The engine protocol version (see the contract in -[engine-plugins.md](engine-plugins.md#the-stdio-protocol-contract)) is tested on -both sides of the conversation and in the rule itself. The rule is a table in -[`protocol_version.rs`](../crates/rocm-engine-protocol/src/protocol_version.rs) -(`the_caret_rule_from_this_builds_version`, every platform), and -`protocol_properties` adds that the field round-trips in both envelopes, that a -missing version is judged as `0.1.0`, and that the rule is reflexive and -symmetric. The client refuses an answer in an incompatible protocol before it -reads `ok` (`an_answer_in_an_incompatible_protocol_is_refused_whatever_it_says`). -The check before an `install` or `launch` is a state matrix against the fake, each -row asserting the error together with which requests the fake recorded: -`a_compatible_engine_is_checked_and_then_sent_the_request` (same, newer -additive and unversioned capabilities answers: two requests, the capabilities -check first), `a_handshaked_request_is_not_sent_when_the_check_fails` -(incompatible, incompatible refusal, unreadable version, an error answer, a crash -with no answer, empty stdout, contaminated stdout, not JSON: only the -capabilities request ever reached the engine), and -`a_request_without_a_handshake_is_sent_once` (every other method is -sent once, and its answer's version is what is checked). The check's own child -is pinned too: `the_check_runs_on_the_requests_environment_without_its_progress` -reads the environment the fake recorded for each run, and -`the_check_withholds_an_inherited_key_file_as_the_request_does` the command it -builds. On the engine side, `answer_engine_request` in `protocol_version.rs` -judges a request's version before its method -(`a_request_is_judged_by_its_version_before_its_method`), and one shared check, -`engine_contract::assert_engine_holds_protocol_contract` (behind the -`test-support` feature), holds every engine to the same list: an incompatible or -unreadable version refused with `incompatible_protocol` for every method in -`EngineMethod::ALL` on the stdio path and the decoded path, and for an unknown -method on the stdio path, `unknown_method` and `invalid_request` for the other -unusable requests, and this build's version on every answer. Each first-party engine runs it -(`stdio_answers_hold_the_engine_protocol_contract` in its `lib.rs`), and -`every_built_in_engine_holds_the_protocol_contract` in `apps/rocm` runs it over -every built-in engine through `answer_builtin_engine_stdio`, the function -`rocm __engine-stdio` answers with; the verb's own stdin reading is covered by -e2e `engine-ipc-08` to `-12`, which run `rocm __engine-stdio vllm`, for `vllm` -only; of those, `-09` to `-12` fail when the verb bypasses the shared reader. -Each engine's `tests/stdio_binary.rs` runs its built `rocm-engine- -stdio` binary and checks that a request for another protocol and input that is -not JSON are each answered with an error envelope and exit status 0. -The shared check is itself tested in both directions: an engine that holds the -contract passes it, and one that ignores the version, or reads it only on the -decoded path, fails it. `the_contract_check_fails_an_engine_that_breaks_any_one_rule` -adds six engines that each break one rule (named in its doc comment), and the -check fails each of them; the check's other rules have no such engine. `engine-ipc-03` to `-07` below show the daemon's side and -`engine-ipc-08` to `-12` the engine's. - -```bash -cargo test -p rocm-engine-protocol -cargo test -p rocm-engine-lemonade -p rocm-engine-vllm -p rocm-engine-aim --lib protocol_contract -cargo test -p rocm-engine-lemonade -p rocm-engine-vllm -p rocm-engine-aim --test stdio_binary -cargo test -p rocm every_built_in_engine_holds_the_protocol_contract -``` - The SIGPIPE tests re-execute the test binary in a fresh process with SIGPIPE at its default action, which is how `rocm` runs, because the test harness leaves it ignored and changing it process-wide would race sibling tests. A write that is @@ -1896,88 +1825,6 @@ List registered managed or read-only runtimes and their exact side-by-side keys: ```bash rocm runtimes list -rocm runtimes list --json -``` - -`--json` prints the same listing as one JSON document on stdout and nothing -else: unset values are `null` rather than ``, each runtime carries -`active` and `rollback_target` flags computed from the same values the text's -`*`/`-` markers are drawn from, and the empty-registry next-step hint is -text-only. The rules every `--json` command follows, and which commands have -one, are in [json-output.md](json-output.md). Scenarios -`@id:runtime-lifecycle-list-json-marks-active-and-rollback` -(`runtime-lifecycle-23`) and `@id:runtime-lifecycle-list-json-empty-registry` -(`runtime-lifecycle-24`) parse the whole of stdout as one document, so a stray -line before or after it fails them; `runtime-lifecycle-23` also checks each -runtime's values as planted, lists the same state as text and checks that the -`*`/`-` rows name the runtimes the JSON flags, and `runtime-lifecycle-07` covers -the text markers on their own. -`@id:runtime-lifecycle-list-json-reports-unusable-runtime` -(`runtime-lifecycle-25`) deletes a runtime's folder and reads -`"status": "unusable"` with the reason `install root is missing: `, and -`@id:runtime-lifecycle-list-json-reports-missing-active-manifest` -(`runtime-lifecycle-26`) deletes the active runtime's registry entry and reads -`active_problem` of kind `missing_manifest_for_key`. -`@id:runtime-lifecycle-list-json-failure-prints-nothing-on-stdout` -(`runtime-lifecycle-30`) covers the failure half of those rules: it replaces a -registry entry with a folder of the same name, so the listing cannot read it -(an entry that reads but does not parse is skipped, not an error), and checks -that `--json` exits 1 with nothing on stdout and a plain-text error on stderr -naming that entry. No scenario checks the -listing's order: scenario 23's two runtimes share one install time, and the -registry is read in filesystem order, which can match key order by chance. -The order is pinned by unit tests: -`runtimes_list_json_has_exactly_the_documented_fields_newest_install_first` -plants five runtimes with one install time in reverse key order beside older -and newer ones, and `registry_sort_is_newest_install_first_then_by_key` tests -the sort on its own. - -Which runtimes the listing marks `active` and `rollback_target`, and when it -reports `active_problem`, are in -[json-output.md](json-output.md#which-runtimes-are-marked): the listing asks -the resolver `rocm examine`, `rocm runtimes activate`/`rollback`, -`rocm runtimes uninstall` and `rocm update` use, and the surfaces that still -resolve differently are listed there. -`@id:runtime-lifecycle-list-default-id-in-other-letter-case` -(`runtime-lifecycle-27`) sets the first runtime's id in upper case through -`rocm config set-default-runtime` and checks that the JSON marks that runtime -active with `active_problem` `null`, and that the text marks it `*` with no -`active_status:` line. -`@id:runtime-lifecycle-list-active-key-in-other-letter-case` -(`runtime-lifecycle-28`) edits the config's active runtime key to the first -runtime's key in upper case while the default id still names the second, and -checks that both forms mark the first runtime active with no problem and that -`rocm examine --json` reports the first runtime's folder as -`active_runtime_root`. -`@id:runtime-lifecycle-list-dead-active-key-falls-back-to-default` -(`runtime-lifecycle-29`) edits the key to one no runtime has while the default -id still names the second runtime, and checks that both forms mark the second -runtime active, that the JSON reports `missing_manifest_for_key` and the text -the matching `active_status:` line, and that `rocm examine --json` reports the -second runtime's folder. -The `listing_state_*` unit tests in -[runtimes_cmd.rs](../apps/rocm/src/runtimes_cmd.rs) list a state matrix in -memory, one test per row (no config; an active key exact, in other case, or naming nothing with -the default id resolving one, none or several; no active key with the default -id matching none, one, one in other case, two, or two differing in case; keys -differing only in case; a previous key exact, in other case, given as a runtime -id, with whitespace, naming nothing, ambiguous, or naming one of two case twins -exactly; and a dead key falling back to the rollback target). Each checks the -JSON flags, `active_problem`, the text markers and the `active_status:` line, -and that `active` and `rollback_target` are what `current_runtime_manifest` and -`select_runtime_manifest` resolve. Keys differing only in case are built in -memory, so these tests hold on a case-insensitive filesystem too. -`runtimes_list_json_writes_a_non_utf8_path_lossily` (Unix only) lists a data -folder whose path is not valid UTF-8, and -`runtime_toolchain_text_and_json_words_agree_for_every_variant` holds the -`toolchain` words in the text and the JSON together: - -```bash -cargo xtask e2e -- -n "runtime-lifecycle-(07|23|24|25|26|27|28|29|30|31) " -cargo test -p rocm --bin rocm runtimes_list -cargo test -p rocm --bin rocm listing_state -cargo test -p rocm --bin rocm runtime_toolchain_text_and_json_words_agree_for_every_variant -cargo test -p rocm --bin rocm registry_sort_is_newest_install_first_then_by_key ``` Each runtime's row is followed by its `install_root:` and a `provenance:` line @@ -2037,32 +1884,6 @@ the `examine` lines. Both plant read-only manifests and run on the mock lane: RUSTC_WRAPPER= cargo xtask e2e -- -n 'runtime-lifecycle-22 |examine-54 ' ``` -`rocm runtimes list --json` gives each runtime the same four facts as a -`provenance` object under the same names, with `null` where the text prints -`unrecorded` ([json-output.md](json-output.md)). Both -forms render from one listing, and the JSON takes its names and order from -`RuntimeProvenance::recorded_fields`, the list `RuntimeProvenance::fields` -shows. `runtimes_list_json_names_recorded_provenance_and_null_for_unrecorded` -in [runtimes_cmd.rs](../apps/rocm/src/runtimes_cmd.rs) pins the whole object -for a nightly, an older, an adopted, a tarball, a padded and an all-blank -runtime; `runtimes_list_text_and_json_name_the_same_provenance` checks over the -same runtimes that the text line and the JSON object name the same facts with -the same values; and -`runtimes_list_json_has_exactly_the_documented_fields_newest_install_first` -pins the object's key set. -`@id:runtime-lifecycle-list-json-names-runtime-provenance` -(`runtime-lifecycle-31`) plants the runtimes of `runtime-lifecycle-22`, reads -each one's provenance from the JSON, and compares it with the text listing of -the same state. It sets `ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK`, as the -examine scenarios that plant a runtime do: with wheel runtimes registered, the -startup update check looks for a Python and the network and can print a -progress line on stdout ahead of the document. It runs on the mock lane: - -```bash -cargo xtask e2e -- -n 'runtime-lifecycle-31 ' -cargo test -p rocm --bin rocm runtimes_list -``` - Activate one validated runtime: ```bash @@ -2190,7 +2011,6 @@ Focused unit coverage: ```bash cargo test -p rocm --bin rocm runtime_activation -cargo test -p rocm --bin rocm runtimes_list cargo test -p rocm --bin rocm runtime_import cargo test -p rocm --bin rocm runtime_adopt cargo test -p rocm --bin rocm runtime_install_writes @@ -2209,6 +2029,7 @@ cargo test -p rocm-core model_recipe cargo test -p rocm-core staleness_warning cargo test -p rocm-core load_model_recipe_index cargo test -p rocm --bin rocm update_report_policy +cargo test -p rocm-engine-lemonade stdio_protocol_routes_all_methods_without_side_effects cargo test -p rocm-engine-vllm stdio_protocol_routes_all_methods_without_side_effects cargo test -p rocm-engine-vllm cargo test -p rocm-engine-aim @@ -3309,50 +3130,23 @@ a hooks build, as `cargo xtask e2e` makes: `cargo build -p rocm -p rocmd suite's own host filter, so it would also run the Windows-only `service-stop-07` on a Linux host, where it fails for want of PowerShell. -`features/engine_ipc.feature` (`engine-ipc-01` to `-12`, Linux, mock lane) +`features/engine_ipc.feature` (`engine-ipc-01` and `-02`, Linux, mock lane) covers how the daemon reads an engine child's answer, through the same -`stop_server` tool (`-01` to `-07`), and how an engine reads a request -(`-08` to `-12`). Each of `-01` to `-07` copies the real `rocmd` into a -scratch directory and puts a stand-in `rocm` shell script beside it, which is the +`stop_server` tool. Each scenario copies the real `rocmd` into a scratch +directory and puts a stand-in `rocm` shell script beside it, which is the executable the standalone daemon runs for an engine request; the stand-in records its argv and the request it was sent, and prints what the scenario -says. Each of `-08` to `-12` runs the real `rocm __engine-stdio vllm`, writes -the scenario's request to its stdin, and reads what it prints and its exit -status. `engine-ipc-01` has the engine answer the stop and then exit non-zero: the +says. `engine-ipc-01` has the engine answer the stop and then exit non-zero: the report carries the engine's answer (not an error built from the exit status). `engine-ipc-02` has it print something that is not an answer, write to stderr and exit non-zero: the report's engine error is the parse failure, naming the -exit status the engine ended with and what was wrong with its stdout, followed -by its stderr. `engine-ipc-03` has the engine answer that it stopped, in an engine -protocol this release cannot use (`9.0.0`): the report's engine result is the -refusal naming both versions, not the answer. `engine-ipc-04` has it write a log -line on stdout before a valid answer: the report's engine error says it wrote -other output before its answer, quoting the line. `engine-ipc-05`, `-06` -and `-07` have it answer in this release's protocol, in a newer one that only -adds to it (the next patch, computed from `ENGINE_PROTOCOL_VERSION`, with a -field this release does not know in the envelope and in the stop's data), and with -no version at all, as an engine from before the -field does: each is read as answered. (They are three scenarios, not one -outline, because the suite keys each scenario's result by its `@id`.) Every one checks the report together with the server's -process, record and endpoint key, and that the stand-in was run once as -`__engine-stdio vllm` with one `stop` request line, written in this release's -protocol. The server is a `vllm` one, for which the engine's -`Stop` is advisory, so in `-02` to `-04` the stop still completes; an engine whose stop +exit status the engine ended with, followed by its stderr. Both check the report together with the server's process, record and +endpoint key, and that the stand-in was run once as `__engine-stdio vllm` with +one `stop` request line. The server is a `vllm` one, for which the engine's +`Stop` is advisory, so in `-02` the stop still completes; an engine whose stop decides the confirmation (`aim`) is not staged here, because teardown would -then run the real engine's stop. `engine-ipc-08` runs the real `rocm -__engine-stdio vllm` and sends it a `stop` request made for protocol `9.0.0` for a -server the engine's own state file names (a live `sleep`, with its `/proc` start -time): the answer is the `incompatible_protocol` refusal naming both versions, -the process is still running and the engine's record still names it, where a -`stop` the engine served would have ended it. `-09` sends a method no engine -has (`frobnicate`) at `9.0.0`, and `-10` a stop whose `protocol_version` is the -number `9`: each is answered `incompatible_protocol`, which only reading the -version before the method or the rest of the envelope can produce, and `-10` -also shows the server still running. `-11` sends `frobnicate` in this release's -protocol (`unknown_method`) and `-12` text that is not JSON (`invalid_request`). -Each of `-08` to `-12` pins the whole answer and an exit status of 0. Run them -with a hooks build and `-n "engine-ipc"`; the steps take this release's version from -`rocm_engine_protocol::ENGINE_PROTOCOL_VERSION`, a dev-dependency of the suite. +then run the real engine's stop. Run them with a hooks build and `-n +"engine-ipc"`. Manual restricted-tool smoke: @@ -4905,22 +4699,49 @@ row is the backend and ordinal with no name — correct and unspecific, rather than specific and wrong. No CI lane has two AMD GPUs, so that branch is covered by unit tests in [host_gpu.rs](../crates/rocm-core/src/host_gpu.rs) only. -**`rocm examine` prints a `rocm_support` line on every host**, at one of three -levels (`gpu_support_level`): ROCm/HIP-supported, Vulkan-only, or unknown. -Unknown covers both "nothing detected" and "a target this build's catalog does -not recognise" — conflating the latter with "confirmed to have no ROCm build" -would turn a detection gap into a claim about the hardware. `examine-55` holds -the line against the `detected_gfx_target` and `compatible_therock_family` the -same report prints, so every lane checks the level its own hardware implies: +**`rocm examine` prints a `rocm_support` line on every host**, at one of five +levels (`gpu_support_level`): ROCm/HIP-supported, Vulkan-only, +Vulkan-unconfirmed, no-GPU-backend, or unknown. Unknown covers both "nothing +detected" and "a target this build's catalog does not recognize" — conflating +the latter with "confirmed to have no ROCm build" would turn a detection gap +into a claim about the hardware. `examine-55` holds the line against the +`detected_gfx_target` and `compatible_therock_family` the same report prints, +so every lane checks the level its own hardware implies: ```bash cargo xtask e2e -- -n '(examine-55)' ``` -Vulkan-only here is inferred from the gfx table, not probed: there are three -support levels and this section describes three. Probing the host for a Vulkan -driver, and the further levels that evidence would make knowable, is separate -work. +The three levels below ROCm/HIP are decided by the Vulkan probe, not by the +gfx table, and each has its own scenario because each is a different +evidentiary state rather than a different wording of one: + +| Scenario | Host it plants | Level asserted | +| --- | --- | --- | +| `examine-56` | An ICD and an enumerated AMD GPU. | Vulkan-only | +| `examine-57` | A `vulkaninfo` that runs and reports nothing. | no GPU backend | +| `examine-58` | Only a software rasteriser (lavapipe). | no GPU backend | +| `examine-59` | No ICD, no device, and no `vulkaninfo` to ask. | Vulkan-unconfirmed | +| `examine-60` | A GPU ICD whose `vulkaninfo` enumerates only a software rasteriser. | Vulkan-only, through `DriverPresentDevicesUnverified` | + +```bash +cargo xtask e2e -- -n '(examine-56|examine-57|examine-58|examine-59|examine-60)' +``` + +`examine-57` and `examine-59` are the pair worth keeping straight: both end +with nothing found, and they differ only in whether a tool was there to look. +That difference is the whole reason `VulkanUnconfirmed` exists, so a change +that collapses them will pass one of these and fail the other rather than +silently reporting a confirmed absence to a host nobody probed. + +`examine-58` and `examine-60` are the second such pair, and they differ only in +which ICD manifest is planted beside the same software-only enumeration. A +lavapipe manifest leaves nothing to contradict the devices, so that host is a +confirmed absence; `radeon_icd.x86_64.json` is a GPU driver the report itself +lists, so telling that host "no Vulkan GPU driver was found - install one" +would contradict the same report's `icds` field with advice it cannot act on. +`examine-60` is also the only scenario that reaches +`VulkanStatus::DriverPresentDevicesUnverified` at all. ## Windows Tool Notes diff --git a/docs/ux-guidelines.md b/docs/ux-guidelines.md index 72b161daee..eb71fb298d 100644 --- a/docs/ux-guidelines.md +++ b/docs/ux-guidelines.md @@ -179,11 +179,3 @@ Command navigability follow-up notes: - Keep backend labels such as wheels, tarballs, runtime keys, registries, and daemon policy out of first-visible TUI screens unless the user opens an explicit advanced/debug view. - -## Machine-Readable Output - -- Text for a person is the default; `--json` is an explicit opt-in per command. -- With `--json`, stdout carries one JSON document and nothing else. Progress, - warnings and diagnostics go to stderr so a piped document stays parseable. -- Which commands have `--json`, the frozen contracts, and the rules for - changing a documented field are in [json-output.md](json-output.md). diff --git a/engines/aim/Cargo.toml b/engines/aim/Cargo.toml index 4454f2528e..97b7d0265d 100644 --- a/engines/aim/Cargo.toml +++ b/engines/aim/Cargo.toml @@ -26,7 +26,3 @@ serde.workspace = true serde_json.workspace = true tempfile = "3" ureq = { version = "2.12", features = ["json", "native-certs"] } - -[dev-dependencies] -# The shared engine protocol contract check (`engine_contract`). -rocm-engine-protocol = { path = "../../crates/rocm-engine-protocol", features = ["test-support"] } diff --git a/engines/aim/src/lib.rs b/engines/aim/src/lib.rs index a3deca7b2f..3bab19210d 100644 --- a/engines/aim/src/lib.rs +++ b/engines/aim/src/lib.rs @@ -155,7 +155,11 @@ pub fn run_cli() -> Result<()> { engine_recipe: None, gpu_selection: crate::process::parse_gpu_selection_arg(gpu.as_deref())?, })?), - CommandKind::Stdio => print_json(&answer_stdio(&read_request()?)), + CommandKind::Stdio => { + let envelope = read_request()?; + let response = handle_envelope(envelope); + print_json(&response) + } CommandKind::ServeHttp { service_id, model_ref, @@ -225,11 +229,6 @@ pub fn builtin_serve_http( } fn handle_envelope(envelope: EngineRequestEnvelope) -> EngineResponseEnvelope { - // Refuse a request made for a protocol this engine cannot serve before its - // payload is read: in another protocol the payload may mean something else. - if let Some(refusal) = rocm_engine_protocol::incompatible_request_response(&envelope) { - return refusal; - } match envelope.method { EngineMethod::Detect => { deserialize_and_respond::(envelope.payload, |request| { @@ -270,10 +269,7 @@ where let request: T = match serde_json::from_value(payload) { Ok(request) => request, Err(error) => { - return EngineResponseEnvelope::failure( - rocm_engine_protocol::INVALID_PAYLOAD_CODE, - error.to_string(), - ); + return EngineResponseEnvelope::failure("invalid_payload", error.to_string()); } }; match handler(request) { @@ -417,21 +413,12 @@ pub(crate) const fn windows_gpu_unsupported_message() -> &'static str { serving is skipped." } -/// The request text on stdin, read to its end. It is decoded by -/// [`answer_stdio`], which judges its protocol version first. -fn read_request() -> Result { +fn read_request() -> Result { let mut input = String::new(); std::io::stdin() .read_to_string(&mut input) .context("failed to read engine stdio request")?; - Ok(input) -} - -/// The answer to the request `text` read on stdin: its protocol version is -/// judged before its method or payload is decoded (see -/// [`rocm_engine_protocol::answer_engine_request`]), then it is handled. -fn answer_stdio(text: &str) -> EngineResponseEnvelope { - rocm_engine_protocol::answer_engine_request(text, handle_envelope) + serde_json::from_str(&input).context("failed to parse engine stdio request") } fn print_json(value: &T) -> Result<()> { @@ -441,19 +428,3 @@ fn print_json(value: &T) -> Result<()> { writeln!(handle)?; Ok(()) } - -#[cfg(test)] -mod protocol_tests { - use super::*; - - /// The engine protocol contract, the same check every engine runs: see - /// [`rocm_engine_protocol::engine_contract`]. - #[test] - fn stdio_answers_hold_the_engine_protocol_contract() { - rocm_engine_protocol::engine_contract::assert_engine_holds_protocol_contract( - "aim", - answer_stdio, - handle_envelope, - ); - } -} diff --git a/engines/aim/tests/stdio_binary.rs b/engines/aim/tests/stdio_binary.rs deleted file mode 100644 index 95b94ffd7f..0000000000 --- a/engines/aim/tests/stdio_binary.rs +++ /dev/null @@ -1,67 +0,0 @@ -// Copyright © Advanced Micro Devices, Inc., or its affiliates. -// -// SPDX-License-Identifier: MIT - -//! The `rocm-engine-aim stdio` binary, end to end: what it reads on stdin goes -//! through the shared request reader, so a request it cannot serve, or input -//! that is not a request, is answered with an error envelope on stdout and a -//! clean exit. - -use std::io::Write as _; -use std::process::{Command, Stdio}; - -/// Run `rocm-engine-aim stdio` with `request` on stdin, on scratch app roots, -/// and return its exit status and the error code of the envelope it printed. -fn answer(label: &str, request: &str) -> (Option, String) { - let root = std::env::temp_dir().join(format!( - "rocm-engine-aim-stdio-{label}-{}", - std::process::id() - )); - let mut child = Command::new(env!("CARGO_BIN_EXE_rocm-engine-aim")) - .arg("stdio") - .env("ROCM_CLI_CONFIG_DIR", root.join("config")) - .env("ROCM_CLI_DATA_DIR", root.join("data")) - .env("ROCM_CLI_CACHE_DIR", root.join("cache")) - .stdin(Stdio::piped()) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()) - .spawn() - .expect("start the engine binary"); - child - .stdin - .take() - .expect("piped stdin") - .write_all(request.as_bytes()) - .expect("write the request"); - let output = child - .wait_with_output() - .expect("wait for the engine binary"); - let _ = std::fs::remove_dir_all(&root); - let stdout = String::from_utf8_lossy(&output.stdout); - let envelope: serde_json::Value = serde_json::from_str(&stdout).unwrap_or_else(|error| { - panic!( - "{label}: no envelope on stdout ({error}): {stdout:?}; stderr: {}", - String::from_utf8_lossy(&output.stderr) - ) - }); - let code = envelope["error"]["code"] - .as_str() - .unwrap_or_default() - .to_owned(); - (output.status.code(), code) -} - -#[test] -fn the_stdio_binary_answers_requests_it_cannot_serve() { - assert_eq!( - answer( - "incompatible", - r#"{"protocol_version":"9.0.0","method":"frobnicate","payload":{}}"# - ), - (Some(0), "incompatible_protocol".to_owned()) - ); - assert_eq!( - answer("garbage", "this is not a request"), - (Some(0), "invalid_request".to_owned()) - ); -} diff --git a/engines/lemonade/Cargo.toml b/engines/lemonade/Cargo.toml index 53ec95e49c..7c5ec45f06 100644 --- a/engines/lemonade/Cargo.toml +++ b/engines/lemonade/Cargo.toml @@ -46,8 +46,6 @@ zip = { version = "9.0", default-features = false, features = ["deflate"] } object = { version = "0.37", default-features = false, features = ["read_core", "elf"] } [dev-dependencies] -# The shared engine protocol contract check (`engine_contract`). -rocm-engine-protocol = { path = "../../crates/rocm-engine-protocol", features = ["test-support"] } rocm-core = { path = "../../crates/rocm-core", features = ["test-support"] } # Archive-extraction property tests; see `crates/rocm-core/src/archive_props.rs`. proptest = { version = "1", default-features = false, features = ["std"] } diff --git a/engines/lemonade/src/lib.rs b/engines/lemonade/src/lib.rs index 112a2c5ffe..b1c33d6a7f 100644 --- a/engines/lemonade/src/lib.rs +++ b/engines/lemonade/src/lib.rs @@ -196,7 +196,8 @@ pub fn run_cli() -> Result<()> { gpu_selection: crate::device_policy::parse_gpu_selection_arg(gpu.as_deref())?, })?)?, CommandKind::Stdio => { - print_json(&answer_stdio(&read_request()?))?; + let envelope = read_request()?; + print_json(&handle_envelope(envelope))?; } CommandKind::ServeHttp { service_id, @@ -261,11 +262,6 @@ pub fn builtin_serve_http( } fn handle_envelope(envelope: EngineRequestEnvelope) -> EngineResponseEnvelope { - // Refuse a request made for a protocol this engine cannot serve before its - // payload is read: in another protocol the payload may mean something else. - if let Some(refusal) = rocm_engine_protocol::incompatible_request_response(&envelope) { - return refusal; - } match envelope.method { EngineMethod::Detect => { deserialize_and_respond::(envelope.payload, |_| { @@ -310,10 +306,7 @@ where Ok(response) => EngineResponseEnvelope::success(response), Err(error) => EngineResponseEnvelope::failure("request_failed", format_error(&error)), }, - Err(error) => EngineResponseEnvelope::failure( - rocm_engine_protocol::INVALID_PAYLOAD_CODE, - error.to_string(), - ), + Err(error) => EngineResponseEnvelope::failure("invalid_payload", error.to_string()), } } @@ -878,21 +871,12 @@ pub(crate) fn current_unix_millis() -> u128 { .as_millis() } -/// The request text on stdin, read to its end. It is decoded by -/// [`answer_stdio`], which judges its protocol version first. -fn read_request() -> Result { +fn read_request() -> Result { let mut buffer = String::new(); std::io::stdin() .read_to_string(&mut buffer) .context("failed to read stdin for engine request")?; - Ok(buffer) -} - -/// The answer to the request `text` read on stdin: its protocol version is -/// judged before its method or payload is decoded (see -/// [`rocm_engine_protocol::answer_engine_request`]), then it is handled. -fn answer_stdio(text: &str) -> EngineResponseEnvelope { - rocm_engine_protocol::answer_engine_request(text, handle_envelope) + serde_json::from_str(&buffer).context("failed to parse engine request envelope") } fn print_json(value: &T) -> Result<()> { @@ -1645,15 +1629,4 @@ mod tests { assert_eq!(response.canonical_model_id, DEFAULT_MODEL); } } - - /// The engine protocol contract, the same check every engine runs: see - /// [`rocm_engine_protocol::engine_contract`]. - #[test] - fn stdio_answers_hold_the_engine_protocol_contract() { - rocm_engine_protocol::engine_contract::assert_engine_holds_protocol_contract( - "lemonade", - answer_stdio, - handle_envelope, - ); - } } diff --git a/engines/lemonade/tests/stdio_binary.rs b/engines/lemonade/tests/stdio_binary.rs deleted file mode 100644 index 5d2b138012..0000000000 --- a/engines/lemonade/tests/stdio_binary.rs +++ /dev/null @@ -1,67 +0,0 @@ -// Copyright © Advanced Micro Devices, Inc., or its affiliates. -// -// SPDX-License-Identifier: MIT - -//! The `rocm-engine-lemonade stdio` binary, end to end: what it reads on stdin goes -//! through the shared request reader, so a request it cannot serve, or input -//! that is not a request, is answered with an error envelope on stdout and a -//! clean exit. - -use std::io::Write as _; -use std::process::{Command, Stdio}; - -/// Run `rocm-engine-lemonade stdio` with `request` on stdin, on scratch app roots, -/// and return its exit status and the error code of the envelope it printed. -fn answer(label: &str, request: &str) -> (Option, String) { - let root = std::env::temp_dir().join(format!( - "rocm-engine-lemonade-stdio-{label}-{}", - std::process::id() - )); - let mut child = Command::new(env!("CARGO_BIN_EXE_rocm-engine-lemonade")) - .arg("stdio") - .env("ROCM_CLI_CONFIG_DIR", root.join("config")) - .env("ROCM_CLI_DATA_DIR", root.join("data")) - .env("ROCM_CLI_CACHE_DIR", root.join("cache")) - .stdin(Stdio::piped()) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()) - .spawn() - .expect("start the engine binary"); - child - .stdin - .take() - .expect("piped stdin") - .write_all(request.as_bytes()) - .expect("write the request"); - let output = child - .wait_with_output() - .expect("wait for the engine binary"); - let _ = std::fs::remove_dir_all(&root); - let stdout = String::from_utf8_lossy(&output.stdout); - let envelope: serde_json::Value = serde_json::from_str(&stdout).unwrap_or_else(|error| { - panic!( - "{label}: no envelope on stdout ({error}): {stdout:?}; stderr: {}", - String::from_utf8_lossy(&output.stderr) - ) - }); - let code = envelope["error"]["code"] - .as_str() - .unwrap_or_default() - .to_owned(); - (output.status.code(), code) -} - -#[test] -fn the_stdio_binary_answers_requests_it_cannot_serve() { - assert_eq!( - answer( - "incompatible", - r#"{"protocol_version":"9.0.0","method":"frobnicate","payload":{}}"# - ), - (Some(0), "incompatible_protocol".to_owned()) - ); - assert_eq!( - answer("garbage", "this is not a request"), - (Some(0), "invalid_request".to_owned()) - ); -} diff --git a/engines/vllm/Cargo.toml b/engines/vllm/Cargo.toml index e7c94e7eeb..05102d0f1e 100644 --- a/engines/vllm/Cargo.toml +++ b/engines/vllm/Cargo.toml @@ -25,7 +25,3 @@ rocm-engine-protocol = { path = "../../crates/rocm-engine-protocol" } serde.workspace = true serde_json.workspace = true tempfile = "3" - -[dev-dependencies] -# The shared engine protocol contract check (`engine_contract`). -rocm-engine-protocol = { path = "../../crates/rocm-engine-protocol", features = ["test-support"] } diff --git a/engines/vllm/src/lib.rs b/engines/vllm/src/lib.rs index c498211f53..93d14140a0 100644 --- a/engines/vllm/src/lib.rs +++ b/engines/vllm/src/lib.rs @@ -191,7 +191,8 @@ pub fn run_cli() -> Result<()> { gpu_selection: crate::process::parse_gpu_selection_arg(gpu.as_deref())?, })?)?, CommandKind::Stdio => { - print_json(&answer_stdio(&read_request()?))?; + let envelope = read_request()?; + print_json(&handle_envelope(envelope))?; } CommandKind::ServeHttp { service_id, @@ -260,11 +261,6 @@ pub fn builtin_serve_http( } fn handle_envelope(envelope: EngineRequestEnvelope) -> EngineResponseEnvelope { - // Refuse a request made for a protocol this engine cannot serve before its - // payload is read: in another protocol the payload may mean something else. - if let Some(refusal) = rocm_engine_protocol::incompatible_request_response(&envelope) { - return refusal; - } match envelope.method { EngineMethod::Detect => { deserialize_and_respond::(envelope.payload, |_| { @@ -314,10 +310,7 @@ where Ok(response) => EngineResponseEnvelope::success(response), Err(error) => EngineResponseEnvelope::failure("request_failed", error.to_string()), }, - Err(error) => EngineResponseEnvelope::failure( - rocm_engine_protocol::INVALID_PAYLOAD_CODE, - error.to_string(), - ), + Err(error) => EngineResponseEnvelope::failure("invalid_payload", error.to_string()), } } @@ -415,21 +408,12 @@ pub(crate) const fn windows_unsupported_message() -> &'static str { "vLLM ROCm serving is supported by rocm-cli only on Linux/WSL; native Windows vLLM is skipped. No CPU fallback is used." } -/// The request text on stdin, read to its end. It is decoded by -/// [`answer_stdio`], which judges its protocol version first. -fn read_request() -> Result { +fn read_request() -> Result { let mut buffer = String::new(); std::io::stdin() .read_to_string(&mut buffer) .context("failed to read stdin for engine request")?; - Ok(buffer) -} - -/// The answer to the request `text` read on stdin: its protocol version is -/// judged before its method or payload is decoded (see -/// [`rocm_engine_protocol::answer_engine_request`]), then it is handled. -fn answer_stdio(text: &str) -> EngineResponseEnvelope { - rocm_engine_protocol::answer_engine_request(text, handle_envelope) + serde_json::from_str(&buffer).context("failed to parse engine request envelope") } fn print_json(value: &T) -> Result<()> { @@ -562,56 +546,36 @@ mod tests { ]; for (method, payload) in success_cases { - let response = handle_envelope(EngineRequestEnvelope::new(method, payload)); + let response = handle_envelope(EngineRequestEnvelope { method, payload }); assert!( response.ok, "expected protocol method to return a typed success envelope: {:?}", response.error ); - assert_eq!( - response.protocol_version.as_deref(), - Some(rocm_engine_protocol::ENGINE_PROTOCOL_VERSION) - ); } - let endpoint = handle_envelope(EngineRequestEnvelope::new( - EngineMethod::Endpoint, - json!({ + let endpoint = handle_envelope(EngineRequestEnvelope { + method: EngineMethod::Endpoint, + payload: json!({ "service_id": service_id.as_str() }), - )); + }); assert!(!endpoint.ok); - assert_eq!( - endpoint.protocol_version.as_deref(), - Some(rocm_engine_protocol::ENGINE_PROTOCOL_VERSION) - ); assert_eq!( endpoint.error.as_ref().map(|error| error.code.as_str()), Some("request_failed") ); for method in [EngineMethod::Install, EngineMethod::Launch] { - let response = handle_envelope(EngineRequestEnvelope::new(method, json!({}))); + let response = handle_envelope(EngineRequestEnvelope { + method, + payload: json!({}), + }); assert!(!response.ok); - assert_eq!( - response.protocol_version.as_deref(), - Some(rocm_engine_protocol::ENGINE_PROTOCOL_VERSION) - ); assert_eq!( response.error.as_ref().map(|error| error.code.as_str()), - Some(rocm_engine_protocol::INVALID_PAYLOAD_CODE) + Some("invalid_payload") ); } } - - /// The engine protocol contract, the same check every engine runs: see - /// [`rocm_engine_protocol::engine_contract`]. - #[test] - fn stdio_answers_hold_the_engine_protocol_contract() { - rocm_engine_protocol::engine_contract::assert_engine_holds_protocol_contract( - "vllm", - answer_stdio, - handle_envelope, - ); - } } diff --git a/engines/vllm/tests/stdio_binary.rs b/engines/vllm/tests/stdio_binary.rs deleted file mode 100644 index e499504f67..0000000000 --- a/engines/vllm/tests/stdio_binary.rs +++ /dev/null @@ -1,67 +0,0 @@ -// Copyright © Advanced Micro Devices, Inc., or its affiliates. -// -// SPDX-License-Identifier: MIT - -//! The `rocm-engine-vllm stdio` binary, end to end: what it reads on stdin goes -//! through the shared request reader, so a request it cannot serve, or input -//! that is not a request, is answered with an error envelope on stdout and a -//! clean exit. - -use std::io::Write as _; -use std::process::{Command, Stdio}; - -/// Run `rocm-engine-vllm stdio` with `request` on stdin, on scratch app roots, -/// and return its exit status and the error code of the envelope it printed. -fn answer(label: &str, request: &str) -> (Option, String) { - let root = std::env::temp_dir().join(format!( - "rocm-engine-vllm-stdio-{label}-{}", - std::process::id() - )); - let mut child = Command::new(env!("CARGO_BIN_EXE_rocm-engine-vllm")) - .arg("stdio") - .env("ROCM_CLI_CONFIG_DIR", root.join("config")) - .env("ROCM_CLI_DATA_DIR", root.join("data")) - .env("ROCM_CLI_CACHE_DIR", root.join("cache")) - .stdin(Stdio::piped()) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()) - .spawn() - .expect("start the engine binary"); - child - .stdin - .take() - .expect("piped stdin") - .write_all(request.as_bytes()) - .expect("write the request"); - let output = child - .wait_with_output() - .expect("wait for the engine binary"); - let _ = std::fs::remove_dir_all(&root); - let stdout = String::from_utf8_lossy(&output.stdout); - let envelope: serde_json::Value = serde_json::from_str(&stdout).unwrap_or_else(|error| { - panic!( - "{label}: no envelope on stdout ({error}): {stdout:?}; stderr: {}", - String::from_utf8_lossy(&output.stderr) - ) - }); - let code = envelope["error"]["code"] - .as_str() - .unwrap_or_default() - .to_owned(); - (output.status.code(), code) -} - -#[test] -fn the_stdio_binary_answers_requests_it_cannot_serve() { - assert_eq!( - answer( - "incompatible", - r#"{"protocol_version":"9.0.0","method":"frobnicate","payload":{}}"# - ), - (Some(0), "incompatible_protocol".to_owned()) - ); - assert_eq!( - answer("garbage", "this is not a request"), - (Some(0), "invalid_request".to_owned()) - ); -} diff --git a/tests/e2e-cucumber/Cargo.toml b/tests/e2e-cucumber/Cargo.toml index 2c61136e44..73050d3279 100644 --- a/tests/e2e-cucumber/Cargo.toml +++ b/tests/e2e-cucumber/Cargo.toml @@ -74,10 +74,6 @@ url = "2" vt100 = "0.18" [dev-dependencies] -# `ENGINE_PROTOCOL_VERSION`, so the engine protocol scenarios name this -# release's version from the constant the binaries stamp rather than a copy of -# it. A dev edge, which `xtask check-crate-edges` exempts. -rocm-engine-protocol = { path = "../../crates/rocm-engine-protocol" } # Reads a printed command line back the way a POSIX shell splits words, so a # scenario can assert what a `tool_call:` line denotes rather than one spelling # of it. diff --git a/tests/e2e-cucumber/features/engine_ipc.feature b/tests/e2e-cucumber/features/engine_ipc.feature index a2ce1f5057..96eb773636 100644 --- a/tests/e2e-cucumber/features/engine_ipc.feature +++ b/tests/e2e-cucumber/features/engine_ipc.feature @@ -1,41 +1,25 @@ -Feature: How the daemon and an engine read each other over stdio +Feature: How the daemon reads an engine's answer # `rocmd` asks an engine to do things (here: stop a server) by running # `rocm __engine-stdio ` and reading what the child prints. The # standalone `rocmd` binary has no such verb of its own and runs the `rocm` - # beside it, which is what makes engine-ipc-01 to -07 stageable from outside: - # each copies the real `rocmd` into a scratch directory and puts a stand-in + # beside it, which is what makes these scenarios stageable from outside: each + # one copies the real `rocmd` into a scratch directory and puts a stand-in # `rocm` next to it, so the daemon's own tool reaches a child whose answer the # scenario controls. The stand-in records the argv and the request it was # given and prints what the scenario says. # - # service-stop-02 covers the engine that answers cleanly; engine-ipc-01 and -02 - # are the other ways an engine child ends; -03 and -04 are answers the daemon - # refuses (written in an engine protocol it cannot use, or not alone on - # stdout), and -05 to -07 answers it reads (in its own protocol, in a newer - # one that only adds to it, and in none, as from an engine older than the - # field). In each, the engine's message in the tool's + # service-stop-02 covers the engine that answers cleanly; the two below are the + # other ways an engine child ends. In each, the engine's message in the tool's # report is checked together with what the stop did to the server: its process, # its record and its endpoint key. The server is a `vllm` one, for which the # engine's `Stop` is advisory (the recorded process decides whether the stop # is confirmed), so the stop going through is part of what is shown, not a # side effect. # - # engine-ipc-08 to -12 are the other direction: the real built-in `vllm` - # engine, run as `rocm __engine-stdio vllm` the way the daemon runs it, reads a - # request. -08 is a stop it cannot serve, for a server whose process the - # engine itself recorded; -09 and -10 are requests it refuses for their - # protocol before it decodes their method (one it does not have) or reads a - # version that is not even text; -11 and -12 are a method it does not have in - # its own protocol, and input that is not a request at all. Each is answered - # on stdout, with a clean exit. - # - # engine-ipc-01 to -08 and -10 are Linux-only, for the same reason as - # service-stop-02: the recorded process carries the start-time token `/proc` - # gives it, and in -01 to -07 the stand-in is a shell script. -09, -11 and - # -12 use neither, but have only been run on Linux, so they keep the tag until - # they are run on Windows. No GPU and no real engine server are involved, so - # these run on the mock lane. + # Linux-only, for the same reason as service-stop-02: the recorded process + # carries the start-time token `/proc` gives it, and the stand-in is a shell + # script. No GPU and no real engine are involved, so these run on the mock lane. @id:engine-ipc-reads-an-answer-printed-before-a-failing-exit @requires-os:linux @@ -61,101 +45,3 @@ Feature: How the daemon and an engine read each other over stdio And the recorded process is no longer running And the server's record reads stopped and names no process And the server's endpoint key file is gone - - @id:engine-ipc-refuses-an-answer-in-a-protocol-it-cannot-use - @requires-os:linux - Scenario: engine-ipc-03 - An engine's answer in an engine protocol this release cannot use is refused, and the stop still completes - Given a managed server whose recorded process is running - And the engine answers the stop request in an engine protocol this release cannot use - When the standalone daemon's stop_server tool stops that server - Then the engine received one stop request for that server over stdio - And the tool reports the engine's answer refused, naming the engine's protocol and this release's - And the tool still reports the server stopped - And the recorded process is no longer running - And the server's record reads stopped and names no process - And the server's endpoint key file is gone - - @id:engine-ipc-refuses-an-answer-with-other-output-on-stdout - @requires-os:linux - Scenario: engine-ipc-04 - An engine's answer with a log line before it on stdout is refused, and the stop still completes - Given a managed server whose recorded process is running - And the engine writes a log line on stdout before its answer to the stop request - When the standalone daemon's stop_server tool stops that server - Then the engine received one stop request for that server over stdio - And the tool reports the engine's answer refused for the log line the engine wrote before it - And the tool still reports the server stopped - And the recorded process is no longer running - And the server's record reads stopped and names no process - And the server's endpoint key file is gone - - @id:engine-ipc-reads-an-answer-in-its-own-protocol - @requires-os:linux - Scenario: engine-ipc-05 - An engine that answers in this release's engine protocol is read as having answered - Given a managed server whose recorded process is running - And the engine answers the stop request in this release's engine protocol - When the standalone daemon's stop_server tool stops that server - Then the engine received one stop request for that server over stdio - And the tool reports the engine's answer to the stop - And the recorded process is no longer running - And the server's record reads stopped and names no process - And the server's endpoint key file is gone - - @id:engine-ipc-reads-an-answer-in-a-newer-compatible-protocol - @requires-os:linux - Scenario: engine-ipc-06 - An engine that answers in a newer engine protocol that only adds to this release's is read as having answered - Given a managed server whose recorded process is running - And the engine answers the stop request in a newer engine protocol that only adds to this release's - When the standalone daemon's stop_server tool stops that server - Then the engine received one stop request for that server over stdio - And the tool reports the engine's answer to the stop - And the recorded process is no longer running - And the server's record reads stopped and names no process - And the server's endpoint key file is gone - - @id:engine-ipc-reads-an-answer-that-names-no-protocol - @requires-os:linux - Scenario: engine-ipc-07 - An engine that names no engine protocol, as one from before the field, is read as having answered - Given a managed server whose recorded process is running - And the engine answers the stop request in no named engine protocol - When the standalone daemon's stop_server tool stops that server - Then the engine received one stop request for that server over stdio - And the tool reports the engine's answer to the stop - And the recorded process is no longer running - And the server's record reads stopped and names no process - And the server's endpoint key file is gone - - @id:engine-ipc-engine-refuses-a-request-in-a-protocol-it-cannot-serve - @requires-os:linux - Scenario: engine-ipc-08 - An engine asked to stop a server in an engine protocol it cannot serve refuses, and leaves the server running - Given an engine server whose process the vllm engine recorded is running - When the vllm engine is asked over stdio to stop that server, in an engine protocol it cannot serve - Then the engine answers that it cannot serve that engine protocol, naming its own and the request's - And the engine server's process is still running - And the vllm engine's record of that server still names its process - - @id:engine-ipc-engine-refuses-an-unknown-method-in-a-protocol-it-cannot-serve - @requires-os:linux - Scenario: engine-ipc-09 - An engine sent a method it does not have, in an engine protocol it cannot serve, refuses it for the protocol - When the vllm engine is sent over stdio a request for a method it does not have, in an engine protocol it cannot serve - Then the engine answers that it cannot serve that engine protocol, naming its own and the request's - - @id:engine-ipc-engine-refuses-a-version-that-is-not-text - @requires-os:linux - Scenario: engine-ipc-10 - An engine asked to stop a server with a protocol version that is not text refuses, and leaves the server running - Given an engine server whose process the vllm engine recorded is running - When the vllm engine is sent over stdio a stop request for that server whose protocol version is not text - Then the engine answers that it cannot read the request's protocol version - And the engine server's process is still running - And the vllm engine's record of that server still names its process - - @id:engine-ipc-engine-answers-an-unknown-method - @requires-os:linux - Scenario: engine-ipc-11 - An engine sent a method it does not have, in its own engine protocol, says it has no such method - When the vllm engine is sent over stdio a request for a method it does not have, in its own engine protocol - Then the engine answers that it has no such method - - @id:engine-ipc-engine-answers-input-that-is-not-a-request - @requires-os:linux - Scenario: engine-ipc-12 - An engine sent something that is not a request says so in an answer - When the vllm engine is sent over stdio something that is not a request - Then the engine answers that what it was sent is not a request diff --git a/tests/e2e-cucumber/features/examine.feature b/tests/e2e-cucumber/features/examine.feature index 27b03d497c..74c7bcdeb4 100644 --- a/tests/e2e-cucumber/features/examine.feature +++ b/tests/e2e-cucumber/features/examine.feature @@ -814,3 +814,87 @@ Feature: GPU detection and system inspection Then the inspection states this host's ROCm support level And the support level agrees with the GPU the inspection detected And the support level leaves a command that fits this host + + # The `VulkanOnly` door needs a Renoir/Cezanne Vega APU and no runner has one, + # but it does not need the hardware: only the two signals the CLI reads for it + # -- a KFD node naming the target, and the host's Vulkan driver state -- both + # of which the harness can plant. So these run on the ungated mock lane, which + # is the lane that has neither. + # + # Each pins one of the answers a probe can reach where inference from the gfx + # table reaches only one: "no ROCm build" does not mean "Vulkan then" on a + # machine nobody has looked at, and these scenarios are what keep those + # answers distinguishable. + @id:examine-names-the-vulkan-driver-an-unsupported-gpu-can-use @requires-os:linux + Scenario: examine-56 - A GPU the official stack rejects is told which way it can still run models + Given a machine whose GPU has no official support but has a working Vulkan driver + When the user inspects that machine + Then the inspection reports the GPU as unsupported by the official stack + And the inspection reports that models can still run through Vulkan + And the inspection names the Vulkan driver it found + + # What this plants is the exit-0-and-empty shape, not a driverless host. A + # host with no driver at all fails to create a Vulkan instance and exits + # non-zero, which the probe reads as a source that did not answer -- so such + # a host is reported as inconclusive, not as a confirmed absence. Confirmed + # absence is deliberately the narrower claim (see `VulkanStatus::Absent` for + # why a failing probe must not be promoted to one), and this scenario covers + # that narrower claim rather than the driverless host. + @id:examine-does-not-promise-vulkan-without-a-driver @requires-os:linux + Scenario: examine-57 - A machine with no way to run models is not told it has one + Given a machine whose GPU has no official support and no Vulkan driver + When the user inspects that machine + Then the inspection reports the GPU as unsupported by the official stack + And the inspection does not claim models can run through Vulkan + And the inspection says no Vulkan driver was found + + # A software renderer is a complete Vulkan implementation that runs on the + # CPU. Counting it would put a GPU-required run on the processor while + # reporting a GPU path - the one outcome the no-fallback rule exists to + # prevent, reached through a backend rather than a policy change. + @id:examine-does-not-count-a-software-renderer-as-a-gpu-path @requires-os:linux + Scenario: examine-58 - A software renderer does not count as a way to run on the GPU + Given a machine whose GPU has no official support and only a software renderer + When the user inspects that machine + Then the inspection does not claim models can run through Vulkan + And the inspection says the only renderer it found runs on the CPU + + # The shape examine-57 does not reach. examine-57 plants a `vulkaninfo` that + # runs and reports no devices, which is the only shape that earns a confirmed + # absence; this host has no `vulkaninfo` to ask at all, and must be told the + # check could not be made rather than either promised Vulkan or declared to + # have nothing. + # + # Known gap, measured rather than assumed: a real `vulkaninfo` on a Linux host + # with no reachable driver does NOT produce examine-57's shape. It prints + # "Found no drivers!" and exits 1, which this probe classifies as + # inconclusive — so such a host lands at *this* scenario's level rather than + # examine-57's. Telling "no drivers" apart from "the tool is broken" needs the + # loader's own message, which the shared capture discards. + @id:examine-cannot-confirm-vulkan-without-vulkaninfo @requires-os:linux + Scenario: examine-59 - A machine that cannot be checked for Vulkan is not told either way + Given a machine whose GPU has no official support and no way to check Vulkan + When the user inspects that machine + Then the inspection reports the GPU as unsupported by the official stack + And the inspection does not claim models can run through Vulkan + And the inspection says it could not confirm whether a Vulkan driver is there + + # examine-58 with one thing changed: the manifest beside the software renderer + # names a real GPU driver. That is the common `render`-group permission shape + # -- the driver is installed, and the user's own account cannot open the + # device, so the loader falls back to llvmpipe -- and it is the one case where + # the device evidence must NOT be allowed to deny the driver. "No Vulkan GPU + # driver was found - install one" would contradict the `icds` field of the + # same report and name an install the host has already done. + # + # The pair is the test: examine-58 and this scenario plant the same + # enumeration and differ only in the manifest, so an implementation that reads + # the devices before the manifests passes one and fails the other instead of + # collapsing both into a confirmed absence. + @id:examine-does-not-deny-an-installed-vulkan-driver-a-software-renderer-masks @requires-os:linux + Scenario: examine-60 - An installed GPU driver masked by a software renderer is not reported as missing + Given a machine whose GPU has no official support and a Vulkan driver masked by a software renderer + When the user inspects that machine + Then the inspection reports the GPU as unsupported by the official stack + And the inspection does not say a Vulkan driver is missing + And the inspection names the installed Vulkan driver it could not confirm diff --git a/tests/e2e-cucumber/features/runtime_lifecycle.feature b/tests/e2e-cucumber/features/runtime_lifecycle.feature index 19bfe62a5b..d4e4f1086b 100644 --- a/tests/e2e-cucumber/features/runtime_lifecycle.feature +++ b/tests/e2e-cucumber/features/runtime_lifecycle.feature @@ -328,130 +328,3 @@ Feature: Runtime lifecycle state machine And its version shows its build date And the older runtime's listing says which of those facts were not recorded instead of guessing And the adopted runtime's listing says it has no recorded package source - - # A script reads the runtime list without scraping the table. stdout must hold - # one JSON document and nothing else; diagnostics belong on stderr. The active - # and rollback flags are the facts the text marks with `*` and `-`, so the - # scenario also lists the same state as text and checks that both forms mark - # the same runtimes. - @id:runtime-lifecycle-list-json-marks-active-and-rollback - Scenario: runtime-lifecycle-23 - A script reads the runtime list as JSON - Given two registered runtimes with the second active after the first - When the user lists the registered runtimes as JSON - Then the output is a single JSON document and nothing else - And the JSON lists both runtimes with their recorded values - And the JSON marks the second runtime active and the first as the rollback target - And the text listing marks the same runtimes as the JSON - - # The empty registry is where the text form prints placeholders (``) - # and a next-step hint; the JSON form has to stay a parseable document with - # nulls instead, not fall back to that text. - @id:runtime-lifecycle-list-json-empty-registry - Scenario: runtime-lifecycle-24 - Listing runtimes as JSON with none registered - Given no ROCm runtime is registered - When the user lists the registered runtimes as JSON - Then the output is a single JSON document and nothing else - And the JSON lists no runtimes and no active runtime - - # A runtime whose folder was deleted outside the CLI stays registered, but - # activation would refuse it. A script has to see that from the document - # alone, without trying the activation. - @id:runtime-lifecycle-list-json-reports-unusable-runtime - Scenario: runtime-lifecycle-25 - The JSON runtime list reports a runtime whose folder is gone as unusable - Given two registered runtimes with the second active after the first - And the first runtime's folder has been deleted - When the user lists the registered runtimes as JSON - Then the output is a single JSON document and nothing else - And the JSON reports the first runtime unusable because its folder is missing - And the JSON reports the second runtime ready - - # The active runtime's registry entry was removed by hand while the config - # still names it. The document has to say so, not just mark nothing active. - @id:runtime-lifecycle-list-json-reports-missing-active-manifest - Scenario: runtime-lifecycle-26 - The JSON runtime list says when the active runtime's registry entry is gone - Given two registered runtimes with the second active after the first - And the second runtime's registry entry has been deleted - When the user lists the registered runtimes as JSON - Then the output is a single JSON document and nothing else - And the JSON reports that the active runtime key has no registered runtime - And the JSON marks no runtime active - - # `rocm config set-default-runtime` stores the id as typed and clears the - # active key, so the list decides the active runtime from the default id - # alone. An id that differs from a runtime's only in letter case still names - # that runtime, and the list must not also report its registry entry missing. - @id:runtime-lifecycle-list-default-id-in-other-letter-case - Scenario: runtime-lifecycle-27 - A default runtime set in other letter case is listed as active with no problem - Given two registered runtimes and none active - When the user sets the default runtime to the first runtime's id in other letter case - And the user lists the registered runtimes as JSON - Then the output is a single JSON document and nothing else - And the JSON shows the default runtime as typed and no active runtime key - And the JSON marks only the first runtime active and reports no problem - And the text listing marks the first runtime active with no active_status line - - # A config edited by hand can name the active runtime in other letter case. - # The commands that act on the active runtime match its key ignoring case, so - # the list has to mark the runtime they act on, and `rocm examine` has to - # report that same runtime. The default runtime still names the second - # runtime, so a list that fell back to it would mark the wrong one. - @id:runtime-lifecycle-list-active-key-in-other-letter-case - Scenario: runtime-lifecycle-28 - An active runtime named in other letter case is listed as the one examine reports - Given two registered runtimes with the second active after the first - And the configuration names the first runtime as active in other letter case - When the user lists the registered runtimes as JSON - Then the output is a single JSON document and nothing else - And the JSON marks only the first runtime active and reports no problem - And the text listing marks the first runtime active with no active_status line - And examine reports the first runtime as the active one - - # The configured active runtime is not registered, but the default runtime - # still names a registered one and the commands fall back to it. The list - # marks that runtime active, as `rocm examine` reports it, and still says the - # configured active runtime is missing, in both forms. - @id:runtime-lifecycle-list-dead-active-key-falls-back-to-default - Scenario: runtime-lifecycle-29 - A missing active runtime is reported while the default runtime the commands use is listed active - Given two registered runtimes with the second active after the first - And the configuration names an unregistered runtime as active - When the user lists the registered runtimes as JSON - Then the output is a single JSON document and nothing else - And the JSON marks only the second runtime active - And the JSON reports that the active runtime key has no registered runtime - And the text listing marks the same runtimes as the JSON - And the text listing says the active runtime key has no registered runtime - And examine reports the second runtime as the active one - - # `--json` changes what a successful list prints, not how a failure is - # reported: errors are not JSON. A registry entry the CLI cannot read stops - # the list, so a script has to learn that from the exit code and an empty - # stdout rather than from a document that looks like a shorter list. - @id:runtime-lifecycle-list-json-failure-prints-nothing-on-stdout - Scenario: runtime-lifecycle-30 - A runtime list that cannot be read fails as JSON with nothing on stdout - Given two registered runtimes with the second active after the first - And the first runtime's registry entry cannot be read - When the user lists the registered runtimes as JSON - Then the list fails with nothing printed on stdout - And the error on stderr is plain text naming the unreadable registry entry - - # A script reads where each runtime came from out of the JSON listing instead - # of parsing the text's `provenance:` line. A fact the manifest never recorded - # has no value there, where the text prints `unrecorded`, so a script cannot - # take the placeholder for a recorded value. The same runtimes as - # `runtime-lifecycle-22` are planted, and the text listing of the same state - # is compared fact by fact, so the two forms are shown to agree. The startup - # update check is off: with wheel runtimes registered it looks for a Python - # and the network, and can print ahead of the document, which is not what - # this scenario is about. The planted manifests need no SDK download or GPU, - # so this runs on the mock lane. - @id:runtime-lifecycle-list-json-names-runtime-provenance - Scenario: runtime-lifecycle-31 - A script reads from the JSON runtime list which stream, source and GPU each runtime was installed from - Given a registered nightly runtime installed for one exact GPU - And a registered runtime installed before its source layout and GPU target were recorded - And a registered runtime adopted from an environment ROCm CLI did not install - And ROCm CLI does not check for runtime updates when it starts - When the user lists the registered runtimes as JSON - Then the output is a single JSON document and nothing else - And the JSON names the nightly runtime's channel, package source, source layout and exact GPU target - And the JSON gives no value for each fact the older runtime did not record instead of guessing - And the JSON gives no package source for the adopted runtime - And the text listing names the same provenance as the JSON for every runtime diff --git a/tests/e2e-cucumber/tests/e2e/examine_steps.rs b/tests/e2e-cucumber/tests/e2e/examine_steps.rs index 294fbe85ff..828ea5a4cf 100644 --- a/tests/e2e-cucumber/tests/e2e/examine_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/examine_steps.rs @@ -1752,6 +1752,26 @@ async fn assert_no_amdgpu_fault_evidence(world: &mut E2eWorld) { } } +/// The human-readable twin of the machine-readable planted-machine step, for +/// scenarios whose subject is a sentence the report prints rather than a field +/// it serialises. +/// +/// It has to be its own step rather than reusing "the user inspects the +/// system", because that one runs through `run_rocm`, which does not consume +/// `World::command_env` -- so a planted host root never reaches the child and +/// the CLI silently describes the *runner* instead. A scenario wired to that +/// step still passes while reporting the lane's own GPU (`gfx942` on the MI300X +/// runners) under a claim about a planted Renoir APU, so examine-56/57/58 must +/// use this one. +#[when("the user inspects that machine")] +async fn user_inspects_planted_machine_text(world: &mut E2eWorld) { + let (stdout, stderr, rc) = + crate::run_rocm_with_scenario_env(world, &["examine", "--framework", "skip"]); + world.cli_output = Some(stdout); + world.cli_stderr = Some(stderr); + world.cli_rc = Some(rc); +} + #[when("the user inspects that machine in machine-readable form")] async fn user_inspects_planted_machine(world: &mut E2eWorld) { let (stdout, stderr, rc) = @@ -3593,6 +3613,35 @@ async fn assert_support_level_advice_fits(world: &mut E2eWorld) { "rocm serve ", &["rocm install sdk", "--engine lemonade"], ), + // The two probed Vulkan tiers land here too, and neither owes `--engine + // lemonade`: on both, nothing has established a backend that can serve + // this GPU, so naming an engine would promise a run the evidence does + // not support. A driver is what clears either condition. + // + // Both arms are load-bearing and must stay: the catch-all below demands + // `--engine lemonade`, which neither tier's text contains, so a host in + // either tier fails examine-49 the moment one of them is dropped. No CI + // lane carries a detected, ROCm-unsupported GPU, so that regression is + // silent here and only shows up on the first such runner. + // + // Told apart by each tier's own wording, as the catalog arm above is: + // `VulkanUnconfirmed` says the probe could not settle it, `NoGpuBackend` + // says it looked and found nothing. The `VulkanUnconfirmed` guard reads + // `rocm_core`'s own constant rather than a copy of its text, so the two + // cannot drift apart when the sentence is reworded. + // + // What that tier owes is ``run `vulkaninfo` ``, not "install a Vulkan + // driver": `rocm_support_line` drops the install advice on a Windows + // host whose AMD display driver the summary already found, since that + // driver *is* the Vulkan driver there. `vulkaninfo` is the one step that + // can clear this condition on every host that reaches it. + (Some(_), None, _) if line.contains(rocm_core::VULKAN_UNCONFIRMED_CLAIM) => ( + "run `vulkaninfo`", + &["rocm install sdk", "--engine lemonade"], + ), + (Some(_), None, _) if line.contains("no Vulkan GPU driver was found") => { + ("install one", &["rocm install sdk", "--engine lemonade"]) + } (Some(_), None, _) => ( "rocm serve --engine lemonade", &["rocm install sdk"], @@ -3616,3 +3665,338 @@ async fn assert_support_level_advice_fits(world: &mut E2eWorld) { ); } } + +/// A KFD `gfx_target_version` naming gfx90c, the Vega iGPU in Renoir / +/// Lucienne / Cezanne / Barcelo APUs. +/// +/// The kernel packs the target as `major * 10000 + minor * 100 + step`, so +/// `9.0.12` is `90012` and decodes to `gfx90c` (step 12 is the hex `c`). This +/// is the one target the CLI recognizes *and* refuses to map to a ROCm package +/// family, so it is what reaches the support level these scenarios are about. +const KFD_GFX90C_TARGET_VERSION: &str = "90012"; + +/// `vulkaninfo --summary` on a host whose Vega iGPU is driven by Mesa RADV. +const RADV_VULKANINFO_SUMMARY: &str = "\ +Devices: +======== +GPU0: +\tapiVersion = 1.3.274 +\tvendorID = 0x1002 +\tdeviceID = 0x1636 +\tdeviceType = PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU +\tdeviceName = AMD Radeon Graphics (RADV RENOIR) +\tdriverID = DRIVER_ID_MESA_RADV +\tdriverName = radv +"; + +/// `vulkaninfo --summary` on a host with only Mesa's CPU rasteriser: a complete +/// Vulkan implementation, and not a GPU. +const LAVAPIPE_VULKANINFO_SUMMARY: &str = "\ +Devices: +======== +GPU0: +\tapiVersion = 1.3.255 +\tvendorID = 0x10005 +\tdeviceType = PHYSICAL_DEVICE_TYPE_CPU +\tdeviceName = llvmpipe (LLVM 15.0.7, 256 bits) +\tdriverName = llvmpipe +"; + +/// Plant a host whose GPU is identified but has no ROCm package family, +/// carrying the Vulkan state the caller describes. +/// +/// `icd_manifest` is the ICD file name the loader would find and +/// `vulkaninfo_summary` what `vulkaninfo --summary` prints; `None` for either +/// means that half of the evidence is absent. +/// +/// The `vulkaninfo` stub is planted in **both** directions, because `PATH` +/// still reaches the rest of the machine: a runner with a real `vulkaninfo` +/// installed would otherwise answer for the fixture, and a scenario about a +/// host with no Vulkan driver has to be hermetic about the host and not only +/// about the planted root. +/// +/// `None` plants a stub that **succeeds and reports no devices**, not one that +/// fails. That distinction is the whole point of the `enumerated` input to +/// `classify_vulkan_support`: a tool that exits non-zero answered nothing, and +/// must leave the host `Inconclusive`, while one that runs and lists nothing is +/// the genuine "looked and found none" that earns a confirmed `Absent`. The +/// earlier `exit 1` stub pinned exactly the conflation this probe exists to +/// avoid, so examine-57 passed for the wrong reason. +fn plant_unsupported_gpu( + world: &mut E2eWorld, + icd_manifest: Option<&str>, + vulkaninfo_summary: Option<&str>, +) { + let root = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .to_owned(); + let host_root = root.join("host-root"); + + let node = host_root.join("sys/class/kfd/kfd/topology/nodes/1"); + std::fs::create_dir_all(&node).expect("failed to create planted KFD node"); + std::fs::write( + node.join("properties"), + format!( + "cpu_cores_count 0\nsimd_count 56\ngfx_target_version {KFD_GFX90C_TARGET_VERSION}\n" + ), + ) + .expect("failed to write planted KFD node properties"); + + if let Some(manifest) = icd_manifest { + let icd_dir = host_root.join("usr/share/vulkan/icd.d"); + std::fs::create_dir_all(&icd_dir).expect("failed to create planted ICD dir"); + std::fs::write( + icd_dir.join(manifest), + "{\"file_format_version\":\"1.0.0\",\"ICD\":{\"library_path\":\"libvulkan_fake.so\"}}\n", + ) + .expect("failed to write planted ICD manifest"); + } + + let bin = root.join("fake-bin"); + std::fs::create_dir_all(&bin).expect("failed to create the fake PATH dir"); + // The same empty-bus `lspci` the other GPU fixtures plant: the probe must + // succeed without describing the runner's real cards. + rocm_core::fake_executable::write_fake_executable(&bin.join("lspci"), "#!/bin/sh\nexit 0\n") + .expect("failed to write the fake lspci"); + let vulkaninfo = match vulkaninfo_summary { + Some(summary) => format!("#!/bin/sh\ncat <<'ROCM_E2E_EOF'\n{summary}ROCM_E2E_EOF\n"), + // Exit 0 with an empty `Devices:` section: the tool answered, and the + // answer is "none". See this function's doc comment. + None => "#!/bin/sh\nprintf 'Devices:\\n=======\\n'\nexit 0\n".to_owned(), + }; + rocm_core::fake_executable::write_fake_executable(&bin.join("vulkaninfo"), &vulkaninfo) + .expect("failed to write the fake vulkaninfo"); + + let path = std::env::join_paths(std::iter::once(bin).chain(std::env::split_paths( + &std::env::var_os("PATH").unwrap_or_default(), + ))) + .expect("PATH entries cannot hold a separator"); + world.command_env.push(("PATH", path)); + world + .command_env + .push(("ROCM_CLI_TEST_HOST_ROOT", host_root.into_os_string())); +} + +#[given("a machine whose GPU has no official support but has a working Vulkan driver")] +async fn unsupported_gpu_with_vulkan(world: &mut E2eWorld) { + plant_unsupported_gpu( + world, + Some("radeon_icd.x86_64.json"), + Some(RADV_VULKANINFO_SUMMARY), + ); +} + +#[given("a machine whose GPU has no official support and no Vulkan driver")] +async fn unsupported_gpu_without_vulkan(world: &mut E2eWorld) { + plant_unsupported_gpu(world, None, None); +} + +/// The *common* no-driver shape, and the one examine-57 does not cover: a host +/// with no ICD and no `vulkaninfo` to ask. The probe must then report that it +/// could not confirm, rather than either promising Vulkan or declaring it absent. +/// +/// Deleting the planted stub is not enough on its own, and doing only that would +/// contradict `plant_unsupported_gpu`'s own "planted in both directions" reason: +/// that function leaves the runner's `PATH` on the end, so a CI host with a real +/// `vulkaninfo` installed would answer for the fixture and this scenario would +/// describe the runner rather than the planted machine. So `PATH` is narrowed to +/// the fake directory as well. `lspci` stays in it, and the fake executables are +/// `#!/bin/sh` scripts reached by absolute path, so nothing else the probe needs +/// is lost — only the ability to find a `vulkaninfo` anywhere. +#[given("a machine whose GPU has no official support and no way to check Vulkan")] +async fn unsupported_gpu_without_vulkaninfo(world: &mut E2eWorld) { + plant_unsupported_gpu(world, None, None); + let bin = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .join("fake-bin"); + std::fs::remove_file(bin.join("vulkaninfo")).expect("failed to remove the planted vulkaninfo"); + // Pushed after `plant_unsupported_gpu`'s own entry: `command_env` is applied + // in order, so this is the `PATH` the child sees. + let path = + std::env::join_paths(std::iter::once(bin)).expect("fake-bin cannot hold a separator"); + world.command_env.push(("PATH", path)); +} + +#[then("the inspection says it could not confirm whether a Vulkan driver is there")] +async fn assert_vulkan_unconfirmed(world: &mut E2eWorld) { + let output = world.cli_output.as_ref().expect("no command was run"); + let line = rocm_support_line(output).expect("no rocm_support line"); + // The constant itself, not a copy of its text: this is the same sentence + // `lemonade_engine_note` renders a few lines further down the same report, + // and reading it from `rocm_core` is what stops this assertion drifting away + // from the wording it is meant to pin. + assert!( + line.contains(rocm_core::VULKAN_UNCONFIRMED_CLAIM), + "the support line must say the probe could not settle it, not assert \ + a driver is absent: {line}\n{output}" + ); + assert!( + line.contains("run `vulkaninfo`"), + "and still name the one step that can settle it: {line}\n{output}" + ); + assert!( + !line.contains("Vulkan backend") && !line.contains("runs on"), + "and it must not promise a Vulkan path it never established: {line}\n{output}" + ); +} + +#[given("a machine whose GPU has no official support and only a software renderer")] +async fn unsupported_gpu_with_software_renderer(world: &mut E2eWorld) { + plant_unsupported_gpu( + world, + Some("lvp_icd.x86_64.json"), + Some(LAVAPIPE_VULKANINFO_SUMMARY), + ); +} + +/// The `render`-group shape: a real GPU driver manifest the loader would find, +/// and a `vulkaninfo` that enumerates only the CPU rasteriser because this user +/// cannot open the device node. +/// +/// Deliberately the *same* enumeration as the step above, with only the +/// manifest changed. The two scenarios are a discrimination rather than two +/// assertions: the device evidence alone cannot tell the hosts apart, so an +/// implementation that reads it before the ICD evidence reports both as a +/// confirmed absence and fails exactly one of the pair. +#[given( + "a machine whose GPU has no official support and a Vulkan driver masked by a software renderer" +)] +async fn unsupported_gpu_with_masked_vulkan_driver(world: &mut E2eWorld) { + plant_unsupported_gpu( + world, + Some("radeon_icd.x86_64.json"), + Some(LAVAPIPE_VULKANINFO_SUMMARY), + ); +} + +#[then("the inspection does not say a Vulkan driver is missing")] +async fn assert_vulkan_driver_not_denied(world: &mut E2eWorld) { + let output = world.cli_output.as_ref().expect("no command was run"); + assert!( + !output.contains("no Vulkan GPU driver was found"), + "a driver this very report lists in `icds` must not be declared missing:\n{output}" + ); + assert!( + !output.contains("install one"), + "nor may the host be sent to install what it already has:\n{output}" + ); + assert!( + output.contains("vulkan: driver_present_devices_unverified"), + "the machine-readable status must say the driver is there and unconfirmed:\n{output}" + ); +} + +#[then("the inspection names the installed Vulkan driver it could not confirm")] +async fn assert_masked_vulkan_driver_named(world: &mut E2eWorld) { + let output = world.cli_output.as_ref().expect("no command was run"); + let line = rocm_support_line(output).expect("no rocm_support line"); + assert!( + line.contains("a Vulkan driver is installed"), + "the support sentence must say what was actually established: {line}\n{output}" + ); + // The evidence line is where a reader can check that claim: it has to name + // the driver the manifest implies and the reason nothing was confirmed, or + // "a driver is installed" is just another unbacked promise. + assert!( + output.contains("Mesa RADV is installed"), + "the evidence line must name the driver the planted manifest implies:\n{output}" + ); + assert!( + output.contains("software (CPU) Vulkan device"), + "and why it could not be confirmed:\n{output}" + ); + assert!( + !output.contains("the Vulkan backend can be used"), + "but an unconfirmed driver is not a confirmed device:\n{output}" + ); +} + +#[then("the inspection reports the GPU as unsupported by the official stack")] +async fn assert_gpu_unsupported_by_rocm(world: &mut E2eWorld) { + let output = world.cli_output.as_ref().expect("no command was run"); + assert!( + output.contains("rocm_support:") && output.contains("not supported by ROCm"), + "the inspection must say the GPU was identified and has no ROCm build:\n{output}" + ); +} + +#[then("the inspection reports that models can still run through Vulkan")] +async fn assert_vulkan_offered(world: &mut E2eWorld) { + let output = world.cli_output.as_ref().expect("no command was run"); + assert!( + output.contains("the Vulkan backend can be used"), + "a host with a working Vulkan device must be told so:\n{output}" + ); + assert!( + output.contains("vulkan: available"), + "the machine-readable line must agree with the sentence:\n{output}" + ); +} + +#[then("the inspection names the Vulkan driver it found")] +async fn assert_vulkan_driver_named(world: &mut E2eWorld) { + let output = world.cli_output.as_ref().expect("no command was run"); + // The driver the planted device reported, not a guess from the ICD file + // name: naming it is what lets a reader check the claim. + // + // Asserted on the `rocm_support` line specifically, not the whole output. + // The `vulkan:` evidence line also carries the driver name, so a plain + // `output.contains("radv")` passed even when the support sentence — the + // half that actually makes the claim — named nothing at all. + let line = rocm_support_line(output).expect("no rocm_support line"); + assert!( + line.contains("radv"), + "the support sentence itself must name the driver, not just the \ + evidence line: {line}\n{output}" + ); +} + +#[then("the inspection does not claim models can run through Vulkan")] +async fn assert_vulkan_not_promised(world: &mut E2eWorld) { + let output = world.cli_output.as_ref().expect("no command was run"); + assert!( + !output.contains("the Vulkan backend can be used"), + "a host with no usable Vulkan GPU must not be promised one:\n{output}" + ); + assert!( + !output.contains("Vulkan backend is expected to work"), + "a host with no usable Vulkan GPU must not be promised one:\n{output}" + ); +} + +#[then("the inspection says no Vulkan driver was found")] +async fn assert_no_vulkan_driver_reported(world: &mut E2eWorld) { + let output = world.cli_output.as_ref().expect("no command was run"); + assert!( + output.contains("no Vulkan GPU driver was found"), + "the inspection must say why no GPU path is open:\n{output}" + ); + assert!( + output.contains("install one"), + "the advice must be able to clear the condition it is printed for:\n{output}" + ); +} + +#[then("the inspection says the only renderer it found runs on the CPU")] +async fn assert_software_renderer_reported(world: &mut E2eWorld) { + let output = world.cli_output.as_ref().expect("no command was run"); + assert!( + output.contains("not a GPU path"), + "a CPU rasteriser must be named as such, not counted as a GPU:\n{output}" + ); + // The support level must agree, not just the evidence line. Without this the + // scenario still passed when `gpu_support_level` ignored the probe entirely: + // the absence of a Vulkan promise was coming from the status wording alone, + // so nothing here held the classification itself. + assert!( + output.contains("no Vulkan GPU driver was found"), + "a host whose only renderer is the CPU has no GPU backend, and the support \ + line must say so:\n{output}" + ); +} diff --git a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs index 429d3573ca..83d34d6ad8 100644 --- a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs @@ -27,14 +27,6 @@ use crate::E2eWorld; // `:` form only in `runtime_id`, which is a manifest field value, never a filename. const FIRST_KEY: &str = "release-tarball-gfx942"; const SECOND_KEY: &str = "release-tarball-gfx1100"; -/// The GPU families `FIRST_KEY` and `SECOND_KEY` are planted with; each family -/// also names the runtime's install folder (see [`planted_install_root`]). -const FIRST_FAMILY: &str = "gfx942"; -/// The version every planted runtime records: a dated nightly-style version, so -/// the JSON (which carries the version as recorded) and the text (which adds -/// the build date) can be told apart. -const PLANTED_VERSION: &str = "7.14.0a20260601"; -const SECOND_FAMILY: &str = "gfx1100"; /// Two keys that differ only in letter case. Each is its own `.json` in the /// registry, so the pair can only coexist on a case-sensitive filesystem — which /// is why the scenario using them carries `@requires-case-sensitive-fs`. @@ -74,7 +66,8 @@ fn plant_runtime(world: &E2eWorld, key: &str, family: &str) -> PathBuf { .all(|ch| ch.is_ascii_alphanumeric() || ch == '-'), "runtime key must be production-style and safe as a registry filename: {key}" ); - let install_root = planted_install_root(world, family); + let root = world.isolated_root.as_ref().expect("no isolated root"); + let install_root = root.path().join(format!("runtime-{family}")); std::fs::create_dir_all(&install_root).expect("failed to create install root"); std::fs::write(install_root.join("payload.txt"), "payload") .expect("failed to write runtime payload"); @@ -87,16 +80,6 @@ fn plant_runtime(world: &E2eWorld, key: &str, family: &str) -> PathBuf { install_root } -/// Where [`plant_runtime`] puts the install root of a runtime of `family`. -fn planted_install_root(world: &E2eWorld, family: &str) -> PathBuf { - world - .isolated_root - .as_ref() - .expect("no isolated root") - .path() - .join(format!("runtime-{family}")) -} - /// The runtime registry under the scenario's isolated data dir — where the CLI /// reads `.json` manifests from. One definition, so a layout change cannot /// leave the planting and the counting looking in different places; the @@ -136,7 +119,7 @@ fn runtime_manifest_json(key: &str, family: &str, install_root: &Path) -> String "format": "tarball", "family": family, "family_source": "manual", - "version": PLANTED_VERSION, + "version": "1.0.0", "install_root": install_root, "selected_artifact_url": format!("https://example.invalid/{key}.tar.gz"), "read_only": true, @@ -387,30 +370,12 @@ pub(crate) fn read_json_if_present(path: &Path) -> Option { /// anyway: it is written first, so it is the half that would be left naming the /// new runtime if the restore did not run. fn config_active_runtime_key(world: &E2eWorld) -> Option { - read_config(world) - .get("active_runtime_key") - .and_then(serde_json::Value::as_str) - .map(str::to_owned) -} - -/// The isolated `config.json`, parsed; a missing file fails the step. -fn read_config(world: &E2eWorld) -> serde_json::Value { let config = config_path(world); read_json_if_present(&config) .unwrap_or_else(|| panic!("failed to read {}: it does not exist", config.display())) -} - -/// Edit the config the way a person editing the file by hand would: set -/// `active_runtime_key` and leave every other value as the CLI wrote it. -fn set_config_active_runtime_key(world: &E2eWorld, runtime_key: &str) { - let mut config = read_config(world); - config["active_runtime_key"] = serde_json::Value::from(runtime_key); - let path = config_path(world); - std::fs::write( - &path, - serde_json::to_string_pretty(&config).expect("config serializes"), - ) - .unwrap_or_else(|error| panic!("failed to write {}: {error}", path.display())); + .get("active_runtime_key") + .and_then(serde_json::Value::as_str) + .map(str::to_owned) } /// The runtime key recorded in the isolated active-runtime marker. @@ -460,80 +425,20 @@ fn write_import_manifest(world: &E2eWorld) -> PathBuf { #[given("two registered runtimes and none active")] async fn two_runtimes(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, FIRST_FAMILY); - plant_runtime(world, SECOND_KEY, SECOND_FAMILY); + plant_runtime(world, FIRST_KEY, "gfx942"); + plant_runtime(world, SECOND_KEY, "gfx1100"); } #[given("two registered runtimes with the second active after the first")] async fn two_runtimes_second_active(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, FIRST_FAMILY); - plant_runtime(world, SECOND_KEY, SECOND_FAMILY); + plant_runtime(world, FIRST_KEY, "gfx942"); + plant_runtime(world, SECOND_KEY, "gfx1100"); // Activate first, then second, so `previous_runtime_key` records the first — // the state rollback must return to. crate::run_rocm_ok(world, &["runtimes", "activate", FIRST_KEY]); crate::run_rocm_ok(world, &["runtimes", "activate", SECOND_KEY]); } -/// Nothing to plant: each scenario starts from an empty isolated root. Asserted -/// rather than assumed, so a fixture that starts seeding runtimes cannot turn -/// the empty-registry scenario into one that lists something. -#[given("no ROCm runtime is registered")] -async fn no_runtime_registered(world: &mut E2eWorld) { - let registry = registry_dir(world); - let registered = std::fs::read_dir(®istry).map_or(0, Iterator::count); - assert_eq!( - registered, - 0, - "the isolated registry {} must start empty", - registry.display() - ); -} - -#[given("the first runtime's folder has been deleted")] -async fn first_runtime_folder_deleted(world: &mut E2eWorld) { - std::fs::remove_dir_all(planted_install_root(world, FIRST_FAMILY)) - .expect("failed to delete the first runtime's install root"); -} - -#[given("the second runtime's registry entry has been deleted")] -async fn second_runtime_manifest_deleted(world: &mut E2eWorld) { - std::fs::remove_file(registry_dir(world).join(format!("{SECOND_KEY}.json"))) - .expect("failed to delete the second runtime's manifest"); -} - -/// The registry entry is replaced by a folder of the same name: the listing -/// finds it among the entries and fails reading it, on every platform and -/// whoever runs the suite, where a file with its permissions removed is still -/// read by root and cannot be made unreadable the same way on Windows. An entry -/// that reads but does not parse would not do: the listing skips those. -#[given("the first runtime's registry entry cannot be read")] -async fn first_runtime_manifest_unreadable(world: &mut E2eWorld) { - let entry = registry_dir(world).join(format!("{FIRST_KEY}.json")); - std::fs::remove_file(&entry) - .unwrap_or_else(|error| panic!("failed to delete {}: {error}", entry.display())); - std::fs::create_dir(&entry) - .unwrap_or_else(|error| panic!("failed to create {}: {error}", entry.display())); -} - -/// A key no runtime is registered under: what the config holds after the -/// active runtime's registry entry goes without the CLI noticing. -const UNREGISTERED_KEY: &str = "release-tarball-gfx90a"; - -#[given("the configuration names the first runtime as active in other letter case")] -async fn config_names_first_in_other_case(world: &mut E2eWorld) { - let other_case = FIRST_KEY.to_ascii_uppercase(); - assert_ne!( - other_case, FIRST_KEY, - "the edit must change the letter case" - ); - set_config_active_runtime_key(world, &other_case); -} - -#[given("the configuration names an unregistered runtime as active")] -async fn config_names_unregistered_runtime(world: &mut E2eWorld) { - set_config_active_runtime_key(world, UNREGISTERED_KEY); -} - #[given("two registered runtimes whose keys differ only in letter case")] async fn two_case_twin_runtimes(world: &mut E2eWorld) { // Distinct families only so each twin gets its own install root. @@ -565,8 +470,8 @@ async fn two_case_twin_runtimes(world: &mut E2eWorld) { #[given("two registered runtimes and a local server recorded on the first")] async fn two_runtimes_and_service_on_first(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, FIRST_FAMILY); - plant_runtime(world, SECOND_KEY, SECOND_FAMILY); + plant_runtime(world, FIRST_KEY, "gfx942"); + plant_runtime(world, SECOND_KEY, "gfx1100"); // Planted BEFORE either activation, so the same record covers both halves of // the scenario: while the first runtime is the one being activated the // server is on it (nothing left behind), and activating the second leaves it @@ -576,8 +481,8 @@ async fn two_runtimes_and_service_on_first(world: &mut E2eWorld) { #[given("two registered runtimes and a publicly bound local server recorded on the first")] async fn two_runtimes_and_public_service_on_first(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, FIRST_FAMILY); - plant_runtime(world, SECOND_KEY, SECOND_FAMILY); + plant_runtime(world, FIRST_KEY, "gfx942"); + plant_runtime(world, SECOND_KEY, "gfx1100"); // `0.0.0.0` with no endpoint key file planted is the whole setup. Restarting // a public bind that has no key is refused before the stop, so the // activation's restart fails while the server is left up on the first @@ -587,8 +492,8 @@ async fn two_runtimes_and_public_service_on_first(world: &mut E2eWorld) { #[given("two registered runtimes and a local server recording no runtime")] async fn two_runtimes_and_service_without_runtime(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, FIRST_FAMILY); - plant_runtime(world, SECOND_KEY, SECOND_FAMILY); + plant_runtime(world, FIRST_KEY, "gfx942"); + plant_runtime(world, SECOND_KEY, "gfx1100"); // `runtime_id: None` is the whole setup — a record that predates runtime // pinning and so says nothing about which runtime its server loaded. write_service_record_with( @@ -645,7 +550,7 @@ async fn services_cannot_be_read(world: &mut E2eWorld) { #[given("a registered read-only runtime")] async fn one_readonly_runtime(world: &mut E2eWorld) { - let install_root = plant_runtime(world, FIRST_KEY, FIRST_FAMILY); + let install_root = plant_runtime(world, FIRST_KEY, "gfx942"); // Stash the install_root path so the uninstall scenario can assert it survives. world.model_name = Some(install_root.to_string_lossy().into_owned()); } @@ -670,23 +575,6 @@ async fn registered_adopted_runtime(world: &mut E2eWorld) { plant_adopted_runtime(world); } -/// A registered wheel runtime makes `rocm` start with the startup update check, -/// which looks for a usable Python and the network, and prints a progress line -/// on stdout ahead of a `--json` document when the Python on `PATH` does not fit -/// (the examine steps turn it off for the same reason). The scenarios that set -/// this are about the listing, not updates. Like every scenario env it is -/// consumed by one run, so a step that runs `rocm` again sets it again. -fn disable_startup_update_check(world: &mut E2eWorld) { - world - .command_env - .push(("ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK", "1".into())); -} - -#[given("ROCm CLI does not check for runtime updates when it starts")] -async fn no_startup_update_check(world: &mut E2eWorld) { - disable_startup_update_check(world); -} - #[given("a runtime manifest to import")] async fn manifest_to_import(world: &mut E2eWorld) { let path = write_import_manifest(world); @@ -834,27 +722,6 @@ async fn list_runtimes(world: &mut E2eWorld) { record(world, stdout, stderr, rc); } -/// The first runtime's id in upper case, which differs from the registered -/// `therock-release:gfx942` only in letter case. -fn first_runtime_id_in_other_case() -> String { - format!("therock-release:{FIRST_FAMILY}").to_ascii_uppercase() -} - -#[when("the user sets the default runtime to the first runtime's id in other letter case")] -async fn set_default_runtime_in_other_case(world: &mut E2eWorld) { - let runtime_id = first_runtime_id_in_other_case(); - crate::run_rocm_ok(world, &["config", "set-default-runtime", &runtime_id]); -} - -/// Runs with the scenario's command environment (none unless a Given step set -/// one), which this run consumes. -#[when("the user lists the registered runtimes as JSON")] -async fn list_runtimes_json(world: &mut E2eWorld) { - let (stdout, stderr, rc) = - crate::run_rocm_with_scenario_env(world, &["runtimes", "list", "--json"]); - record(world, stdout, stderr, rc); -} - #[when("the user uninstalls that runtime")] async fn uninstall(world: &mut E2eWorld) { let (stdout, stderr, rc) = @@ -1143,399 +1010,6 @@ async fn second_marked_rollback(world: &mut E2eWorld) { ); } -/// The whole of stdout parsed as one JSON value: `serde_json::from_str` refuses -/// anything but whitespace after the value, so a stray line before or after the -/// document fails here rather than in a script that pipes it. -fn listing_json(world: &E2eWorld) -> serde_json::Value { - let out = ok_output(world); - serde_json::from_str(&out).unwrap_or_else(|error| { - panic!( - "stdout of `runtimes list --json` is not one JSON document ({error}):\n{}", - combined(world) - ) - }) -} - -/// The `runtime_key` of every listed runtime whose boolean `flag` is set. -/// Every runtime must carry `flag` as a boolean: read through `runtime[flag]` -/// alone, a missing or renamed field would count as `false` and an assertion -/// that nothing is flagged would still pass. -fn listed_keys_with(listing: &serde_json::Value, flag: &str) -> Vec { - listing["runtimes"] - .as_array() - .unwrap_or_else(|| panic!("`runtimes` is not an array:\n{listing:#}")) - .iter() - .filter(|runtime| { - runtime - .get(flag) - .and_then(serde_json::Value::as_bool) - .unwrap_or_else(|| panic!("a runtime has no boolean `{flag}`:\n{listing:#}")) - }) - .map(|runtime| { - runtime["runtime_key"] - .as_str() - .unwrap_or_else(|| panic!("a runtime has no runtime_key:\n{listing:#}")) - .to_owned() - }) - .collect() -} - -/// The `runtime_key`s of the runtime rows the text form of `runtimes list` -/// marks with `glyph`, in listing order. A row is exactly what the CLI's -/// `write_marked_row` prints under `installed:`: two spaces, the marker, a -/// space, then ` runtime_id=...`. Anchoring on that layout keeps a -/// legend, status or path line that happens to start with `- ` from counting. -fn text_rows_marked(text: &str, glyph: &str) -> Vec { - text.lines() - .filter_map(|line| line.strip_prefix(&format!(" {glyph} "))) - .filter_map(|row| { - let (key, rest) = row.split_once(' ')?; - rest.starts_with("runtime_id=").then(|| key.to_owned()) - }) - .collect() -} - -#[then("the output is a single JSON document and nothing else")] -async fn output_is_one_json_document(world: &mut E2eWorld) { - let listing = listing_json(world); - assert!( - listing.is_object(), - "expected a JSON object, got:\n{listing:#}" - ); - let out = world.cli_output.as_deref().unwrap_or_default(); - assert!( - out.starts_with('{'), - "stdout must start with the document itself, got {out:?}" - ); - assert!( - out.ends_with('\n') && !out.ends_with("\n\n"), - "the document must end with exactly one newline, got {out:?}" - ); -} - -/// `key` is present in `value` and `null`. `value[key]` alone reads a missing -/// key as `null` too, so it would not notice the key being dropped. -fn assert_null_field(value: &serde_json::Value, key: &str) { - assert_eq!( - value.as_object().and_then(|object| object.get(key)), - Some(&serde_json::Value::Null), - "`{key}` must be present and null:\n{value:#}" - ); -} - -/// The listed runtime whose `runtime_key` is `key`. -fn listed_runtime<'a>(listing: &'a serde_json::Value, key: &str) -> &'a serde_json::Value { - listing["runtimes"] - .as_array() - .unwrap_or_else(|| panic!("`runtimes` is not an array:\n{listing:#}")) - .iter() - .find(|runtime| runtime["runtime_key"] == key) - .unwrap_or_else(|| panic!("{key} is not listed:\n{listing:#}")) -} - -/// Both planted runtimes, each with the values `plant_runtime` recorded in its -/// manifest, and nothing else. The listing's order is not checked here: both -/// share one install time, so the order rests on the `runtime_key` tie-break, -/// which the unit tests -/// `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first` -/// and `registry_sort_is_newest_install_first_then_by_key` pin. -#[then("the JSON lists both runtimes with their recorded values")] -async fn json_lists_both_runtimes(world: &mut E2eWorld) { - let listing = listing_json(world); - let mut listed: Vec<&str> = listing["runtimes"] - .as_array() - .expect("`runtimes` is an array") - .iter() - .map(|runtime| runtime["runtime_key"].as_str().unwrap_or_default()) - .collect(); - listed.sort_unstable(); - let mut expected = [FIRST_KEY, SECOND_KEY]; - expected.sort_unstable(); - assert_eq!(listed, expected, "{listing:#}"); - for (key, family) in [(FIRST_KEY, FIRST_FAMILY), (SECOND_KEY, SECOND_FAMILY)] { - let runtime = listed_runtime(&listing, key); - assert_eq!( - runtime["runtime_id"], - format!("therock-release:{family}"), - "{key}" - ); - assert_eq!(runtime["family"], family, "{key}"); - assert_eq!(runtime["format"], "tarball", "{key}"); - // As recorded, not the text's display form with the build date. - assert_eq!(runtime["version"], PLANTED_VERSION, "{key}"); - assert_eq!(runtime["mode"], "read-only", "{key}"); - assert_eq!(runtime["status"], "ready", "{key}"); - assert_null_field(runtime, "unusable_reason"); - // The planted manifest has no `devel` field, which the CLI reads as - // a legacy install that included the toolchain. - assert_eq!(runtime["toolchain"], "included", "{key}"); - let install_root = runtime["install_root"] - .as_str() - .unwrap_or_else(|| panic!("{key} has no install_root:\n{listing:#}")); - assert_eq!( - Path::new(install_root), - planted_install_root(world, family), - "{key}" - ); - } -} - -#[then("the JSON marks the second runtime active and the first as the rollback target")] -async fn json_marks_active_and_rollback(world: &mut E2eWorld) { - let listing = listing_json(world); - assert_eq!( - listed_keys_with(&listing, "active"), - [SECOND_KEY], - "{listing:#}" - ); - assert_eq!( - listed_keys_with(&listing, "rollback_target"), - [FIRST_KEY], - "{listing:#}" - ); - assert_eq!(listing["active_runtime_key"], SECOND_KEY, "{listing:#}"); - assert_eq!(listing["previous_runtime_key"], FIRST_KEY, "{listing:#}"); - // A healthy state reports no problem, in either form. - assert_null_field(&listing, "active_problem"); - let text = crate::run_rocm_ok(world, &["runtimes", "list"]); - assert!( - !text.contains("active_status:"), - "a healthy listing must print no active_status line:\n{text}" - ); -} - -#[then("the JSON lists no runtimes and no active runtime")] -async fn json_lists_nothing(world: &mut E2eWorld) { - let listing = listing_json(world); - assert_eq!(listing["runtimes"], serde_json::json!([]), "{listing:#}"); - for unset in [ - "default_runtime_id", - "active_runtime_key", - "previous_runtime_key", - "active_problem", - ] { - assert_null_field(&listing, unset); - } - // The paths are reported even with nothing registered, and each is the - // isolated data dir's own: swapping the two would fail here. - let runtimes_dir = registry_dir(world) - .parent() - .expect("the registry has a parent") - .to_path_buf(); - for (field, expected) in [ - ("registry", registry_dir(world)), - ("marker", runtimes_dir.join("active.json")), - ] { - let reported = listing - .get(field) - .and_then(serde_json::Value::as_str) - .unwrap_or_else(|| panic!("`{field}` is not a path:\n{listing:#}")); - assert_eq!(Path::new(reported), expected, "`{field}`:\n{listing:#}"); - } -} - -/// Lists the same state as text and compares its `*`/`-` rows with the JSON -/// flags just read, so the two forms are shown to agree, not assumed to. -#[then("the text listing marks the same runtimes as the JSON")] -async fn text_marks_match_json(world: &mut E2eWorld) { - let listing = listing_json(world); - let text = crate::run_rocm_ok(world, &["runtimes", "list"]); - let active = listed_keys_with(&listing, "active"); - // Two empty lists agree too; this step is only evidence where something is - // active. - assert!( - !active.is_empty(), - "the JSON marks no runtime active, so there is nothing to compare:\n{listing:#}" - ); - // The text has one marker column and gives it to `*` when a runtime is - // both active and the rollback target, so `-` shows only the others. - let rollback_only: Vec = listed_keys_with(&listing, "rollback_target") - .into_iter() - .filter(|key| !active.contains(key)) - .collect(); - assert_eq!(text_rows_marked(&text, "*"), active, "{text}"); - assert_eq!(text_rows_marked(&text, "-"), rollback_only, "{text}"); -} - -#[then("the JSON shows the default runtime as typed and no active runtime key")] -async fn json_shows_default_as_typed(world: &mut E2eWorld) { - let listing = listing_json(world); - assert_eq!( - listing["default_runtime_id"], - first_runtime_id_in_other_case(), - "{listing:#}" - ); - assert_null_field(&listing, "active_runtime_key"); -} - -#[then("the JSON marks only the first runtime active and reports no problem")] -async fn json_marks_first_active_without_problem(world: &mut E2eWorld) { - let listing = listing_json(world); - assert_eq!( - listed_keys_with(&listing, "active"), - [FIRST_KEY], - "{listing:#}" - ); - assert_null_field(&listing, "active_problem"); -} - -#[then("the JSON marks only the second runtime active")] -async fn json_marks_only_second_active(world: &mut E2eWorld) { - let listing = listing_json(world); - assert_eq!( - listed_keys_with(&listing, "active"), - [SECOND_KEY], - "{listing:#}" - ); -} - -/// The install root `rocm examine --json` reports (`summary.active_runtime_root`) -/// for the active runtime, which comes from the resolver the commands use. -fn examined_active_runtime_root(world: &E2eWorld) -> PathBuf { - let (stdout, stderr, rc) = - crate::run_rocm(world, &["examine", "--framework", "skip", "--json"]); - assert_eq!(rc, 0, "examine failed:\n{stdout}\n{stderr}"); - let examined: serde_json::Value = serde_json::from_str(&stdout) - .unwrap_or_else(|error| panic!("examine --json is not JSON ({error}):\n{stdout}")); - let root = examined["summary"]["active_runtime_root"] - .as_str() - .unwrap_or_else(|| panic!("examine reports no active runtime root:\n{examined:#}")); - PathBuf::from(root) -} - -#[then("examine reports the first runtime as the active one")] -async fn examine_reports_first_active(world: &mut E2eWorld) { - assert_eq!( - examined_active_runtime_root(world), - planted_install_root(world, FIRST_FAMILY) - ); -} - -#[then("examine reports the second runtime as the active one")] -async fn examine_reports_second_active(world: &mut E2eWorld) { - assert_eq!( - examined_active_runtime_root(world), - planted_install_root(world, SECOND_FAMILY) - ); -} - -#[then("the text listing says the active runtime key has no registered runtime")] -async fn text_reports_missing_active_key(world: &mut E2eWorld) { - let key = config_active_runtime_key(world).expect("the config names an active runtime key"); - let text = crate::run_rocm_ok(world, &["runtimes", "list"]); - let status: Vec<&str> = text - .lines() - .map(str::trim_start) - .filter(|line| line.starts_with("active_status:")) - .collect(); - assert_eq!( - status, - [format!( - "active_status: missing manifest for active_runtime_key={key}" - )], - "{text}" - ); -} - -#[then("the text listing marks the first runtime active with no active_status line")] -async fn text_marks_first_active_without_status(world: &mut E2eWorld) { - let text = crate::run_rocm_ok(world, &["runtimes", "list"]); - assert_eq!(text_rows_marked(&text, "*"), [FIRST_KEY], "{text}"); - assert!( - !text.contains("active_status:"), - "the runtime it marks active must not also be reported missing:\n{text}" - ); -} - -#[then("the JSON reports the first runtime unusable because its folder is missing")] -async fn json_reports_first_unusable(world: &mut E2eWorld) { - let listing = listing_json(world); - let runtime = listed_runtime(&listing, FIRST_KEY); - assert_eq!(runtime["status"], "unusable", "{listing:#}"); - // The reason is prose for a person, not a code; it is the message - // activation refuses with, naming the folder that is gone. - let folder = planted_install_root(world, FIRST_FAMILY); - assert_eq!( - runtime["unusable_reason"], - format!("install root is missing: {}", folder.display()), - "{listing:#}" - ); -} - -#[then("the JSON reports the second runtime ready")] -async fn json_reports_second_ready(world: &mut E2eWorld) { - let listing = listing_json(world); - let runtime = listed_runtime(&listing, SECOND_KEY); - assert_eq!(runtime["status"], "ready", "{listing:#}"); - assert_null_field(runtime, "unusable_reason"); -} - -/// Names the key the config holds, read back from the config file, and checks -/// that no listed runtime has it in any letter case. -#[then("the JSON reports that the active runtime key has no registered runtime")] -async fn json_reports_missing_active_manifest(world: &mut E2eWorld) { - let listing = listing_json(world); - let key = config_active_runtime_key(world).expect("the config names an active runtime key"); - assert_eq!( - listing["active_problem"], - serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": key}), - "{listing:#}" - ); - assert_eq!(listing["active_runtime_key"], key.as_str(), "{listing:#}"); - let listed: Vec<&str> = listing["runtimes"] - .as_array() - .expect("`runtimes` is an array") - .iter() - .filter_map(|runtime| runtime["runtime_key"].as_str()) - .collect(); - assert!( - !listed - .iter() - .any(|listed| listed.eq_ignore_ascii_case(&key)), - "`{key}` is registered after all:\n{listing:#}" - ); -} - -/// The failure half of the JSON rules in docs/json-output.md: exit 1 and an -/// empty stdout, so a script that reads stdout cannot mistake the failure for a -/// listing. -#[then("the list fails with nothing printed on stdout")] -async fn list_fails_with_empty_stdout(world: &mut E2eWorld) { - let stderr = world.cli_stderr.as_deref().unwrap_or_default(); - assert_eq!(world.cli_rc, Some(1), "stderr:\n{stderr}"); - assert_eq!( - world.cli_output.as_deref(), - Some(""), - "stdout must be empty when the list fails; stderr:\n{stderr}" - ); -} - -/// The error is the plain text a person reads, not a JSON error document, and -/// it names the entry that could not be read so the user knows what to repair. -#[then("the error on stderr is plain text naming the unreadable registry entry")] -async fn stderr_names_unreadable_entry(world: &mut E2eWorld) { - let stderr = world.cli_stderr.as_deref().unwrap_or_default(); - assert!( - serde_json::from_str::(stderr.trim()).is_err(), - "the error must not be a JSON document:\n{stderr}" - ); - let entry = registry_dir(world).join(format!("{FIRST_KEY}.json")); - assert!( - stderr.contains(&format!("failed to read {}", entry.display())), - "stderr must name {}:\n{stderr}", - entry.display() - ); -} - -#[then("the JSON marks no runtime active")] -async fn json_marks_none_active(world: &mut E2eWorld) { - let listing = listing_json(world); - assert!( - listed_keys_with(&listing, "active").is_empty(), - "{listing:#}" - ); -} - #[then("the CLI refuses and requires --yes")] async fn uninstall_refused_without_yes(world: &mut E2eWorld) { let rc = world.cli_rc.expect("no command rc recorded"); @@ -2122,110 +1596,3 @@ async fn adopted_listing_says_source_unrecorded(world: &mut E2eWorld) { adoption marker as a package source:\n{out}" ); } - -/// The `provenance` object the JSON listing gives `runtime_key`, compared whole -/// against `expected` by the steps below, so a fact under another name, a -/// missing one, or the text's `unrecorded` in place of `null` fails. -fn assert_json_provenance(world: &E2eWorld, runtime_key: &str, expected: &serde_json::Value) { - let listing = listing_json(world); - assert_eq!( - &listed_runtime(&listing, runtime_key)["provenance"], - expected, - "{runtime_key}:\n{listing:#}" - ); -} - -#[then( - "the JSON names the nightly runtime's channel, package source, source layout and exact GPU target" -)] -async fn json_names_nightly_provenance(world: &mut E2eWorld) { - assert_json_provenance( - world, - NIGHTLY_EXACT_TARGET_KEY, - &serde_json::json!({ - "channel": "nightly", - "source": NIGHTLY_SOURCE, - "source_layout_generation": NIGHTLY_SOURCE_LAYOUT, - "device_target": NIGHTLY_DEVICE_TARGET, - }), - ); -} - -/// The older runtime's family is the exact `gfx942`, so a target guessed from -/// it would be a plausible string here rather than `null`. -#[then( - "the JSON gives no value for each fact the older runtime did not record instead of guessing" -)] -async fn json_gives_null_for_unrecorded_facts(world: &mut E2eWorld) { - assert_json_provenance( - world, - FIRST_KEY, - &serde_json::json!({ - "channel": "release", - "source": format!("https://example.invalid/{FIRST_KEY}.tar.gz"), - "source_layout_generation": null, - "device_target": null, - }), - ); -} - -#[then("the JSON gives no package source for the adopted runtime")] -async fn json_gives_adopted_runtime_no_source(world: &mut E2eWorld) { - assert_json_provenance( - world, - ADOPTED_KEY, - &serde_json::json!({ - "channel": "release", - "source": null, - "source_layout_generation": null, - "device_target": null, - }), - ); -} - -/// Lists the same state as text and compares every runtime's `provenance:` line -/// with the JSON object just read: the same names, the same values, and -/// `unrecorded` exactly where the JSON has `null`. -#[then("the text listing names the same provenance as the JSON for every runtime")] -async fn text_provenance_matches_json(world: &mut E2eWorld) { - let listing = listing_json(world); - // The listing run consumed the scenario's setting; this run sets it again. - disable_startup_update_check(world); - let (text, stderr, rc) = crate::run_rocm_with_scenario_env(world, &["runtimes", "list"]); - assert_eq!(rc, 0, "the text listing failed:\n{text}\n{stderr}"); - let runtimes = listing["runtimes"] - .as_array() - .unwrap_or_else(|| panic!("`runtimes` is not an array:\n{listing:#}")); - assert!( - !runtimes.is_empty(), - "the JSON lists no runtime, so there is nothing to compare:\n{listing:#}" - ); - for runtime in runtimes { - let key = runtime["runtime_key"] - .as_str() - .unwrap_or_else(|| panic!("a runtime has no runtime_key:\n{listing:#}")); - let object = runtime["provenance"] - .as_object() - .unwrap_or_else(|| panic!("{key} has no provenance object:\n{listing:#}")); - let shown: Vec<(&str, &str)> = listed_provenance(&text, key) - .split(' ') - .map(|pair| { - pair.split_once('=') - .unwrap_or_else(|| panic!("{key}: {pair:?} is not name=value:\n{text}")) - }) - .collect(); - assert_eq!( - shown.len(), - object.len(), - "{key}: the text and the JSON name different facts:\n{text}\n{listing:#}" - ); - for (name, value) in shown { - let expected = match object.get(name) { - Some(serde_json::Value::Null) => "unrecorded", - Some(serde_json::Value::String(recorded)) => recorded.as_str(), - other => panic!("{key}: the JSON's {name} is {other:?}:\n{listing:#}"), - }; - assert_eq!(value, expected, "{key}: {name}:\n{text}\n{listing:#}"); - } - } -} diff --git a/tests/e2e-cucumber/tests/e2e/service_stop_steps.rs b/tests/e2e-cucumber/tests/e2e/service_stop_steps.rs index 39d7e92d0e..024f0b5fee 100644 --- a/tests/e2e-cucumber/tests/e2e/service_stop_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/service_stop_steps.rs @@ -4,8 +4,7 @@ //! Steps for stopping a managed service: `rocm services stop --yes` //! (confirmed, and unconfirmed through the `ROCM_E2E_STOP_OUTCOME` seam), and -//! `rocmd sandbox-tool stop_server`; and for `engine_ipc.feature`, the steps -//! that run `rocm __engine-stdio vllm` with a request and read its answer. +//! `rocmd sandbox-tool stop_server`. //! //! Black-box: plants a managed-service record as plain JSON in its own isolated //! data dir — the same on-disk shape `rocm serve --managed` writes — then runs @@ -17,7 +16,6 @@ use std::path::PathBuf; use std::process::{Command, Stdio}; use cucumber::{given, then, when}; -use rocm_engine_protocol::ENGINE_PROTOCOL_VERSION; use crate::E2eWorld; @@ -203,15 +201,6 @@ async fn managed_server_with_a_recycled_pid(world: &mut E2eWorld) { /// the process: it was not signalled, so it is still running. #[then("the process now holding the recorded process id is still running")] async fn process_holding_the_pid_still_runs(world: &mut E2eWorld) { - assert_recorded_process_still_running( - world, - "the stop signalled a process that is not the recorded server", - ); -} - -/// The process the scenario recorded has not exited; `failure` says what it -/// means if it has. -fn assert_recorded_process_still_running(world: &mut E2eWorld, failure: &str) { let process = world .recorded_process .as_mut() @@ -221,7 +210,7 @@ fn assert_recorded_process_still_running(world: &mut E2eWorld, failure: &str) { .try_wait() .expect("failed to check the recorded process") .is_none(), - "{failure}" + "the stop signalled a process that is not the recorded server" ); } @@ -461,75 +450,6 @@ async fn engine_prints_garbage_and_fails(world: &mut E2eWorld) { ); } -/// The version a stand-in engine names when it answers in a protocol this -/// release cannot use: a later major, which no caret rule accepts. -const INCOMPATIBLE_PROTOCOL: &str = "9.0.0"; - -/// This release's engine protocol with its patch raised by one: a newer -/// protocol that only adds to this release's, which the caret rule accepts. -fn next_patch_version() -> String { - let (rest, patch) = ENGINE_PROTOCOL_VERSION - .rsplit_once('.') - .expect("the engine protocol version is MAJOR.MINOR.PATCH"); - let patch: u64 = patch.parse().expect("the patch is a number"); - format!("{rest}.{}", patch + 1) -} - -/// The stop answer every stand-in below gives, with `version` as its -/// `protocol_version` (none at all for `None`, as an engine older than the -/// field writes it). -fn stop_answer(version: Option<&str>) -> String { - let mut answer = serde_json::json!({"ok": true, "data": {"stopped": true, "graceful": true}}); - if let Some(version) = version { - answer["protocol_version"] = serde_json::Value::from(version); - } - answer.to_string() -} - -#[given("the engine answers the stop request in an engine protocol this release cannot use")] -async fn engine_answers_in_an_incompatible_protocol(world: &mut E2eWorld) { - install_standalone_daemon( - world, - &format!("echo '{}'", stop_answer(Some(INCOMPATIBLE_PROTOCOL))), - ); -} - -#[given("the engine writes a log line on stdout before its answer to the stop request")] -async fn engine_logs_on_stdout_before_answering(world: &mut E2eWorld) { - install_standalone_daemon( - world, - &format!( - "echo 'stand-in engine: loading model'\necho '{}'", - stop_answer(Some(ENGINE_PROTOCOL_VERSION)) - ), - ); -} - -/// An answer in this release's protocol, in a newer one that only added to it -/// (the next patch: same minor, so the caret rule accepts it), or with no -/// version, as an engine from before the field writes it. The newer one carries -/// the addition too: a field this release does not know, in the envelope and -/// in the stop's data, which it must ignore. -#[given( - regex = r"^the engine answers the stop request in (this release's engine protocol|a newer engine protocol that only adds to this release's|no named engine protocol)$" -)] -async fn engine_answers_in_a_usable_protocol(world: &mut E2eWorld, protocol: String) { - let next_patch = next_patch_version(); - let version = match protocol.as_str() { - "this release's engine protocol" => Some(ENGINE_PROTOCOL_VERSION), - "a newer engine protocol that only adds to this release's" => Some(next_patch.as_str()), - "no named engine protocol" => None, - other => panic!("no stand-in for {other:?}"), - }; - let mut answer: serde_json::Value = - serde_json::from_str(&stop_answer(version)).expect("the stop answer is JSON"); - if protocol == "a newer engine protocol that only adds to this release's" { - answer["hint"] = serde_json::Value::from("a field added after this release"); - answer["data"]["drained_requests"] = serde_json::Value::from(0); - } - install_standalone_daemon(world, &format!("echo '{answer}'")); -} - // ── When ─────────────────────────────────────────────────────────── /// Runs the pinned, directly-runnable form `serve_summary.rs`'s `stop` row @@ -675,9 +595,9 @@ async fn engine_answered_the_stop(world: &mut E2eWorld) { ); } -/// The stop report `rocmd sandbox-tool stop_server` printed, parsed as JSON, -/// after asserting that the tool exited 0: in every scenario that reads the -/// report this way, the stop itself succeeds whatever the engine answered. +/// The stop report `rocmd sandbox-tool stop_server` printed, with the tool's own +/// exit status checked first: both engine endings below leave the stop itself +/// succeeding. fn tool_report(world: &E2eWorld) -> serde_json::Value { let stdout = world.cli_output.as_deref().unwrap_or_default(); assert_eq!( @@ -714,23 +634,12 @@ async fn engine_received_one_stop_request(world: &mut E2eWorld) { .unwrap_or_else(|error| panic!("the request is not JSON ({error}): {requests:?}")); assert_eq!(request["method"], "stop", "{request}"); assert_eq!(request["payload"]["service_id"], SERVICE_ID, "{request}"); - // The daemon writes its request in its own engine protocol. - assert_eq!( - request["protocol_version"], ENGINE_PROTOCOL_VERSION, - "{request}" - ); } /// What the engine printed before it exited non-zero is what the report carries: /// a stop it answered, with no error taken from the exit status. #[then("the tool reports the engine's answer to the stop, not the status it exited with")] async fn engine_answer_survives_a_failing_exit(world: &mut E2eWorld) { - assert_engine_answered_the_stop(world); -} - -/// The report carries the stand-in's stop answer as the engine's result, and -/// the stop itself completed. -fn assert_engine_answered_the_stop(world: &E2eWorld) { let report = tool_report(world); assert_eq!( report["result"]["engine_stop"], @@ -752,61 +661,13 @@ async fn unreadable_answer_reported_with_stderr(world: &mut E2eWorld) { assert_eq!( engine_stop["error"], "failed to parse engine response envelope \ - (engine stdio process exited with code 1): the engine's stdout is not JSON \ - (expected ident at line 1 column 2), starting with `this is not an answer` \ - (an engine writes only its JSON answer to stdout; logs go to stderr); \ + (engine stdio process exited with code 1); \ stderr: engine exploded: no container runtime", "{report}" ); assert!(engine_stop.get("stopped").is_none(), "{report}"); } -/// An answer in a protocol this release cannot use is not taken as the stop's -/// result, even though it says the engine stopped: the report carries the -/// refusal, naming both versions, and nothing from the answer. -#[then( - "the tool reports the engine's answer refused, naming the engine's protocol and this release's" -)] -async fn incompatible_answer_refused(world: &mut E2eWorld) { - let report = tool_report(world); - let engine_stop = &report["result"]["engine_stop"]; - assert_eq!( - *engine_stop, - serde_json::json!({ - "attempted": true, - "error": format!( - "engine answered in engine protocol {INCOMPATIBLE_PROTOCOL}, which this \ - release (engine protocol {ENGINE_PROTOCOL_VERSION}) cannot use" - ), - }), - "{report}" - ); -} - -/// An answer with a log line before it on stdout is refused, and the error says -/// what the engine did wrong, quoting the line it wrote before its answer. -#[then("the tool reports the engine's answer refused for the log line the engine wrote before it")] -async fn contaminated_answer_refused(world: &mut E2eWorld) { - let report = tool_report(world); - assert_eq!( - report["result"]["engine_stop"], - serde_json::json!({ - "attempted": true, - "error": "failed to parse engine response envelope: the engine wrote other \ - output to stdout before its answer, starting with `stand-in engine: \ - loading model` (an engine writes only its JSON answer to stdout; logs go \ - to stderr)", - }), - "{report}" - ); -} - -/// The engine's own answer is the stop's engine result. -#[then("the tool reports the engine's answer to the stop")] -async fn engine_answer_reported(world: &mut E2eWorld) { - assert_engine_answered_the_stop(world); -} - /// For a `vllm` server the engine's `Stop` is advisory: the recorded process /// decides, so a failed request does not leave the server unconfirmed. #[then("the tool still reports the server stopped")] @@ -1039,204 +900,3 @@ fn assert_succeeded(world: &E2eWorld) { combined_output(world) ); } - -// ── An engine reading a request (engine-ipc-08 to -12) ───────────── - -/// The `vllm` engine's own record of a server (`/engines/vllm/state/`), -/// as the engine writes it when it starts one. -fn vllm_engine_state_path(world: &E2eWorld) -> PathBuf { - engine_state_dir(world).join(format!("{SERVICE_ID}.json")) -} - -/// A process the `vllm` engine recorded as a server it started: a real `sleep`, -/// named in the engine's state file with the start-time token `/proc` gives it, -/// so a `stop` the engine served would find and end it. -#[given("an engine server whose process the vllm engine recorded is running")] -async fn vllm_engine_recorded_a_running_server(world: &mut E2eWorld) { - let process = Command::new("sleep") - .arg("300") - .stdin(Stdio::null()) - .stdout(Stdio::null()) - .stderr(Stdio::null()) - .spawn() - .expect("failed to start the process to record"); - let state = serde_json::json!({ - "service_id": SERVICE_ID, - "status": "ready", - "pid": process.id(), - "start_ticks": start_ticks(process.id()), - }); - world.recorded_process = Some(process); - std::fs::create_dir_all(engine_state_dir(world)).expect("failed to create engine state dir"); - std::fs::write( - vllm_engine_state_path(world), - serde_json::to_vec_pretty(&state).expect("failed to serialize engine state"), - ) - .expect("failed to write the engine's state"); -} - -/// Runs `rocm __engine-stdio vllm`, the command the daemon reaches an engine -/// through, sends it `request` on stdin and records what it printed and how it -/// exited. -fn send_to_vllm_over_stdio(world: &mut E2eWorld, request: &str) { - use std::io::Write as _; - let mut command = Command::new(crate::rocm_binary()); - command - .args(["__engine-stdio", ENGINE]) - .stdin(Stdio::piped()) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()); - world.isolate_cmd(&mut command); - let mut child = command.spawn().expect("failed to run rocm __engine-stdio"); - child - .stdin - .take() - .expect("piped stdin") - .write_all(format!("{request}\n").as_bytes()) - .expect("failed to send the request"); - let output = child.wait_with_output().expect("failed to wait for rocm"); - world.cli_output = Some(String::from_utf8_lossy(&output.stdout).into_owned()); - world.cli_stderr = Some(String::from_utf8_lossy(&output.stderr).into_owned()); - world.cli_rc = Some(output.status.code().unwrap_or(-1)); -} - -/// A `stop` request for the server, written for [`INCOMPATIBLE_PROTOCOL`]. -#[when( - "the vllm engine is asked over stdio to stop that server, in an engine protocol it cannot serve" -)] -async fn ask_vllm_to_stop_in_an_incompatible_protocol(world: &mut E2eWorld) { - let request = serde_json::json!({ - "protocol_version": INCOMPATIBLE_PROTOCOL, - "method": "stop", - "payload": {"service_id": SERVICE_ID, "force": true}, - }); - send_to_vllm_over_stdio(world, &request.to_string()); -} - -/// The requests the engine-side scenarios send. `frobnicate` is a method no -/// engine has, so in an incompatible protocol the only answer that names the -/// protocol is one given before the method is decoded; the stop whose -/// version is the number `9` is likewise refused only if the version is read -/// before the envelope is decoded as a whole. -#[when( - regex = r"^the vllm engine is sent over stdio (a request for a method it does not have, in an engine protocol it cannot serve|a stop request for that server whose protocol version is not text|a request for a method it does not have, in its own engine protocol|something that is not a request)$" -)] -async fn send_vllm_a_request(world: &mut E2eWorld, request: String) { - let text = match request.as_str() { - "a request for a method it does not have, in an engine protocol it cannot serve" => { - serde_json::json!({ - "protocol_version": INCOMPATIBLE_PROTOCOL, - "method": "frobnicate", - "payload": {}, - }) - .to_string() - } - "a stop request for that server whose protocol version is not text" => serde_json::json!({ - "protocol_version": 9, - "method": "stop", - "payload": {"service_id": SERVICE_ID, "force": true}, - }) - .to_string(), - "a request for a method it does not have, in its own engine protocol" => { - serde_json::json!({ - "protocol_version": ENGINE_PROTOCOL_VERSION, - "method": "frobnicate", - "payload": {}, - }) - .to_string() - } - "something that is not a request" => "this is not a request".to_owned(), - other => panic!("no request for {other:?}"), - }; - send_to_vllm_over_stdio(world, &text); -} - -/// The answer `rocm __engine-stdio` printed, checked to be exactly an error -/// envelope with `code` and `message`, in this release's protocol, after a -/// clean exit: every refusal is an answer the daemon can report, not a crash. -fn assert_engine_error_answer(world: &E2eWorld, code: &str, message: &str) { - let stdout = world.cli_output.as_deref().unwrap_or_default(); - assert_eq!( - world.cli_rc, - Some(0), - "rocm __engine-stdio failed:\n{stdout}\n{}", - world.cli_stderr.as_deref().unwrap_or_default() - ); - let answer: serde_json::Value = - serde_json::from_str(stdout).unwrap_or_else(|error| panic!("{error}: {stdout}")); - assert_eq!( - answer, - serde_json::json!({ - "protocol_version": ENGINE_PROTOCOL_VERSION, - "ok": false, - "error": {"code": code, "message": message}, - }), - "{answer}" - ); -} - -#[then( - "the engine answers that it cannot serve that engine protocol, naming its own and the request's" -)] -async fn engine_refused_the_protocol(world: &mut E2eWorld) { - assert_engine_error_answer( - world, - "incompatible_protocol", - &format!( - "this engine speaks engine protocol {ENGINE_PROTOCOL_VERSION}; the request was made \ - for protocol {INCOMPATIBLE_PROTOCOL}, which it cannot serve" - ), - ); -} - -#[then("the engine answers that it cannot read the request's protocol version")] -async fn engine_refused_an_unreadable_version(world: &mut E2eWorld) { - assert_engine_error_answer( - world, - "incompatible_protocol", - &format!( - "this engine speaks engine protocol {ENGINE_PROTOCOL_VERSION}; the request named \ - protocol version \"9\", which is not a MAJOR.MINOR.PATCH version, so it cannot be \ - served" - ), - ); -} - -#[then("the engine answers that it has no such method")] -async fn engine_has_no_such_method(world: &mut E2eWorld) { - assert_engine_error_answer( - world, - "unknown_method", - &format!( - "this engine (engine protocol {ENGINE_PROTOCOL_VERSION}) has no method \"frobnicate\"" - ), - ); -} - -#[then("the engine answers that what it was sent is not a request")] -async fn engine_says_not_a_request(world: &mut E2eWorld) { - assert_engine_error_answer( - world, - "invalid_request", - "the request is not JSON: expected ident at line 1 column 2", - ); -} - -#[then("the engine server's process is still running")] -async fn engine_server_still_running(world: &mut E2eWorld) { - assert_recorded_process_still_running( - world, - "the engine refused the stop but its server's process exited", - ); -} - -#[then("the vllm engine's record of that server still names its process")] -async fn vllm_engine_record_unchanged(world: &mut E2eWorld) { - let pid = recorded_pid(world); - let state: serde_json::Value = serde_json::from_slice( - &std::fs::read(vllm_engine_state_path(world)).expect("the engine's state is gone"), - ) - .expect("the engine's state is not JSON"); - assert_eq!(state["pid"], pid, "{state}"); - assert_eq!(state["status"], "ready", "{state}"); -}