Files
LithosAnanke/v4/include/v4/blocks.h
T
Claude 6dcfbe6740 Capsule blocks steps 3+4 for v4: capsules are placed in RAM and load their lowest block
Captain Bob ruled: Block n lands at n-R; the lowest block is
interpreted; chaining is the developer's; together, v4 first.
- v4_blocks_place_capsule copies each Block n into RAM block n - R as 16
  lines of 64, space-padded, in any file order. A later block of the
  same number overwrites. It refuses a block below R.
- The mesh's load(), its capsule reader (CAPSULE-OPEN/(LINES), so a
  child's forth79.4th via BIRTH too), boot.c and test_host_unit's model
  each place a capsule, then interpret "<lowest> LOAD".
- mkdictionary.py skips --> when it types capsules at the hosted prompt.
- The v4 capsules are renumbered into R..2R-1, landing at RAM 1900 and
  up, away from POST's blocks 0-5. Each is chained with -->, and
  centre.4th's gap at 8103 is closed.

Test first:
- test_host_blocks.c gained 6 placement checks; it failed to build
  before.
- test_mesh_boot.c checks forth79's lowest block in RAM block 1900; it
  failed before.

After: POST is 990/990; all 52 tests at 64 bits, test-32, hosted-check
and ASan/UBSan pass; the amd64 kernel builds; the dictionary has 404
words.

Logs are in logs/20261118-capsule-place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-18 20:33:21 +00:00

100 lines
5.1 KiB
C

/* SPDX-License-Identifier: LicenseRef-Starship-1.0
* Copyright (c) 2023-2026 Robert A. James
*/
/* blocks.h -- a node asks its kernel for a block.
* docs/v4.0.0/MESH.md section 8, docs/v4.0.0/ENGINE.md 3.3,
* docs/v4.0.0/V3-PARITY.md 1d.
*
* A node only ever asks for a block by number, and it asks the kernel: a
* request written to the port where its kernel is, as any kernel word is.
* This is v3's way (v3/src/word_source/block_words.c). The node has a
* WINDOW in its memory, V4_BLOCK_SLOTS slots of 256 cells, as a v3 VM has
* four slots of 1 KiB at the top of its memory. The kernel keeps the
* record of which block is in which slot and does all the copying, and it
* writes into the window and nowhere else in the node. The requests, the
* same for every node:
*
* V4_REQ_BLOCK ( n -- waddr status ) the slot that holds block n, read
* from storage if it is not in one
* V4_REQ_BUFFER ( n -- waddr status ) a slot for block n, of zeros if it
* is not in one: nothing is read
* V4_REQ_UPDATE ( -- status ) the block most recently asked for
* is marked changed
* V4_REQ_SAVE_BUFFERS ( -- status ) every block marked is written
* V4_REQ_EMPTY_BUFFERS ( -- ) every slot is let go; nothing is
* written
*
* Their numbers are below zero: the requests a host names for its own
* words (KERNEL-WORD) count up from 1.
*
* waddr is the word address of the slot, or 0 when the status is not 0.
* The status is 0; or V4_BLOCK_RANGE, there is no such block; or
* V4_BLOCK_REFUSED: storage would not have a block that had to be written,
* the stack did not hold the request's argument, or the window is not all
* in the node's memory.
*
* WHEN A BLOCK IS WRITTEN is FORTH-79's: UPDATE marks it, and it is written
* by SAVE-BUFFERS or when its slot is wanted for another block. (v3's
* UPDATE copies the slot to the kernel at once; the standard is followed.)
* A slot whose block is not marked is taken before one whose block is. A
* block that storage would not take is let go of: its slot is empty, and
* the kernel keeps the block as it was before, not what was refused.
*
* When the kernel's chain of devices changes, everything in the slots is
* let go and nothing of it is written, as v3 does (blk_vm_check_epoch).
*
* A block is 1024 bytes and 256 cells, four bytes to a cell, the first
* lowest, whatever the cell width: a block read leaves the rest of each
* cell zero, and a write takes the low 32 bits.
*
* The blocks are the kernel's block subsystem's (v3/src/block_subsystem.c).
* Who may have which block is not checked here yet (MESH.md 8.4).
*/
#ifndef V4_BLOCKS_H
#define V4_BLOCKS_H
#include "v4/node.h"
#define V4_REQ_BLOCK (-1)
#define V4_REQ_BUFFER (-2)
#define V4_REQ_UPDATE (-3)
#define V4_REQ_SAVE_BUFFERS (-4)
#define V4_REQ_EMPTY_BUFFERS (-5)
#define V4_BLOCK_OK 0
#define V4_BLOCK_REFUSED 2
#define V4_BLOCK_RANGE 3
#define V4_BLOCK_SLOTS 4u
/* What the kernel keeps for one node. */
typedef struct {
v4_cell window; /* word address of the first slot */
uint32_t block[V4_BLOCK_SLOTS]; /* the block in each slot; 0: none */
unsigned char changed[V4_BLOCK_SLOTS]; /* UPDATEd and not yet written */
unsigned next; /* where the search for a slot to take begins */
int last; /* the slot most recently asked for; -1: none */
uint64_t epoch; /* the chain as it was when the slots were filled */
} v4_blocks;
/* A node's window is at `window`, and nothing is in it. */
void v4_blocks_init(v4_blocks *w, v4_cell window);
/* If `request` is one of the five, serve it for the node and return 1.
* Otherwise touch nothing and return 0. The node is stopped, blocked at
* its port, when this is called. */
int v4_blocks_serve(v4_blocks *w, v4_node *n, v4_cell request);
/* A CAPSULE OF FORTH BLOCKS, PLACED (docs/v4.0.0/plans/2026-11-18-capsule-blocks.md). Each
* `Block n` of the capsule text from p to end is copied into the kernel's RAM block n - R, where
* R is the RAM block count (BLK_RAM_USER_BLOCKS, v3/include/blk_layout.h), as 16 lines of 64
* characters padded with spaces -- in whatever order the file has them; a later block of the same
* number overwrites an earlier one. Where a block lands is the capsule's author's affair: nothing
* checks it but that n is at least R. The lowest block placed is in *lowest, which the loader
* interprets (`LOAD`); what runs after it is the capsule's own (`-->`, `LOAD`, `THRU`). Returns
* how many blocks were placed, or -1: a block below R, a line over 64 characters or more than 16
* lines, or a block storage would not give, in which case some may have been placed. */
int v4_blocks_place_capsule(const uint8_t *p, const uint8_t *end, uint32_t *lowest);
#endif /* V4_BLOCKS_H */