LithosAnanke/v4/include/v4/stack.h

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