From b1e05e5b2cc54993971d3ab091c9472e238f5f16 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Tue, 10 Nov 2026 03:11:07 -0400 Subject: [PATCH] npu: the head image's cache key, because the SAME container packs differently under different kernel sets (engine#1716) Reading `run_lm_head` corrected my own design on #1716: the image's geometry does not come from the container. int i_qkv = -1; // widest design with K == kpad_ const int T = designs_[i_qkv].N; // <- the KERNEL SET's tile width const size_t tile_elems = (size_t)kpad_ * (size_t)T; lctx.packB_into(*pw.bo, bt.data(), kpad_, T, ...); // and the design's `blocked` flag changes the byte order so one container packs to a DIFFERENT image under `kernels-h4096-b8` than under a non-blocked set. A key that omitted kpad, T or blocked would serve one kernel set's image to another -- and since the acceptance test is a correlation, the wrong image would still look plausible, which is exactly the class of failure this contract exists to make impossible. So the key is a digest over {format version, kpad, T, blocked, head-hash}, and the file name is that digest: a cache written by one run is found by the next, and two kernel sets cannot share one entry. 4 arms, device-free, in `npu_design_grid_test` (94 ok lines total): each of the four facts changes the digest individually; the name is stable for the same key; and it CHANGES when T changes. `tools/copyright.py --check` rc 0. Still the format and the key only: the cache itself (first-serve fill, bounded-sample verification inside `run_lm_head` where `kpad_`/`T` are in scope, and the `npu-pack import --kernels` pre-warm) is the next slice. --- npu/forward/include/q4nx_head_image.h | 26 ++++++++++++++++++++++++++ npu/forward/src/q4nx_head_image.c | 25 +++++++++++++++++++++++++ tests/npu_design_grid_test.c | 21 +++++++++++++++++++++ 3 files changed, 72 insertions(+) diff --git a/npu/forward/include/q4nx_head_image.h b/npu/forward/include/q4nx_head_image.h index 56d292261..c3fc9ff87 100644 --- a/npu/forward/include/q4nx_head_image.h +++ b/npu/forward/include/q4nx_head_image.h @@ -56,6 +56,32 @@ int q4nx_head_image_read(const char *path, int8_t *codes, int codes_n, float *sc // The hash the writer would compute, so a caller that built an image itself can compare against a file it read. uint64_t q4nx_head_image_hash(const int8_t *codes, const float *scales, int kd, int nd); +// The cache KEY (engine#1716, from reading run_lm_head): a head image is only valid for one combination of the kernel-set +// geometry and the container's head bytes, because the forward packs with +// +// const int T = designs_[i_qkv].N; // the widest design with K == kpad_ +// const size_t tile_elems = (size_t)kpad_ * (size_t)T; +// lctx.packB_into(bo, bt.data(), kpad_, T, ...); // and the design's `blocked` flag changes the byte order +// +// so the SAME container packs to a DIFFERENT image under a different kernel set. A key that omitted `kpad`, `T` or +// `blocked` would serve one set's image to another -- and the aggregate correlation would still look plausible, which is +// the failure this whole contract exists to make impossible. +// +// The key is a 64-bit digest of exactly those four facts, one of which is a digest of the head bytes themselves. +typedef struct { + uint32_t kpad; // K padded to the kernel grid (the BO's row count) + uint32_t t; // the design's N: columns per tile + uint32_t blocked; // 1 when the design packs blocked (b8), 0 otherwise + uint64_t head_hash; // FNV-1a over the container's lm_head.weight bytes +} Q4nxHeadImageKey; + +// Returns a digest over {version, key}, so a key can name a file without embedding four numbers and a hash in a filename. +uint64_t q4nx_head_image_key_digest(const Q4nxHeadImageKey *key); + +// The suggested file name for a key: "headimg-<16 hex>.q4hi". `out` is written NUL-terminated; returns 1 on success. +int q4nx_head_image_key_name(const Q4nxHeadImageKey *key, char *out, int out_n); + + #ifdef __cplusplus } #endif diff --git a/npu/forward/src/q4nx_head_image.c b/npu/forward/src/q4nx_head_image.c index 6dce8c0b9..356505da0 100644 --- a/npu/forward/src/q4nx_head_image.c +++ b/npu/forward/src/q4nx_head_image.c @@ -83,6 +83,31 @@ int q4nx_head_image_write(const char *path, const int8_t *codes, const float *sc return 1; } +uint64_t q4nx_head_image_key_digest(const Q4nxHeadImageKey *key) { + if (!key) return 0; + struct { + uint32_t version; + uint32_t kpad; + uint32_t t; + uint32_t blocked; + uint64_t head_hash; + } fields; + fields.version = Q4NX_HEAD_IMAGE_VERSION; + fields.kpad = key->kpad; + fields.t = key->t; + fields.blocked = key->blocked; + fields.head_hash = key->head_hash; + uint64_t h = 1469598103934665603ull; + return fnv1a(h, &fields, sizeof fields); +} + +int q4nx_head_image_key_name(const Q4nxHeadImageKey *key, char *out, int out_n) { + if (!key || !out || out_n < 8) return 0; + const uint64_t d = q4nx_head_image_key_digest(key); + const int n = snprintf(out, (size_t)out_n, "headimg-%016llx.q4hi", (unsigned long long)d); + return n > 0 && n < out_n; +} + int q4nx_head_image_read(const char *path, int8_t *codes, int codes_n, float *scales, int scales_n, Q4nxHeadImageInfo *info, char *why, int why_n) { if (why && why_n > 0) why[0] = 0; diff --git a/tests/npu_design_grid_test.c b/tests/npu_design_grid_test.c index b92314fcd..b3447d81f 100644 --- a/tests/npu_design_grid_test.c +++ b/tests/npu_design_grid_test.c @@ -568,6 +568,27 @@ static void test_head_image(void) { "head image: no image reads as a refusal"); check(why[0] != 0 && strstr(why, "not there") != NULL, "... whose reason is that it is not there"); } + /* (e) THE KEY: each of the four facts a head image depends on must change it. kpad, T and blocked come from the + * kernel designs and head_hash from the container, so any one of them differing means a DIFFERENT image -- and + * keying on fewer would serve one kernel set's image to another while the correlation still looked plausible. */ + { + Q4nxHeadImageKey base = {96, 64, 1, q4nx_head_image_hash(codes, scales, kd, nd)}; + const uint64_t d0 = q4nx_head_image_key_digest(&base); + Q4nxHeadImageKey k[4]; + for (int i = 0; i < 4; i++) k[i] = base; + k[0].kpad++; k[1].t++; k[2].blocked = 0; k[3].head_hash ^= 1ull; + int changed = 0; + for (int i = 0; i < 4; i++) + if (q4nx_head_image_key_digest(&k[i]) != d0) changed++; + check_int(changed, 4, "head image key: kpad, T, blocked and the head hash each change the digest"); + /* and the name is stable for the same key, so a cache written by one run is found by the next */ + char n1[64], n2[64], n3[64]; + check(q4nx_head_image_key_name(&base, n1, (int)sizeof n1) == 1, "head image key: it names a file"); + check(q4nx_head_image_key_name(&base, n2, (int)sizeof n2) == 1 && strcmp(n1, n2) == 0, + "... the same name for the same key"); + check(q4nx_head_image_key_name(&k[1], n3, (int)sizeof n3) == 1 && strcmp(n1, n3) != 0, + "... and a different name when T changes, so two kernel sets cannot share one cached image"); + } /* (d) a truncated file refuses rather than returning a partial image */ { check(q4nx_head_image_write(path, codes, scales, kd, nd) == 1, "head image: written for the truncation arm");