Skip to content

feat(examine): let the user choose which framework to probe - #218

Merged
volen-silo merged 2 commits into
mainfrom
feat/examine-framework-flag
Aug 12, 2026
Merged

volen-silo merged 2 commits into
mainfrom
feat/examine-framework-flag

Conversation

@volen-silo

Copy link
Copy Markdown
Collaborator
  • If this PR fixes a bug, searched tests/e2e-cucumber/expectations.toml for the fixed ticket ID and removed/narrowed any now-stale xfail rows. The row for this gap is removed here.

Stacked on #217, which is stacked on #216. Merge in that order; this diff shrinks to just the flag once they land.

Summary

FrameworkProbe has had four variants all along, and the probe acts on all four. No caller ever passed anything but the default, so from the command line there was no choice to make — rocm examine --framework skip was an unknown argument. This is wiring, not new capability.

$ rocm examine --framework nonsense --json
error: invalid value 'nonsense' for '--framework <FRAMEWORK>'
  [possible values: auto, pytorch, llama-cpp, skip]

The flag is a CLI-side mirror of the library enum rather than a ValueEnum derived on it, so clap stays out of rocm-core.

It applies to --json only, and the help says so. The human report carries no framework line, so the flag would otherwise be a silent no-op there — worse than one that admits its scope.

Test plan

Two unit tests cover what this host cannot:

  • the mapping is pinned for all four variants, so a renamed one cannot quietly fall back to the default;
  • rocm examine --help is asserted to offer all four. That they existed in the library but were unreachable is the defect, so "the library has them" would be the wrong thing to assert.

Two more in rocm-core pin the behaviour the flag selects: skip records "skipped" — a distinct answer from "unknown", which means the probe ran and found nothing — and touches none of the other framework fields, so it cannot quietly do the work it claims to avoid.

Locally: cargo xtask e2e gives 40 scenarios, 3 xfail, 0 XPASS, 0 unexpected. cargo fmt --all --check, workspace clippy, clippy -p e2e-cucumber --test e2e, and the 62 harness unit tests are all clean.

A defect found while doing this, and deliberately not fixed here

The scenario becomes @requires-bare-metal, and the reason is worth a reviewer's attention rather than being buried in a tag.

On WSL2 the probe returns as soon as it recognises the platform — before its framework step — so framework stays "unknown" whatever the flag says. Verified on a WSL2 box: all four values yield unknown. The scenario therefore has nothing to assert there.

That early return exists because the driver and kernel probes do not apply under WSL2, which is true. But it also skips the framework probe, and PyTorch on WSL2 is a supported, AMD-documented configuration — so examine --json can never tell a WSL user what ROCm build their PyTorch has. That is a real gap, it belongs with the rest of the WSL work rather than smuggled in here, and the tag's doc comment now records it so the next reader does not have to rediscover it.

🤖 Generated with Claude Code

@juhovainio

Copy link
Copy Markdown
Collaborator

I reviewed this PR and traced its claims against the live branch code rather than just the diff, and everything held up.

  • probe_framework's Skip arm sets e.framework = "skipped".to_owned() and does nothing else (crates/rocm-core/src/examine.rs:1040-1055), matching the "skipped is distinct from unknown, and skip touches nothing else" claim and its two new unit tests.
  • The WSL2 early-return claim is exactly right: Examination::probe checks e.is_wsl and returns before ever reaching the if e.os_family == "linux" branch that calls probe_framework (examine.rs:251-268). So on WSL2 the --framework flag genuinely has nowhere to act, regardless of value, which is why the scenario had to become @requires-bare-metal rather than being fixed here.
  • The CLI wiring is a straight, complete mapping: FrameworkArg (apps/rocm/src/main.rs:847-868) covers all four FrameworkProbe variants with no fallback branch, dispatch passes framework.into() through (main.rs:1454), and examine() only reads framework inside the if json branch (main.rs:1984-1985) - so the "affects --json only" scope is enforced structurally, not just documented.
  • The Examination struct genuinely has framework, framework_version, framework_rocm_version, framework_arch_list, and framework_notes as the second new unit test expects.
  • The style-only second commit (restoring the trailing newline expectations.toml needs) is a trivial, correct fix for the same file the first commit edited.

CI is green across the board, including both self-hosted GPU/Strix Halo lanes and the Windows build (relevant here since the CLI enum lives outside rocm-core, keeping clap off that crate as intended).

Looks safe to approve after final validation - this is a diff-and-code read, not a substitute for CI or a live run. One non-blocking note: this PR is stacked on #217, which is stacked on #216, and should merge in that order for the diffs to stay this small.

@volen-silo
volen-silo force-pushed the fix/examine-json-parity branch from 1aa8fed to f9d6d3f Compare August 12, 2026 12:07
@volen-silo
volen-silo force-pushed the feat/examine-framework-flag branch from 83c5fa8 to 0415b50 Compare August 12, 2026 12:13
Base automatically changed from fix/examine-json-parity to main August 12, 2026 12:40
`FrameworkProbe` has had four variants all along, and the probe acted on all
four. No caller ever passed anything but the default, so from the command line
there was no choice to make: `rocm examine --framework skip` was an unknown
argument. The fix is wiring, not new capability.

The flag is a CLI-side mirror of the library enum rather than a `ValueEnum`
derived on it, so clap stays out of rocm-core. It applies to `--json` only and
says so: the human report carries no framework line, and a flag that silently
does nothing is worse than one that admits its scope.

Two unit tests cover what the machine cannot. The mapping is pinned so a
renamed variant cannot quietly fall back to the default, and the help output is
asserted to offer all four -- that they existed but were unreachable is the
whole defect, so "the library has them" is not the thing to test.

The scenario becomes @requires-bare-metal. On WSL2 the probe returns as soon as
it recognises the platform, before its framework step, so `framework` stays
"unknown" whatever the flag says and the scenario has nothing to assert. That
the probe gives up that early is a separate defect -- PyTorch on WSL2 is a
supported configuration and the report says nothing about it -- and is left to
the WSL work rather than smuggled in here.

Signed-off-by: Eugene Volen <Eugene.Volen@amd.com>
Removing the xfail row for the framework flag left the file ending in a blank
line, which `end-of-file-fixer` rejects. Caught by prek in CI, not locally --
the hook is available here and is worth running before pushing a file whose
tail was edited.

Signed-off-by: Eugene Volen <Eugene.Volen@amd.com>
@volen-silo
volen-silo force-pushed the feat/examine-framework-flag branch from 0415b50 to 06e9b30 Compare August 12, 2026 12:53
@volen-silo
volen-silo enabled auto-merge August 12, 2026 12:55
@volen-silo
volen-silo disabled auto-merge August 12, 2026 13:00
@juhovainio

Copy link
Copy Markdown
Collaborator

Checked back after the base rebase. The head commits are unchanged (638ed51, 06e9b30) — same diff I already reviewed, just replayed onto main now that #216 and #217 (the stack this was built on) have merged, per the note in my earlier comment. No new code to re-review. CI is green (one Windows GPU e2e job still pending). Still looks safe to approve.

@volen-silo
volen-silo added this pull request to the merge queue Aug 12, 2026

@rominf rominf 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.

Not blocking, and the diff itself looks good to me — I confirmed the key property, that omitting --framework preserves the previous behaviour exactly (the --json branch previously hardcoded FrameworkProbe::Auto, and default_value_t = FrameworkArg::Auto reproduces it verbatim).

One housekeeping item: the PR description carries an AI-generation footer (🤖 Generated with …). Worth stripping before this merges, since the repo is public. The commit messages are clean.

Merged via the queue into main with commit aa6da98 Aug 12, 2026
23 checks passed
@volen-silo
volen-silo deleted the feat/examine-framework-flag branch August 12, 2026 15: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.

3 participants