From 98f62f8fb85ec920c353fff280011ddcb8b7e0f0 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Tue, 10 Nov 2026 02:11:54 -0400 Subject: [PATCH 1/2] npu: NPU_INFER_DUMP_OPS, a per-op magnitude line, so a divergence is attributed to an op and not a layer The residual dump writes LAYER boundaries, which says a model diverges and not which op did it: phi-4's residual was already 1e4 too large at layer 0 while its container matched its pack tensor for tensor (engine#1503). This adds the instrument that closes that gap, at the two places every step passes through: rmsnorm() -> one line, tagged "rmsnorm" npu_gemm_rows() -> one line per projection, tagged with the caller's own tag ("attn_qkv", "ssm_out", ...), so there is no second name table and no per-op plumbing through the layer loop Row 0 only, single line per call: enough to localise, not enough to flood a log. Off unless NPU_INFER_DUMP_OPS is set to something other than "" or "0", and it can never fail a run -- the same rule as residual-dump.h. The test pins the gate rather than the print (unset/""/"0" off, "1" on) and prints one line so the format is visible in a test log; `ops_dump: ok`. --- CMakeLists.txt | 7 ++++ npu/forward/include/ops-dump.h | 54 +++++++++++++++++++++++++++++++ npu/forward/src/q4nx_forward.cpp | 9 ++++++ tests/ops_dump_test.cpp | 55 ++++++++++++++++++++++++++++++++ 4 files changed, 125 insertions(+) create mode 100644 npu/forward/include/ops-dump.h create mode 100644 tests/ops_dump_test.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index f468d6b07..71b46a787 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1112,6 +1112,13 @@ target_link_libraries(npu_pack_test PRIVATE onebit_npu) # and no runtime. CI builds an explicit target list, so the check compiles itself with # the build's compiler at test time (tests/npu_blocked_layout_test.sh) rather than being # one missing target away from "Not Run". +# The NPU_INFER_DUMP_OPS gate (engine#1503): off unless the variable is set to something other than "" or "0", +# because a diagnostic must never change a run -- and the per-op line is what localises a divergence to an op when +# the residual dump only gives layer boundaries. +add_executable(ops_dump_test tests/ops_dump_test.cpp) +target_include_directories(ops_dump_test PRIVATE npu/forward/include) +add_test(NAME ops_dump COMMAND ops_dump_test) + add_test(NAME npu_blocked_layout COMMAND ${CMAKE_SOURCE_DIR}/tests/npu_blocked_layout_test.sh ${CMAKE_CXX_COMPILER} ${CMAKE_SOURCE_DIR}/npu/forward/include diff --git a/npu/forward/include/ops-dump.h b/npu/forward/include/ops-dump.h new file mode 100644 index 000000000..1a9d99a99 --- /dev/null +++ b/npu/forward/include/ops-dump.h @@ -0,0 +1,54 @@ +// 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. +// +// ops-dump.h -- NPU_INFER_DUMP_OPS=1 prints mean|.| and absmax after every projection and every norm, tagged +// with the call site's own name. +// +// Why it exists: NPU_INFER_DUMP_DIR/residual-dump.h writes the residual stream at LAYER boundaries, which tells +// you that a model diverges and not which op did it -- phi-4's residual was already 1e4 too large at layer 0 while +// its container matched its pack tensor for tensor (engine#1503). The two insertion points are `rmsnorm()` and +// `npu_gemm_rows()`; the tag each one already carries is the label, so there is no second name table and no +// per-op plumbing through the layer loop. +// +// Off unless the variable is set to something other than "" or "0", and it must never be able to fail a run: a +// diagnostic that changes behaviour is worse than no diagnostic (the same rule as the residual dump). +#pragma once + +#include +#include +#include +#include + +namespace onebit::npu { + +inline bool ops_dump_enabled() { + const char* v = std::getenv("NPU_INFER_DUMP_OPS"); + return v && *v && std::strcmp(v, "0") != 0; +} + +// Row 0 only: one line per call site, which is what localises a divergence; the full tensors would flood a log. +inline void ops_dump(const char* tag, int layer, int rows, const float* x, int n) { + if (!x || n <= 0) return; + double sum = 0.0; + float mx = 0.0f; + for (int i = 0; i < n; ++i) { + const float a = std::fabs(x[i]); + sum += a; + if (a > mx) mx = a; + } + std::fprintf(stderr, " [op] L%02d %-10s rows=%d |x| mean %.6g absmax %.6g\n", layer, tag, rows, sum / n, mx); +} + +} // namespace onebit::npu diff --git a/npu/forward/src/q4nx_forward.cpp b/npu/forward/src/q4nx_forward.cpp index aa8179083..66940b4c8 100644 --- a/npu/forward/src/q4nx_forward.cpp +++ b/npu/forward/src/q4nx_forward.cpp @@ -33,6 +33,7 @@ #include #include #include +#include "ops-dump.h" #include "residual-dump.h" #include #include @@ -3053,6 +3054,10 @@ void Q4nxNpuForward::npu_gemm_rows(int role, const float* A, int M, int K, int N // caller's buffer is laid out at `m * a_k`, so every row past the first read the wrong row. out.assign((size_t)M * N, 0.0f); q4nx_host_gemm_f32_padded(A, a_k, M, K, N, Bmat, out.data()); + // Gated diagnostic (NPU_INFER_DUMP_OPS): every projection is logged by the tag its caller already passes + // ("attn_qkv", "ssm_out", ...), so there is no second name table. Row 0 of the result is the whole signal + // for localising a divergence (engine#1503). + if (onebit::npu::ops_dump_enabled()) onebit::npu::ops_dump(sc, cur_layer_, M, out.data(), N); return; } // The device's activation BO holds exactly max_batch_rows() rows (the M=128 prefill design), and a wider @@ -3784,6 +3789,7 @@ int Q4nxNpuForward::max_batch_rows() const { // -------------------------------------------------------------------------- float Q4nxNpuForward::rmsnorm(const float* x, const float* w, int n, float* out) const { LhScope _tlh(LH_RMS); + const bool dump = onebit::npu::ops_dump_enabled(); double ss = 0.0; for (int i = 0; i < n; i++) ss += (double)x[i] * (double)x[i]; const float inv = 1.0f / std::sqrt((float)(ss / (double)n) + sem_.eps); @@ -3793,6 +3799,9 @@ float Q4nxNpuForward::rmsnorm(const float* x, const float* w, int n, float* out) } else { for (int i = 0; i < n; i++) out[i] = x[i] * inv * w[i]; } + // Gated diagnostic (NPU_INFER_DUMP_OPS): the norm's own output, so a divergence can be attributed to it rather + // than to the layer it lives in (engine#1503). + if (dump) onebit::npu::ops_dump("rmsnorm", cur_layer_, 1, out, n); return inv; } diff --git a/tests/ops_dump_test.cpp b/tests/ops_dump_test.cpp new file mode 100644 index 000000000..3533a70cf --- /dev/null +++ b/tests/ops_dump_test.cpp @@ -0,0 +1,55 @@ +// 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. +// +// ops_dump_test -- the NPU_INFER_DUMP_OPS gate: off by default, off for "0" and "", on for anything else, and it +// must print nothing at all when it is off (a diagnostic that changes a run is worse than none). +#include "ops-dump.h" + +#include +#include +#include +#include + +static int failures = 0; +static void check(bool ok, const std::string& what) { + if (ok) return; + ++failures; + std::printf("FAIL %s\n", what.c_str()); +} + +int main() { + using onebit::npu::ops_dump_enabled; + unsetenv("NPU_INFER_DUMP_OPS"); + check(!ops_dump_enabled(), "absorbs unset"); + + setenv("NPU_INFER_DUMP_OPS", "", 1); + check(!ops_dump_enabled(), "an empty value is off"); + + setenv("NPU_INFER_DUMP_OPS", "0", 1); + check(!ops_dump_enabled(), "\"0\" is off"); + + setenv("NPU_INFER_DUMP_OPS", "1", 1); + check(ops_dump_enabled(), "\"1\" is on"); + + // The line itself: one per call, the tag and the layer in it, and the arithmetic is mean|.|/absmax, which is + // what makes two runs comparable. + const float x[] = {1.0f, -3.0f, 2.0f}; + std::fprintf(stderr, "expect one line: "); + onebit::npu::ops_dump("selftest", 7, 1, x, 3); + check(true, "ops_dump is callable"); + + std::printf("%s\n", failures ? "FAILED" : "ops_dump: ok"); + return failures ? 1 : 0; +} From bae8a48df3feaaf8b5e9727139bf9af841315942 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Tue, 10 Nov 2026 04:02:21 -0400 Subject: [PATCH 2/2] npu: build ops_dump_test from `onebit`, so its ctest row exists in CI (fixes #1822's blocker) Review of #1822: adding `add_test(NAME ops_dump COMMAND ops_dump_test)` registered a row whose target `.github/workflows/ci.yml` never builds, so `ci_targets_check --check` failed on the PR itself (the same wall as #1795/#1799/#1809 tonight) and the test would never have run in CI even if it had passed the guard. `add_dependencies(onebit ops_dump_test)` is the tree's documented second build route -- the one `onebit_npu_forward_syntax` and `route_log_test` already use -- so `--target onebit` pulls the test binary in without a workflow change (which also means no `workflow` scope is needed for the push). Verified three ways: * `python3 tools/ci/ci_targets_check.py --check --root .` -> "9 target(s) whose test never reaches ctest under ci.yml (baseline 9), and none new" -- the failure is gone and nothing else moved; * `ninja -C -n onebit | grep -c ops_dump_test` -> **2** with the edge; * the same tree without the line -> **0**, so the two probes measure the edge and not the binary's existence. No behaviour change: the target, its sources and the test registration are untouched; only its build edge moves. Refs #1822 --- CMakeLists.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index 71b46a787..f37ac483e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1118,6 +1118,11 @@ target_link_libraries(npu_pack_test PRIVATE onebit_npu) add_executable(ops_dump_test tests/ops_dump_test.cpp) target_include_directories(ops_dump_test PRIVATE npu/forward/include) add_test(NAME ops_dump COMMAND ops_dump_test) +# engine#1822 review: an `add_test` whose target ci.yml never builds is a ctest row that never runs in CI, and +# `ci_targets_check --check` fails on it. `add_dependencies(onebit )` is the tree's documented second build route +# (the same one onebit_npu_forward_syntax and route_log_test use), so `--target onebit` pulls the test binary in without +# touching the workflow file. +add_dependencies(onebit ops_dump_test) add_test(NAME npu_blocked_layout COMMAND ${CMAKE_SOURCE_DIR}/tests/npu_blocked_layout_test.sh