From 7f4d946d2ecc1d75ef6db7027ada48e86f531569 Mon Sep 17 00:00:00 2001 From: rajames Date: Wed, 7 Oct 2026 09:09:20 -0400 Subject: [PATCH] docs(v4.0.0): storage -- correct what MESH.md 8.5 said of v3's BLOCK It said a v3 VM's BLOCK gives the kernel's buffer. It does not: each v3 VM has a window of four slots in its own memory, and BLOCK copies the kernel's block into one. The entry now says what v3 does and where v4 differs from it. Co-Authored-By: Claude Opus 5.5 --- docs/v4.0.0/MESH.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/docs/v4.0.0/MESH.md b/docs/v4.0.0/MESH.md index 92b2c586..80551ec7 100644 --- a/docs/v4.0.0/MESH.md +++ b/docs/v4.0.0/MESH.md @@ -382,12 +382,27 @@ Found by review of step 6 on 2026-10-07; nothing is built for either. - **A node keeps its own copy of a block.** `BLOCK` gives the address of one of the node's two buffers, and the kernel is asked only when a block - is not in one. In v3 a VM's `BLOCK` gives the kernel's buffer, so every - VM sees one copy. Here, if node A has block *n* in a buffer and node B - writes it, A goes on reading what it had; and if A then does `UPDATE` and - `SAVE-BUFFERS`, all of B's block is overwritten. One node alone cannot - see this, and the unit test's readers had never held the block they - read. + is not in one. If node A has block *n* in a buffer and node B writes it, + A goes on reading what it had; and if A then does `UPDATE` and + `SAVE-BUFFERS`, all of B's block is overwritten. + **Corrected 2026-10-07.** This entry first said that in v3 a VM's `BLOCK` + gives the kernel's buffer, so that every VM sees one copy. That was + wrong, and was not checked against v3 before it was written. In v3 each + VM has a window of four 1 KiB slots at the top of its own memory + (`v3/include/vm.h`, `BLK_VM_SLOTS`; `v3/src/word_source/block_words.c`, + `blk_vm_load`): `BLOCK` copies the kernel's block into a slot, unless + the block is already in one, and gives the slot's address. So a v3 VM + keeps its own copy too, and two VMs can each hold a stale one, exactly + as here. Where v4 differs from v3: + - two buffers, where v3 has four slots; + - the node keeps the record of what is in them and does the asking, + where in v3 the block words are the kernel's and the kernel keeps the + record and does the copying, only ever into the window; + - `UPDATE` marks the buffer and it is written when the buffer is wanted + or at `SAVE-BUFFERS`, as FORTH-79 has it, where v3's `UPDATE` copies + the slot to the kernel at once; + - v3 lets go of every slot when the device chain changes; v4 does that + in one place only, after POST on bare metal. - **A block read over the node's own code.** The kernel checks that the 256 cells are in the node's memory and nothing more, so a request made by hand with an address in the nucleus overwrites it and the node stops.