Repository navigation
docs(host-probing): say which summary callers read the kernel release more than once - #1027
Conversation
… 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 <jussi.elo@amd.com>
Security scan found no critical or high findings on lines changed by this pull requestView the security scan run for complete reports. “New” means the finding is located in a changed file on an added or modified line; it is not a base-versus-head findings delta. |
There was a problem hiding this comment.
🟢 Approval recommended
The documentation-only clarification of kernel-release read counts and timeout costs has no active review issues.
No open issues 🎉
What changed in this PR
This docs-only follow-up to #990 corrects the host-probing note’s description of kernel-release reads and timeout costs. It does not change runtime behavior.
Changes:
- Distinguishes single-read summary callers from chat bridge tools, the daemon’s examine tool, and executed driver installs that read twice.
- Clarifies Linux’s five-second per-read timeout, the ten-second combined limit for serial reads, and unchanged Windows and examination-only behavior.
| File | Description |
|---|---|
| docs/host-probing.md | Corrects caller read counts and clarifies timeout costs and platform scope. |
Review effort: Balanced
nowycondro
left a comment
There was a problem hiding this comment.
🤖 Automated review · review-code · head 5c2848a1f872
Review — no blocking findings
Full review of the whole change.
Docs-only follow-up to #990, naming no ticket; the PR description's claims about which call sites read the kernel release once vs. more than once, and what timeout exposure each one carries, were traced against the current source rather than taken on trust.
Blocking
None
Non-blocking
None
Decisions for the author
- No tracking link for the newly-quantified multi-read latency (3 paths now documented as paying up to 10 s instead of 5 s) — non-blocking-improvement
docs/host-probing.mditself links a tracking issue for at least one other known defect it documents (#623, for a timeout-join issue, ~line 215), but the three multi-read paths this PR newly quantifies (chat bridgeexamine/doctor,rocmd'sexaminetool, an executedrocm install driver) get no equivalent link, even though the PR body explicitly defers fixing them to "a later pair of the host-probing series." Not a defect in what's written — the paragraph's own wording ("as they did before this change") scopes the correction honestly — but linking a tracking issue, consistent with the doc's own established practice elsewhere, would make the deferred follow-up easier to find later.
Positive signals
- Every specific, checkable claim in the reworded paragraphs (per-call-site read counts, the 5 s/1.5 s timeout split, the Linux-only reach of the longer timeout, the
rocm install driver --reconcileaddition) was independently traced against the current source by two separate passes and holds up exactly — down to distinguishing the in-processrocm examinepath in the chat bridge (one read) from the MCPexamine/doctortool arm in the same file (two reads), which is an easy pair to conflate and the PR gets right. - The PR body itself documents having grepped README/
docs/*.md/docs/architecture.mdfor the same claim before relying on the correction being complete, and the new markdown links follow this repo's AGENTS.md §5 relative-link convention (verified: all four newly-linked files exist at head, none use a bare path or afile.rs:42citation).
Deployment notes
None — no code or behavior change.
What this covered
Read the full diff (docs/host-probing.md, the only file changed) against f573ba002f1c…5c2848a1f872. Independently traced every call site of ExamineSummary::gather/gather_without_driver_facts/gather_after and detect_kernel_version across apps/rocm/src/chat/mcp_bridge.rs, apps/rocm/src/examine_report_text.rs, apps/rocm/src/examine_cmd.rs, apps/rocmd/src/mcp.rs, apps/rocm/src/driver_install.rs, apps/rocm/src/runtime_install_finalize.rs, apps/rocm/src/freeform_answer.rs, apps/rocm/src/bridge_snapshot.rs, apps/rocmd/src/host_snapshot.rs, apps/rocmd/src/sandbox.rs, crates/rocm-core/src/examine.rs, crates/rocm-core/src/host_gpu.rs, crates/rocm-core/src/host_gpu/os_facts.rs, crates/rocm-core/src/host_gpu/capture.rs, crates/rocm-core/src/examine/host_env.rs and crates/rocm-core/src/probe_exec.rs — once directly, and again via two independent fan-out workers, all three agreeing with no discrepancy. Checked README/docs/architecture.md/source comments repo-wide for a stale instance of the corrected claim (none found) and checked the neighboring CPU-model section for the same latent mistake (none found — it's already more precise). Checked all GitHub check runs for this commit: every run completed with conclusion success or skipped, none failing.
Did not run: no test execution was applicable (prose-only change, no behavior to exercise); "code comments" and "history" passes are folded into the call-site trace and the git log check above since no source file changed. Not reconciled against any discussion on the PR (the one prior automated review, from copilot-pull-request-reviewer[bot], was checked only to confirm it isn't a duplicate of this account's own review at this head — its content was not read or weighed).
Not a human review. This is an automated code review; please verify findings independently before acting on them.
juhovainio
left a comment
There was a problem hiding this comment.
Docs-only change. I checked the new text against the code: the callers it names (chat bridge examine/doctor, the rocmd examine tool, and rocm install driver on an executed install) do read the kernel release more than once, --reconcile and the dry run read it once, and I found no other caller of the summary gatherers the paragraph misses. The Linux-only scope and the 3 s vs 10 s arithmetic are right. This reflects a read of the diff against the source, not a runtime check. Two small non-blocking nits are inline.
| ### 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. |
There was a problem hiding this comment.
Nit: this paragraph is now one very long line; the three multi-read paths would read well as a bullet list, which would also make later edits diff cleanly.
There was a problem hiding this comment.
Agreed. In d0371a0 the three paths that read the kernel release more than once are now a bullet list under their own lead-in line instead of a semicolon-separated run inside the paragraph, so later edits to one path diff on its own line. The wording of each path is unchanged, and I re-checked all three against the call sites again: the examine and doctor tools of the chat bridge gather twice, the rocmd examine tool gathers and then runs rocm examine as a child, and rocm install driver gathers before the plan and again after an executed one.
| 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`. |
There was a problem hiding this comment.
Nit: the three multi-read paths are enumerated here and again in the paragraph above; consider pointing back to it so the two cannot drift.
There was a problem hiding this comment.
Agreed. In d0371a0 the timeout bullet no longer names the three paths a second time: it now says that the two reads of each of the three multi-read paths listed above run one after the other, so each can wait up to 10 s instead of 3 s. The list in the paragraph above is now the only place the paths are enumerated, so the two statements cannot drift apart.
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 <jussi.elo@amd.com>
Summary
A docs-only follow-up to #990, which converged the two
uname -rreads behindrocm examineinto one. An automated review of that PR pointed out that the kernel-release section ofdocs/host-probing.mdsays something the code contradicts, and the same sentence's neighbour, the note on who pays the longer timeout, undercounts. This corrects both statements from the call sites. No code changes.What was wrong
The section said "Callers that gather only the summary (the text form, the MCP and bridge snapshots) still read once for themselves." Not every one of them reads once. Tracing every caller of
ExamineSummary::gatherandgather_without_driver_facts(the only places that rundetect_kernel_versionbesidesprobe_os):examineanddoctortools inapps/rocm/src/chat/mcp_bridge.rscallExamineSummary::gather()and thenrender_examine_text(), which goes throughexamine_human_reportinapps/rocm/src/examine_report_text.rs, which callsExamineSummary::gather()again. That is two reads in one process.examinetool inapps/rocmd/src/mcp.rscallsExamineSummary::gather()in process and thenrun_rocm_capture(&["examine"]), which runsrocm examineas a child process; its text form callsgather()again. That is two reads in two processes.rocm install driverinapps/rocm/src/driver_install.rscallsgather()before it builds the plan (install_driver) and, when it executes the plan, again through the post-install closure. That is one read for a dry run or a plan that is only reported, two for an executed install.All other callers read once per call: the text form of
rocm examine, the in-processrocm examineof the chat bridge,build_codex_bridge_snapshot,rocmd'sbuild_bridge_snapshotand sandbox examine snapshot, the free-form answer,rocm install driver --reconcile, and the runtime-install finalizer (which only asks when a runtime that cannot serve raises the question of whether the host has a GPU).None of these three multi-read paths is new: #990 touches none of those files, and each read was already there when it was bounded by 1.5 s. What #990 changed is that the limit is now 5 s, so the multiplicity now matters, which is why the second statement needed fixing too.
The timeout note listed the callers that can wait up to 5 s instead of 1.5 s but did not say that a caller reading twice pays it twice (up to 10 s instead of 3 s for the three paths above, each pair being serial), that the longer limit applies on Linux only (the summary on Windows still reads
cmd /C verunder the 1.5 s limit), that examination-only callers such asrocm diagnosealready waited 5 s inprobe_osand are unchanged, and it left outrocm install driver --reconcile.What changed
Two paragraphs in the "Decided and delivered" part of the "Kernel version" section of
docs/host-probing.md: the sentence about summary-only callers now lists which ones read once and names the three that read more than once, and the cost sentence of the timeout decision now states the per-read, Linux-only reach and the doubled worst case. I grepped the README,docs/*.mdand thedocs/architecture.mdrows for the same claim. Thearchitecture.mdrows say only thatrocm examine --jsonreads the release once, which is true, so they are unchanged.What this does not do
It does not remove the extra reads or give any caller a read-once path; that would be a code change and a decision for a later pair of the host-probing series.
Tests
No behaviour changes, so no Gherkin scenario is needed: the change is prose in a design note, and the claims it corrects are not asserted by any scenario (the existing
examine-43andexamine-44coverrocm examine --json, which this does not touch).Checks run locally on the commit:
cargo xtask check-architecture-doc,cargo xtask lychee(and thelycheehook at commit time),cargo fmt --check, and the commit hooks (trailing whitespace, end of files, merge-conflict markers, commit signing, license headers). The fullcargo test --workspacegate and clippy were not run because no Rust source, test or manifest changed. The diff was scanned for internal names and trackers; the only keyword hit is the existing phrase "crate-private".