From 5c2848a1f872f85a786424344d9035fda29a8936 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Tue, 10 Nov 2026 16:12:03 +0000 Subject: [PATCH 1/2] docs(host-probing): say which summary callers read the kernel release more than once The kernel-release section said callers that gather only the summary "still read once for themselves". Three paths read more than once for one user action: the chat bridge's examine and doctor tools gather the summary and then render the text form, which gathers it again; rocmd's examine tool gathers in process and then runs `rocm examine` as a child, which gathers again; and `rocm install driver` gathers before the plan and again after an executed one. The timeout note, which listed who can now wait 5 s instead of 1.5 s, did not say that these callers pay it per read, so each can wait up to 10 s, nor that the limit applies on Linux only and that examination-only callers such as `rocm diagnose` already waited 5 s. It also left out `rocm install driver --reconcile`. Both statements are rewritten from the call sites. No code or behaviour changes. Signed-off-by: Jussi Elo --- docs/host-probing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/host-probing.md b/docs/host-probing.md index f2a7444a5..765c96b80 100644 --- a/docs/host-probing.md +++ b/docs/host-probing.md @@ -75,11 +75,11 @@ 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); and `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 the `examine` and `doctor` tools of the chat bridge, of the `examine` tool of `rocmd` and of an executed `rocm install driver` 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. From d0371a06d7047e9b0a229dab706b6302511eae53 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Wed, 11 Nov 2026 09:01:44 +0000 Subject: [PATCH 2/2] docs: list the multi-read callers once in the host-probing note Break the three kernel-release paths that read more than once out of the long "Decided and delivered" paragraph into a bullet list, and have the timeout bullet point back to that list instead of naming the three again, so the two statements cannot drift. No change to what the note claims. Signed-off-by: Jussi Elo --- docs/host-probing.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/host-probing.md b/docs/host-probing.md index 765c96b80..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 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); and `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 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 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 the `examine` and `doctor` tools of the chat bridge, of the `examine` tool of `rocmd` and of an executed `rocm install driver` 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`. +- 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.