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
26 changes: 26 additions & 0 deletions npu/forward/include/q4nx_head_image.h
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 25 additions & 0 deletions npu/forward/src/q4nx_head_image.c
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
21 changes: 21 additions & 0 deletions tests/npu_design_grid_test.c
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand Down
Loading