Files
LithosAnanke/v4/include/v4/text.h
T
Claude e8e7ec8b9f feat(v4): word accounts at call -- the word ID in the header, the kernel's records, the Stadium charged per tick (#189)
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
2026-11-13 19:12:44 +00:00

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 */