Skip to content
Closed
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
12 changes: 12 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1112,6 +1112,18 @@ 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)
# 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 <target>)` 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
${CMAKE_CXX_COMPILER} ${CMAKE_SOURCE_DIR}/npu/forward/include
Expand Down
54 changes: 54 additions & 0 deletions npu/forward/include/ops-dump.h
Original file line number Diff line number Diff line change
@@ -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 <cmath>
#include <cstdio>
#include <cstdlib>
#include <cstring>

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
9 changes: 9 additions & 0 deletions npu/forward/src/q4nx_forward.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
#include <chrono>
#include <cmath>
#include <cstdio>
#include "ops-dump.h"
#include "residual-dump.h"
#include <cstdlib>
#include <cstring>
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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);
Expand All @@ -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;
}

Expand Down
55 changes: 55 additions & 0 deletions tests/ops_dump_test.cpp
Original file line number Diff line number Diff line change
@@ -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 <cstdio>
#include <cstdlib>
#include <cstring>
#include <string>

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;
}
Loading