ENGINE step 4 Phase 2 (plan docs/v4.0.0/plans/2026-11-13-engine-step4-phase2-word-accounts.md). Rulings, Captain Bob 2026-11-13: "ID field in the header"; "Per heartbeat tick"; the ACL "All of it in Phase 4". - The word ID, at xt-4 before the flags (ENGINE.md 3b). The system's words are numbered as they are assembled, by a new directive, #id, (and #ids, the count), in the C assembler (text.c) and in the machine ROM's (capsules/v4/rom), which counts in the system's own (NEXT-ID). (HEADER) numbers later words; FORGET gives back the IDs it frees, always the newest; COLD resets to (BOOT-ID); (SEAL) records it. All 313 system headers carry the cell. - The kernel's records (v4/mesh.h): (TELL-DEFINED) and (TELL-FORGOTTEN), requests -19/-20 on port 0, which the kernel puts in (WORD-DEFINED)/(WORD-FORGOTTEN) when it seals a node, and reads the system's own words once. A bit per address marks a word's xt (calls into the ROM or headerless code are not words); at call, the bit test and a count. v4_mesh_charge hands the owner the calls since. - The Stadium: stadium_words_charge -- N calls as N of stadium_word_dispatch's dispatches, shared by calls when the reservoir is short; sk_v4.c charges every node's words at the tick beside its opcodes, and stadium_word_forget before an ID is used again. - Tests first: test_text.c, test_host_dict.c, test_host_quit.c (numbering, FORGET, COLD), test_mesh_boot.c (44 checks), kernel/tests/test_stadium_words.c; qemu_session.py: Hera's words admitted after POST. - amd64: Stadium words: promotions=141 after POST, CONSERVED; POST 539/539; word_count=377; dict_hash 0xa854ba15b437d288 (the new cell); the boot 142 s against Phase 1's 153 s. - v4 test, test-32: all pass; v4-checks: 80 programs under the sanitizers, 0 failures; the hosted builds alike. docs/reference/v4-dictionary.tsv: the two new words; FABRIC-3 XLVIII.24. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
191 lines
8.7 KiB
C
191 lines
8.7 KiB
C
/* SPDX-License-Identifier: LicenseRef-Starship-1.0
|
|
* Copyright (c) 2023-2026 Robert A. James
|
|
*/
|
|
/* text.h -- assemble definitions written as text onto a node.
|
|
*
|
|
* Until now every DECOMPOSITION.md definition was retyped by hand in the
|
|
* tests as calls to the slot packer (asm.h), one opcode at a time. This
|
|
* reads the definitions as they are written in the document instead:
|
|
*
|
|
* : EMIT ( c -- ) CONSOLE-TX b! !b ;
|
|
* : SPACE 32 jump EMIT
|
|
*
|
|
* and lays them down through the same slot packer, so the words it produces
|
|
* are the ones the hand-written calls would have produced. It is test
|
|
* support, like asm.h: it is not the compiler capsule (JUSTIFICATION.md
|
|
* section 9), which is itself v4 code and will be assembled by this.
|
|
*
|
|
* THE NOTATION. Tokens are separated by white space. Names are case
|
|
* sensitive; the 32 opcode mnemonics are lower case.
|
|
*
|
|
* \ ... comment to the end of the line
|
|
* ( ... ) comment to the closing parenthesis
|
|
* : NAME start the word NAME at the next instruction word. A
|
|
* word ends where the next one starts; `;` is the return
|
|
* opcode and a word may hold several, or none (it then
|
|
* runs on into the next word).
|
|
* NAME call the word NAME. It may be defined later in the
|
|
* text, or in a later call to v4_text_assemble.
|
|
* 123 -5 $FF a literal: `@p` and its value. Decimal, or hex after $.
|
|
* It must fit a cell, as a signed or an unsigned number.
|
|
* CONST a constant given by v4_text_constant: a literal.
|
|
* CONST+N the constant plus the number N: one literal. (Only when
|
|
* the whole token is not itself a name.)
|
|
* &NAME the address of the word NAME, which must already be
|
|
* defined: a literal.
|
|
* ; + dup a! ... an opcode. `@p` cannot be written; write the number.
|
|
* jump X call X if X -if X next X
|
|
* a branch to X: a label of this word if it has one of
|
|
* that name, before or after the branch; otherwise a word.
|
|
* LABEL: a label, at the next instruction word. Labels belong
|
|
* to the word they are in and may be used before they
|
|
* are defined.
|
|
* FOR ... NEXT `push`, then the body, then `next` back to the body.
|
|
* FOR ... UNEXT the same with `unext`: the body and the `unext` must
|
|
* fit one instruction word and hold no literal.
|
|
* macro NAME ... endmacro
|
|
* NAME stands for the tokens between, wherever it is
|
|
* written afterwards (the document's "in line"). A macro
|
|
* may use other macros; it may not define a word, a label
|
|
* or a macro.
|
|
*
|
|
* constant NAME VALUE
|
|
* NAME is the number VALUE, as v4_text_constant gives it.
|
|
*
|
|
* #, VALUE one cell of data at the next word address (the word
|
|
* being built is ended first). VALUE is a number, a
|
|
* constant, CONST+N, or &NAME of a word already defined.
|
|
* ", TOKEN TOKEN, whatever its characters, as a counted string: its
|
|
* count byte, then its characters, four to a cell, low
|
|
* byte first, zero-padded to a whole cell.
|
|
*
|
|
* set NAME VALUE an assembler variable: like a constant, but it may be
|
|
* set again (the newest value is its value). In code it
|
|
* is a literal.
|
|
* here as a VALUE: the next word address, the word being built
|
|
* ended first. Not something to assemble on its own.
|
|
* store ADDR VALUE ADDR, a VALUE that is a word of RAM, is given VALUE: the
|
|
* state the system is switched on in.
|
|
* start NAME the end of the text: every branch must have its target,
|
|
* and NAME, a word, is where the system starts
|
|
* (v4_text_start). Nothing may follow.
|
|
* These four, constant, #, and ", are the ROM's language
|
|
* (docs/v4.0.0/MACHINE.md): the ROM assembles the same
|
|
* text the same way.
|
|
*
|
|
* header NAME a dictionary entry for NAME (capsules/v4/sys/dict.f18), laid down
|
|
* in front of the word that the next `:` starts, and
|
|
* linked to the header before it. NAME is taken as it
|
|
* stands -- it may be ( or \ or + -- and is at most 31
|
|
* characters. Between it and the `:` may come the flags
|
|
* immediate, data, inline and compile-only. The word after
|
|
* `:` is the assembler's name for the code, as always, and
|
|
* need not be the same: header + inline : PLUS + ;
|
|
*
|
|
* A name is looked up in this order: opcode, macro, number, constant, label
|
|
* (for a branch target), word. So an opcode's name cannot be redefined, and
|
|
* the FORTH words that share one (`@`, `!`, `+`, ...) are written as their
|
|
* opcode sequences.
|
|
*
|
|
* BRANCH PLACEMENT. A branch's address field is what is left of its word, so
|
|
* it reaches less the later its slot. The slot packer refuses a branch that
|
|
* cannot reach its target; this never asks it to: a branch is put in a slot
|
|
* only if that slot reaches the whole node (at 1024 words, every legal slot),
|
|
* and otherwise starts a new word.
|
|
*
|
|
* ERRORS. The first error stops the assembly and is kept: v4_text_error
|
|
* gives a message with the line number, and every later call does nothing.
|
|
*/
|
|
#ifndef V4_TEXT_H
|
|
#define V4_TEXT_H
|
|
|
|
#include "v4/asm.h"
|
|
|
|
#define V4_TEXT_MAX_SYMBOLS 2048u /* words, constants and macros */
|
|
#define V4_TEXT_MAX_LABELS 64u /* in one word */
|
|
#define V4_TEXT_MAX_REFS 1024u /* branches whose target is not known yet */
|
|
#define V4_TEXT_POOL 65536u /* characters of names and macro text */
|
|
#define V4_TEXT_MAX_TOKEN 63u
|
|
#define V4_TEXT_MAX_DEPTH 8u /* macros inside macros; FOR inside FOR */
|
|
|
|
typedef struct {
|
|
unsigned name; /* offset into pool */
|
|
unsigned char kind;
|
|
v4_cell value; /* address, constant, or macro text offset */
|
|
} v4_text_symbol;
|
|
|
|
typedef struct {
|
|
unsigned name;
|
|
v4_asm_ref ref;
|
|
unsigned line;
|
|
int local; /* may still turn out to be a label of this word */
|
|
} v4_text_ref;
|
|
|
|
typedef struct {
|
|
v4_asm as;
|
|
|
|
v4_text_symbol sym[V4_TEXT_MAX_SYMBOLS];
|
|
unsigned nsym;
|
|
|
|
struct { unsigned name; v4_cell addr; } label[V4_TEXT_MAX_LABELS];
|
|
unsigned nlabel;
|
|
|
|
v4_text_ref ref[V4_TEXT_MAX_REFS];
|
|
unsigned nref;
|
|
|
|
v4_cell for_addr[V4_TEXT_MAX_DEPTH];
|
|
unsigned nfor;
|
|
|
|
char pool[V4_TEXT_POOL];
|
|
unsigned pool_used;
|
|
|
|
v4_cell latest; /* xt of the newest header, 0 if none */
|
|
v4_cell start; /* the word `start` named, -1 if none yet */
|
|
int header_pending; /* a header waits for its `:` */
|
|
v4_cell next_id; /* the next word ID a header is given (#189, Phase 2) */
|
|
|
|
unsigned line;
|
|
int failed;
|
|
char message[224];
|
|
} v4_text;
|
|
|
|
/* Start assembling at word address `origin` of node `n`. */
|
|
void v4_text_begin(v4_text *t, v4_node *n, v4_cell origin);
|
|
|
|
/* Give NAME a value; written in the text it is a literal. */
|
|
void v4_text_constant(v4_text *t, const char *name, v4_cell value);
|
|
|
|
/* Assemble `source`, a NUL-terminated string. May be called several times;
|
|
* words, constants and macros carry over, labels do not. Returns 1 if there
|
|
* has been no error. */
|
|
int v4_text_assemble(v4_text *t, const char *source);
|
|
|
|
/* The same for the text in the file at `path`. Its errors name the file. */
|
|
int v4_text_assemble_file(v4_text *t, const char *path);
|
|
|
|
/* Finish: every branch must have found its target. Returns 1 if there has
|
|
* been no error. Assembling may continue afterwards. */
|
|
int v4_text_finish(v4_text *t);
|
|
|
|
/* The address of the word NAME, or -1 if there is none. */
|
|
v4_cell v4_text_word(const v4_text *t, const char *name);
|
|
|
|
/* The xt of the newest `header`, 0 if there has been none: what the
|
|
* dictionary's LATEST starts as. */
|
|
v4_cell v4_text_latest(const v4_text *t);
|
|
|
|
/* The value of the constant or set variable NAME: 1 and *value, or 0 if
|
|
* NAME is neither. */
|
|
int v4_text_value(const v4_text *t, const char *name, v4_cell *value);
|
|
|
|
/* The word `start` named, or -1 if the text has had no start. */
|
|
v4_cell v4_text_start(const v4_text *t);
|
|
|
|
/* The next free word address. */
|
|
v4_cell v4_text_here(v4_text *t);
|
|
|
|
/* "" if there has been no error, else what and where. */
|
|
const char *v4_text_error(const v4_text *t);
|
|
|
|
#endif /* V4_TEXT_H */
|