diff --git a/docs/host-probing.md b/docs/host-probing.md index f2a7444a5..cba2eea58 100644 --- a/docs/host-probing.md +++ b/docs/host-probing.md @@ -75,11 +75,19 @@ Proposal: `detect_kernel_version` survives and `probe_os` calls it for `kernel_r ### Decided and delivered -The change took the proposed survivor: `detect_kernel_version` in [os_facts.rs](../crates/rocm-core/src/host_gpu/os_facts.rs) is the one `uname -r` reader, and `probe_os` in [host_env.rs](../crates/rocm-core/src/examine/host_env.rs) calls it for `kernel_release` on Linux, native and WSL alike, with a failed read left empty. It is also one read per inspection where one command runs both stacks: `rocm examine --json` builds both through `Examination::probe_with_summary`, which probes this host and gathers the summary from that examination with the crate-private `ExamineSummary::gather_after` (so no caller can pair the summary with an examination of another host, such as one deserialised from a report), and the summary takes the examination's `kernel_release` (a failed read included) on Linux instead of running `uname -r` again, so the two fields cannot disagree on a transient failure and a hung `uname` costs one timeout, not two. Callers that gather only the summary (the text form, the MCP and bridge snapshots) still read once for themselves. `uname -v` stays in `probe_os`. Windows is out of this change: the examination still leaves `kernel_release` empty there and the summary still reads `cmd /C ver` under the shorter optional-command timeout; whether `kernel_release` should be filled on Windows stays open, and so does the Windows unit test the proposal mentioned, because the Windows branches did not change. +The change took the proposed survivor: `detect_kernel_version` in [os_facts.rs](../crates/rocm-core/src/host_gpu/os_facts.rs) is the one `uname -r` reader, and `probe_os` in [host_env.rs](../crates/rocm-core/src/examine/host_env.rs) calls it for `kernel_release` on Linux, native and WSL alike, with a failed read left empty. It is also one read per inspection where one command runs both stacks: `rocm examine --json` builds both through `Examination::probe_with_summary`, which probes this host and gathers the summary from that examination with the crate-private `ExamineSummary::gather_after` (so no caller can pair the summary with an examination of another host, such as one deserialised from a report), and the summary takes the examination's `kernel_release` (a failed read included) on Linux instead of running `uname -r` again, so the two fields cannot disagree on a transient failure and a hung `uname` costs one timeout, not two. Callers that gather only the summary still read for themselves, and most of them read once per call: the text form of `rocm examine` (`examine_human_report` in [examine_report_text.rs](../apps/rocm/src/examine_report_text.rs)), the in-process `rocm examine` of the chat bridge, the bridge snapshots and the host snapshot, the sandbox examine snapshot of `rocmd`, the free-form answer, `rocm install driver --reconcile`, and the runtime-install finalizer (which asks only when a runtime that cannot serve raises the question of whether the host has a GPU). + +Three paths read more than once for one user action, as they did before this change: + +- the `examine` and `doctor` tools of the chat bridge in [mcp_bridge.rs](../apps/rocm/src/chat/mcp_bridge.rs) gather the summary and then render the text form, which gathers it again (two reads in one process); +- the `examine` tool of `rocmd` in [mcp.rs](../apps/rocmd/src/mcp.rs) gathers the summary in process and then runs `rocm examine` as a child process, whose text form gathers it again (two reads, in two processes); +- `rocm install driver` in [driver_install.rs](../apps/rocm/src/driver_install.rs) gathers the summary before it builds the plan and, when it runs the plan, once more afterwards (one read for a dry run or a plan that is only reported, two for an executed install). + +`uname -v` stays in `probe_os`. Windows is out of this change: the examination still leaves `kernel_release` empty there and the summary still reads `cmd /C ver` under the shorter optional-command timeout; whether `kernel_release` should be filled on Windows stays open, and so does the Windows unit test the proposal mentioned, because the Windows branches did not change. The four open questions are decided as follows. -- Timeout: 5 s, the longer of the two old limits (`KERNEL_RELEASE_TIMEOUT`, written out as five seconds rather than borrowed from `SHORT`, which is also 5 s today, and pinned by `the_kernel_release_timeout_is_five_seconds`). `uname -r` is a few bytes the kernel hands over, so a read that takes seconds is a stalled host, where waiting costs little and a spurious "unknown" costs more: `kernel_release` feeds the WSL version check and the kernel-dependent diagnoses, which read an empty value as nothing to report. The cost is that every caller of `ExamineSummary::gather` and `gather_without_driver_facts` that reads the kernel for itself (the text of `rocm examine`, the MCP and bridge snapshots, the free-form answer, `rocm install driver`, the runtime-install finalizer, and `rocmd`'s host snapshot, MCP and sandbox paths) can wait up to 5 s instead of 1.5 s on a host whose `uname` hangs; none of them is on a path run for every command. `rocm examine --json` waits for one timeout, because it hands the examination's read to the summary. +- Timeout: 5 s, the longer of the two old limits (`KERNEL_RELEASE_TIMEOUT`, written out as five seconds rather than borrowed from `SHORT`, which is also 5 s today, and pinned by `the_kernel_release_timeout_is_five_seconds`). `uname -r` is a few bytes the kernel hands over, so a read that takes seconds is a stalled host, where waiting costs little and a spurious "unknown" costs more: `kernel_release` feeds the WSL version check and the kernel-dependent diagnoses, which read an empty value as nothing to report. The cost is that every caller of `ExamineSummary::gather` and `gather_without_driver_facts` that reads the kernel for itself on Linux, native or WSL (the text of `rocm examine`, the MCP and bridge snapshots, the free-form answer, `rocm install driver` and its `--reconcile` form, the runtime-install finalizer, and `rocmd`'s host snapshot, MCP and sandbox paths) can wait up to 5 s per read instead of 1.5 s on a host whose `uname` hangs, and a caller that reads more than once pays that more than once: the two reads of each of the three multi-read paths listed above run one after the other, so each of those can wait up to 10 s instead of 3 s. None of these is on a path run for every command. `rocm examine --json` waits for one timeout, because it hands the examination's read to the summary. Windows does not change: the summary there reads `cmd /C ver` under the 1.5 s limit, and the examination-only callers, such as `rocm diagnose`, already waited up to 5 s in `probe_os`. - Failure: `None` in the summary (`` in the text, null in the JSON) and an empty `kernel_release` in the examination, with no `probe_failures` entry, as before. Adding an entry would change `status` to degraded on a host without a usable `uname`, such as a minimal container, which is a bigger change than the pair warrants. An empty `kernel_release` reads as WSL 2 in `is_wsl1_kernel`, as before. - Non-zero exit with output: dropped by both. The examination used to keep what a failing `uname` printed; the summary dropped it. A release from a `uname` that failed is not trustworthy. - Decoding: strict UTF-8 for both. The examination used to decode lossily. A release is ASCII in practice, so the only input that moves is one that is not UTF-8 at all, and a string with replacement characters in it would reach the diagnoses and the WSL check as if it were a release.