Add gfx1250/MI450 target reference and AMD kernel-compiler survey

[gstoner]

Depends on #475 — four links in this PR point at docs/audit/compiler/TILESIGHT_ASSESSMENT.md, which lands there. Merge #475 first, or expect those four to dangle until it does. The dependency is substantive, not accidental: two of this PR's findings are direct answers to the mock-cost-model gap #475 records.

Motivation

Two questions drove this: what is gfx1250 (MI450) actually, and what have AMD's own kernel compilers already solved that we are about to re-derive?

The tree's gfx1250 entries were explicitly marked PROVISIONAL — placeholders copied from RDNA because no ISA had been consulted. And we had never read AMD's kernel compilers (as opposed to kernel libraries) at source level, despite building the same kind of thing.

Documentation only. No code changes.

Technical Details

backend/rocm/GFX1250_MI450_COMPILER_REFERENCE.md

Target facts derived from LLVM tablegen, ROCm library source, and the on-machine assembler rather than vendor prose. Every claim carries a provenance marker ([V] source / [A] locally assembled / [S] AMD prose / [I] inference), §0 gives the resolution order when sources disagree — they do — and §10 gives commands to re-derive everything without AMD hardware.

Findings that correct or extend current assumptions:

Finding	Current tree
FeatureClusters is on gfx1250/1251, not gfx950	rocm_target.py asserts the exact opposite. Latent — supports_cluster_mode() has no codegen consumer — but inverted.
LDS 327680 B, 1024 addressable VGPRs	65536 / 256, both marked PROVISIONAL. The VGPR figure matters: rocm_tiling.py treats the register budget as the dominant tiling lever.
gfx1250 vs gfx1251 are complementary SKUs — same WMMA instruction 4x apart, FP64 6x apart the other way	_GFX1250_CLASS_ARCHES treats them as one class. Correct for ABI, wrong for any cost model.
Async/tensor waits are never auto-inserted by LLVM — they come from llvm.amdgcn.{asyncmark,wait.asyncmark}, and a too-large index yields no wait, not a conservative one	ROCM_WaitTokenOp has no immediate operand, so it can only express a full drain.
AMD clusters are multicast-into-own-LDS + a barrier, shader-engine scoped, with no distributed shared address space	An NVIDIA CGA kernel that reads a peer CTA's shared memory will not lower.

Also covers the WMMA co-execution hazard (LLVM's exact wait-state table — going through LLVM handles it, hand-emitted asm does not), TDM's descriptor contract, device-initiated SDMA, and the UALink/IFoE fabric.

compiler/AMD_KERNEL_COMPILER_SURVEY.md

StinkyTofu, rocRoller, Composable Kernel and hipBLASLt read for transferable architecture. §6 ranks 21 items take/skip. The two most useful are structural:

• rocRoller's observer scheduling (peek/modify/observe) gives a cost query before commitment — the primitive a measured arbiter needs and that a pass pipeline cannot express.
• CK derives vector width, access count and traversal order from a distribution encoding, rather than having a kernel author write them. Of four concerns, only two are authored.

It also records two static, device-free quality metrics found in production AMD code: a step-distance locality histogram, and a bank-conflict analyzer that computes N-way conflict from a descriptor alone. Both bear directly on the mock-cost-model finding in #475 — and the second is unit-testable ("this descriptor is conflict-free for a warp-wide access on N banks") with no device.

Convergence worth noting: StinkyTofu's Logical-IR → Asm-IR split is Decision #19 arrived at independently, and its "new arch = a directory of .def files, no C++ edits" is Decision #28's plugin seam done as data — which also gives us a falsifiable acceptance test for our own seam.

APPLE_AUDIT.md — backlog item 8

The follow-on the survey implies. Apple is the only backend that executes broadly enough to say whether such a metric predicts anything, so the action is to calibrate one against recorded latency, not to add one. A metric that cannot rank Apple kernels should not be trusted to rank ROCm or NVIDIA kernels we cannot measure.

Test Plan

• tests/unit/test_audit_docs.py — frontmatter / lifecycle gate for authored audit docs
• scripts/check_generated_docs.sh — generated-doc drift gate
• Manual: all relative links resolve; all internal §N.M cross-references resolve; all referenced in-tree source paths exist

Test Result

• test_audit_docs.py: 8 passed
• Generated docs: 24 in sync
• Links/refs: all resolve, except the four TILESIGHT_ASSESSMENT.md references noted at the top, which resolve once Add calibrated target performance parameters and block rasterization order #475 lands

Both documents are audit_role: reference and state explicitly that they are not status surfaces. No counts are copied into prose (Decision #26).

Risk level

None. Documentation only — no code, no C++, no build files, no generated docs regenerated.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 84076eb11f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".