feat(v4.0.0): the system boots from a nucleus and loads its capsules

One boot, v4/system/boot.c, for both products: it starts the nucleus image,
finds each capsule in the baked capsule directory, recomputes its hash,
checks its signature, gives its blocks to the node a line at a time, and
prints PARITY:V4_NUCLEUS, PARITY:V4_CAPSULE and PARITY:OK before the prompt.
A line the node does not accept ends the boot with the capsule, block and
line named.  docs/v4.0.0/NUCLEUS.md.

- hosted Linux product for amd64, aarch64 and riscv64 (make -C v4 hosted);
  make -C v4 hosted-check boots all three and requires identical output
- the kernel's v4 entry (STARFORTH_V4=1) calls the same boot
- capsules/v4/forth79.4th, block 6000: no definitions yet
- mkimage builds the nucleus only; no FORTH source is compiled at build time
- capsule_blocks.c: the Block-header parse, free of any VM, for every loader

Verified: make -C v4 test passes; hosted-check passes on the three ISAs with
the same hashes; the kernel compiles with STARFORTH_V4=1 on the three.
Not verified: no bare-metal boot of v4 has been run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-05 15:28:30 -04:00
co-authored by Claude Opus 5.5
parent 903321e548
commit 294e69463a
18 changed files with 968 additions and 8 deletions
+71
View File
@@ -0,0 +1,71 @@
/* image.h -- a capsule image: the host node's memory with the vocabulary in
* it, and what a loader needs to know to start it.
*
* The compiler capsule is text (capsule/ *.v4) and FORTH source (capsule/
* *.fth). tools/mkimage.c assembles the one and has a node compile the
* other, on the build machine, and writes what the node's memory then holds
* as a C file. A system that is to run the vocabulary -- the hosted binary,
* the bare-metal kernel -- links that file and calls v4_image_boot: it needs
* no assembler, no files and no C library.
*
* An image is for one cell width, one node size and one pair of stack sizes;
* v4_image_boot refuses an image the engine was not built for.
*/
#ifndef V4_IMAGE_H
#define V4_IMAGE_H
#include "v4/exec.h"
/* one word of memory that is not zero */
typedef struct {
v4_cell addr;
v4_cell value;
} v4_image_cell;
typedef struct {
const v4_image_cell *cells; /* every non-zero word of memory, in address order */
unsigned count;
/* what the image was built for */
unsigned cell_bits, node_words, data_ring, ret_ring;
/* where to start, and where a fault goes */
v4_cell entry; /* QUIT */
v4_cell fault_table; /* (FAULTS) */
/* KEY's code: a node whose P is in key_start .. key_end - 1 with no
* character pending is waiting for one */
v4_cell key_start, key_end;
/* the memory-mapped registers (DECOMPOSITION.md section 7; D-4 leaves
* the map to the loader, and this is the map the image was built with) */
v4_cell console_tx, console_rx, console_status;
v4_cell dstack_reg, rstack_reg;
v4_cell node_error;
v4_cell storage_reg;
/* the dictionary's two variables: DP holds HERE, a byte address, and
* LATEST the newest word of FORTH. What lies below HERE, and LATEST,
* is what the dictionary hash covers (v4/include/v4/boot.h). */
v4_cell dp, latest;
} v4_image;
/* The image built from v4/capsule (the generated file defines it). */
extern const v4_image v4_capsule_image;
/* Reset `n`, load the image into it, attach its registers -- with `disk`,
* `blocks` blocks of 1024 bytes, as its block storage, or none if `disk` is
* 0 -- and leave it about to execute its first instruction. Returns 1, or 0
* if the image is not for this build of the engine (nothing is then done).
*
* After it, the caller runs the node: v4_exec_step_word again and again,
* taking what the node prints from n->console (and setting n->console_len
* back to 0) and giving it what is typed with v4_node_console_feed. */
int v4_image_boot(v4_node *n, v4_exec_state *es, v4_heat *h, const v4_image *im,
unsigned char *disk, unsigned blocks);
/* 1 if the node is waiting for a character: it is inside KEY and none is
* pending. */
int v4_image_waiting(const v4_node *n, const v4_image *im);
#endif /* V4_IMAGE_H */