Files
LithosAnanke/v4/include/v4/stack.h
T
Claude 37469f6c54 feat(v4): v3's whole POST is v4's POST -- 990 cases, all passed on Hera (#189)
Phase 7, Task 8: PARITY:V4_POST tests=990 pass=990 fail=0 on Hera (mesh-boot); the hosted
product 945 of them, all passed -- the 45 cases of physics.4th's words need the kernel.

- Enlarged, as ruled ("Enlarge v4 to fit"): a node is 32768 words, its data stack 1024
  deep (v3's), host and kernel alike; the dictionary's end moves with them.
- POST's runner compares every value a case leaves (v3's leave 101); V4_POST_KERNEL marks
  a case of the kernel's words, and a host without a kernel does not run it.
- mkpost.py --all is POST's table (make -C v4 post79), with docs/v4.0.0/POST.md; it reads a
  module's #defines (v3's Mama cases are MAMA_IMPLEMENTED, 0: v3's own POST skips all 20);
  it cuts no line between a word and the name it takes.
- Rules for the last of the table: the min/max and array-sum programs written as meant,
  CREATE's 26-character name (FORTH-79: 31), many_defs.
- POST_FLOOR 990.
- Tests sized for a 32-deep stack and a 16384-word node made deep-stack-ready
  (test_host_depth, test_host_quit, test_host_node, hosted-check, depthsweep.py).

make -C v4 test: all v4 tests passed. make -C kernel/tests test: all passed.
depthsweep at 1024: 230 runs, 0 failures. v4-checks running.

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

126 lines
5.6 KiB
C

/* SPDX-License-Identifier: LicenseRef-Starship-1.0
* Copyright (c) 2023-2026 Robert A. James
*/
/* stack.h -- F18 circular hardware stacks (DECOMPOSITION.md D-2), counted (D-16).
*
* REVISED BY D-16 (2026-10-04). What follows describes the storage, which is
* unchanged: registers over a ring that wraps. But a running programme no
* longer sees the wrap. Each stack also counts what it holds, and the
* executor faults before an opcode would push onto a full stack or pop an
* empty one (exec.h). The wrap is now only what push and pop do when C code
* calls them directly at either end.
*
* D-2 rules these explicitly: "F18 circular stacks, hidden. Data stack 10
* deep (T, S + 8 circular), return stack 9 deep (R + 8 circular), exactly as
* the F18. No stack pointer is visible to code, so DEPTH, PICK, ROLL, .S,
* SP@ and SP! are retired everywhere, host node included."
*
* Two consequences that the ISA and the capsule code must both respect:
*
* 1. A running programme cannot overflow or underflow a stack: before every
* opcode the executor checks that the stacks hold what it takes and have
* room for what it leaves, and faults instead (D-16, exec.h). The ring
* below still wraps -- that is what push and pop do when C code calls
* them at either end, and why C code that serves a node checks the depth
* first (manage.c, blocks.c) -- but no opcode reaches the wrap.
*
* 2. Nesting is shallow: a mesh node's stacks are the F18's 10 and 9; the
* host node's are 1024 and 32 (D-17, revised 2026-11-14 for v3's whole
* POST: V4_DATA_RING and V4_RET_RING, set in v4/Makefile and kernel/Makefile). One value or one call past either depth is a stack fault
* with its message, where under D-2 it corrupted silently.
*
* (Points 1 and 2 corrected 2026-11-12, #181: they said there was no overflow
* detection "and there never will be", and that exceeding a depth corrupted
* silently -- D-2's rule, which D-16 revised.)
*
* The T/S + 8-ring decomposition is the hardware shape, not an optimisation:
* T and S are architectural registers (section 1.1 lists them), and the ring
* is the circular part behind them. It is provably equivalent to a flat
* 10-deep circular buffer, which is what tests/test_stack.c checks it
* against -- see the equivalence argument in stack.c.
*/
#ifndef V4_STACK_H
#define V4_STACK_H
#include "v4/cell.h"
#include "v4/guard.h"
/* D-2: data stack is T, S + 8 circular = 10 deep. That is a mesh node. The
* ring size is a build parameter, like node memory (node.h): D-17 gives the
* host node, which runs the interpreter and the compiler under the user's
* programme, deeper stacks. Nothing else about the mechanism changes. */
#ifndef V4_DATA_RING
#define V4_DATA_RING 8
#endif
#define V4_DATA_DEPTH (V4_DATA_RING + 2)
/* D-2: return stack is R + 8 circular = 9 deep; a build parameter likewise. */
#ifndef V4_RET_RING
#define V4_RET_RING 8
#endif
#define V4_RET_DEPTH (V4_RET_RING + 1)
/* 5% safety boundary at each end of each ring, per guard.h. The bands sit
* immediately either side of `ring` -- a boundary separated from the payload
* by another field catches nothing -- and are storage the struct owns, because
* a mesh node has no heap. Widths are 1 element each at the current ring
* sizes; V4_GUARD_ELEMS scales them if a ring size ever changes. */
#define V4_DATA_BOUND V4_GUARD_ELEMS(V4_DATA_RING)
#define V4_RET_BOUND V4_GUARD_ELEMS(V4_RET_RING)
typedef struct {
v4_cell t; /* T -- top of data stack (a register) */
v4_cell s; /* S -- second (a register) */
unsigned head;
unsigned depth; /* how many values it holds, 0 .. V4_DATA_DEPTH (D-16) */
v4_cell guard_head[V4_DATA_BOUND];
v4_cell ring[V4_DATA_RING];
v4_cell guard_tail[V4_DATA_BOUND];
} v4_dstack;
typedef struct {
v4_cell r; /* R -- top of return stack (a register) */
unsigned head;
unsigned depth; /* how many entries it holds, 0 .. V4_RET_DEPTH (D-16) */
v4_cell guard_head[V4_RET_BOUND];
v4_cell ring[V4_RET_RING];
v4_cell guard_tail[V4_RET_BOUND];
} v4_rstack;
void v4_dstack_reset(v4_dstack *st);
void v4_dstack_push(v4_dstack *st, v4_cell x);
v4_cell v4_dstack_pop(v4_dstack *st);
/* Read the top without disturbing the stack. T is a register on hardware, so
* this is a plain read and needs no ring access. */
v4_cell v4_dstack_peek(const v4_dstack *st);
/* Read the second element without disturbing the stack. */
v4_cell v4_dstack_peek2(const v4_dstack *st);
void v4_rstack_reset(v4_rstack *st);
void v4_rstack_push(v4_rstack *st, v4_cell x);
v4_cell v4_rstack_pop(v4_rstack *st);
v4_cell v4_rstack_peek(const v4_rstack *st);
/* 1 if both boundaries of the data stack are intact, else 0. See guard.h for
* what this catches that AddressSanitizer does not. */
/* THE DEPTH COUNT (DECOMPOSITION.md D-16, ruled 2026-10-04). Each stack
* counts what it holds: a push adds one, up to the stack's size, and a pop
* takes one, down to zero. The storage is still the F18's -- registers over
* a ring -- and push and pop still do exactly what they did when the count
* is at either end, so these functions never fail. It is the executor that
* guards: it reads the count before every opcode and faults instead of
* pushing onto a full stack or popping an empty one (exec.h).
*
* v4_dstack_clear and v4_rstack_clear empty a stack: the count goes to zero
* and nothing else changes. */
void v4_dstack_clear(v4_dstack *st);
void v4_rstack_clear(v4_rstack *st);
int v4_dstack_guards_intact(const v4_dstack *st);
int v4_rstack_guards_intact(const v4_rstack *st);
#endif /* V4_STACK_H */