[adriadam10]

What

The hardware oracle proposed in #843: tools/hw-oracle/ runs a body of RDNA assembly on a local AMD GPU, one input row per lane, and prints the 16 output dwords of each lane. It is meant for measuring instruction semantics before implementing them and for pinning measured rows in tests/execution/. Usage, kernel ABI and limits are in docs/dev/HW_ORACLE.md.

• oracle.c loads a code object through the ROCm HSA runtime and dispatches it on /dev/kfd. oracle --target prints the GPU's gfx name.
• template.s is the kernel wrapper: v4-v7 hold the inputs and v10-v25 are stored. It works in wave32 and wave64, gives 4 KiB of LDS, and takes the FLOAT_MODE (IEEE, f32/f16 denormals) per run.
• hw_oracle.py builds the oracle once, assembles the body for the detected target with clang + ld.lld, and runs it. It works from the command line or as run(body, rows, ...) from Python.

It isn't tied to a distribution. The runtime comes from ROCM_PATH, /opt/rocm or the system paths (libhsa-runtime-dev, rocm-runtime-devel, hsa-rocr), and the target is read from the GPU. Nothing is registered in CMake or CI: CI has no AMD GPU.

Draft until @boykopovar decides on #843. If he'd rather not have the tool in the repository, I'll close this.

Tested

Linux (CachyOS), Radeon 660M (RDNA2, gfx1035), HSA runtime from the Arch packages under ROCM_PATH. Checked wave32 and wave64, IEEE=0 (the f16 example in the doc keeps the NaN payload), coarse (LDS and float atomics kernel), extra (SGPR load past the rows), and 2500 rows split over 3 dispatches. Five of the kernels I measured with for the shader PRs (division, f16, relative moves, LDS atomics) give bit-identical results with this version and with the one I have used since 2026-10-03 (#264, #318, #320), on 1160 rows each (64 for the LDS one, which only addresses 64 lanes). Not tested on RDNA3 or on other distributions.

Checklist

• Based on current main; no other open PR implements the same functions
• One topic per PR; follow-ups go in a new PR
• No comments in code except technical debt
• Unimplemented paths throw (NotImplemented_nid_no_patch); silent stubs are listed in TechnicalDebt
• No notes, investigation .md files or images added to the repository (attach them to this PR)
• New third-party code is a submodule built from source
• Generic behaviour, not specific to one title
• Depends on: none
• AI-assisted: yes

[adriadam10]

boykopovar agreed on #843 (Discord): merging. Based on current main, CI green.