From 0730dcb29f69aeca3b0f8332b260590017afe13e Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Sun, 8 Nov 2026 19:23:13 -0400 Subject: [PATCH 1/2] build: a gate for a declared-but-undefined Q4nxNpuForward member (the #1573 class) CI builds --target onebit only, because a full build links the NPU forward and wants the private ONEBIT_NPU_RT_DIR, so a header declaration without a definition passes every check and still breaks for anyone with a runtime -- which is exactly what happened to the 3-argument step_batch_embeds. -fsyntax-only cannot see it either: a missing definition is a link-time fact. tools/ci/npu_decl_check.py pairs the two lists by (name, arity): the direct members of class Q4nxNpuForward in npu/forward/include/q4nx_forward.h that need an out-of-line definition, against every Q4nxNpuForward::( in the tree. The arity is what makes it catch an overload (a bare-name check called step_batch_embeds defined because its 4-argument sibling exists). On this head it refuses exactly that symbol; with #1574's fix applied it reports 43 declared members, all defined. Two ctest rows, both device-free and runtime-free: the gate itself, and a self-test that drives the fixture pairs (missing overload, definition in a second translation unit, a comma inside <>). Refs #1575, #1573. --- CMakeLists.txt | 9 ++ tools/ci/npu_decl_check.py | 299 +++++++++++++++++++++++++++++++++++++ 2 files changed, 308 insertions(+) create mode 100755 tools/ci/npu_decl_check.py diff --git a/CMakeLists.txt b/CMakeLists.txt index 0d8a5f29f..e52b23dfd 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -682,6 +682,15 @@ if(Python3_Interpreter_FOUND) # only real pair verified on the first candidate, so the line never ran) and the residual tolerance it # accepts and refuses at. Fixtures are ~200 KB each and built from the rule, so they can be wrong on purpose. add_test(NAME fconst19_measure COMMAND ${Python3_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/fconst19_measure_test.py) + # A member declared in npu/forward/include/q4nx_forward.h and never defined keeps `main` green while a full + # `cmake --build` fails at link time (engine#1573: the 3-argument step_batch_embeds). CI cannot catch it -- + # .github/workflows/ci.yml builds `--target onebit` only, because a full build wants the private NPU runtime -- + # and `-fsyntax-only` cannot see a link-time fact. This pairs the two lists by (name, arity): device-free, no + # runtime, no build, milliseconds. + add_test(NAME npu_decl_check + COMMAND ${Python3_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tools/ci/npu_decl_check.py --check --root ${CMAKE_SOURCE_DIR}) + add_test(NAME npu_decl_check_self + COMMAND ${Python3_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tools/ci/npu_decl_check.py --self-test) # the new-model watcher's alert contract (offline: synthetic batches against the # committed registry, plus FastFlowLM's org listing and releases from the recorded # payloads under tests/fixtures/fflm/ — engine #588), so a regression cannot leave the diff --git a/tools/ci/npu_decl_check.py b/tools/ci/npu_decl_check.py new file mode 100755 index 000000000..6f4d8c48d --- /dev/null +++ b/tools/ci/npu_decl_check.py @@ -0,0 +1,299 @@ +#!/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. +"""Refuse a member of Q4nxNpuForward that is declared in the header and never defined (engine#1573, #1575). + +`main` was green while a full `cmake --build` failed at 92 %: `step_batch_embeds` had two overloads, only the +`HybridInputs` one was defined, and `npu/forward/embeds_equiv_probe.cpp` calls the other. CI cannot see it -- +`.github/workflows/ci.yml` builds `--target onebit` only, because a full build links the NPU forward and wants the private +`ONEBIT_NPU_RT_DIR` -- and `-fsyntax-only` cannot see it either, because a missing definition is a link-time fact, not a +syntax one. + +So this pairs the two lists by hand, at (name, arity), which is enough to catch that class and cheap enough to run on every +PR with no runtime, no device and no build: + +* declarations -- the direct members of `class Q4nxNpuForward` in the header that need a definition out of line: a body + written in the header (`{ ... }`), `= delete`, `= default` and `operator` are skipped, and so are the members of a nested + `struct`/`class`, which belong to that type rather than to the forward; +* definitions -- every `Q4nxNpuForward::(` in the tree, from `git ls-files`, so a definition in a second + translation unit still counts. + +Overloads are why the key carries the parameter count: `step_batch_embeds(3)` missing while `step_batch_embeds(4)` exists is +exactly the shape that broke, and a bare-name check would have called it defined. + +usage: + tools/ci/npu_decl_check.py --check [--root DIR] + tools/ci/npu_decl_check.py --self-test +""" +import argparse +import os +import re +import subprocess +import sys + +HEADER = "npu/forward/include/q4nx_forward.h" +CLASS = "Q4nxNpuForward" + +SKIP_STATEMENT = ("using ", "typedef ", "friend ", "template", "static_assert", "enum ", "class ", "struct ", + "union ", "operator") + + +def strip_code(text): + """Blank out comments and string/char literals, keeping every newline so line numbers survive.""" + out = [] + i, n = 0, len(text) + while i < n: + c = text[i] + two = text[i:i + 2] + if two == "//": + j = text.find("\n", i) + j = n if j < 0 else j + out.append(" " * (j - i)) + i = j + elif two == "/*": + j = text.find("*/", i + 2) + j = n if j < 0 else j + 2 + out.append("".join(ch if ch == "\n" else " " for ch in text[i:j])) + i = j + elif c in "\"'": + j = i + 1 + while j < n and text[j] != c: + j += 2 if text[j] == "\\" else 1 + j = min(j + 1, n) + out.append("".join(ch if ch == "\n" else " " for ch in text[i:j])) + i = j + else: + out.append(c) + i += 1 + return "".join(out) + + +def matching(text, start, open_ch, close_ch): + """Index of the bracket that closes the one at `start`, or -1.""" + depth = 0 + for i in range(start, len(text)): + if text[i] == open_ch: + depth += 1 + elif text[i] == close_ch: + depth -= 1 + if depth == 0: + return i + return -1 + + +def arity(params): + """How many parameters a parameter list holds: top-level commas + 1, with `()` and `(void)` being none.""" + params = params.strip() + if not params or re.fullmatch(r"void\s*", params): + return 0 + depth, count = 0, 1 + for ch in params: + if ch in "(<[{": + depth += 1 + elif ch in ")>]}": + depth -= 1 + elif ch == "," and depth == 0: + count += 1 + return count + + +def class_body(code): + """The text between `class Q4nxNpuForward {` and its closing brace, or None.""" + m = re.search(r"\bclass\s+" + CLASS + r"\b[^;{]*\{", code) + if not m: + return None + start = m.end() - 1 + end = matching(code, start, "{", "}") + return None if end < 0 else code[start + 1:end] + + +def declarations(code): + """[(name, arity, line)] for the direct members of the class that need an out-of-line definition.""" + body = class_body(code) + if body is None: + return None + offset = code.index(body) if body else 0 + found, depth, current = [], 0, [] + for idx, ch in enumerate(body): + if ch == "{": + depth += 1 + current.append(ch) + elif ch == "}": + depth -= 1 + current.append(ch) + elif ch == ";" and depth == 0: + found.extend(_declaration("".join(current), offset + idx - len(current) + 1)) + current = [] + else: + current.append(ch) + return found + + +def _declaration(statement, line_pos): + """One statement at class scope -> [(name, arity, line)] (empty when it is not a function declaration).""" + text = " ".join(statement.split()) + if not text or "(" not in text: + return [] + if any(text.startswith(k) or text.startswith("static " + k.strip()) for k in SKIP_STATEMENT) or "operator" in text: + return [] + paren = text.index("(") + if "=" in text[:paren] or "{" in text or "delete" in text or "default" in text: + return [] # a data member with an initialiser, or a definition written in the header + close = matching(text, paren, "(", ")") + if close < 0: + return [] + name = re.findall(r"[A-Za-z_]\w*", text[:paren]) + if not name: + return [] + return [(name[-1], arity(text[paren + 1:close]), 0)] + + +def definitions(code): + """{(name, arity)} for every `Q4nxNpuForward::(` the text defines or declares out of line.""" + found = set() + for m in re.finditer(r"\b" + CLASS + r"::([A-Za-z_]\w*)\s*\(", code): + open_at = m.end() - 1 + close = matching(code, open_at, "(", ")") + if close > 0: + found.add((m.group(1), arity(code[open_at + 1:close]))) + return found + + +def line_of(code, needle, hits): + """Line number of the n-th occurrence of `needle` (1-based), for the message.""" + start = 0 + for _ in range(max(hits, 1)): + at = code.find(needle + "(", start) + if at < 0: + return "?" + start = at + 1 + return code.count("\n", 0, at) + 1 + + +def check(root): + """The gate: print a refusal per declared-but-undefined member, and return the number of them.""" + header = os.path.join(root, HEADER) + try: + code = strip_code(open(header).read()) + except OSError as e: + print(f"npu_decl_check: cannot read {HEADER}: {e}") + return 1 + declared = declarations(code) + if declared is None: + print(f"npu_decl_check: no `class {CLASS}` in {HEADER}") + return 1 + + sources = subprocess.run(["git", "-C", root, "ls-files", "*.cpp", "*.cc"], capture_output=True, text=True) + if sources.returncode != 0: + print(f"npu_decl_check: git ls-files failed in {root}") + return 1 + defined = set() + for rel in sources.stdout.split(): + path = os.path.join(root, rel) + if not os.path.isfile(path): + continue # a submodule (third_party/llama.cpp) is a gitlink, not source we parse + try: + defined |= definitions(strip_code(open(path, errors="replace").read())) + except OSError: + continue + + missing = [(name, count) for name, count, _ in declared if (name, count) not in defined] + for name, count in missing: + plural = "" if count == 1 else "s" + print(f"npu_decl_check: {CLASS}::{name} ({count} parameter{plural}) is declared in {HEADER} and never defined" + f" -- a full build links it and fails, and CI does not link it at all (engine#1573)") + if not missing: + print(f"npu_decl_check: {len(declared)} declared member(s), all defined") + return len(missing) + + +SELF_HEADER = """class Q4nxNpuForward { +public: + bool plain(int a, int b); // needs a definition: 2 parameters + bool heavy(int a, int b, std::vector& c); // needs one: 3 (the #1573 shape) + void inline_body() const { return; } // written in the header: never looked for + void removed() = delete; // no definition expected + struct Nested { size_t bytes() const; }; // belongs to Nested, not to the forward +}; +""" + + +def self_test(): + """Fixture pairs: the gate must be red on the #1573 shape and green once the definitions exist.""" + import tempfile + bad = 0 + with tempfile.TemporaryDirectory() as tmp: + os.makedirs(os.path.join(tmp, "npu/forward/include")) + os.makedirs(os.path.join(tmp, "npu/forward/src")) + open(os.path.join(tmp, HEADER), "w").write(SELF_HEADER) + subprocess.run(["git", "init", "-q", tmp], check=False) + + def write_sources(body, second=""): + open(os.path.join(tmp, "npu/forward/src/q4nx_forward.cpp"), "w").write(body) + open(os.path.join(tmp, "npu/forward/src/other.cpp"), "w").write(second) + # --check reads `git ls-files`, so the fixture has to be in the index (same set CI sees) + subprocess.run(["git", "-C", tmp, "add", "-A"], check=False, capture_output=True) + + # (a) only the 3-parameter overload defined -> exactly `plain (2 parameters)` refused + write_sources("bool Q4nxNpuForward::heavy(int a, int b, std::vector& c) { return true; }\n") + import io + from contextlib import redirect_stdout + buf = io.StringIO() + with redirect_stdout(buf): + rc = check(tmp) + printed = buf.getvalue() + if rc != 1 or "plain (2 parameters)" not in printed or "heavy" in printed: + print(f"npu_decl_check --self-test: (a) expected one refusal for plain (2 parameters), got rc={rc}: {printed.strip()}") + bad += 1 + + # (b) the definition moved to a second translation unit -> green + write_sources("", "bool Q4nxNpuForward::plain(int a, int b) { return a == b; }\n" + "bool Q4nxNpuForward::heavy(int a, int b, std::vector& c) { return true; }\n") + buf = io.StringIO() + with redirect_stdout(buf): + rc = check(tmp) + if rc != 0: + print(f"npu_decl_check --self-test: (b) a definition in another .cpp must count, got rc={rc}: {buf.getvalue().strip()}") + bad += 1 + + # (c) a default argument and a nested `<...>` type in the signature still count their parameters right + open(os.path.join(tmp, HEADER), "w").write( + "class Q4nxNpuForward {\n bool f(std::map> m, int n = -1);\n};\n") + write_sources("bool Q4nxNpuForward::f(std::map> m, int n) { return n > 0; }\n") + buf = io.StringIO() + with redirect_stdout(buf): + rc = check(tmp) + if rc != 0: + print(f"npu_decl_check --self-test: (c) two parameters with a comma inside <> must pair, got rc={rc}: {buf.getvalue().strip()}") + bad += 1 + print(f"npu_decl_check --self-test: {bad} failure(s)") + return 1 if bad else 0 + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--check", action="store_true", help="pair the header's declarations with the tree's definitions") + ap.add_argument("--root", default=".", help="repository root for --check (default: .)") + ap.add_argument("--self-test", action="store_true") + args = ap.parse_args() + if args.self_test: + return self_test() + if args.check: + return 1 if check(os.path.abspath(args.root)) else 0 + ap.error("--check or --self-test") + + +if __name__ == "__main__": + sys.exit(main()) From 1c283235173f4a64a36760d67e4026ac651021f1 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Sun, 8 Nov 2026 19:23:48 -0400 Subject: [PATCH 2/2] docs/npu: the runtime page says which build CI links, and the gate that covers the gap --- docs/npu.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/npu.md b/docs/npu.md index 8e6a5fdec..01022b29f 100644 --- a/docs/npu.md +++ b/docs/npu.md @@ -1826,6 +1826,16 @@ cmake -B build -G Ninja -DONEBIT_NPU=ON -DONEBIT_NPU_RT_LIB=/libnpu_rt_api - The release builds the runtime from a pinned commit named in `config/npu-runtime.config` ([releases.md](releases.md#private-components)). +**A full build links every executable; public CI links one.** `.github/workflows/ci.yml` builds `--target onebit` only, because +that is the target that needs no runtime. The gap that leaves is narrow but real: a member declared in +`npu/forward/include/q4nx_forward.h` and never defined in a `.cpp` compiles, passes `-fsyntax-only` (a missing definition is a +link-time fact, not a syntax one), keeps every check green — and fails `cmake --build` for anyone who does have a runtime. That +is how `main` went red for full builds while CI stayed green on the 3-argument `step_batch_embeds` (engine#1573). ctest +`npu_decl_check` (`tools/ci/npu_decl_check.py`) closes it: it pairs the header's direct members against every +`Q4nxNpuForward::(` in the tree by **name and arity**, so a missing overload is refused by name instead of surfacing as a +92 %-through link error, and it needs no runtime, no device and no build. `npu_decl_check_self` drives the gate's own fixtures +(a missing overload, a definition in a second translation unit, a comma inside `<>`). + The NPU needs the `amdxdna` kernel driver. `third_party/xdna-driver` pins upstream [amd/xdna-driver](https://github.com/amd/xdna-driver) as the driver version the engine is checked against (the kernel's own copy also works); nothing from the pin is built into or shipped with