feat(v4.0.0): the nucleus is a capsule, sent to a node born empty

MESH.md step 2.  A capsule of F18 code is the words a neighbour writes to a
node's port: for each stretch of memory, "@p a! @p push", the address and
count, "@p !+ unext" and the words; then a jump to the start.  A node born
empty executes that from its port, so it needs nothing in it beforehand.

- capsule.h/.c: v4_capsule_write, any node's memory as such a capsule
- mkimage writes the nucleus so, to capsules/v4/nucleus-64.f18, and the
  addresses a host needs as a C file; the memory image is no longer linked
  into either product
- mkcapsule is unchanged: the nucleus capsule is a built file kept under
  capsules/, as BLOCK_MAP.md is, and is baked, hashed and signed with the
  rest
- boot: the node is born empty (v4_image_born); the nucleus capsule is
  found, its hash and signature checked, and given to the node a word at a
  time as it reads its port; PARITY:V4_NUCLEUS carries its name and hash

Verified: test_fabric.c (59 checks, both widths, and under ASan and UBSan):
a memory with a programme and scattered words arrives word for word in an
empty node and runs.  The nucleus capsule rebuilds byte for byte.
hosted-check passes on three ISAs; clean qemu with STARFORTH_V4=1 on amd64,
aarch64 and riscv64 takes the nucleus in, passes POST (550 of 550) and
answers lines typed at each prompt (logs/20261006-102421, -102706,
-103048).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-06 10:33:15 -04:00
co-authored by Claude Opus 5.5
parent 9af442f793
commit 42610e844f
17 changed files with 718 additions and 88 deletions
+55
View File
@@ -0,0 +1,55 @@
/* capsule.c -- a capsule of F18 code. See capsule.h.
*
* Nothing here uses the C library.
*/
#include "v4/capsule.h"
#include "v4/iword.h"
#include "v4/opcode.h"
/* A stretch of zeros shorter than this, between words that are not zero, is
* sent with them: starting a new stretch costs four words. */
#define GAP 4u
static v4_cell words_of(unsigned a, unsigned b, unsigned c, unsigned d)
{
unsigned op[V4_SLOT_COUNT];
unsigned k;
op[0] = a; op[1] = b; op[2] = c; op[3] = d;
for (k = 4; k < V4_SLOT_COUNT; k++) op[k] = V4_OP_NOP;
return (v4_cell)v4_iword_assemble(op, 0);
}
/* `jump addr`, the jump in the first slot so that its address is as wide as
* an address can be */
static v4_cell jump_to(v4_cell addr)
{
v4_ucell mask = (v4_ucell)v4_iword_slot_mask(0);
v4_ucell word = (v4_ucell)words_of(V4_OP_JUMP, V4_OP_NOP, V4_OP_NOP, V4_OP_NOP);
return (v4_cell)((word & ~mask) | ((v4_ucell)addr & mask));
}
unsigned v4_capsule_write(const v4_node *n, v4_cell start,
void (*out)(void *self, v4_cell word), void *self)
{
unsigned k = 0, written = 0;
while (k < V4_NODE_WORDS) {
unsigned first, last, zeros, i;
if (n->mem[k] == 0) { k++; continue; }
first = last = k;
zeros = 0;
for (i = k + 1; i < V4_NODE_WORDS && zeros < GAP; i++) {
if (n->mem[i] != 0) { last = i; zeros = 0; } else zeros++;
}
out(self, words_of(V4_OP_FETCH_P, V4_OP_BANG_A, V4_OP_FETCH_P, V4_OP_PUSH));
out(self, (v4_cell)first);
out(self, (v4_cell)(last - first));
out(self, words_of(V4_OP_FETCH_P, V4_OP_STORE_INC, V4_OP_UNEXT, V4_OP_NOP));
for (i = first; i <= last; i++) out(self, n->mem[i]);
written += 4u + (last - first + 1u);
k = last + 1;
}
out(self, jump_to(start));
return written + 1u;
}
+3 -11
View File
@@ -1,34 +1,26 @@
/* image.c -- start a node from a capsule image. See image.h.
/* image.c -- the StarForth nucleus, as its host knows it. See image.h.
*
* Nothing here uses the C library: the bare-metal kernel links this file.
*/
#include "v4/image.h"
int v4_image_boot(v4_node *n, v4_exec_state *es, v4_heat *h, const v4_image *im,
int v4_image_born(v4_node *n, v4_exec_state *es, v4_heat *h, const v4_image *im,
unsigned char *disk, unsigned blocks)
{
unsigned i;
if (im->cell_bits != (unsigned)V4_CELL_BITS || im->node_words != (unsigned)V4_NODE_WORDS
|| im->data_ring != (unsigned)V4_DATA_RING || im->ret_ring != (unsigned)V4_RET_RING)
return 0;
v4_node_reset(n);
v4_node_born(n, im->port);
v4_exec_reset(es);
v4_heat_reset(h);
for (i = 0; i < im->count; i++)
if (v4_node_addr_ok(im->cells[i].addr)) n->mem[im->cells[i].addr] = im->cells[i].value;
v4_node_console_attach(n, im->console_tx);
v4_node_console_input_attach(n, im->console_rx, im->console_status);
v4_node_stack_regs_attach(n, im->dstack_reg, im->rstack_reg);
v4_node_error_attach(n, im->node_error);
v4_node_fault_attach(n, im->fault_table);
v4_node_port_attach(n, im->port);
if (disk && blocks) v4_node_storage_attach(n, im->storage_reg, disk, blocks);
n->mem[im->line_status] = V4_LINE_COMPLETED;
n->p = im->idle;
return 1;
}