/* SPDX-License-Identifier: LicenseRef-Starship-1.0 * Copyright (c) 2023-2026 Robert A. James */ /* f18a.c -- build a train's engine (f18a.h). */ #define _POSIX_C_SOURCE 200809L #include "f18a.h" #include "v4/artifact.h" #include "v4/effect.h" #include "v4/text.h" #include "starkernel/sha512.h" #include "starkernel/xxhash64.h" #include #include #include #include #include #include #define MAX_FILES 256u #define MAX_RECORD 65536u static v4_node n; /* large: not on the stack */ static v4_text tx; typedef struct { /* an import, resolved */ uint64_t id; v4_effect fx; uint32_t caps; /* the exporter's unit 5: the port bit */ uint32_t req[64]; unsigned nreq; } import_t; typedef struct { char *err; size_t errlen; int failed; import_t *imp; unsigned nimp; v4_text_addr *rec; uint32_t *pool; size_t npool, cappool; } build_t; static int fail(build_t *b, const char *fmt, ...) { va_list ap; if (b->failed) return 0; b->failed = 1; va_start(ap, fmt); vsnprintf(b->err, b->errlen, fmt, ap); va_end(ap); return 0; } static char *read_file(const char *path, size_t *len) { FILE *f = fopen(path, "rb"); char *buf = NULL; long size; if (!f) return NULL; if (fseek(f, 0, SEEK_END) == 0 && (size = ftell(f)) >= 0 && fseek(f, 0, SEEK_SET) == 0 && (buf = malloc((size_t)size + 1u)) != NULL && fread(buf, 1, (size_t)size, f) == (size_t)size) { buf[size] = 0; *len = (size_t)size; } else { free(buf); buf = NULL; } fclose(f); return buf; } static const char *base_of(const char *path) { const char *s = strrchr(path, '/'); return s ? s + 1 : path; } /* the provenance's framing: the name, a NUL, the length in 8 bytes low first, the bytes */ static void frame(sha512_ctx_t *c, const char *name, const char *bytes, size_t len) { unsigned char l8[8]; unsigned i; for (i = 0; i < 8; i++) l8[i] = (unsigned char)((unsigned long long)len >> (8 * i)); sha512_update(c, (const uint8_t *)name, strlen(name) + 1u); sha512_update(c, l8, 8); sha512_update(c, (const uint8_t *)bytes, len); } static int frame_file(build_t *b, sha512_ctx_t *c, const char *name, const char *path) { size_t len; char *t = read_file(path, &len); if (!t) return fail(b, "cannot read %s", path); frame(c, name, t, len); free(t); return 1; } static int by_name(const void *x, const void *y) { return strcmp(*(char *const *)x, *(char *const *)y); } /* the names in `dir` that end in `ext`, sorted; how many, or -1 */ static int list(const char *dir, const char *ext, char **names, unsigned max) { DIR *d = opendir(dir); struct dirent *e; unsigned c = 0; size_t el = strlen(ext); if (!d) return -1; while ((e = readdir(d)) != NULL) { size_t l = strlen(e->d_name); if (l <= el || strcmp(e->d_name + l - el, ext) != 0) continue; if (c == max) { closedir(d); return -1; } names[c] = malloc(l + 1u); if (!names[c]) { closedir(d); return -1; } memcpy(names[c], e->d_name, l + 1u); c++; } closedir(d); qsort(names, c, sizeof names[0], by_name); return (int)c; } /* ---- the string pool: unit 0 is 0, so an offset of 0 is "none" ---- */ static uint32_t pool_unit(build_t *b, uint32_t v) { if (b->npool == b->cappool) { size_t c = b->cappool ? b->cappool * 2u : 256u; uint32_t *g = realloc(b->pool, c * sizeof *g); if (!g) { fail(b, "out of memory"); return 0; } b->pool = g; b->cappool = c; } b->pool[b->npool] = v; return (uint32_t)b->npool++; } static uint32_t pool_string(build_t *b, const char *s) { size_t len = strlen(s), i; uint32_t first = (uint32_t)b->npool; unsigned char bytes[260]; if (len > 255u) { fail(b, "a name too long: %s", s); return 0; } memset(bytes, 0, sizeof bytes); bytes[0] = (unsigned char)len; memcpy(bytes + 1, s, len); for (i = 0; i < (1u + len + 3u) / 4u; i++) pool_unit(b, (uint32_t)bytes[4 * i] | ((uint32_t)bytes[4 * i + 1] << 8) | ((uint32_t)bytes[4 * i + 2] << 16) | ((uint32_t)bytes[4 * i + 3] << 24)); return first; } /* ---- imports ---- */ static int import_effect(void *ctx, v4_cell addr, v4_effect *out) { build_t *b = ctx; unsigned k; for (k = 0; k < b->nimp; k++) if (addr == V4_TEXT_IMPORT_ADDR(k)) { *out = b->imp[k].fx; return 1; } return 0; } static int resolve_import(build_t *b, const f18a_args *a, unsigned k) { const char *train, *name; unsigned char *art; size_t len; unsigned i, j; v4_f18a_layout l; const char *why; import_t *im = &b->imp[k]; v4_text_import_at(&tx, k, &train, &name); for (i = 0; i < a->ntrains && strcmp(a->trains[i].name, train) != 0; i++) ; if (i == a->ntrains) return fail(b, "import of %s from %s, a train not given", name, train); art = (unsigned char *)read_file(a->trains[i].path, &len); if (!art) return fail(b, "cannot read %s, the train %s", a->trains[i].path, train); if (!v4_f18a_check(art, len, V4_CELL_BITS, &l, &why)) { free(art); return fail(b, "the train %s: %s", train, why); } im->id = xxhash64(art, len, 0); for (j = 0; j < l.e; j++) { size_t x = l.exports + V4_F18A_EXPORT * (size_t)j; const unsigned char *p = art + (l.pool + v4_f18a_unit(art, x)) * 4u; if (p[0] == strlen(name) && memcmp(p + 1, name, p[0]) == 0) { uint32_t d = v4_f18a_unit(art, x + 3), r = v4_f18a_unit(art, x + 4), caps = v4_f18a_unit(art, x + 5); im->fx.fixed = 1; im->fx.d_taken = d & 0xFFFFu; im->fx.d_left = d >> 16; im->fx.r_taken = r & 0xFFFFu; im->fx.r_left = r >> 16; im->caps = caps & V4_F18A_PORTS; im->nreq = 0; if (caps & ~V4_F18A_PORTS) { uint32_t off = caps & ~V4_F18A_PORTS, cnt = v4_f18a_unit(art, l.pool + off), q; for (q = 0; q < cnt && im->nreq < 64u; q++) im->req[im->nreq++] = v4_f18a_unit(art, l.pool + off + 1u + q); } free(art); return 1; } } free(art); return fail(b, "the train %s does not export %s", train, name); } /* ---- capabilities: what a word can be seen to need, and what the words it calls declare ---- */ static int has_req(const v4_cell *req, unsigned nreq, v4_cell r) { unsigned i; for (i = 0; i < nreq; i++) if (req[i] == r) return 1; return 0; } static int word_info_at(v4_cell addr, v4_text_word_info *out) { unsigned i; for (i = 0; i < v4_text_word_count(&tx); i++) if (v4_text_word_at(&tx, i, out) && out->addr == addr) return 1; return 0; } /* Walk word `w`'s code from its entry, as effect.c does, and check what it is seen to need against what * it declares. Within an instruction word, the literals and where A and B were set from them are * followed: a store of a known number to the kernel's port is a request; any other use of the node's * ports is "ports". Calls: the callee's declared needs. */ static int check_caps(build_t *b, const v4_text_word_info *w, v4_cell code_end, int has_port, v4_cell port) { v4_cell *todo, *seen; size_t ntodo = 0, nseen = 0, cap = (size_t)code_end + 8u; int ok = 1; todo = malloc(cap * sizeof *todo); seen = calloc((size_t)code_end + 1u, sizeof *seen); if (!todo || !seen) { free(todo); free(seen); return fail(b, "out of memory"); } todo[ntodo++] = w->addr; while (ntodo && ok) { v4_cell at = todo[--ntodo], p; v4_iword word; v4_cell val[8]; int known[8]; int sp = 0; /* the top few cells of the data stack, as far as known */ v4_cell areg = 0, breg = 0; int aknown = 0, bknown = 0; unsigned slot; if (at < 0 || at >= code_end || seen[at]) continue; seen[at] = 1; nseen++; word = (v4_iword)n.mem[at]; p = at + 1; #define PUSHV(v, k) do { if (sp < 8) { val[sp] = (v); known[sp] = (k); sp++; } else { memmove(val, val + 1, 7 * sizeof val[0]); memmove(known, known + 1, 7 * sizeof known[0]); val[7] = (v); known[7] = (k); } } while (0) #define POPV() (sp > 0 ? (sp--, known[sp]) : 0) #define TOPV() (sp > 0 ? val[sp - 1] : 0) #define TOPK() (sp > 0 ? known[sp - 1] : 0) for (slot = 0; slot < V4_SLOT_COUNT && ok; slot++) { unsigned op = v4_iword_op(word, slot); v4_cell t; int is_port_a = has_port && aknown && areg >= port && areg <= port + (v4_cell)V4_PORT_HAVE; int is_port_b = has_port && bknown && breg >= port && breg <= port + (v4_cell)V4_PORT_HAVE; switch (op) { case V4_OP_SEMI: case V4_OP_EX: slot = V4_SLOT_COUNT; p = -1; break; case V4_OP_JUMP: case V4_OP_CALL: case V4_OP_IF: case V4_OP_MINUS_IF: case V4_OP_NEXT: t = v4_iword_branch(p, word, slot); if (op == V4_OP_CALL || (op == V4_OP_JUMP && (t < 0 || t >= code_end))) { v4_text_word_info cw; unsigned k, r; int cports = 0; const v4_cell *creq = NULL; unsigned cnreq = 0; v4_cell ireq[64]; if (t >= 0 && t < code_end && word_info_at(t, &cw)) { cports = cw.ports; creq = cw.req; cnreq = cw.nreq; } else if (t >= 0 && t < code_end) { if ((size_t)ntodo < cap) todo[ntodo++] = t; } else for (k = 0; k < b->nimp; k++) if (t == V4_TEXT_IMPORT_ADDR(k)) { cports = (b->imp[k].caps & V4_F18A_PORTS) != 0; for (r = 0; r < b->imp[k].nreq; r++) ireq[r] = (v4_cell)b->imp[k].req[r]; creq = ireq; cnreq = b->imp[k].nreq; } if (cports && !w->ports) ok = fail(b, "%s calls a word that touches ports, and does not declare ports", w->name); for (r = 0; ok && r < cnreq; r++) if (!has_req(w->req, w->nreq, creq[r])) ok = fail(b, "%s calls a word that makes request %ld, and does not declare that request", w->name, (long)creq[r]); if (op == V4_OP_JUMP) p = -1; } else if (t >= 0 && t < code_end) { if ((size_t)ntodo < cap) todo[ntodo++] = t; if (op == V4_OP_JUMP) p = -1; } slot = V4_SLOT_COUNT; break; case V4_OP_UNEXT: break; case V4_OP_FETCH_P: PUSHV(n.mem[p], 1); p++; break; case V4_OP_BANG_A: aknown = TOPK(); areg = TOPV(); (void)POPV(); break; case V4_OP_BANG_B: bknown = TOPK(); breg = TOPV(); (void)POPV(); break; case V4_OP_STORE_A: case V4_OP_STORE_INC: case V4_OP_STORE_B: { int through_port = (op == V4_OP_STORE_B) ? is_port_b : is_port_a; v4_cell where = (op == V4_OP_STORE_B) ? breg : areg; if (through_port) { if (where == port && TOPK()) { if (!has_req(w->req, w->nreq, TOPV())) ok = fail(b, "%s makes request %ld, and does not declare that request", w->name, (long)TOPV()); } else if (!w->ports) ok = fail(b, "%s touches ports, and does not declare ports", w->name); } (void)POPV(); if (op == V4_OP_STORE_INC) aknown = 0; break; } case V4_OP_STORE_P: (void)POPV(); p++; break; case V4_OP_FETCH_A: case V4_OP_FETCH_INC: case V4_OP_FETCH_B: { int through_port = (op == V4_OP_FETCH_B) ? is_port_b : is_port_a; if (through_port && !w->ports) ok = fail(b, "%s touches ports, and does not declare ports", w->name); if (op == V4_OP_FETCH_INC) aknown = 0; PUSHV(0, 0); break; } case V4_OP_DUP: { v4_cell v = TOPV(); int k = TOPK(); PUSHV(v, k); break; } case V4_OP_OVER: case V4_OP_PUSH_A: case V4_OP_RPOP: PUSHV(0, 0); break; case V4_OP_DROP: case V4_OP_PUSH: (void)POPV(); break; case V4_OP_ADD: case V4_OP_AND: case V4_OP_XOR: (void)POPV(); (void)POPV(); PUSHV(0, 0); break; case V4_OP_TWO_STAR: case V4_OP_TWO_SLASH: case V4_OP_INV: case V4_OP_MUL_STEP: (void)POPV(); PUSHV(0, 0); break; default: break; } } #undef PUSHV #undef POPV #undef TOPV #undef TOPK if (p >= 0 && ok && (size_t)ntodo < cap) todo[ntodo++] = p; /* on into the next word */ } free(todo); free(seen); return ok; } /* ---- the artifact ---- */ static void put_unit(unsigned char *o, size_t u, uint32_t v) { o[4 * u] = (unsigned char)v; o[4 * u + 1] = (unsigned char)(v >> 8); o[4 * u + 2] = (unsigned char)(v >> 16); o[4 * u + 3] = (unsigned char)(v >> 24); } int f18a_build(const f18a_args *a, unsigned char **out, size_t *len, char *err, size_t errlen) { static const char *const tool_files[] = { "tools/mkf18a.c", "tools/f18a.c", "tools/f18a.h", "src/artifact.c", "src/asm.c", "src/effect.c", "src/iword.c", "src/text.c", }; build_t b; char *names[MAX_FILES], path[1024]; int nfiles = 0, i; unsigned k, e = 0, nwords; v4_cell code_end, port = 0; int has_port; v4_effects *fx = NULL; unsigned char prov[4][64]; unsigned char *o = NULL; size_t total, u; uint32_t *exp_units = NULL; v4_text_word_info wi; memset(&b, 0, sizeof b); b.err = err; b.errlen = errlen; err[0] = 0; *out = NULL; *len = 0; b.rec = malloc(MAX_RECORD * sizeof *b.rec); if (!b.rec) return fail(&b, "out of memory"); pool_unit(&b, 0); /* assemble: the map, then the train's .f18 in name order, at 0 */ nfiles = list(a->dir, ".f18", names, MAX_FILES); if (nfiles < 0) { free(b.rec); return fail(&b, "cannot list %s", a->dir); } if (nfiles == 0) fail(&b, "%s holds no .f18", a->dir); v4_node_reset(&n); v4_text_begin(&tx, &n, 0); v4_text_record(&tx, b.rec, MAX_RECORD); if (!b.failed && !v4_text_assemble_file(&tx, a->map)) fail(&b, "%s", v4_text_error(&tx)); for (i = 0; i < nfiles && !b.failed; i++) { snprintf(path, sizeof path, "%s/%s", a->dir, names[i]); if (!v4_text_assemble_file(&tx, path)) fail(&b, "%s", v4_text_error(&tx)); } if (!b.failed && !v4_text_finish(&tx)) fail(&b, "%s", v4_text_error(&tx)); code_end = v4_text_here(&tx); if (!b.failed && v4_text_latest(&tx) != 0) fail(&b, "a header in a train's source: placement makes the entries"); if (!b.failed && v4_text_start(&tx) >= 0) fail(&b, "a start in a train's source: a train is not started"); if (!b.failed) { v4_cell w; for (w = code_end; w < (v4_cell)V4_NODE_WORDS; w++) if (n.mem[w] != 0) { fail(&b, "a store outside the code, at %ld: a train's source may not store", (long)w); break; } } has_port = v4_text_value(&tx, "(PORT)", &port); /* the imports, then the effects */ b.nimp = v4_text_import_count(&tx); b.imp = calloc(b.nimp + 1u, sizeof *b.imp); if (!b.imp) fail(&b, "out of memory"); for (k = 0; k < b.nimp && !b.failed; k++) resolve_import(&b, a, k); if (!b.failed && !(fx = v4_effects_new(&n, 0, code_end, import_effect, &b))) fail(&b, "out of memory"); /* the exports: every : word with a fixed effect; each word's capabilities checked */ nwords = v4_text_word_count(&tx); exp_units = calloc((size_t)nwords * V4_F18A_EXPORT + 1u, sizeof *exp_units); if (!exp_units) fail(&b, "out of memory"); for (k = 0; k < nwords && !b.failed; k++) { v4_effect ef; uint32_t *x; v4_text_word_at(&tx, k, &wi); if (!check_caps(&b, &wi, code_end, has_port, port)) break; ef = v4_effect_of(fx, wi.addr, (wi.flags & 8) ? V4_EFFECT_INLINE : V4_EFFECT_CALLED); if (!ef.fixed) continue; if (strlen(wi.name) > 31u) { fail(&b, "%s: an export's name is at most 31 characters, as the dictionary's", wi.name); break; } x = exp_units + (size_t)e * V4_F18A_EXPORT; x[0] = pool_string(&b, wi.name); x[1] = (uint32_t)wi.addr; x[2] = (uint32_t)wi.flags; x[3] = (uint32_t)ef.d_taken | ((uint32_t)ef.d_left << 16); x[4] = (uint32_t)ef.r_taken | ((uint32_t)ef.r_left << 16); x[5] = wi.ports ? V4_F18A_PORTS : 0u; if (wi.nreq) { unsigned q; uint32_t off = pool_unit(&b, wi.nreq); for (q = 0; q < wi.nreq; q++) pool_unit(&b, (uint32_t)wi.req[q]); x[5] |= off; } e++; } /* the relocations: every branch can reach every word of a node */ for (k = 0; k < v4_text_addresses(&tx) && !b.failed; k++) { const v4_text_addr *r = &b.rec[k]; if (r->cell < 0 || r->cell >= code_end) fail(&b, "an address outside the code, at %ld", (long)r->cell); else if (r->slot < 4u && (v4_ucell)v4_iword_slot_mask(r->slot) < (v4_ucell)(V4_NODE_WORDS - 1u)) fail(&b, "a branch at %ld that cannot reach every word of a node", (long)r->cell); } /* the provenance */ if (!b.failed) { sha512_ctx_t c; char cfg[256]; size_t ml; char *map; char *hnames[MAX_FILES]; int nh; sha512_init(&c); for (i = 0; i < nfiles && !b.failed; i++) { snprintf(path, sizeof path, "%s/%s", a->dir, names[i]); frame_file(&b, &c, names[i], path); } sha512_final(&c, prov[0]); sha512_init(&c); for (k = 0; k < sizeof tool_files / sizeof tool_files[0] && !b.failed; k++) { snprintf(path, sizeof path, "%s/%s", a->tool_root, tool_files[k]); frame_file(&b, &c, tool_files[k], path); } snprintf(path, sizeof path, "%s/include/v4", a->tool_root); nh = list(path, ".h", hnames, MAX_FILES); if (nh < 0) fail(&b, "cannot list %s", path); for (i = 0; i < nh; i++) { char name[300]; snprintf(name, sizeof name, "include/v4/%s", hnames[i]); snprintf(path, sizeof path, "%s/%s", a->tool_root, name); if (!b.failed) frame_file(&b, &c, name, path); free(hnames[i]); } sha512_final(&c, prov[1]); sha512_init(&c); snprintf(cfg, sizeof cfg, "V4_CELL_BITS=%d V4_NODE_WORDS=%u V4_DATA_RING=%u V4_RET_RING=%u V4_ROM_WORDS=%u", V4_CELL_BITS, (unsigned)V4_NODE_WORDS, (unsigned)V4_DATA_RING, (unsigned)V4_RET_RING, (unsigned)V4_ROM_WORDS); frame(&c, "config", cfg, strlen(cfg)); map = read_file(a->map, &ml); if (!map) fail(&b, "cannot read %s", a->map); else { frame(&c, base_of(a->map), map, ml); free(map); } sha512_final(&c, prov[2]); sha512_init(&c); frame_file(&b, &c, base_of(a->rom), a->rom); sha512_final(&c, prov[3]); } /* write it */ if (!b.failed) { size_t exports = V4_F18A_HEADER + V4_F18A_PROV, imports = exports + (size_t)V4_F18A_EXPORT * e; size_t relocs = imports + (size_t)V4_F18A_IMPORT * b.nimp; size_t verify = relocs + (size_t)V4_F18A_RELOC * v4_text_addresses(&tx); size_t pool = verify + V4_F18A_VERIFY, code = pool + b.npool; unsigned cb = V4_CELL_BITS / 8u, q; uint32_t *imp_names = calloc(b.nimp + 1u, sizeof *imp_names); for (k = 0; k < b.nimp && imp_names; k++) { const char *train, *name; v4_text_import_at(&tx, k, &train, &name); imp_names[k] = pool_string(&b, name); } if (!imp_names) fail(&b, "out of memory"); code = pool + b.npool; total = code * 4u + (size_t)code_end * cb; o = b.failed ? NULL : calloc(total, 1); if (!b.failed && !o) fail(&b, "out of memory"); if (o) { put_unit(o, 0, V4_F18A_MAGIC); put_unit(o, 1, V4_F18A_ABI); put_unit(o, 2, (uint32_t)V4_CELL_BITS); put_unit(o, 3, (uint32_t)V4_NODE_WORDS); put_unit(o, 4, e); put_unit(o, 5, b.nimp); put_unit(o, 6, v4_text_addresses(&tx)); put_unit(o, 7, (uint32_t)b.npool); put_unit(o, 8, (uint32_t)code_end); put_unit(o, 9, (uint32_t)exports); for (q = 0; q < 4; q++) memcpy(o + (V4_F18A_HEADER + 16u * q) * 4u, prov[q], 64); for (u = 0; u < (size_t)e * V4_F18A_EXPORT; u++) put_unit(o, exports + u, exp_units[u]); for (k = 0; k < b.nimp; k++) { size_t x = imports + (size_t)V4_F18A_IMPORT * k; const v4_effect *f = &b.imp[k].fx; put_unit(o, x, (uint32_t)b.imp[k].id); put_unit(o, x + 1, (uint32_t)(b.imp[k].id >> 32)); put_unit(o, x + 2, imp_names[k]); put_unit(o, x + 3, (uint32_t)f->d_taken | ((uint32_t)f->d_left << 16)); put_unit(o, x + 4, (uint32_t)f->r_taken | ((uint32_t)f->r_left << 16)); } for (k = 0; k < v4_text_addresses(&tx); k++) { const v4_text_addr *r = &b.rec[k]; put_unit(o, relocs + 2u * k, (uint32_t)r->cell | ((uint32_t)r->slot << 29)); put_unit(o, relocs + 2u * k + 1u, r->import < 0 ? V4_F18A_INTERNAL : (uint32_t)r->import); } for (u = 0; u < b.npool; u++) put_unit(o, pool + u, b.pool[u]); for (u = 0; u < (size_t)code_end; u++) { v4_ucell v = (v4_ucell)n.mem[u]; for (q = 0; q < cb; q++) o[code * 4u + u * cb + q] = (unsigned char)(v >> (8u * q)); } *out = o; *len = total; } free(imp_names); } for (i = 0; i < nfiles; i++) free(names[i]); if (fx) v4_effects_free(fx); free(exp_units); free(b.imp); free(b.pool); free(b.rec); return !b.failed; }