Skip to content

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.c
index 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.h
index 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 is
diff --git a/c/coli b/c/coli
index 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_workers
if getattr(a, "cluster_coordinator", None): e["CLUSTER_COORDINATOR"] = a.cluster_coordinator
if 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 the
diff --git a/c/colibri.c b/c/colibri.c
index 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");
+ }
#endif
Model m; double t0=now_s(); model_init(&m,snap,cap,ebits,dbits);
/* KV_TQ requires power-of-two row widths: both codecs rotate through a
diff --git a/c/tests/test_xdna_execution.c b/c/tests/test_xdna_execution.c
index 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.py
new file mode 100644
index 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.md
new file mode 100644
index 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.