rajamesandClaude Opus 5.5
067f317c47
First code for StarForth v4 (JUSTIFICATION.md section 10, step 1): one node of the 32-instruction core as a C99 model, with cell width as a build parameter. - Node: P, A, B, F18 circular stacks (10 and 9 deep, D-2), word-addressed memory (D-1), 5% guard bands on every bounded list. - Instruction word: six 5-bit slots in 32 bits at every cell width. - Executor: all 32 opcodes of DECOMPOSITION.md 1.3. Cell arithmetic wraps explicitly; no signed overflow or implementation-defined shift. - Heat: per-opcode and per-call-target counters and the anti-clock, driven by instruction retirement (1.4, D-6 interim). - Slot packer and runner for tests, and a reference unsigned multiply in plain C99 with no 128-bit type. Tests run at 32- and 64-bit cells, and under ASan and UBSan. They cover every opcode and execute the first section 4 definitions (NIP SWAP OR NEGATE ROT 0< 0= 2DUP - U<) against the C operation each stands for. UM* as written in section 4 is exact only while u1 <= 2^(n-2). Two known failing cases are pinned in test_foundation.c until it is rewritten. DECOMPOSITION.md: record D-9, the instruction word is 32 bits at every cell width (ruled 2026-10-02). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
90 lines
3.7 KiB
C
90 lines
3.7 KiB
C
/* stack.h -- F18 circular hardware stacks (DECOMPOSITION.md D-2).
|
|
*
|
|
* 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. There is no overflow or underflow detection, and there never will be.
|
|
* Pushing past the bottom silently overwrites the oldest entry. This is
|
|
* hardware behaviour, reproduced faithfully here rather than defended
|
|
* against: a golden model that trapped on overflow would diverge from
|
|
* the thing it is a model of, which is the whole point of the exercise.
|
|
*
|
|
* 2. Nesting is therefore shallow (10 and 9), and exceeding either depth
|
|
* corrupts silently rather than faulting. DECOMPOSITION.md section 3
|
|
* calls this out as the constraint that "every CAP definition in section
|
|
* 4 and 5 must be re-checked against ... before it is accepted as a POST
|
|
* target; the hand traces so far assumed unbounded stacks."
|
|
*
|
|
* 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. */
|
|
#define V4_DATA_RING 8
|
|
#define V4_DATA_DEPTH (V4_DATA_RING + 2)
|
|
|
|
/* D-2: return stack is R + 8 circular = 9 deep. */
|
|
#define V4_RET_RING 8
|
|
#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;
|
|
|
|
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;
|
|
|
|
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. */
|
|
int v4_dstack_guards_intact(const v4_dstack *st);
|
|
int v4_rstack_guards_intact(const v4_rstack *st);
|
|
|
|
#endif /* V4_STACK_H */
|