Files
LithosAnanke/v4/include/v4/exec.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

94 lines
4.5 KiB
C

/* SPDX-License-Identifier: LicenseRef-Starship-1.0
* Copyright (c) 2023-2026 Robert A. James
*/
/* exec.h -- instruction execution for v4.
*
* DECOMPOSITION.md section 1.2: "Slots execute left to right." A branch
* (jump, call, next, if, -if) takes its target from all bits to the right of
* its slot and replaces the same low bits of P (page-relative). Branches are
* legal in slots 0-3 only. Nothing to the right of a branch executes, taken
* or not, because those bits are its address.
*
* Section 1.4: "Every retired instruction increments that opcode's heat counter
* and advances the anti-clock; every `call` increments the heat counter of its
* target. None of this costs an instruction." A call's target is counted by
* whoever runs the node, through the hook below (ENGINE.md step 3; plan
* 2026-10-20, Task A1, #189): the kernel keeps a word's accounts. The engine's
* own per-call-target table, a stand-in, is gone.
*
* The node owns P, A, B, the stacks and memory; heat and the anti-clock are
* separate physics state (section 7 names them as registers).
*
* THREE POINTS THE SPEC LEAVES TO THE F18, and which this model takes from it:
*
* - `ex` ends the word, like `;`. P has been replaced, so the remaining
* slots belong to a word that is no longer the current one.
* - `unext` restarts the *already fetched* word at slot 0. It does not
* refetch and does not move P, so `@p` and `!p` inside a unext loop step
* through the words that follow the loop word. When R reaches 0 the loop
* ends and execution continues with the slot after `unext`.
* - `+*` shifts T arithmetically (sign bit kept). Section 1.3 says only
* "shift T:A right one bit"; D-3 says plain F18 semantics.
*
* A branch opcode in slot 4 or 5 is outside the spec. The model does not trap
* it: it applies the 7- or 2-bit target the layout formula gives.
*/
#ifndef V4_EXEC_H
#define V4_EXEC_H
#include "v4/heat.h"
#include "v4/iword.h"
#include "v4/node.h"
/* Called at `call` once the return address is pushed and before P moves to the
* target (so P is still the return address). It returns where P goes: the
* target, or another address the call is sent to instead, which returns to the
* caller as the target would (the ACL's check at call, docs/v4.0.0/plans/
* 2026-11-19-acl-at-call.md). NULL: no hook, and P goes to the target. */
typedef v4_cell (*v4_call_hook)(void *ctx, v4_node *n, v4_cell target);
/* Called when an instruction retires, after HEAT-OP counts it, with its opcode (0..31): compudynamics on the
* opcodes (#189 Phase 7, ruling 7). NULL: no hook. */
typedef void (*v4_retire_hook)(void *ctx, v4_node *n, unsigned op);
typedef struct {
v4_uheat_t anticlock;
v4_call_hook on_call; /* reset leaves NULL */
void *on_call_ctx;
v4_retire_hook on_retire; /* reset leaves NULL */
void *on_retire_ctx;
/* A node blocked at its port in the middle of an instruction word
* (node.h) goes on, when it has been served, from the slot after the
* store: the word and the slot are kept here meanwhile. */
int resume;
v4_iword resume_iw;
unsigned resume_slot;
unsigned resume_faults; /* n->faults when it blocked: a fault since then means P is a handler and the rest of the word is abandoned */
} v4_exec_state;
void v4_exec_reset(v4_exec_state *es);
/* Execute one instruction word: fetch at P, advance P, run the slots left to
* right until the word ends. A unext loop runs to completion inside one call,
* so the call does not return while R is nonzero at a `unext`. Returns the
* number of instructions retired.
*
* FAULTS (node.h; D-14 and D-16). Before an opcode runs, the stacks must
* hold what it takes -- a T or S it only reads counts -- and have room for
* what it leaves; and an address it uses, or P at the fetch, must be inside
* node memory. If not, that opcode and the rest of the word do not execute,
* both stacks are emptied, and P is that kind's word of the node's fault
* table on return. With no table the node stops, and this does nothing and
* returns 0 from then on. */
unsigned v4_exec_step_word(v4_node *n, v4_exec_state *es, v4_heat *h);
/* Execute a single opcode. The branch opcodes read their target from `w` and
* `slot`; every other opcode ignores both. `unext` here only updates R; the
* restart is v4_exec_step_word's. A value above 31 does nothing and retires
* nothing. */
void v4_exec_op(v4_node *n, v4_exec_state *es, v4_heat *h,
unsigned op, v4_iword w, unsigned slot);
#endif /* V4_EXEC_H */