Commit Graph
11 Commits
Author SHA1 Message Date
dsh 0c75772cbb geometry: the ring size becomes a build option, and the machine takes 64 cells
259 was never part of the machine, just the historical default, so
kDefaultMemoryCells is now R8FORGE_MEMORY_CELLS (1..65536, default 259) with a
range guard in CMake, the same way the cell width already worked.  All five VMs
read it from geometry.hh, so nothing else had to change.

Measured the highest cell each tape in the tree actually touches by walking its
> and < and recording the peak (no tape does a < at cell 0, so none of them
depend on wrapping): calc 51, hello 49, signed_demo 34, term 27, and the
asm/test.r8asm self test 155, because it lays every macro cell block out side by
side.  So a 64 cell ring runs every program we ship; only the self test needs
the default.

Verified: the full ctest suite is 8/8 at both 128 and 64 cells (11 bit); at the
hardware geometry of 8 bit plus 64 cells the widthfree label is 5/5, and the
calculator tape is byte for byte identical to the 259 cell build and its
sessions take the same 166348 steps.  The self test also produces identical
output at 64 cells but 216 more steps, because its high cells fold back onto low
ones -- which is why SPEC section 1.2 states the rule: ring size must be at
least the highest cell a program touches plus one.

Hardware payoff: at 64 cells dp is a 6 bit counter whose wrap is free, so the
TTL build loses its modulo-259 comparator logic (four to five chips), the RAM
needs 64 bytes, and the drum shrinks to 8 tracks by 64 cells (at 3000 rpm that
is 52 s for a calculator session, so it wants to spin faster).  hardware.md is
updated to the 8 bit / 64 cell machine throughout.
2026-11-20 15:34:03 +08:00
dsh d1939a687c hardware: the machine is 8 bits, and that fixes the budget too
Decision: the physical machine uses 8 bit cells.  11 bits is half decimal
semantics and half superstition; at 8 bits a cell is a byte, so , and . are
plain byte I/O, the whole 259 cell ring is 259 bytes and fits one 6116, and the
datapath is one 74HC299 plus an XOR.

It also settles the instruction pointer problem: the 8 bit calculator is 51378
instructions, back under the historical 65536, where the 11 bit one had grown
to 73624 with its terminal front end.  Measured tape sizes and step counts at 8
bits (build8, MSVC):

  full_add          95 instructions, 36 bytes
  hello            577 instructions, 217 bytes
  term           16414 instructions, 6.2 KB
  signed_demo    37511 instructions, 14.1 KB
  asm/test.r8asm 43676 instructions, 16.4 KB, 99824 steps, 52 OUTs
  calc           51378 instructions, 19.3 KB, 166348 steps for "12 34 + ."

The note now records the 8 bit numbers next to the 11/16/32 ones, recomputes the
TTL bill of materials (20-28 chips instead of 25-35: one RAM, one shift
register, four or five ip counters), gives the drum 8 tracks instead of 11, and
adds an optional M4 that widens the machine back to 11 bits by swapping the ROM
to demonstrate that width is a build parameter rather than runtime state.
Milestone M2 now expects exactly 99824 steps and M3 expects "046" from the
calculator, both of which the software side already produces.
2026-11-20 15:18:55 +08:00
dsh 12a2254078 docs: a design note for building the machine out of silicon
docs/hardware.md turns the ISA into hardware requirements and works out what a
physical ROT-8 needs.  The load-bearing observation is that nothing in the
instruction set can observe time -- no counters, no interrupts, and the I/O
behaviours are "block until a character" and "latch the cell" -- so any
implementation that reproduces the same sequence of (ip, dp, cells, output) is
the same machine, at any clock rate and any number of cycles per instruction.
That is what makes the build tractable: a microcoded sequencer, slow memory or
even a drum are all legal.

The note pins the parts that are easy to get wrong: the exact scan boundaries
for [ and ] (the ] case jumps back onto the [ itself so it re-tests, which the
reference rot8.c gets right and a naive implementation gets wrong), the halt
condition, cells starting at zero, and the input convention -- , blocks until a
character arrives and an explicit EOF reads as 0, otherwise every interactive
read would return zero and the program would exit at once.

Budget: 3 bits per instruction, so the flagship tape is 23.4 KB of ROM and the
calculator at 11 bits is 27.6 KB; the data ring is 259 cells by W bits at most
518 bytes.  Two consequences: the instruction pointer needs at least 17 bits
because the calculator now assembles to 73624, past the historical INS_SIZE of
65536, and the 32 bit calculator (126 KB) does not fit the block RAM of the
small boards.

Three carriers are compared: FPGA first (Tang Nano 9K, about 58 KB of BSRAM, a
weekend of work), discrete TTL as the real machine (25-35 chips, 0.25-0.5 M
instructions per second, a few weeks) and electromechanical as the showpiece
(a drum with 11 tracks and 259 cells per track, read and write heads one cell
apart so a read-modify-write costs one cell time: 22 s for a whole calculator
session at 3000 rpm).  The verification plan leans on what already exists: a
packer into the 3 bit format, the RTL testbench compared against tape_run step
by step, then the panel single-stepped against an exported trace.

Nothing is implemented; the note ends with the decisions that come first --
which carrier, which width (8, 11 or 16), program storage, and whether the
physical tape form matters.  The first concrete step would be M0: the packer
plus a rot8.v testbench, which needs no hardware purchase and gives all three
carriers the same golden model.
2026-11-20 15:14:42 +08:00
dsh 1513111689 synth: measure whether the address-aware metric can shrink a real program
It cannot.  The calculator assembles to 73624 characters in the default flat
metric and 73940 with --synth-chars (identity layout), 316 more.  Three reasons,
now written down in SPEC section 3.7:

* the travel term 2*(hi-lo) is translation invariant, so moving a group of cells
  farther or nearer changes nothing; only a permutation or a spread can, and the
  contiguous identity layout is already the tightest of those;
* the library blocks are expanded at dozens of call sites with different
  addresses, so a single layout line is a guess that the real sites rarely
  match;
* the model still ignores the hop between blocks, and the exact metric tends to
  pick programs with more blocks (six blocks for the adder table against five,
  82 emitted characters against 87 -- five characters, which the other tables
  give back and more).

Cell placement is the lever that works, and it is already spent: the terminal
front end first put its borrowed classifier cells at 52..57 (77164 characters)
and moving them into 20..29 gave 73624, minus 3540.  Five single-cell moves on
the current map were measured too (T and DEPTH to 17, HAVE and CNT to 52, S2
back to 52) and every one is longer: +182, +2900, +92, +134, +3810.  So the map
is a local optimum and the only way down from 73.6k is to drop features.

The experiment left three metric-0 cache entries behind; they were deleted, so
the committed cache still holds only what the flat metric needs.
2026-11-19 14:33:25 +08:00
dsh 5c414292d2 calc: a terminal front end -- echo, backspace editing and a prompt
The calculator now behaves like the terminal tape from the previous commit:
every character is echoed, backspace edits the digit window, Enter commits the
line and prints the next prompt, and '.' puts its result on its own line:

    > 12 34 + .
    0046
    > 12<BS>3 .
    0013
    > ^D

It is not the terminal's line buffer moved over: the calculator consumes one
character at a time, and replaying a buffered line would mean unrolling the
engine once per buffer cell, which does not fit.  Line editing here is the
digit window: backspace shifts it right by one, pads a '0' in front, echoes
"space, backspace" and keeps accumulating.

Three things had to be learned the hard way, all recorded in docs/calc.md ?8:

* a borrowed constant cell gets eaten.  KBS (the 8 that backspace subtracts)
  lived in SC+5, and the operator step erases SC..SC+6 wholesale, so the first
  byte after an operator was treated as a backspace -- every character of
  "12 34 + ." came out as an erase.  It is now loaded right before each use.
  It also must not borrow R: the EOF test writes R every round.
* set_1 only forces the low bit; cells lent to the classifier have to be
  re-initialised each round rather than assumed clean.
* the prompt after Enter has to be printed before the command dispatch and the
  operators run, because EH (the "this was Enter" flag) borrows SC+3, which
  mul uses as scratch -- the first version printed a prompt after every
  multiplication.

The tape went 64983 -> 73624 characters (+8.6k: three copies for the window
shift alone are ~4.4k, the two subtracts ~3k).  That is past the old
ROT-8-viz INS_SIZE of 65536; the current VM sizes its buffer from the tape and
runs 112802 characters at 16 bits and 336304 at 32 bits, so only the
historical budget is gone, not the ability to run it.  Ducking under 65536
again would mean dropping line editing: echo plus the Enter prompt alone is
about +2.5k, still over.

Verified: ctest 8/8 (examples_test checks the new header stream), the width
matrix at 11, 16 and 32 bits (calc stream, terminal tape and the viz's serial
output all agree; 73624 / 112802 / 336304 characters), and docs/calc.md records
step counts for the whole session list -- "12 34 + ." is 287589 steps, about
17% more than before the front end.
2026-11-19 14:27:30 +08:00
dsh 0c218abf32 calc: a 3 cell RPN stack -- nesting now works
The two register machine (A accumulator + P pending operand) could not nest:
"1 2 + 3 4 * + ." printed 0007 because the second operator overwrote the
first.  The calculator now keeps a 3 cell stack (S0 is the top), operators run
immediately (pop two, push one), '.' is a real peek (repeated '.' shows the
same value, and it no longer flushes anything), and ',' clears both the stack
and the depth.

Depth is counted in DEPTH because the unary minus rule needs it: '-' is unary
iff the stack is empty.  The previous "the previous character was an operator"
rule is wrong for a stack machine -- in "1 2 + -" the minus has to be a binary
subtraction (popping an empty cell yields 0, and 0 - top is exactly a
negation); treating it as unary would silently swallow the sign.  The
"have == 0" rule from the original plan was already wrong for the old machine
("2 * -5" would lose its minus).

Sizing was driven by the tape: every push/pop is one copy per stack cell
(~500 characters), and the file has to stay under 65536.  So 3 cells instead
of the 16 the TODO dreamed of: push is two copies (S2<-S1, S1<-S0), an
operator is two more (S1<-S2, then the result), and the new number is written
straight into clb_undigits' target cell (it erases N itself) so the extra
"result -> top" copy disappears -- that one was worth 540 characters.  S2 sits
in cell 33, the freed OP cell: putting it at 51 cost 3.7k in walking alone.

64983 characters (was 62624) and 246142 steps for "12 34 + ." (was 280645 --
the old settle-the-pending-OP block is gone).  The file header carries the
measured session list, the nesting cases, the stack move order (high to low,
or the source gets overwritten) and the older "2047 3 / ." caveat; docs/calc.md
gets the stack section, and SPEC 5.4/7.10 now point at DEPTH instead of NEED.
2026-11-18 21:45:00 +08:00
dsh 10f164b480 docs: the signed wrappers in SPEC, AGENTS, README and TODO
SPEC gains 7.10 with both contracts, the five design points and the measured
tape lengths; 5.4 stops saying "implementation pending" and spells out why the
range is asymmetric -- |N| can be outside the signed range while still fitting
unsigned, so 1024 has to print -1024 and the absolute value cannot be done by
clearing the sign bit.

Numbers re-measured on this machine, because some had drifted: the flagship is
62351 characters / 202159 steps (documented as 62513 / 206491), --opt takes it
to 56338, the calculator is 62624, the byte level test is 23 items over 22
macros, and asm/ has 55 macros in 23 files.

tests/widths.ps1 no longer compares the viz's serial output below 8 bit cells:
the viz prints one number per OUT there, so the 7 bit "viz FAILED" was the
script's expectation, not the tape -- the calculator itself passes at 7 bits
through r8forge_derive, and the same failure reproduces with the previous
calculator (checked against HEAD in a temp worktree).  The TODO gains the open
question of whether the flagship should keep the 65536 limit at all, plus the
evidence that a 16 bit tape of 96052 characters runs fine in the viz.
2026-11-18 21:14:07 +08:00
dsh 3543003a78 digits: reorder the scratch block -- 22% fewer steps, 15% less tape
The profile said 77% of clb_digits' steps are pointer moves, so the layout of its
13 cell scratch block (S..S+12) is the cost.  The block is one rigid 7 cell unit
(clb_divmod owns its internal order: Rhi,Sd,Bo,Cm=Bc,Ci,buf,NR) plus six free
units, so the legal space is 5040 permutations.  All 5040 were assembled and run
(minimal driver, value 2047):

  old: TEN Q R [block] counter T F
  new: T1 R [block] TEN Q F counter

   tape 13,717 -> 11,717 chars (-14.6%)
   steps 145,114 -> 113,264 (-21.9%)
   pointer moves 111,958 -> 80,108 (-28.4%)   non-move steps identical (33,156)

Full 2048 value sweep: worst 164,843 -> 123,731 (-24.9%), mean 144,904 -> 112,552
(-22.3%), better on all 2048 values.  The old layout ranked 3459/5040.

Two things worth remembering.  First, ordering the units by the wrapper's first
visit order is *worse* than the old layout (150,748 steps): first visit ignores
revisit frequency -- the counter is touched once per round, TEN is copied into Bc
every round, T1 is hammered by clb_add_ip's carry chain.  Second, the n-1 lower
bound is not reachable here: 74% of the steps still execute inside clb_divmod's
block, whose order is not clb_digits' to choose, so this lever is now exhausted
(that is what the exhaustive search proves).

Min tape is not min steps either: block-first BQTRT1F1C gives the shortest tape
(10,713) but 123,890 steps.  Tape counts a .tp once, steps count its execution.

Ripple: asm/test.r8asm 64,513 -> 62,513 chars, 236,439 -> 206,491 steps, INS_SIZE
headroom ~1k -> ~3k; --opt 58,060 -> 56,350; calc --opt 52,857; calc_op 77,356 ->
69,324 chars / 599,090 -> 476,170 steps.

Verified: ctest 8/8, byte_op_test 21 items (digits 2048/2048), examples_test 18,
--opt assembles, SPEC 7.7/10.2 + AGENTS + README + docs/calc.md + docs/divmod.md
numbers updated.  New driver drv/digits_layout.r8asm keeps the measurement honest
(one clb_digits call, no output, value fed as 0=2047).
2026-11-18 17:27:05 +08:00
dsh b2ba20b885 vms: raise the step cap from 5M to 20M
5 million steps was picked when the worst macro (clb_add_ip with B=2047) sat just
under a million, so it caught hangs quickly.  The interactive programs changed the
arithmetic: one printed line of the desk calculator costs about 225k steps (40k
for clb_undigits, up to 32k for the operation, ~141k for clb_digits), which is only
about twenty lines before the cap, and examples_test applies the same cap to every
example.

At roughly 2.3e8 steps per second a 20M cap costs 0.09 s when a program really does
run away, and byte_op_test (the only place that runs 465k programs) is unchanged --
so the safety net stays cheap while a session gets four times the room.

docs/calc.md, docs/divmod.md, docs/byte-ops.md and SPEC's "500 ?" mentions now say
2000 ?.
2026-11-11 11:04:14 +08:00
dsh 692995af59 docs: the desk calculator's design and the order to build it in
ci / wide sweep (manual) (11) (push) Skipped
ci / wide sweep (manual) (24) (push) Skipped
ci / wide sweep (manual) (16) (push) Skipped
ci / wide sweep (manual) (32) (push) Skipped
ci / wide sweep (manual) (8) (push) Skipped
ci / cold cache (manual) (push) Skipped
ci / baseline (11 bit) (push) Canceled after 0s
ci / cell 8 (push) Canceled after 0s
ci / cell 16 (push) Canceled after 0s
ci / cell 32 (push) Canceled after 0s
Back to the RPN idea, but written down before any code: the command protocol
(* + , - . / are exactly 0x2A..0x2F, digits 0x30..0x39, so one bit 4 test splits
them and t = C - 0x2A is the command index), the memory map (working cells, a
fixed 4 deep stack, library scratch, a pre-seeded constant block), the step
budget per token, and the five stages with the driver each one gets verified by.

Two decisions recorded there: EOF (0) ends the loop by erasing its counter, and
the stack stays a fixed 4 cells -- .tp is an assembly time constant, so a moving
stack pointer is the one thing this machine cannot do cheaply.
2026-11-10 19:35:24 +08:00
dsh a82d95658e docs: one home per fact -- README as the front door, SPEC as the contract, AGENTS as the manual
The three documents had grown to 2038 lines and quoted each other: 2199 appeared
seven times, 3977 ten times, AGENTS carried a 200-line copy of SPEC's byte-level
tables while README carried another 155-line copy still showing 8-bit-era numbers
(clb_add_nc 688, clb_not_ip 17, ...) that are wrong at 11 bits.

Split by responsibility, keep every fact exactly once:

  README.md   front door: what it is, 30-second build+run, directory map, where
              to read next                                     547 -> 143 lines
  SPEC.md     the contract: %synth, geometry, every macro's signature / cells /
              tape length / who verifies it, test matrix, boundaries, maintenance
                                                               901 -> 807 lines
  AGENTS.md   the manual: hard rules, build and self-check commands, the traps,
              current state, next candidates, do-not-touch list
                                                               590 -> 132 lines

Long-form reasoning moves into docs/ instead of being dropped:

  docs/divmod.md    the shift-restore division story (was SPEC 14, 102 lines;
                    renumbered 1..6, SPEC keeps a pointer and the references in
                    SPEC 7.6 and asm/divmod.r8asm now point there)
  docs/byte-ops.md  the byte-level design history (was README's 155-line section,
                    rewritten with 11-bit numbers since the old ones were
                    measured at 8 bits)

Also fixes what the dedupe exposed: SPEC no longer claims only the multiplier has
a step bound, and raw_sub's comment no longer repeats the retracted "1.48M steps"
figure. Every section reference in the tree resolves; the baseline still passes
(asm/test.r8asm 64513 characters, 21 byte-op items, 14 examples, 48 macros).
2026-11-09 16:34:15 +08:00