diff --git a/docs/v4.0.0/DECOMPOSITION.md b/docs/v4.0.0/DECOMPOSITION.md index ae8a99d1..8ae8e135 100644 --- a/docs/v4.0.0/DECOMPOSITION.md +++ b/docs/v4.0.0/DECOMPOSITION.md @@ -18,7 +18,7 @@ model produces the same results as the v3 C primitive it replaces. 0. [Fates](#0-fates) 1. [The v4 core ISA](#1-the-v4-core-isa) 2. [Compiler conventions](#2-compiler-conventions) -3. [Open decisions](#3-open-decisions) +3. [Decisions](#3-decisions) 4. [Foundation layer (new words)](#4-foundation-layer-new-words) 5. [Fate of every v3 primitive](#5-fate-of-every-v3-primitive) 6. [Messaging between nodes](#6-messaging-between-nodes) @@ -48,9 +48,9 @@ model produces the same results as the v3 C primitive it replaces. | Item | v4 node | | --- | --- | | Cell | 32 bits (mesh node). The host node's width is a build parameter; see D-5. | -| Addressing | Word-addressed (pending D-1). | +| Addressing | Word-addressed (D-1). | | Registers | `T` (top of data stack), `S` (second), `R` (top of return stack), `P` (program counter), `A` and `B` (address registers). | -| Stacks | Hardware stacks below `S` and `R`. Depth and visibility are D-2. | +| Stacks | F18 circular hardware stacks, not visible to code (D-2): data stack `T`, `S` + 8 circular (10 deep), return stack `R` + 8 circular (9 deep). No overflow or underflow; pushing past the bottom silently overwrites the oldest entry. | | Instruction word | Six 5-bit slots, plus 2 spare bits. | ### 1.2 Instruction word layout @@ -154,21 +154,28 @@ document that clobber `A`: `@ ! +! -! 2@ 2! C@ C! UM* * UM/MOD SEND RECV`. Words --- -## 3. Open decisions +## 3. Decisions -These must be settled before the golden model is built. Where a definition below depends on one, it -says so. +Ruled by Captain Bob, 2026-10-01, except D-4 and D-6, which are deferred to development step 2 (the +hosted mesh, `JUSTIFICATION.md` §10) because only the mesh and the RTL depend on them. Where a +definition below depends on one, it says so. -| ID | Decision | Default in this document | +| ID | Decision | Ruling | | --- | --- | --- | -| **D-1** | Word addressing (pure Moore) or byte addressing. | Word addressing. `C@`/`C!` are CAP; `CELLS` is a no-op. | -| **D-2** | Stack depth, and whether the stacks are visible (needed by `DEPTH`, `PICK`, `ROLL`, `SP@`, `SP!`). | Stacks backed by node RAM, with the data stack pointer exposed as MM register `DSP`. | -| **D-3** | Exact `+*` semantics at 32 bits: whether the add carries out of `T` into the shift. | Carry is kept (extended multiply step), so `UM*` returns a full 64-bit product. | -| **D-4** | Node memory map, including port and register addresses. | Symbolic names only (§6, §7). | -| **D-5** | Host node cell width. | 32 on a Zynq-7000 (Cortex-A9); 64 on an aarch64 host. The compiler capsule is written width-independent. | -| **D-6** | Which heat structures exist in hardware: per-opcode counters only, or also per-call-target and word-to-word transition counters. | Per-opcode and per-call-target. Transition counters deferred. | -| **D-7** | `ROLL` semantics. | Fix to ANS (count from the top). v3's bottom-counting `ROLL` is retired. | -| **D-8** | Q48.16 signedness. | Signed. v3's unsigned comparisons and `Q.FROM-INT` clamping are retired. | +| **D-1** | Word addressing (pure Moore) or byte addressing. | **Word addressing.** `C@`/`C!` are CAP; `CELLS` is a no-op. | +| **D-2** | Stack depth, and whether the stacks are visible. | **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. | +| **D-3** | Exact `+*` semantics at 32 bits: whether the add carries out of `T` into the shift. | **Plain F18 semantics.** The carry out of `T` is not kept. `UM*` in §4 must be revised accordingly (see the note there). | +| **D-4** | Node memory map, including port and register addresses. | **Deferred** to step 2. Symbolic names only for now (§6, §7). | +| **D-5** | Host node cell width. | **Match the host CPU:** 32 on a Zynq-7000 (Cortex-A9), 64 on an aarch64 host. The compiler capsule is written width-independent. | +| **D-6** | Which heat structures exist in hardware: per-opcode counters only, or also per-call-target and word-to-word transition counters. | **Deferred** to step 2. The golden model implements per-opcode and per-call-target heat in the meantime. | +| **D-7** | `ROLL` semantics. | **Moot.** `ROLL` is retired under D-2. | +| **D-8** | Q48.16 signedness. | **Signed.** v3's unsigned comparisons and `Q.FROM-INT` clamping are retired. | + +**Consequences of D-2 that every definition must respect.** The data stack holds 10 items and the +return stack 9, and every `call`, `FOR`, `DO` loop frame and `push` uses return-stack slots. Nesting +is therefore shallow, and exceeding either depth corrupts silently rather than faulting. Every CAP +definition in §4 and §5 must be re-checked against these limits before it is accepted as a POST +target; the hand traces so far assumed unbounded stacks. --- @@ -193,6 +200,10 @@ dependency order. : U< ( u1 u2 -- flag ) 2DUP xor 0< IF NIP 0< ELSE - 0< THEN ; \ ---- multiply (D-3) ----------------------------------------------------- +\ NEEDS REVISION: written for the carry-keeping +* that D-3 rejected. With +\ plain F18 +* the carry out of T is lost, so this is only correct when the +\ partial sums never overflow T (operands below 2^31). A full-range UM* +\ needs a correction step; to be rewritten and proven on the golden model. : UM* ( u1 u2 -- ulo uhi ) a! 0 31 FOR +* UNEXT push drop a pop ; \ ---- divide: 32-step restoring division, divisor held in A -------------- @@ -237,9 +248,9 @@ Section numbers match the v3 primitive reference. | `?DUP` | CAP | `dup IF dup THEN` | | `ROT` | CAP | §4 | | `-ROT` | CAP | `ROT ROT` | -| `DEPTH` | MM | Read `DSP` (D-2). | -| `PICK` | MM + CAP | Read stack RAM at `DSP − n` (D-2). 0-based, as in v3. | -| `ROLL` | CAP | Rewritten with ANS semantics (D-7), using `PICK` and a copy loop. | +| `DEPTH` | RET | No visible stack pointer (D-2). | +| `PICK` | RET | No visible stack pointer (D-2). | +| `ROLL` | RET | No visible stack pointer (D-2); D-7 is moot. | ### 5.2 Return stack @@ -374,7 +385,7 @@ All output reaches the console through `EMIT` (DEV). | --- | --- | --- | | `<#` `#` `#S` `HOLD` `SIGN` `#>` | CAP | Standard pictured-output definitions over `UM/MOD` and a hold buffer. v3's tolerant `#>` (pops `ud` only if present) is not kept; v4 follows the standard stack effect. | | `.` `.R` `U.` `U.R` `D.` `D.R` | CAP | Built on pictured output and `TYPE`. | -| `.S` | CAP | Walks the stack via `DSP` (D-2). | +| `.S` | RET | No visible stack pointer (D-2). | | `?` | CAP | `@ .` | | `DUMP` | CAP | Loop over `@`/`C@` with pictured output. | | `BASE` | CAP | Variable. | @@ -441,7 +452,7 @@ The storage service belongs to the Artemis role, now a device node. | Word | Fate | Notes | | --- | --- | --- | | `HERE` `ALIGN` `ALLOT` `,` `C,` `2,` `PAD` `LATEST` | CC | The dictionary lives on the host node. | -| `SP@` `SP!` | MM | `DSP` register (D-2). | +| `SP@` `SP!` | RET | No visible stack pointer (D-2). | ### 5.13 Dictionary manipulation @@ -688,7 +699,6 @@ Addresses are assigned in the node memory map (D-4). Names only here. | Register | Access | Contents | | --- | --- | --- | -| `DSP` | R/W | Data stack pointer (D-2). | | `HEAT-OP[0..31]` | R | Per-opcode retirement heat. | | `HEAT-CALL[...]` | R/W | Per-call-target heat, with freeze bit (D-6). | | `ANTICLOCK` | R | Virtual tick: a pure function of the execution stream. |