Files
LithosAnanke/v4/include/v4/image.h
T
Claude 7af88cc704
Build / Image PC (push) Successful in 6m13s
Build / Image MILKV (push) Successful in 6m40s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 14m18s
Build / Image RASPI (push) Successful in 3m11s
v4 ACL: the countdown at call, as v3 -- the call hook may redirect
Captain Bob ruled "As v3: add at call", "Engine: call redirects" and
"Build it".
- The engine's call hook returns where P goes.
- The kernel checks every call from code defined at run time. A TTL is
  counted down at the call. At a TTL of 0, or a denied word, the call is
  sent to (ACL-CALL), with the target on the data stack, which rechecks
  or refuses it by the word's own name, then goes on to it.
- A word being compiled is no longer checked, as in v3.

Two things were added while building, both from v3:
- (ACL-BUSY) turns the check off while the policy rechecks. Without it
  the recheck recursed.
- (ACL-CALL) does its own refusal and leaves WORD's buffer alone. A first
  version broke POST's CONVERT.digits.

Test first: test_mesh_boot's five new checks failed before; now 120 pass
and POST is 990/990. test_exec tests the redirect. test_host_quit's two
v4-only expectations now follow v3: a denied word compiles.

All 52 tests, test-32 and ASan/UBSan pass. An amd64 session passes 18/18.
Five alternating host boots: +1.4% median, inside the noise.
DECOMPOSITION.md 5.20 is updated, and the FPGA's call opcode is recorded
as owing the same redirect.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:10:16 +00:00

139 lines
6.7 KiB
C

/* SPDX-License-Identifier: LicenseRef-Starship-1.0
* Copyright (c) 2023-2026 Robert A. James
*/
/* image.h -- the StarForth system, as its host knows it: where things are
* in a node that holds it, and how a line is handed to that node.
*
* The system is text, the .f18 blobs of capsules/v4/sys, and the machine's
* ROM assembles it when the machine starts (docs/v4.0.0/MACHINE.md; v4/
* system/boot.c). Its host knows two things of it:
*
* - the memory map, before it is built: v4_map_image, a C file that
* tools/mkmap.c writes from the map (`mkmap image`);
* - what only the assembled system knows -- where it waits, its fault
* table, KEY -- from the image record, a fixed block of RAM whose
* address is a constant of the map and which the system's source
* stores (capsules/v4/sys/end.f18): v4_image_from_node.
*
* A node that holds the system is sent text as messages and sends back
* what it prints (v4/include/v4/message.h); nothing here hands it a line.
*
* A description is for one cell width, one node size and one pair of stack
* sizes; v4_image_born refuses one the engine was not built for.
*/
#ifndef V4_IMAGE_H
#define V4_IMAGE_H
#include "v4/exec.h"
typedef struct {
/* what the image was built for */
unsigned cell_bits, node_words, data_ring, ret_ring;
/* Where the system waits for a message (capsules/v4/sys/quit.f18,
* (IDLE)): a node that holds the system begins there, and with nothing
* to do it is asleep at a wire inside it (operation 8, MESH.md 7d.3).
* This, fault_table, key_start and key_end are -1 until the system is
* built (v4_image_from_node). */
v4_cell idle;
v4_cell fault_table; /* (FAULTS): where a fault goes */
v4_cell port; /* word address of the node's port (node.h) */
/* 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 system is built with) */
v4_cell console_tx, console_rx, console_status;
v4_cell dstack_reg, rstack_reg;
v4_cell node_error;
v4_cell heat_reg; /* HEAT-OP[0]; ANTICLOCK is 32 after it (node.h, #189) */
v4_cell me; /* (ME): the node's number, which messages go by (v4/mesh.h, #189) */
/* 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;
/* What COLD returns the system to and FORGET will not go below: two
* cells, DP and LATEST as they were when the system was complete, and
* the variable (FENCE). The system's source sets them; a system that
* loads capsules when it boots sets them again when it has
* (v4_image_seal). */
v4_cell boot_cells, fence;
/* the word IDs (#189, Phase 2): (NEXT-ID), the ID the next entry is given, and (BOOT-ID), what
* it was when the system was complete, which COLD comes back to (v4_image_seal sets it) */
v4_cell next_id, boot_id;
/* (WORD-DEFINED) and (WORD-FORGOTTEN): the xts of the words a node runs when an entry is made
* and when entries go, or 0 (dict.f18); a kernel that keeps records puts its own there */
v4_cell word_defined, word_forgotten;
/* (HOT): the hot-words cache (#189, Phase 7; Captain Bob, 2026-11-13): its count, the slot the kernel
* takes next when it is full, the lookup's index, then V4_IMAGE_HOT_SIZE xts, which (LOOKUP) tries before
* the dictionary. The kernel fills it, when its build has ENABLE_HOTWORDS_CACHE; otherwise it is empty. */
v4_cell hot;
/* CONTEXT: the variable that holds the address of the vocabulary names are looked up in first (dict.f18) */
v4_cell context;
/* the tick, as v3's (#189 Phase 7): (TOKENS), which INTERPRET counts tokens in; dictionary space, the code
* defined at run time, from which a call is a word run; and where INTERPRET and EXECUTE make their calls */
v4_cell tokens, dict_lo, dict_hi, runx, exec;
/* the ACL's check at call (docs/v4.0.0/plans/2026-11-19-acl-at-call.md): the cell that holds (ACL-CALL)'s address,
* and the cell that is 1 while the policy rechecks a word */
v4_cell acl_call, acl_busy;
/* the block window: the word address of the slots the kernel copies
* blocks into (v4/blocks.h) */
v4_cell block_window;
/* the image record (capsules/v4/sys/end.f18): four cells, where the
* system waits, its fault table, KEY and the word after KEY; and the
* ROM's two cells that say why it stopped, if it did: the code of its
* error (0 if none) and the line it was on, counting from 0 */
v4_cell record, rom_failed, rom_errline;
} v4_image;
/* The system's error for a node blocked at a port with no one on it
* (capsules/v4/sys/core.f18's list; node.h, v4_node_port_gone): "No one on
* that port". */
#define V4_ERROR_NO_ONE 18
/* The memory map's description of the system (the generated file defines
* it): what is known of it before it is built. */
extern const v4_image v4_map_image;
#define V4_IMAGE_HOT_SIZE 32 /* v3's HOTWORDS_CACHE_SIZE */
/* What only the assembled system knows, read from the image record of the
* node `n` that holds it into `im`, which the map's description is in.
* Returns 1, or 0 if the record does not name addresses of the node's
* memory (nothing is then changed). */
int v4_image_from_node(const v4_node *n, v4_image *im);
/* The system is complete: what is in the dictionary now is what COLD comes
* back to, and FORGET will not go below it. */
void v4_image_seal(v4_node *n, const v4_image *im);
/* The dictionary hash of a node started from `im`: FNV-1a over its memory
* below HERE, a cell at a time, low byte first, and then LATEST. It does
* not depend on the machine: every build of one commit, with one cell
* width, gives the same hash for the same dictionary. */
uint64_t v4_image_dict_hash(const v4_node *n, const v4_image *im);
/* A node newly born (node.h), with the registers the system expects of the
* node it runs on. Its memory is empty and it is blocked
* reading its ports: its code is yet to be sent to it, or assembled on it. Returns 1, or 0
* if the description is not for this build of the engine (nothing is then
* done). */
int v4_image_born(v4_node *n, v4_exec_state *es, v4_heat *h, const v4_image *im);
/* 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 */