docs(rocm): generate the per-architecture support matrix from the table

[demandal25]

Summary

The README described architecture support as the literal string gfx942/gfx950, repeated at nine call sites. That phrasing cannot express either of the two things the capability table from #285 knows: that an op can be supported on one architecture and broken on the other, and that some rows are measured while others are only declared.

It was already wrong when I started. AITER causal batch prefill is miscompiled on gfx950 under ROCm 7.2.x — silently, wrong numbers rather than an error — and no reader of the README could have learned that from it.

This generates the matrix from flashinfer/arch_caps.py, which is the same data backend="auto" consults at runtime, so the docs cannot disagree with the routing.

What it renders

Four states rather than a checkmark:

	meaning
✅ validated	a suite was run on that board, and the evidence string is printed below the table
◻️ declared	supported, but no per-op measurement has been recorded on that architecture
⚠️ broken on some toolchains	with the half-open version window, the reason, and the override env var
❌ not available

The first two are the honest part. Every HIP row currently renders as declared, because those per-op measurements genuinely have not been recorded — the suites cover them, but no per-op HIP evidence was ever attributed. A hand-written table would have given all of them a ✅.

Drift protection

A pre-commit hook runs the generator with --check, so an arch_caps.py edit that does not regenerate the README fails before review rather than after someone trusts a stale row.

It rides the existing pre-commit job rather than needing a new workflow, and deliberately imports nothing from the flashinfer package — __init__.py raises on a CPU-only torch build, so the script loads arch_caps directly by path, the same technique the conformance suite uses. Stdlib only.

Test plan

• --check exits 0 on a clean tree.
• --check exits 1 with an actionable message when a row is perturbed (flipped rope/aiter on gfx950 to UNSUPPORTED), and 0 again once restored — so the hook is not vacuously passing.
• Full pre-commit run green on all three files, including the new hook.
• Rendered output reviewed: the batch_prefill/aiter gfx950 cell carries the ⚠️ and the footnote reproduces the ROCm [7.2, 7.3) window, the 97.6% figure, the backend='fa2' workaround, and the upstream link.

Columns are derived from whatever architectures the table declares, not hard-coded, so adding a third architecture adds a column without anyone remembering to.

The hook caught a real drift before I did

Not a contrived test. #286 merged while this branch was in flight, renaming the activation row to silu_and_mul so it matches the string the call sites actually pass. This branch was based on 00e93c2c, so its generated README still said activation — and CI failed on my own hook:

--- README.md (committed)
+++ README.md (generated)
-| `activation` | `aiter` | ✅ | ✅ |
+| `silu_and_mul` | `aiter` | ✅ | ✅ |
-| `activation` | `hip` | ◻️ | ◻️ |
+| `silu_and_mul` | `hip` | ◻️ | ◻️ |

That is exactly the failure mode this PR exists to prevent, and it happened on the PR that introduces the prevention. A hand-maintained table would have shipped the stale op name silently. Rebased onto 4ccc4b33 and regenerated.

The second commit adds the diff output above. The first version printed only "out of date", which told me nothing — I could not reproduce the failure on either local interpreter, because the cause was the base branch moving rather than anything about the environment.

Note for reviewers

One interaction worth knowing about, since it is the kind of thing that breaks a week later: markdownlint rewrites - list bullets to * in place, which would leave the generated block failing its own --check on the very next run — two hooks fighting each other over the same file. The generator emits markdownlint-clean output (no inline HTML in headers, * bullets) so they agree. That is why the column headers are plain gfx942 (CDNA3) rather than carrying the SKU list; the SKUs are already spelled out in the Supported GPUs line directly above.

This does not touch the existing per-kernel Feature Support Matrix, which documents routing conditions rather than architecture validation. The two answer different questions.

[Copilot]

Pull request overview

This PR adds a generator that renders the ROCm per-architecture support matrix in README.md directly from flashinfer/arch_caps.py, and wires it into pre-commit so the docs cannot drift from the runtime routing/capability table.

Changes:

• Add scripts/gen_arch_support_matrix.py to render/splice the generated matrix block (with --check for CI/pre-commit enforcement).
• Update README.md to include the generated “Per-architecture support matrix” section (including known-bad footnotes and evidence lines).
• Add a local pre-commit hook to fail if the README matrix is out of date with flashinfer/arch_caps.py.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
scripts/gen_arch_support_matrix.py	New generator + --check mode to keep README’s matrix synchronized with arch_caps.py.
README.md	Adds the generated support-matrix section and rendered output/footnotes.
.pre-commit-config.yaml	Adds a local hook to enforce that the generated README block is current.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

scripts/gen_arch_support_matrix.py:210

• The generated README block contains non-ASCII characters (emoji). Path.read_text() uses the platform default encoding, which can break on systems where UTF-8 is not the default (e.g., Windows). Read with an explicit UTF-8 encoding to make the hook deterministic across environments.

    current = README.read_text()
    updated = splice(current, render(_load_arch_caps()))

scripts/gen_arch_support_matrix.py:238

• For the same reason as the UTF-8 read, write the updated README using an explicit UTF-8 encoding so emoji and other non-ASCII characters are preserved consistently across platforms.

    if current != updated:
        README.write_text(updated)
        print(f"updated {README.relative_to(REPO_ROOT)}")

README.md:130

• The generated evidence line says gfx950 was measured on MI350X, but the earlier "Supported GPUs" line in the same section says gfx950 corresponds to MI355X. This looks like a doc inconsistency that could confuse readers; consider reconciling the SKU naming (either broaden the supported list or adjust the evidence source).

* `gfx942` — MI300X / rocm 7.2.0 / aiter 0.1.10 / torch 2.9.1 / 2026-08-19
* `gfx950` — MI350X / rocm 7.2.0 / aiter 0.1.10 / torch 2.9.1 / 2026-08-19

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (4)

scripts/gen_arch_support_matrix.py:113

• entry.support.SUPPORTED accesses an Enum member via the Enum instance, which will raise AttributeError at runtime. Compare against the Enum class (or use type(entry.support)) so the generator can run.

def _cell(entry, footnote_ids: dict[int, int]) -> str:
    if entry is None or entry.support is not entry.support.SUPPORTED:
        return UNSUPPORTED

scripts/gen_arch_support_matrix.py:78

• Loading arch_caps.py assumes spec_from_file_location() always returns a spec with a loader. If it returns None (or has loader=None), this will fail with a confusing exception. Add an explicit check and exit with a clear message.

    spec = importlib.util.spec_from_file_location(qualified, PKG_DIR / "arch_caps.py")
    module = importlib.util.module_from_spec(spec)
    sys.modules[qualified] = module
    spec.loader.exec_module(module)

scripts/gen_arch_support_matrix.py:238

• Write README.md explicitly as UTF-8; otherwise this can fail to encode the generated Unicode status symbols on non-UTF-8 default locales.

    if current != updated:
        README.write_text(updated)
        print(f"updated {README.relative_to(REPO_ROOT)}")

scripts/gen_arch_support_matrix.py:210

• This script generates Unicode symbols (✅/⚠️/◻️/❌). Using the platform default encoding can raise UnicodeEncodeError on systems where UTF-8 is not the default (notably some Windows setups). Read README.md explicitly as UTF-8.

    current = README.read_text()
    updated = splice(current, render(_load_arch_caps()))

[demandal25]

Suppressed comments in review 4983274571 — all three accepted, fixed in e256f0d.

• UTF-8 pinned on both the README read and write; verified --check exits 0 under LC_ALL=C LANG=C PYTHONUTF8=0.
• gfx950 SKUs reconciled toward the measurement: MI350X and MI355X are both gfx950, so the SKU lists were the incomplete half rather than the evidence being wrong. The published-image table further down is left alone — it records what that image was tested on.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.