Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦
C
feat(xdna): add explicit packaged XDNA mode
Kenneth-Javier Ortigozaea2ecb63ffb5
diff --git a/c/backend_xdna.c b/c/backend_xdna.cindex 097dd04f..80cc0291 100644--- a/c/backend_xdna.c+++ b/c/backend_xdna.c@@ -955,7 +955,16 @@ const char *coli_xdna_exec_text(ColiXdnaExec e){* artifact currently open in the helper. The prepared WEIGHT is not here: it* belongs to the tensor, which outlives any of this. */static int g_xdna_force; /* internal test control only */+/* Explicit PRODUCT policy (W2-N7-P1), deliberately distinct from g_xdna_force.+ * Set only from a parsed user request; never from discovery, never by default. */+static int g_xdna_explicit;static char g_xdna_root[1024]; /* artifact root; empty = none */+/* Set only by the test seam. When 0, the root is the PRODUCT one derived from+ * the executable directory. Kept as a separate flag rather than inferred from+ * g_xdna_root being empty, because "a test deliberately set no root" and "no+ * test has spoken, use the product default" are different states and the first+ * must not silently acquire the second. */+static int g_xdna_root_overridden;static ColiXdnaHard g_xdna_last_hard = COLI_XDNA_HARD_ELIGIBLE;static ColiXdnaExec g_xdna_last_exec = COLI_XDNA_EXEC_DECLINED;static int g_xdna_dispatches, g_xdna_completions, g_xdna_artifact_opens;@@ -1121,8 +1130,93 @@ ColiXdnaHard coli_xdna_test_last_hard(void){ return g_xdna_last_hard; }ColiXdnaExec coli_xdna_test_last_exec(void){ return g_xdna_last_exec; }void coli_xdna_test_set_force_execution(int on){ g_xdna_force = on ? 1 : 0; }+/* The product artifact root: <exe-dir>\xdna. Same anchor as the helper, same+ * absolute form, same refusal to search. */+int coli_xdna_product_artifact_root(char *out, size_t cap){+#ifdef _WIN32+ char exe[512];+ DWORD n = GetModuleFileNameA(NULL, exe, (DWORD)sizeof exe);+ if(n == 0 || n >= sizeof exe) return 0;+ char *slash = strrchr(exe, '\\');+ char *fwd = strrchr(exe, '/');+ if(fwd && (!slash || fwd > slash)) slash = fwd;+ if(!slash) return 0;+ *slash = '\0';+ int written = snprintf(out, cap, "%s\\%s", exe, COLI_XDNA_ARTIFACT_DIR);+ return written > 0 && (size_t)written < cap;+#else+ (void)out; (void)cap;+ return 0;+#endif+}++/* The root actually used by execution: a test override when one was set,+ * otherwise the product location. Returns NULL when neither is available,+ * which the artifact status treats as ARTIFACT_UNAVAILABLE -- never as a+ * licence to look somewhere else. */+static const char *coli_xdna_effective_root(char *scratch, size_t cap){+ if(g_xdna_root_overridden) return g_xdna_root[0] ? g_xdna_root : NULL;+ if(coli_xdna_product_artifact_root(scratch, cap)) return scratch;+ return NULL;+}++const char *coli_xdna_provision_text(ColiXdnaProvision p){+ switch(p){+ case COLI_XDNA_PROV_READY: return "READY";+ case COLI_XDNA_PROV_NOT_REQUESTED: return "NOT_REQUESTED";+ case COLI_XDNA_PROV_PACKAGE_MISSING: return "PACKAGE_MISSING";+ case COLI_XDNA_PROV_PACKAGE_INCOMPLETE: return "PACKAGE_INCOMPLETE";+ case COLI_XDNA_PROV_INTEGRITY_FAILED: return "INTEGRITY_FAILED";+ case COLI_XDNA_PROV_HELPER_UNAVAILABLE: return "HELPER_UNAVAILABLE";+ case COLI_XDNA_PROV_REGISTRY_INVALID: return "REGISTRY_INVALID";+ }+ return "UNKNOWN";+}++ColiXdnaProvision coli_xdna_provision_status(const char **missing_name){+ if(missing_name) *missing_name = NULL;+ if(!coli_xdna_registry_validate()) return COLI_XDNA_PROV_REGISTRY_INVALID;++ char scratch[1024];+ const char *root = coli_xdna_effective_root(scratch, sizeof scratch);+ if(!root) return COLI_XDNA_PROV_PACKAGE_MISSING;++ /* Every row this build ships, not just the first. A package holding only+ * the small bucket would otherwise report READY and then fail at the first+ * long request -- surfacing at activation is the whole point. */+ int checked = 0;+ for(int i = 0; i < g_nrows; i++){+ const ColiXdnaArtifact *a = &g_rows[i];+ const char *names[2] = { a->xclbin_name, a->insts_name };+ const char *hashes[2] = { a->xclbin_sha256, a->insts_sha256 };+ for(int k = 0; k < 2; k++){+ ColiXdnaStatic st = coli_xdna_check_file(root, names[k], hashes[k]);+ if(st == COLI_XDNA_STATIC_QUALIFIED){ checked++; continue; }+ if(missing_name) *missing_name = names[k];+ if(st == COLI_XDNA_STATIC_ARTIFACT_INTEGRITY_FAILED)+ return COLI_XDNA_PROV_INTEGRITY_FAILED;+ /* Absent file. If NOTHING was verified yet the package as a whole is+ * missing; if some files verified, the package is present but+ * incomplete. Different problems, different fixes. */+ return checked ? COLI_XDNA_PROV_PACKAGE_INCOMPLETE+ : COLI_XDNA_PROV_PACKAGE_MISSING;+ }+ }++ /* Bytes are good. The helper is the remaining prerequisite, and it is+ * reported separately because "install the package" and "the helper will+ * not load" are not the same instruction. */+ if(coli_xdna_binding() != COLI_XDNA_AVAILABLE)+ return COLI_XDNA_PROV_HELPER_UNAVAILABLE;++ return COLI_XDNA_PROV_READY;+}++void coli_xdna_set_explicit_enabled(int on){ g_xdna_explicit = on ? 1 : 0; }+int coli_xdna_explicit_enabled(void){ return g_xdna_explicit; }void coli_xdna_test_set_artifact_root(const char *root){+ g_xdna_root_overridden = 1;if(root && *root) snprintf(g_xdna_root, sizeof g_xdna_root, "%s", root);else g_xdna_root[0] = '\0';}@@ -1206,7 +1300,9 @@ static ColiXdnaHard coli_xdna_engine_gates(ColiXdnaFamily family,* different actions, and an operator who is told only* ARTIFACT_NOT_QUALIFIED cannot tell a missing file from a tampered* one. */- switch(coli_xdna_artifact_status(&q, g_xdna_root[0] ? g_xdna_root : NULL)){+ char root_scratch[1024];+ const char *eff_root = coli_xdna_effective_root(root_scratch, sizeof root_scratch);+ switch(coli_xdna_artifact_status(&q, eff_root)){case COLI_XDNA_STATIC_QUALIFIED:break;case COLI_XDNA_STATIC_ARTIFACT_UNAVAILABLE:@@ -1323,8 +1419,11 @@ static ColiXdnaExec coli_xdna_attempt(ColiXdnaFamily family,/* 13 device / runtime / artifact runtime object, opened lazily. */if(!g_lane.open || g_lane.m != am || g_lane.k != (unsigned)I || g_lane.n != (unsigned)O){char xb[2048], ib[2048];- if(!coli_xdna_join(xb, sizeof xb, g_xdna_root, row->xclbin_name)- || !coli_xdna_join(ib, sizeof ib, g_xdna_root, row->insts_name)){+ char rs2[1024];+ const char *r2 = coli_xdna_effective_root(rs2, sizeof rs2);+ if(!r2+ || !coli_xdna_join(xb, sizeof xb, r2, row->xclbin_name)+ || !coli_xdna_join(ib, sizeof ib, r2, row->insts_name)){g_xdna_last_hard = COLI_XDNA_HARD_ARTIFACT_RUNTIME_UNAVAILABLE;return (g_xdna_last_exec = COLI_XDNA_EXEC_ARTIFACT_OPEN_FAILED);}@@ -1443,9 +1542,19 @@ int coli_xdna_try_matmul(ColiXdnaFamily family,int I, int O, int gs, int planar,float *y, const float *x, int S){- /* Gate 0: the internal control. Without it this function is inert, which is- * what keeps the lane from being an automatic scheduler. */- if(!g_xdna_force){+ /* Gate 0: PERMISSION. Without it this function is inert, which is what keeps+ * the lane from being an automatic scheduler.+ *+ * Two independent sources, and they are not interchangeable:+ * g_xdna_explicit the user asked for it (`coli --xdna` -> COLI_XDNA=1)+ * g_xdna_force an internal qualification run forced it+ *+ * Neither is discovery. Present hardware, a loadable helper and valid+ * artifacts do not set either one, so a machine that COULD run this lane+ * still does not until someone says so. Permission is also not selection:+ * every hard gate below still decides, and an unqualified operation runs+ * the current path no matter who asked. */+ if(!(g_xdna_explicit || g_xdna_force)){/* Clear validity here too. Declining before the core runs still ends an* attempt, and a stale 1 left over from an earlier success would claim* an XDNA result for an operation the lane never touched. */diff --git a/c/backend_xdna.h b/c/backend_xdna.hindex 984a64c7..d12d4544 100644--- a/c/backend_xdna.h+++ b/c/backend_xdna.h@@ -43,6 +43,11 @@ extern "C" {* never collide with the host-side coli_xdna_ names in this header. */#define COLI_XDNA_HELPER_DLL "coli_xdna.dll"+/* Directory, relative to the executable, holding the qualified artifacts of the+ * optional XDNA package. A fixed relative name, joined to an absolute+ * executable directory -- never searched for. */+#define COLI_XDNA_ARTIFACT_DIR "xdna"+/* Prepared-host pointer alignment required by the qualified Windows XRT* userptr path. Scoped to that path deliberately: it is not a claim about* every XRT implementation. The payload SIZE need not be a page multiple. */@@ -483,6 +488,83 @@ int coli_xdna_try_matmul(ColiXdnaFamily family,* when nothing was ever initialised, and safe to repeat. */void coli_xdna_execution_shutdown(void);+/* -- explicit product policy (W2-N7-P1) -----------------------------------+ *+ * The ONLY non-test way to permit this lane. It is set from an explicit user+ * request parsed by Colibri (`coli --xdna` -> COLI_XDNA=1), never from hardware+ * discovery, never from a helper, never from an economic comparison, and never+ * by default.+ *+ * "Permit" is exact. Enabling does NOT force anything onto the device: every+ * hard gate still decides, and an operation this lane was not qualified for+ * still runs the current path. The user is authorising a qualified+ * reduced-precision lane, not overriding eligibility.+ *+ * Kept separate from the test seam on purpose. The test control forces+ * execution for qualification runs; this one expresses product intent. They+ * must not be the same switch, because a test seam that could be reached from+ * a user-facing option would be a way to enable unqualified behaviour in+ * production. */+/* -- optional package provisioning (W2-N7-P1-A1) ---------------------------+ *+ * Where the qualified artifact bytes come from in a shipped build.+ *+ * V1 contract: an OPTIONAL sidecar package installed beside the executable.+ *+ * <exe-dir>\coli_xdna.dll the helper+ * <exe-dir>\xdna\<registry names> the qualified artifacts+ *+ * The artifact root is derived from the executable path exactly as the helper+ * path already is: absolute, and NOT a search. No PATH, no working directory,+ * no recursive lookup, no first-match. W1 established that a same-basename+ * module already loaded beats a later absolute-path load, and the same+ * reasoning applies to artifacts: a search order here would be unsafe and+ * unpredictable. A package that is not where we look is simply ABSENT.+ *+ * Provisioning answers "where are the qualified bytes?". It does NOT answer+ * "should XDNA run?" -- a complete, valid, hash-perfect package enables+ * nothing on its own. That remains the explicit policy above. */++/* Product-facing provisioning verdict.+ *+ * The execution path keeps its coarser hard/exec codes; this exists so the+ * DIAGNOSTIC layer can tell a user which of several very different problems+ * they have. "Your build lacks the feature", "install the optional package",+ * and "your package is corrupt" have three different fixes, and collapsing+ * them into one ARTIFACT_UNAVAILABLE line tells the user nothing actionable. */+typedef enum {+ COLI_XDNA_PROV_READY = 0, /* every required byte present and verified */+ COLI_XDNA_PROV_NOT_REQUESTED, /* explicit policy is off; nothing resolved */+ COLI_XDNA_PROV_PACKAGE_MISSING, /* the artifact directory is not there */+ COLI_XDNA_PROV_PACKAGE_INCOMPLETE, /* directory present, a required file is not */+ COLI_XDNA_PROV_INTEGRITY_FAILED, /* file present, bytes are not the qualified bytes */+ COLI_XDNA_PROV_HELPER_UNAVAILABLE, /* no compatible helper beside the executable */+ COLI_XDNA_PROV_REGISTRY_INVALID /* the compiled registry itself is unusable */+} ColiXdnaProvision;++/* Stable label, allocation-free. */+const char *coli_xdna_provision_text(ColiXdnaProvision p);++/* The absolute artifact root this build will use: <exe-dir>\xdna.+ * Returns 0 if the executable path cannot be determined. Pure resolution --+ * it touches no file and enables nothing. */+int coli_xdna_product_artifact_root(char *out, size_t cap);++/* Resolve the package and verify EVERY artifact the currently qualified+ * product lane needs, against the SHA256 values compiled into the registry.+ *+ * Verifies the whole set, not the first row: a package missing only the M256+ * artifact would otherwise look READY until a long request arrived, which is+ * exactly the class of failure that should surface at activation instead.+ *+ * `missing_name`, when non-NULL, receives a pointer to the static registry+ * filename responsible for a non-READY verdict, so a diagnostic can name it.+ * The pointer is into the compiled registry and outlives any caller. */+ColiXdnaProvision coli_xdna_provision_status(const char **missing_name);++void coli_xdna_set_explicit_enabled(int on);+int coli_xdna_explicit_enabled(void);+/* -- the two internal execution modes -------------------------------------** AF0 froze two conceptual modes and I6 defines both mechanically. Neither isdiff --git a/c/coli b/c/coliindex 804d6098..0d592a51 100755--- a/c/coli+++ b/c/coli@@ -687,6 +687,9 @@ def env_for(a):e.setdefault("PIPE", "1")e.setdefault("PILOT_REAL", "1")e["COLI_POLICY"]=a.policy+ # Explicit request only. Absent flag => variable absent => engine default,+ # which is the current path. Never set from discovery or from a plan.+ if getattr(a, "xdna", False): e["COLI_XDNA"]="1"if getattr(a, "cluster_workers", None): e["CLUSTER_WORKERS"] = a.cluster_workersif getattr(a, "cluster_coordinator", None): e["CLUSTER_COORDINATOR"] = a.cluster_coordinatorif a.ram: e["RAM_GB"]=str(a.ram)@@ -1889,6 +1892,15 @@ def main():default=os.environ.get("COLI_POLICY","quality"),help="resource policy (explicit --topk/--topp overrides warn and proceed)")common.add_argument("--repin", type=int, default=0, help="adapt RAM/VRAM experts every N tokens")+ # Explicit, default-off opt-in to the qualified native XDNA2 (Ryzen AI NPU)+ # lane. Deliberately NOT a --policy value: --policy chooses how the planner may+ # spend memory, this chooses a compute device, and a user wanting quality+ # planning ON the NPU must be able to say both. Deliberately not inferred from+ # hardware either -- the reduced-precision consequence means the user has to ask.+ common.add_argument("--xdna", action="store_true",+ help="experimental: run qualified GLM operations on the AMD XDNA2 NPU "+ "(reduced-precision BF16 path; output may differ; unsupported "+ "operations use the normal path)")# Absent (None) = not explicitly set: the glm engine gets the 0 sentinel and picks# (8 historically; 1 on Metal+darwin+fast SSD, #379 -- an honest F_NOCACHE probe# measures "fast", cached in <model>/.coli_ssd), while non-glm arches get thediff --git a/c/colibri.c b/c/colibri.cindex ec625d21..186526a1 100644--- a/c/colibri.c+++ b/c/colibri.c@@ -11083,6 +11083,87 @@ int main(int argc, char **argv){cluster_init();atexit(cluster_close_all);}+#endif+ /* EXPLICIT XDNA REQUEST (W2-N7-P1, ordering corrected by P1-A1).+ *+ * COLI_XDNA=1 is an explicit user decision, parsed and owned by `coli`+ * (--xdna). Read once, before the model runs.+ *+ * ORDERING IS THE POINT. P1 emitted the reduced-precision warning as soon+ * as the request was parsed -- it announced that operations "will use the+ * native NPU", and then dispatched zero times because no production+ * artifact root existed. The message was a promise the run did not keep.+ *+ * So the success warning now comes LAST, after the package has been+ * resolved and every qualified artifact verified against the registry.+ * Anything short of that gets its own diagnostic and the normal path:+ * "this build cannot", "install the package", "your package is corrupt"+ * and "the helper will not load" are four different problems with four+ * different fixes.+ *+ * Everything goes to stderr. SCORE mode writes machine-readable results+ * to stdout and its parser consumes any stdout line starting with a digit+ * or a minus sign, so a diagnostic there would be absorbed as a score. */+#ifdef COLI_XDNA+ { const char *xe = getenv("COLI_XDNA");+ if(xe && atoi(xe)){+ const char *missing = NULL;+ ColiXdnaProvision pv = coli_xdna_provision_status(&missing);+ char root[1024];+ int have_root = coli_xdna_product_artifact_root(root, sizeof root);+ switch(pv){+ case COLI_XDNA_PROV_READY:+ coli_xdna_set_explicit_enabled(1);+ fprintf(stderr,+ "[XDNA] experimental: qualified GLM shared expert operations will use the\n"+ "[XDNA] native NPU with a reduced-precision BF16 compute path. Model output\n"+ "[XDNA] may differ from the normal path, and generated text has been observed\n"+ "[XDNA] to diverge. Operations this lane does not support continue to use the\n"+ "[XDNA] normal path.\n");+ break;+ case COLI_XDNA_PROV_PACKAGE_MISSING:+ fprintf(stderr,+ "[XDNA] requested, but the XDNA package was not found%s%s: "+ "continuing on the normal path\n",+ have_root ? " at " : "", have_root ? root : "");+ break;+ case COLI_XDNA_PROV_PACKAGE_INCOMPLETE:+ fprintf(stderr,+ "[XDNA] requested, but the XDNA package is incomplete (missing %s)%s%s: "+ "continuing on the normal path\n",+ missing ? missing : "a required artifact",+ have_root ? " in " : "", have_root ? root : "");+ break;+ case COLI_XDNA_PROV_INTEGRITY_FAILED:+ fprintf(stderr,+ "[XDNA] requested, but an XDNA artifact does not match its expected hash "+ "(%s): refusing to use it, continuing on the normal path\n",+ missing ? missing : "unknown file");+ break;+ case COLI_XDNA_PROV_HELPER_UNAVAILABLE:+ fprintf(stderr,+ "[XDNA] requested, and the artifact package is valid, but the XDNA helper "+ "(" COLI_XDNA_HELPER_DLL ") is not usable beside the executable: "+ "continuing on the normal path\n");+ break;+ case COLI_XDNA_PROV_REGISTRY_INVALID:+ fprintf(stderr,+ "[XDNA] requested, but this build's artifact registry is invalid: "+ "continuing on the normal path\n");+ break;+ case COLI_XDNA_PROV_NOT_REQUESTED:+ break; /* unreachable here: the request is what got us in */+ }+ }+ }+#else+ /* Built without the lane. An explicit request deserves an answer rather+ * than silence -- the user asked for something this binary cannot do. */+ { const char *xe = getenv("COLI_XDNA");+ if(xe && atoi(xe))+ fprintf(stderr, "[XDNA] requested, but this build has no XDNA support: "+ "continuing on the normal path\n");+ }#endifModel m; double t0=now_s(); model_init(&m,snap,cap,ebits,dbits);/* KV_TQ requires power-of-two row widths: both codecs rotate through adiff --git a/c/tests/test_xdna_execution.c b/c/tests/test_xdna_execution.cindex 654f28ef..df8e6e28 100644--- a/c/tests/test_xdna_execution.c+++ b/c/tests/test_xdna_execution.c@@ -696,6 +696,279 @@ int main(int argc, char **argv){ck(coli_xdna_prepared_live_objects()==0, "prepared image released");}+ /* ==================================================================+ * W2-N7-P1 -- EXPLICIT PRODUCT POLICY+ *+ * The product control is separate from the test force. These cases are+ * about PERMISSION, not about execution: they check who may turn the lane+ * on and what happens when nobody has.+ * ================================================================== */+ /* ==================================================================+ * W2-N7-P1-A1 -- PRODUCTION PROVISIONING+ *+ * Where the qualified bytes come from in a shipped build, and what+ * happens when they are absent, incomplete or not what they claim.+ * ================================================================== */+ printf("A1 production artifact root -- absolute, derived, never searched\n");+ {+ char root[1024];+ int ok = coli_xdna_product_artifact_root(root, sizeof root);+ ck(ok, "product root resolves");+ if(ok){+ /* Absolute: on Windows a drive letter and colon, or a UNC prefix. */+ int absolute = (root[0] && root[1] == ':') ||+ (root[0] == '\\' && root[1] == '\\');+ ck(absolute, "product root is absolute, not relative to the CWD");+ /* It ends with the fixed artifact directory name. */+ size_t rl = strlen(root), dl = strlen(COLI_XDNA_ARTIFACT_DIR);+ ck(rl > dl && strcmp(root + rl - dl, COLI_XDNA_ARTIFACT_DIR) == 0,+ "product root ends with the fixed artifact directory name");+ /* Deriving it twice gives the same answer -- it is a pure+ * function of the executable path, not of the environment. */+ char again[1024];+ ck(coli_xdna_product_artifact_root(again, sizeof again) &&+ strcmp(root, again) == 0, "product root is deterministic");+ }+ /* A tiny buffer must fail rather than truncate into a wrong path. */+ char tiny[8];+ ck(coli_xdna_product_artifact_root(tiny, sizeof tiny) == 0,+ "product root refuses to truncate into a shorter wrong path");+ }++ printf("A1 provisioning verdicts -- missing, incomplete, corrupt, ready\n");+ {+ registry_both();+ use_helper(g_helper);++ /* PACKAGE MISSING: point the root at a directory that does not exist. */+ { char nowhere[1024];+ snprintf(nowhere, sizeof nowhere, "%s/no_such_package_dir", g_root);+ coli_xdna_test_set_artifact_root(nowhere);+ const char *who = NULL;+ ColiXdnaProvision p = coli_xdna_provision_status(&who);+ ck(p == COLI_XDNA_PROV_PACKAGE_MISSING, "absent directory -> PACKAGE_MISSING");+ ck(strcmp(coli_xdna_provision_text(p), "PACKAGE_MISSING") == 0,+ "PACKAGE_MISSING has a stable label");+ }++ /* READY: the fixture root holds both fixture artifacts, and the test+ * registry rows point at them with correct hashes. */+ coli_xdna_test_set_artifact_root(g_root);+ { const char *who = NULL;+ ColiXdnaProvision p = coli_xdna_provision_status(&who);+ ck(p == COLI_XDNA_PROV_READY, "complete valid fixture package -> READY");+ ck(who == NULL, "READY names no offending file");+ }++ /* INTEGRITY FAILED: same filenames, different bytes. The file is+ * exactly where it should be and named exactly right -- and is still+ * refused, because bytes that are not the qualified bytes are not the+ * qualified lane. */+ { char xp[2048];+ snprintf(xp, sizeof xp, "%s", g_xclbin);+ FILE *f = fopen(xp, "r+b");+ ck(f != NULL, "fixture artifact is writable for the corruption case");+ if(f){+ fseek(f, 16, SEEK_SET);+ unsigned char orig = 0, flip;+ size_t got = fread(&orig, 1, 1, f);+ flip = (unsigned char)(orig ^ 0xFFu);+ fseek(f, 16, SEEK_SET); fwrite(&flip, 1, 1, f); fclose(f);++ const char *who = NULL;+ ColiXdnaProvision p = coli_xdna_provision_status(&who);+ ck(p == COLI_XDNA_PROV_INTEGRITY_FAILED,+ "correct filename, wrong bytes -> INTEGRITY_FAILED");+ ck(who != NULL, "INTEGRITY_FAILED names the offending file");++ /* and execution refuses it too, not just the report */+ coli_xdna_test_set_force_execution(1);+ ColiXdnaPrepared *slot = NULL;+ float *x = mk_x(8, TK, 31u);+ float *y = (float*)malloc((size_t)8*TN*sizeof(float));+ poison(y, (size_t)8*TN);+ ColiXdnaExec e = coli_xdna_test_attempt(COLI_XDNA_FAMILY_MOE_SHARED_GATE_UP,+ &slot, 4, W.q4, W.s, TK, TN, 64, 0, y, x, 8);+ ck(e == COLI_XDNA_EXEC_DECLINED, "corrupt artifact -> execution DECLINED");+ ck(coli_xdna_test_last_hard() == COLI_XDNA_HARD_ARTIFACT_INTEGRITY_FAILED,+ "corrupt artifact -> ARTIFACT_INTEGRITY_FAILED");+ ck(coli_xdna_test_dispatches() == 0, "corrupt artifact -> zero dispatches");+ { int untouched = 1;+ for(size_t i=0;i<(size_t)8*TN;i++) if(y[i]!=POISON){ untouched=0; break; }+ ck(untouched, "corrupt artifact -> caller output untouched"); }+ coli_xdna_prepared_release(&slot); free(x); free(y);+ coli_xdna_test_set_force_execution(0);++ /* restore the fixture for the tests that follow */+ f = fopen(xp, "r+b");+ if(f){ fseek(f, 16, SEEK_SET); fwrite(&orig, 1, 1, f); fclose(f); }+ ck(got == 1, "fixture byte was read before being flipped");+ }+ }++ /* back to READY after restoring the byte */+ { const char *who = NULL;+ ck(coli_xdna_provision_status(&who) == COLI_XDNA_PROV_READY,+ "restoring the byte restores READY");+ }++ /* Extra unrelated files in the directory must not change anything:+ * selection is registry-driven, never a directory scan. */+ { char extra[2048];+ snprintf(extra, sizeof extra, "%s/zz_unrelated.xclbin", g_root);+ if(write_blob(extra, 7u, 256)){+ const char *who = NULL;+ ck(coli_xdna_provision_status(&who) == COLI_XDNA_PROV_READY,+ "an extra unknown file in the directory is ignored");+ remove(extra);+ }+ }++ /* HELPER UNAVAILABLE is reported separately from the bytes. */+ { coli_xdna_test_set_helper_path("no_such_helper_at_all.dll");+ const char *who = NULL;+ ColiXdnaProvision p = coli_xdna_provision_status(&who);+ ck(p == COLI_XDNA_PROV_HELPER_UNAVAILABLE,+ "valid bytes + no helper -> HELPER_UNAVAILABLE, not a package verdict");+ use_helper(g_helper);+ coli_xdna_test_set_artifact_root(g_root);+ }+ }++ printf("A1 provisioning does not enable -- a READY package is still inert\n");+ {+ registry_both();+ use_helper(g_helper);+ coli_xdna_test_set_artifact_root(g_root);+ coli_xdna_test_set_force_execution(0);+ coli_xdna_set_explicit_enabled(0);++ const char *who = NULL;+ ck(coli_xdna_provision_status(&who) == COLI_XDNA_PROV_READY,+ "package is READY");+ ck(coli_xdna_binding() == COLI_XDNA_AVAILABLE, "helper is bound");+ ck(coli_xdna_explicit_enabled() == 0, "and the policy is STILL off");++ ColiXdnaPrepared *slot = NULL;+ float *x = mk_x(16, TK, 88u);+ float *y = (float*)malloc((size_t)16*TN*sizeof(float));+ poison(y, (size_t)16*TN);+ int handled = coli_xdna_try_matmul(COLI_XDNA_FAMILY_MOE_SHARED_GATE_UP,+ &slot, 4, W.q4, W.s, TK, TN, 64, 0, y, x, 16);+ ck(handled == 0, "READY package + policy off -> declines");+ ck(coli_xdna_test_dispatches() == 0, "READY package + policy off -> zero dispatches");+ { int untouched = 1;+ for(size_t i=0;i<(size_t)16*TN;i++) if(y[i]!=POISON){ untouched=0; break; }+ ck(untouched, "READY package + policy off -> caller output untouched"); }+ coli_xdna_prepared_release(&slot); free(x); free(y);+ }++ printf("P1 explicit product policy -- default off, explicit on\n");+ {+ registry_both();++ /* DEFAULT: everything a discovering system could find is present and+ * valid -- helper bound, artifacts staged and integrity-checked, a+ * registry holding both buckets -- and the lane still does nothing. */+ use_helper(g_helper);+ coli_xdna_test_set_artifact_root(g_root);+ coli_xdna_test_set_force_execution(0);+ coli_xdna_set_explicit_enabled(0);+ ck(coli_xdna_explicit_enabled()==0, "default: explicit policy is OFF");++ ColiXdnaPrepared *slot = NULL;+ int S = 32;+ float *x = mk_x(S, TK, 5150u);+ float *y = (float*)malloc((size_t)S*TN*sizeof(float));+ poison(y, (size_t)S*TN);+ int handled = coli_xdna_try_matmul(COLI_XDNA_FAMILY_MOE_SHARED_GATE_UP,+ &slot, 4, W.q4, W.s, TK, TN, 64, 0, y, x, S);+ ck(handled==0, "default: candidate declines");+ ck(coli_xdna_test_last_exec()==COLI_XDNA_EXEC_DECLINED, "default: DECLINED");+ ck(coli_xdna_test_dispatches()==0, "default: zero dispatches");+ ck(coli_xdna_test_bucket_dispatches((unsigned)TM)==0, "default: zero on M64");+ ck(coli_xdna_test_bucket_dispatches((unsigned)TM2)==0, "default: zero on M256");+ ck(coli_xdna_test_artifact_opens()==0, "default: no artifact opened");+ ck(coli_xdna_test_output_valid()==0, "default: no output claimed");+ { int untouched = 1;+ for(size_t i=0;i<(size_t)S*TN;i++) if(y[i]!=POISON){ untouched=0; break; }+ ck(untouched, "default: caller output untouched"); }++ /* NO SILENT ACTIVATION: the things a naive implementation might have+ * treated as "XDNA is available, so use it" are all true right now. */+ ck(coli_xdna_binding()==COLI_XDNA_AVAILABLE,+ "default: a compatible helper IS bound -- and that alone changes nothing");+ ck(coli_xdna_explicit_enabled()==0,+ "default: a bound helper does not set the product policy");++ /* EXPLICIT: the same call, the same everything, one bit of user intent. */+ coli_xdna_set_explicit_enabled(1);+ ck(coli_xdna_explicit_enabled()==1, "explicit: policy reads back ON");+ poison(y, (size_t)S*TN);+ handled = coli_xdna_try_matmul(COLI_XDNA_FAMILY_MOE_SHARED_GATE_UP,+ &slot, 4, W.q4, W.s, TK, TN, 64, 0, y, x, S);+ ck(handled==1, "explicit: the SAME operation is now handled");+ ck(coli_xdna_test_bucket_dispatches((unsigned)TM)==1, "explicit: dispatched on M64");+ { float *REFS = (float*)malloc((size_t)S*TN*sizeof(float));+ oracle(REFS, x, coli_xdna_prepared_image(slot), S, TK, TN);+ int exact = 1;+ for(size_t i=0;i<(size_t)S*TN;i++) if(y[i]!=REFS[i]){ exact=0; break; }+ ck(exact, "explicit: result matches the BF16 oracle");+ free(REFS); }++ /* PERMISSION IS NOT SELECTION: an operation the lane was never+ * qualified for still runs the current path, however explicit the+ * user was. Opting in buys the qualified lane, not a bypass. */+ coli_xdna_test_reset_bucket_counters();+ { ColiXdnaPrepared *s2 = NULL;+ int Sbig = TM2+1; /* above every bucket */+ float *xb = mk_x(Sbig, TK, 77u);+ float *yb = (float*)malloc((size_t)Sbig*TN*sizeof(float));+ poison(yb, (size_t)Sbig*TN);+ int h2 = coli_xdna_try_matmul(COLI_XDNA_FAMILY_MOE_SHARED_GATE_UP,+ &s2, 4, W.q4, W.s, TK, TN, 64, 0, yb, xb, Sbig);+ ck(h2==0, "explicit: an unqualified shape still declines");+ ck(coli_xdna_test_last_hard()==COLI_XDNA_HARD_M_OUT_OF_RANGE,+ "explicit: declines for the SHAPE reason, not the policy");+ ck(coli_xdna_test_bucket_dispatches((unsigned)TM)==0 &&+ coli_xdna_test_bucket_dispatches((unsigned)TM2)==0,+ "explicit: no dispatch on either bucket");+ { int untouched = 1;+ for(size_t i=0;i<(size_t)Sbig*TN;i++) if(yb[i]!=POISON){ untouched=0; break; }+ ck(untouched, "explicit: caller output untouched by the decline"); }+ coli_xdna_prepared_release(&s2); free(xb); free(yb); }++ /* A wrong-family operation is likewise unaffected by permission. */+ coli_xdna_test_reset_bucket_counters();+ { ColiXdnaPrepared *s3 = NULL;+ float *yf = (float*)malloc((size_t)S*TN*sizeof(float));+ poison(yf, (size_t)S*TN);+ int h3 = coli_xdna_try_matmul(COLI_XDNA_FAMILY_NONE,+ &s3, 4, W.q4, W.s, TK, TN, 64, 0, yf, x, S);+ ck(h3==0, "explicit: wrong semantic family still declines");+ ck(coli_xdna_test_last_hard()==COLI_XDNA_HARD_FAMILY_UNSUPPORTED,+ "explicit: declines for the FAMILY reason");+ coli_xdna_prepared_release(&s3); free(yf); }++ /* Turning it back off restores the default immediately. */+ coli_xdna_set_explicit_enabled(0);+ coli_xdna_test_reset_bucket_counters();+ poison(y, (size_t)S*TN);+ handled = coli_xdna_try_matmul(COLI_XDNA_FAMILY_MOE_SHARED_GATE_UP,+ &slot, 4, W.q4, W.s, TK, TN, 64, 0, y, x, S);+ ck(handled==0, "policy off again: declines");+ /* per-bucket, not the cumulative aggregate: the aggregate still holds the+ * dispatch the explicit case above legitimately made. Asserting 0 on it+ * would be asserting that history never happened. */+ ck(coli_xdna_test_bucket_dispatches((unsigned)TM)==0 &&+ coli_xdna_test_bucket_dispatches((unsigned)TM2)==0,+ "policy off again: zero NEW dispatches on either bucket");+ ck(coli_xdna_test_last_exec()==COLI_XDNA_EXEC_DECLINED,+ "policy off again: DECLINED, not a failure");++ coli_xdna_prepared_release(&slot); free(x); free(y);+ }+coli_xdna_test_set_helper_path(NULL);coli_xdna_shutdown();coli_xdna_test_set_registry(NULL,0);diff --git a/c/tools/build_xdna_package.py b/c/tools/build_xdna_package.pynew file mode 100644index 00000000..c1a036d9--- /dev/null+++ b/c/tools/build_xdna_package.py@@ -0,0 +1,194 @@+"""Assemble the optional XDNA sidecar package from already-built qualified inputs.++The optional package is what makes `coli --xdna` able to do anything: it carries+the helper and the qualified artifacts to the fixed locations the engine+resolves.++ <package-root>/+ coli_xdna.dll+ xdna/+ wa_F3_M64_K6144_N2048.xclbin+ wa_F3_M64_K6144_N2048_insts.bin+ wa_F3_M256_K6144_N2048.xclbin+ wa_F3_M256_K6144_N2048_insts.bin++This script BUILDS NOTHING. It does not compile artifacts, does not compile the+helper, and does not download. It copies inputs that already exist and refuses+to produce a package unless every expected file is present and every byte hashes+to the value the engine will demand at runtime.++That refusal is the point. A package assembled from the wrong bytes would fail+closed at load anyway -- with a diagnostic pointing at the user's installation+rather than at the release that shipped it. Catching it here puts the error+where it can be fixed.++The expected names and hashes are PARSED FROM c/backend_xdna.c, not restated+here. There is exactly one place in this repository that decides which artifact+bytes are acceptable, and duplicating it into a packaging script would create a+second source of truth that could drift.++Usage:++ python tools/build_xdna_package.py --helper <path-to-coli_xdna.dll> \\+ --artifacts <dir-with-the-4-files> \\+ --out <package-root>+ python tools/build_xdna_package.py ... --zip <out.zip>+ python tools/build_xdna_package.py --verify <package-root>+"""+import argparse+import hashlib+import os+import re+import shutil+import sys+import zipfile++HERE = os.path.dirname(os.path.abspath(__file__))+REGISTRY_SRC = os.path.normpath(os.path.join(HERE, "..", "backend_xdna.c"))+HEADER_SRC = os.path.normpath(os.path.join(HERE, "..", "backend_xdna.h"))+++def artifact_dir_name():+ """The relative directory the engine appends to the executable directory."""+ src = open(HEADER_SRC, encoding="utf-8").read()+ m = re.search(r'#define\s+COLI_XDNA_ARTIFACT_DIR\s+"([^"]+)"', src)+ if not m:+ sys.exit("could not find COLI_XDNA_ARTIFACT_DIR in backend_xdna.h")+ return m.group(1)+++def helper_name():+ src = open(HEADER_SRC, encoding="utf-8").read()+ m = re.search(r'#define\s+COLI_XDNA_HELPER_DLL\s+"([^"]+)"', src)+ if not m:+ sys.exit("could not find COLI_XDNA_HELPER_DLL in backend_xdna.h")+ return m.group(1)+++def required_files():+ """(filename, sha256) for every artifact the compiled registry names.++ Parsed from the production registry table so the package can never disagree+ with the binary that will verify it.+ """+ src = open(REGISTRY_SRC, encoding="utf-8").read()+ m = re.search(r"g_xdna_production_rows\[\]\s*=\s*\{(.*?)\n\};", src, re.S)+ if not m:+ sys.exit("could not find g_xdna_production_rows[] in backend_xdna.c")+ body = m.group(1)+ pairs = re.findall(r'"([A-Za-z0-9_\.]+\.(?:xclbin|bin))"\s*,\s*"([0-9a-f]{64})"', body)+ if not pairs:+ sys.exit("registry parsed but no (filename, sha256) pairs found")+ seen, out = set(), []+ for name, h in pairs:+ if name in seen:+ if dict(out).get(name) != h:+ sys.exit("registry names %s with two different hashes" % name)+ continue+ seen.add(name)+ out.append((name, h))+ return out+++def sha256(path):+ h = hashlib.sha256()+ with open(path, "rb") as f:+ for chunk in iter(lambda: f.read(1 << 20), b""):+ h.update(chunk)+ return h.hexdigest()+++def verify_tree(root, adir, hname, need_helper=True):+ """Return a list of problems; empty means the package is well-formed."""+ problems = []+ if need_helper:+ hp = os.path.join(root, hname)+ if not os.path.isfile(hp):+ problems.append("helper missing: %s" % hname)+ adir_path = os.path.join(root, adir)+ if not os.path.isdir(adir_path):+ problems.append("artifact directory missing: %s/" % adir)+ return problems+ for name, want in required_files():+ p = os.path.join(adir_path, name)+ if not os.path.isfile(p):+ problems.append("artifact missing: %s/%s" % (adir, name))+ continue+ got = sha256(p)+ if got != want:+ problems.append("artifact hash mismatch: %s/%s\n expected %s\n actual %s"+ % (adir, name, want, got))+ return problems+++def main():+ ap = argparse.ArgumentParser(description=__doc__,+ formatter_class=argparse.RawDescriptionHelpFormatter)+ ap.add_argument("--helper", help="path to the already-built coli_xdna.dll")+ ap.add_argument("--artifacts", help="directory holding the qualified artifact files")+ ap.add_argument("--out", help="package root to create")+ ap.add_argument("--zip", help="also write this zip of the package root")+ ap.add_argument("--verify", help="verify an existing package root and exit")+ a = ap.parse_args()++ adir, hname = artifact_dir_name(), helper_name()+ need = required_files()++ if a.verify:+ problems = verify_tree(a.verify, adir, hname)+ for p in problems:+ print("FAIL " + p)+ if problems:+ sys.exit("package INVALID: %d problem(s)" % len(problems))+ print("package OK: %s + %d artifacts, all hashes match the registry"+ % (hname, len(need)))+ return++ if not (a.helper and a.artifacts and a.out):+ sys.exit("need --helper, --artifacts and --out (or --verify)")++ # Check every input BEFORE writing anything, so a bad input never produces a+ # half-built package that looks assembled.+ problems = []+ if not os.path.isfile(a.helper):+ problems.append("helper not found: %s" % a.helper)+ for name, want in need:+ p = os.path.join(a.artifacts, name)+ if not os.path.isfile(p):+ problems.append("input artifact missing: %s" % p)+ continue+ got = sha256(p)+ if got != want:+ problems.append("input artifact hash mismatch: %s\n expected %s\n actual %s"+ % (p, want, got))+ if problems:+ for p in problems:+ print("FAIL " + p)+ sys.exit("refusing to build a package from %d bad input(s)" % len(problems))++ os.makedirs(os.path.join(a.out, adir), exist_ok=True)+ shutil.copy2(a.helper, os.path.join(a.out, hname))+ for name, _ in need:+ shutil.copy2(os.path.join(a.artifacts, name), os.path.join(a.out, adir, name))++ after = verify_tree(a.out, adir, hname)+ if after:+ for p in after:+ print("FAIL " + p)+ sys.exit("package verification failed after copy")++ print("package built: %s" % a.out)+ print(" %s" % hname)+ for name, h in need:+ print(" %s/%-34s %s" % (adir, name, h))++ if a.zip:+ with zipfile.ZipFile(a.zip, "w", zipfile.ZIP_DEFLATED) as z:+ z.write(os.path.join(a.out, hname), hname)+ for name, _ in need:+ z.write(os.path.join(a.out, adir, name), "%s/%s" % (adir, name))+ print("zip written: %s (%d bytes)" % (a.zip, os.path.getsize(a.zip)))+++if __name__ == "__main__":+ main()diff --git a/docs/xdna.md b/docs/xdna.mdnew file mode 100644index 00000000..b06081d3--- /dev/null+++ b/docs/xdna.md@@ -0,0 +1,110 @@+# XDNA backend (Windows, AMD Ryzen AI NPU)++colibrì includes an **experimental, opt-in** backend that runs some GLM+operations on an AMD XDNA2 NPU using a **reduced-precision BF16 compute path**.+It is off by default, it is never selected automatically, and model output may+differ from the normal path.++```bash+coli run --xdna "your prompt"+```++Without `--xdna` nothing changes: no helper is loaded, no device is opened, and+the engine produces exactly the results it produces today. Installing the+optional package does not enable anything on its own.++## What runs on the NPU++Only the **MoE shared-expert gate/up projection** for GLM+(`K=6144, N=2048`, fmt=4 grouped int4, group size 64), and only at sequence+lengths the qualified artifacts cover:++| rows per call | runs on |+|---|---|+| 1 – 64 | NPU, M64 artifact |+| 65 – 256 | NPU, M256 artifact |+| more than 256 | normal path |++Everything else — the down projection, routed experts, attention, every other+model — uses the normal path. Any operation the lane does not support, and any+runtime failure, falls back to the exact computation the engine performs+without this backend.++## Precision++The NPU path converts activations and weights to BF16 and accumulates in F32.+This is **not** the same arithmetic as the normal path, and it is not claimed to+be equivalent:++- per-option scores on a small internal benchmark changed on every operation the+ NPU handled;+- in a separate experiment with free-running generation, 5 of 8 prompts produced+ **different text**.++Whether that matters for your use is a judgement you have to make. The mode+exists so the choice is explicit.++## Installing the optional package++The NPU backend needs two things beside the executable: a helper DLL and the+qualified kernel artifacts. They ship as a separate optional download, not in+the main archive.++Extract it over your colibrì directory so the layout is:++```+<colibri directory>\+ colibri.exe+ coli_xdna.dll+ xdna\+ wa_F3_M64_K6144_N2048.xclbin+ wa_F3_M64_K6144_N2048_insts.bin+ wa_F3_M256_K6144_N2048.xclbin+ wa_F3_M256_K6144_N2048_insts.bin+```++Both locations are resolved **relative to the executable**, by absolute path.+`PATH` and the working directory are not searched, so the package has to be in+that one place. Every artifact is checked against a hash built into the binary+before it is used.++Requirements: Windows, an XDNA2-class NPU, and AMD's XRT runtime installed for+the helper to load.++## When something is missing++`--xdna` always tells you what happened and always keeps running on the normal+path:++```+[XDNA] requested, but this build has no XDNA support: continuing on the normal path+[XDNA] requested, but the XDNA package was not found at <dir>\xdna: continuing on the normal path+[XDNA] requested, but the XDNA package is incomplete (missing <file>) in <dir>\xdna: ...+[XDNA] requested, but an XDNA artifact does not match its expected hash (<file>):+ refusing to use it, continuing on the normal path+[XDNA] requested, and the artifact package is valid, but the XDNA helper+ (coli_xdna.dll) is not usable beside the executable: ...+```++An artifact whose bytes do not match the expected hash is refused even though+you asked for the NPU — bytes that are not the qualified bytes are not the+qualified kernel.++When everything is in place you get the activation notice instead, once:++```+[XDNA] experimental: qualified GLM shared expert operations will use the+[XDNA] native NPU with a reduced-precision BF16 compute path. Model output+[XDNA] may differ from the normal path, and generated text has been observed+[XDNA] to diverge. Operations this lane does not support continue to use the+[XDNA] normal path.+```++All of this goes to stderr, so it never mixes into machine-readable output.++## What this backend does not do++- It is not enabled by having the hardware, the helper, or the package.+- It does not choose between the NPU and the normal path on speed or cost.+- No speed claim is made here; none has been measured in a comparable way.+- It does not extend to other models or other operations.