Skip to content

docs(host-probing): say which summary callers read the kernel release more than once - #1027

Merged
jussielo-amd merged 2 commits into
mainfrom
docs-host-probing-reach
Nov 11, 2026
Merged

jussielo-amd merged 2 commits into
mainfrom
docs-host-probing-reach

Conversation

@jussielo-amd

Copy link
Copy Markdown
Collaborator

Summary

A docs-only follow-up to #990, which converged the two uname -r reads behind rocm examine into one. An automated review of that PR pointed out that the kernel-release section of docs/host-probing.md says 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::gather and gather_without_driver_facts (the only places that run detect_kernel_version besides probe_os):

  • The examine and doctor tools in apps/rocm/src/chat/mcp_bridge.rs call ExamineSummary::gather() and then render_examine_text(), which goes through examine_human_report in apps/rocm/src/examine_report_text.rs, which calls ExamineSummary::gather() again. That is two reads in one process.
  • The examine tool in apps/rocmd/src/mcp.rs calls ExamineSummary::gather() in process and then run_rocm_capture(&["examine"]), which runs rocm examine as a child process; its text form calls gather() again. That is two reads in two processes.
  • rocm install driver in apps/rocm/src/driver_install.rs calls gather() 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-process rocm examine of the chat bridge, build_codex_bridge_snapshot, rocmd's build_bridge_snapshot and 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 ver under the 1.5 s limit), that examination-only callers such as rocm diagnose already waited 5 s in probe_os and are unchanged, and it left out rocm 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/*.md and the docs/architecture.md rows for the same claim. The architecture.md rows say only that rocm examine --json reads 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-43 and examine-44 cover rocm examine --json, which this does not touch).

Checks run locally on the commit: cargo xtask check-architecture-doc, cargo xtask lychee (and the lychee hook at commit time), cargo fmt --check, and the commit hooks (trailing whitespace, end of files, merge-conflict markers, commit signing, license headers). The full cargo test --workspace gate 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".

… 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>
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor
Security scan found no critical or high findings on lines changed by this pull request

View 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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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

@jussielo-amd
jussielo-amd marked this pull request as ready for review November 10, 2026 17:43
@jussielo-amd
jussielo-amd requested a review from a team as a code owner November 10, 2026 17:43
@jussielo-amd
jussielo-amd requested a review from rominf November 10, 2026 17:43

@nowycondro nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 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.md itself 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 bridge examine/doctor, rocmd's examine tool, an executed rocm 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 --reconcile addition) was independently traced against the current source by two separate passes and holds up exactly — down to distinguishing the in-process rocm examine path in the chat bridge (one read) from the MCP examine/doctor tool 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.md for 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 a file.rs:42 citation).

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 juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/host-probing.md Outdated
### 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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/host-probing.md Outdated
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`.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

There are no active review issues for the documentation-only clarification of kernel-release read counts and timeout behavior.

No open issues 🎉

Review effort: Balanced

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 11, 2026
Merged via the queue into main with commit 50d2456 Nov 11, 2026
47 checks passed
@jussielo-amd
jussielo-amd deleted the docs-host-probing-reach branch November 11, 2026 09:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants