Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -444,6 +444,9 @@ add_python_test(pr_carry_check_self ${CMAKE_SOURCE_DIR}/tools/ci/pr_carry_check.
# branch that deletes a reviewed class passes it -- measured on #2021, where 41 classes became 40 and --check-gaps
# still printed "none of the 41 reviewed significant classes is mapped". A test row for the three arms that do see it.
add_python_test(registry_loss_check_test ${CMAKE_SOURCE_DIR}/tests/registry_loss_check_test.py)
# engine#2406 puts "audit those on a pin bump" on the f16 ratchet's green line; this is that audit
# for the HIP add-on's kernels, which the ratchet cannot see (it walks *.loom).
add_python_test(hip_f16_audit_self ${CMAKE_SOURCE_DIR}/tools/ci/hip_f16_audit.py --self-test)
# engine#2398: the stale-branch test, which `tests_referenced` refuses to leave unregistered -- a test no
# runner names is a test nobody runs.
add_python_test(branch_stale_check_test ${CMAKE_SOURCE_DIR}/tests/branch_stale_check_test.py)
Expand Down
194 changes: 194 additions & 0 deletions tools/ci/hip_f16_audit.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
#!/usr/bin/env python3
# Copyright 2026 bong-water-water-bong
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""hip_f16_audit.py -- the f16 properties `hrx_f16_narrowing` enforces, over the HIP add-on's kernels.

`tools/ci/hrx_f16_narrowing.py` walks the Loom corpus (`corpus.rglob("*.loom")`) and cannot see the add-on,
whose kernels live in the gpu-kernels repo as `.hip`/`.h`. A gpu-kernels pin bump therefore adds kernels that
no check reads -- engine#2406 put that on the ratchet's green line as *"audit those on a pin bump"*, which was
done by hand twice on 2026-11-14 (engine#2405's 1,210 new lines, gpu-kernels#76's `q41_decode.hip`). This is
that audit, mechanised.

Two properties, the same two the Loom ratchet counts:

narrowing -- an f32 value written into f16 (`__float2half*`, `(half)x`, `half(x)`)
accumulator -- an f16 accumulator (`half acc`, `__half acc`, `half sum`, `half_t acc`)

A narrowing is not automatically a defect: writing a block's `d` scale into a q4_0 block is the format, and
`set_rows_q4_0.hip` does exactly that. An **f16 accumulator is** the defect the Loom ratchet exists to prevent,
because it folds rounding into a sum that grows with the key count. So narrowing is reported per file and an
accumulator fails the audit.

Usage:
hip_f16_audit.py --dir <gpu-kernels checkout>
hip_f16_audit.py --dir … --json
hip_f16_audit.py --self-test

Exit 0 no f16 accumulator (the table is still printed), 1 one or more, 2 the tree could not be read (which is
not a pass -- the same rule as the ratchet: `cannot tell` never reads as clean).
"""

import argparse
import json
import re
import sys
from pathlib import Path

KERNEL_SUBDIR = Path("addons/hip-hrx/kernels")

# `__float2half`, `__float2half_rn`, `(half)v`, `half(v)`. Deliberately not `half x = ...`, which declares.
NARROWING = re.compile(r"__float2half\w*\s*\(|\(\s*(?:__)?half\s*\)\s*[A-Za-z_(]|\b(?:__)?half\s*\(\s*[A-Za-z_]")
# an accumulator declared in f16: `half acc`, `__half acc =`, `half_t acc`, and `acc` declared as such.
# `half`, `__half`, `half_t`, `_Float16`, and the vector spellings these kernels actually use
# (`half16`/`half8`/`half2`, `typedef _Float16 half16 __attribute__((ext_vector_type(16)))`). Measured on
# gpu-kernels 96593660718d: the first version matched only the scalar spellings, and `glm_mla_decode.hip`
# declares its operands as `half16` -- an accumulator written that way would have been missed entirely.
ACCUMULATOR = re.compile(r"\b(?:(?:__)?half\w*|_Float16)\s+(?:acc|accum|sum|total|dot|partial)\w*")


COMMENTS = re.compile(r"//[^\n]*|/\*.*?\*/", re.S)


def audit_file(path):
raw = path.read_text(encoding="utf-8", errors="replace")
# Blank the comments rather than deleting them, so reported line counts stay true. Measured: the first run
# of this tool flagged `kquant_tokens_q8.hip:181`, which is the sentence "sends half of them and keeps the
# other half (by bit M of its lane ...)" -- prose, matched by the `half (` pattern.
text = COMMENTS.sub(lambda m: " " * len(m.group(0)), raw)
narrowings = [m.group(0).strip() for m in NARROWING.finditer(text)]
accumulators = sorted(set(m.group(0).strip() for m in ACCUMULATOR.finditer(text)))
return {"file": path.name, "narrowings": len(narrowings), "accumulators": accumulators,
"lines": text.count("\n") + 1}


def audit(root):
kernels = Path(root) / KERNEL_SUBDIR
if not kernels.is_dir():
return None
rows = [audit_file(p) for p in sorted(kernels.glob("*.hip"))] + \
[audit_file(p) for p in sorted(kernels.glob("*.h"))]
return rows


def report(rows, as_json):
if as_json:
print(json.dumps(rows, indent=1))
else:
for row in rows:
acc = ", ".join(row["accumulators"]) if row["accumulators"] else "-"
print(f" {row['file']:34} {row['lines']:5} lines narrowings {row['narrowings']:3} "
f"f16 accumulators {acc}")
bad = [row for row in rows if row["accumulators"]]
return bad


def self_test():
import tempfile
problems = []

def chk(want, got, what):
if want != got:
problems.append(f"{what}: want {want!r}, got {got!r}")

with tempfile.TemporaryDirectory() as tmp:
kernels = Path(tmp) / KERNEL_SUBDIR
kernels.mkdir(parents=True)
# the format case: one narrowing, no accumulator (set_rows_q4_0.hip's block scale)
(kernels / "format.hip").write_text(
"const float d = vmax / -8.0f;\n"
"*reinterpret_cast<uint16_t *>(dst) = __half_as_ushort(__float2half_rn(d));\n")
# the clean case: f32 accumulation
(kernels / "clean.hip").write_text(
"float acc[4] = {0, 0, 0, 0};\nacc[k] = fmaf(d, q, acc[k]);\n")
# the defect case
(kernels / "f16acc.hip").write_text(
"__half acc = 0;\nfor (int i = 0; i < n; ++i) acc = acc + __float2half(v[i]);\n")
rows = audit(tmp)
chk(3, len(rows), "three kernels audited")
by = {row["file"]: row for row in rows}
chk(1, by["format.hip"]["narrowings"], "the block scale is one narrowing")
chk([], by["format.hip"]["accumulators"], "a narrowing alone is not an accumulator")
chk(0, by["clean.hip"]["narrowings"], "fmaf accumulation narrows nothing")
chk([], by["clean.hip"]["accumulators"], "a float accumulator is not f16")
chk(["__half acc"], by["f16acc.hip"]["accumulators"], "the actual defect is found")
bad = [row["file"] for row in rows if row["accumulators"]]
chk(["f16acc.hip"], bad, "exactly the one defect file fails")

# the vector spelling: glm_mla_decode.hip declares its operands as `half16`, and an accumulator written
# that way must fail too -- the first version of this regex matched only the scalar spellings.
(kernels / "vecacc.hip").write_text(
"typedef _Float16 half16 __attribute__((ext_vector_type(16)));\n"
"half16 acc = (half16) 0.0f;\nacc = acc + v;\n")
rows = audit(tmp)
by = {row["file"]: row for row in rows}
chk(["half16 acc"], by["vecacc.hip"]["accumulators"], "a half16 accumulator is found")
# and an operand declared half16 is NOT an accumulator: the real kernel is correct
(kernels / "vecoperand.hip").write_text(
"float8 s = (float8) 0.0f;\nhalf16 a = load();\ns = wmma(a, b, s);\n")
rows = audit(tmp)
by = {row["file"]: row for row in rows}
chk([], by["vecoperand.hip"]["accumulators"], "a half16 operand with a float8 accumulator is clean")

# prose is not a narrowing: the first real run flagged a comment saying "half (by bit M ...)"
(kernels / "comment.hip").write_text(
"// sends half of them and keeps the other half (by bit M of its lane id)\n"
"/* a block comment mentioning half (too) */\nfloat x = 0;\n")
rows = audit(tmp)
by = {row["file"]: row for row in rows}
chk(0, by["comment.hip"]["narrowings"], "a comment mentioning 'half (' is not a narrowing")
chk(6, len(rows), "every file in the tree is audited (4 originals + 2 vector cases)")

chk(None, audit("/nonexistent-path-xyz"), "an unreadable tree is None, not an empty pass")

if problems:
for problem in problems:
print("FAIL " + problem)
return 1
print("hip_f16_audit self-test: ok")
return 0


def main(argv):
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument("--dir", help="a gpu-kernels checkout (must contain addons/hip-hrx/kernels)")
ap.add_argument("--json", action="store_true")
ap.add_argument("--self-test", action="store_true")
a = ap.parse_args(argv)
if a.self_test:
return self_test()
if not a.dir:
print("hip_f16_audit: --dir is required (the gpu-kernels checkout to audit)", file=sys.stderr)
return 2
rows = audit(a.dir)
if rows is None:
print(f"hip_f16_audit: {Path(a.dir) / KERNEL_SUBDIR} is not a directory - cannot tell, "
f"and that is not a pass", file=sys.stderr)
return 2
bad = report(rows, a.json)
if bad:
for row in bad:
print(f"FAIL hip_f16_audit: {row['file']} accumulates in f16 ({', '.join(row['accumulators'])}) -- "
f"the Loom ratchet refuses this in a .loom body and it cannot see this file",
file=sys.stderr if a.json else sys.stdout)
return 1
if a.json:
return 0 # --json is machine-readable: the summary would make the output unparseable
print(f"hip_f16_audit: {len(rows)} kernel file(s), no f16 accumulator; "
f"{sum(row['narrowings'] for row in rows)} narrowing(s), which are format writes unless a file says otherwise")
return 0


if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
Loading