Skip to content

Kernels: fixed HIP compilation-unit id, so code objects don't depend on the build folder - #6

Merged
phantoslayer21 merged 1 commit into
mainfrom
proposal/kernel-cuid
Nov 13, 2026
Merged

phantoslayer21 merged 1 commit into
mainfrom
proposal/kernel-cuid

Conversation

@phantoslayer21

@phantoslayer21 phantoslayer21 commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

What

clean/runner/build.py passes a fixed compilation-unit id (-cuid=wg_<output name>) to every HIP device compile. The id is the output file's base name, with characters outside [A-Za-z0-9_] replaced by _, so it has no path in it. The module docstring now shows the flag, and a small CPU unit test (clean/tests/test_build_cuid.py) checks the command. BUILDING.md, "Comparing kernels with a release", says what to compare.

The branch is one commit on top of main (the two earlier commits are squashed, so the history carries only the corrected message).

Why

Without -cuid, clang derives each code object's compilation-unit id itself. That id sets the __hip_cuid_... symbol name in the code object, so a build without -cuid can't be compared with another build by file hash. With a fixed id the symbol name doesn't depend on the build folder.

Measured

Built from this change with the BUILDING.md 3.3 command, code objects only (--extra-archs gfx1200 --no-model-k --no-runtime), HIP SDK 7.2:

  • Two different build folders: all 54 code objects (gfx1201 and gfx1200) are byte-identical.
  • Against release 0.6.0 (71 files: these 54, plus 17 gfx1201.* files that the runtime step copies unchanged from them): all 54 have identical .text and .note sections and the same section list. .rodata is identical in 52. In post_w64__orig.co (both targets), .rodata moves by 64 bytes, and its 93 kernel descriptors differ only in their code-entry offset, by exactly that amount. No file is byte-identical to 0.6.0, because 0.6.0 was built without -cuid.

Because of that last point, BUILDING.md tells you to compare 0.6.0 by .text and .note, not by .rodata or the whole file. Builds made with -cuid can be compared file by file.

Not measured: DXIL, kernels.json and the DX12 manifest (so BUILDING.md makes no new claim about them) and model K code objects (the build used --no-model-k).

Testing

  • The comparisons above. The code objects aren't run: this change touches only the compile command and symbol names.
  • clean/tests/test_build_cuid.py runs on the CPU, executes nothing and uses dummy compiler and ROCm paths. It asserts that device_command(...) puts -cuid=wg_<name> in the command, that the id is the same for two different output folders and follows the output file's name, and that it contains no path. It passes locally with Python 3.12.
  • CI runs the CPU Python tests, including this new unit test, and the CPU builds. It does not build or compare kernels or code objects, so the byte-identity results above come from the manual comparisons, not from CI. It runs on this pull request once the CI workflow is on main (Community setup #5).

Checklist

  • Every commit has a Signed-off-by: line.
  • One new source file, the unit test, which carries SPDX-License-Identifier: MIT and is this project's own; the other changed files are this project's own too (clean/runner/build.py, BUILDING.md).
  • No files of the original upscaler, no model data, game files, captures, screenshots or binaries; no paths, user or machine names.
  • No new third-party component.
  • Kernel change meant to be bit-identical: the comparison is shown above.

…ompile

device_command in clean/runner/build.py now adds -cuid=wg_<output file name> to every
HIP device compile (the id is the output file's base name, with characters outside
[A-Za-z0-9_] replaced by "_", so it has no path in it). Without -cuid, clang derives the
id itself; the id sets the __hip_cuid_... symbol name in the code object, and with a
fixed id that name does not depend on the build folder. The gfx1201 and gfx1200 builds
of one kernel get the same id.

Measured (HIP SDK 7.2, BUILDING.md 3.3 command, code objects only: --extra-archs
gfx1200 --no-model-k --no-runtime):
- built in two different folders, all 54 code objects are byte-identical;
- against release 0.6.0, which was built without -cuid, no file is byte-identical. All
  54 have identical .text and .note sections and the same section list. .rodata is
  identical in 52; in post_w64__orig.co (both targets) it moves by 64 bytes, and its
  93 kernel descriptors differ only in their code-entry offset, by that amount.
Not measured: DXIL or kernels.json, model K code objects. The code objects were not run.

BUILDING.md, "Comparing kernels with a release": builds made with -cuid compare file
by file; for 0.6.0 compare the .text and .note sections, not .rodata or the whole file.
The module docstring of build.py shows the flag. A CPU unit test,
clean/tests/test_build_cuid.py, checks that the command carries -cuid=wg_<name>, the
same for any output folder, with no path in it.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
@phantoslayer21
phantoslayer21 marked this pull request as ready for review November 13, 2026 15:31
@phantoslayer21
phantoslayer21 merged commit d28f942 into main Nov 13, 2026
2 checks passed
@phantoslayer21
phantoslayer21 deleted the proposal/kernel-cuid branch November 13, 2026 15:54
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.

1 participant