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 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-07 09:09:20 -04:00
co-authored by Claude Opus 5.5
parent bcfd6556a8
commit 7f4d946d2e
+21 -6
View File
@@ -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.