[jussielo-amd]

Closes ROCMAI-893.

Why this note exists

rocm examine reads several host facts through two separate stacks in rocm-core: the summary in host_gpu.rs (the text form, and the summary object of --json) and the examination in examine.rs (the rest of --json, rocm diagnose and Doctor reports). rocm examine --json runs both back to back, so the same fact can appear twice in one document from two separate reads, and the copies have drifted. Before anyone converges them, someone has to decide which copy of each pair should survive, because the surviving side decides which behaviour users keep. This adds a proposal for that decision as docs/host-probing.md, linked from the rocm-core inventory in docs/architecture.md. The note is a snapshot, to be retired when the convergence tickets close, and says so at the top and in the architecture entry.

What the note proposes

The top of the note has a table with one row per pair: the proposed survivor and the biggest difference a user can see today, so a reader can skip the host-by-host detail. Below it, for each duplicate it names both implementations as links, states how they differ today, says what a user can see, and proposes a survivor and a direction of calls. It first records that the imports already run one way (the examination calls into the summary, never the reverse) while stating plainly that shared code is not shared reads: on WSL rocm examine --json still runs the WSL summary twice and ldconfig -p four times, and the examination uses the os-release reader and parser directly rather than detect_distro_name. It proposes the rule that follows from the imports: the summary stack owns how a fact is asked of the operating system, the examination owns the document and its JSON contract. Per pair: kernel version (detect_kernel_version survives), CPU model (one reader returning model and vendor together), Windows GPU query (the summary's inventory survives, with NVIDIA and adapter names flagged as constraints), marketing name to gfx target (AMD_MARKETING_GFX_TARGETS survives), PATH lookup (the PATHEXT-aware behaviour survives under the name which), and subprocess runners (run_with_timeout as the one bounded executor, CommandCapture extended with a typed outcome rather than a second capture type).

Verifying each claimed duplicate against main turned up three things the ticket text did not say. The Windows CPU read has three implementations, not two. The Windows GPU query has more than one counterpart on the summary side (pnputil, the video controller, the PnP entity and a one-line driver query), and --json asks for the video controller three times in the usual case and five when the summary's inventory is absent, because the display gfx-target and driver-detail fallbacks each query again. The two name tables are not equivalent: the examination's covers only some APU names and no discrete GPU, so an RX 7900 XTX with no HIP SDK has an empty gpus[].gfx_target beside summary.detected_gfx_target: gfx1100 in the same document, and the two disagree about Krackan (gfx1150 versus gfx1152). Two more came from reading which host reaches which code. On WSL the examination returns from its WSL branch before the native Linux branch reads the CPU, so cpu_model is empty and cpu_vendor is unknown on every WSL host while summary.cpu is populated; the CPU change therefore does not reach WSL, and the note requires it to scope its comparison to non-WSL hosts or to make collecting CPU facts on WSL an explicit behaviour change. And the runner convergence is not only a timeout change: run_with_timeout takes its buffer 200 ms after the child exits, so a successful capture can lose output a descendant writes later, where the older helpers wait for EOF; the note lists that with the other successful-run differences (read error, wait error, spawn failure, encoding, stderr, poll interval) and requires a late-descendant characterisation test. A table in the note says which host (native Linux, WSL, native Windows, a Windows host inspecting a WSL distro) reads each fact with which stack, and each follow-up item names the hosts its characterisation test must cover. Every claim read from the code is marked as verified; anything that depends on a real host is marked UNCONFIRMED.

What it deliberately leaves open

How NVIDIA adapters are represented once the examination reads the inventory, whether gpus[].name should come from pnputil or from WMI, which timeout wins for the kernel and CPU reads, whether kernel_release should be filled on Windows, whether the typed outcome sits on CommandCapture or beside it, and whether the near copy of the candidate-spelling logic in apps/rocm joins the PATH change. The note proposes; it does not mandate.

Follow-up order

One pair per change, each starting with a characterisation test that is green against today's code, and none of them described as output-preserving: the PATH lookup change alters which tools are reported present (an empty PATH entry, a PATH that is not UTF-8, Windows candidate spellings), the CPU change leaves WSL unchanged or changes it on purpose, and the runner change alters the timeout path and can shorten a successful capture, so the note requires each such difference to get a scenario or a stated reason, and scopes the kernel and CPU comparison scenarios to the hosts where both sides are filled. The order is PATH lookup, kernel version, CPU model, marketing names (best done by finishing the open #521, which already proposes that convergence and conflicts with main), the Windows GPU query, and last the subprocess runners (the bounded-join fix in #623 does not wait for it). Filing one ticket per pair is left for after this merges.

Verification

Docs only. Ran: the docs-links check as CI runs it (lychee --config lychee.toml './**/*.md', lychee 0.24.2) with 0 errors, cargo xtask lychee (exit 0), the repository's commit hooks (license header, markdown links, signing, whitespace, merge-conflict markers), a leak scan of the diff, a conflict-marker grep, and a check that no added line in docs/architecture.md carries a phase label. Not run: cargo test, cargo clippy and the smoke script, because no code is touched; cargo xtask manifest --check, because the manifest table covers Cargo dependencies and no manifest-relevant file changed. Nothing was executed on Windows. The WSL claim about the CPU was also checked by one rocm examine --json run on a WSL2 host with a local debug build of unrecorded revision (cpu_model empty, cpu_vendor unknown, summary.cpu populated); every other claim is read from the code, and the runner differences were not run.

User-visible behaviour

None. This is a docs-only change, so no scenario applies; the note cites the existing scenarios examine-machine-readable-report, examine-both-forms-agree-on-gpu and examine-windows-driver-version-date-and-age as the ones later changes would extend.

[Copilot]

🟡 Changes recommended

The documentation still understates fallback query counts, conflates shared implementations with reused observations, and omits observable PATH lookup differences and required scenarios from the convergence plan.

3 open issues

• Shared helpers do not reuse probe results across separate reads · New
• Inventory-missing paths add extra video-controller queries · New
• PATH replacement changes observable tool-availability results · New

What changed in this PR

This docs-only PR proposes how rocm-core’s summary and examination stacks should converge on shared host-probing implementations. It changes no runtime behavior.

Changes:

• Compares six areas of duplication and proposes ownership, surviving implementations, and call direction.
• Outlines follow-up sequencing, characterization tests, and unresolved compatibility decisions, including coordination with #521 and #623.
• Links the proposal from the architecture inventory.

File	Description
docs/​host-probing.md	Adds the host-probing comparison and proposed convergence plan.
docs/​architecture.md	Links the design note beside the relevant rocm-core modules.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The proposal omits successful-exit capture loss from late descendant output and its required characterization test, and its CPU comparison plan does not account for WSL skipping CPU probing.

2 open issues

• WSL CPU facts remain unset in the comparison · New
• Drain grace can truncate output from late-writing descendants · New

3 resolved since last review

• PATH replacement changes observable tool-availability results
• Inventory-missing paths add extra video-controller queries
• Shared helpers do not reuse probe results across separate reads

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues were identified for this documentation-only host-probing convergence proposal.

No open issues 🎉

2 resolved since last review

• Drain grace can truncate output from late-writing descendants
• WSL CPU facts remain unset in the comparison

_{Review effort: Balanced}

[juhovainio]

Docs-only change; I found nothing blocking. Approving with a few optional suggestions.

What I checked: the timeouts, poll intervals, DRAIN_GRACE, the uname handling, the CPU vendor logic and the CommandCapture fields against current sources all match the note. Links are relative and resolve, and the checks that ran are green. The E2E/GPU jobs skip on the docs-only path filter.

Non-blocking:

• Length: the ticket asks for a short note; this is ~190 dense lines and the decision per pair is buried mid-paragraph. A two-line summary per pair (survivor + biggest user-visible difference) would let a reader skip the host-by-host detail.
• Title vs. content: the title says "decides", but the note says it "decides nothing by itself" (a proposal). Something like "propose" would match.
• Derived counts: the 3 vs 5 video-controller queries and 4 ldconfig runs on WSL come from reading the code rather than a run. The note labels them as such, which is the right call.
• Repetition: the same per-host facts recur across several sections.
• Snapshot: consider marking the note as a snapshot to retire once the convergence tickets close.

[juhovainio]

The ticket asks for a short note. Consider adding a two-line decision summary per pair (survivor + biggest user-visible difference) near the top, so a reader can skip the host-by-host detail.

[jussielo-amd]

Added a "Summary by pair" table right after the status and reading notes, in 383b828: one row per pair with the proposed survivor and the biggest user-visible difference, each linking to its section. Every cell repeats a claim already in the detailed section (no new claims), and I also collapsed a few per-host statements that the host table already makes (the WSL CPU and Windows kernel cases, the WSL GPU case, the native Linux and WSL name lookup, and the repeated PATH and runner differences in the order). The note did not get much shorter overall, because I did not drop any claim that appears only once, but the decision per pair is now readable from the top.

[juhovainio]

Optional: say the note is a snapshot to be retired when the convergence tickets close, so the inventory does not keep pointing at a stale design record.

[jussielo-amd]

Done in 383b828: the entry now ends with "It is a snapshot, to be retired when the convergence tickets close", and the note itself says the same near the top, including that its entry in architecture.md goes with it.

[Copilot]

🟡 Changes recommended

The documentation incorrectly treats NVIDIA as the only non-AMD inventory case and must clarify that rebuilding gpus[] also needs to account for existing Intel rows excluded by the current examination query.

1 open issue

• Include Intel adapters when rebuilding the GPU inventory baseline · New

_{Review effort: Balanced}