SPEC is the contract and drv/ is what the tests sweep, but there was no place
that showed a reader how a group is actually used. examples/ now has one stand
alone program per group, each ending in output calls:
base_macros.r8asm S5 set_0 vs erase, rol/ror, copy vs bit_copy vs
clb_bit_mov, step
bit_adder.r8asm S6 4 bit ripple carry adder built from
clb_bit_add_nc, then bit_raw_add for the
preserving variant
byte_raw_ops.r8asm S7.1 raw_add/raw_inc/raw_and/raw_or/raw_xor/raw_sub,
printing the operands afterwards to show the
whole point of the family: they survive
byte_clobber.r8asm S7.2 clb_add/sub/neg/inc_nc (operands eaten) and the
S7.3 clb_and residue (240 & 204 -> B = 12)
byte_in_place.r8asm S8 not/inc/neg/dec/add_ip and clb_nonzero
sum_loop.r8asm S5.1 clb_ones + loop/endloop: 1+2+...+N, count from
data rather than from the assembler
mul_demo.r8asm S9 82*141 and 2047*2047
divmod_demo.r8asm S7.6 2047/10 and 2047/1 (the case that used to hang),
reusing the scratch block on purpose
digits_demo.r8asm S7.7 1234 and 7 -> four ASCII digits
Every header carries a `; out 1 2 3` line: the expected OUT stream, so the
file itself says what it prints. The new r8forge_examples_test target runs all
of examples/*.r8asm and compares that line with the real output (a file without
the marker counts as a failure), printing the tape length and step count on the
way. That makes examples the second place after byte_op_test that checks
behaviour instead of just "it assembles", and keeps the examples from rotting as
the macros change. The six %synth examples get the marker too: their inputs are
all zero, so they print 0 0.
All 15 examples pass. The values in the headers were checked with
r8forge_tape_run (the second interpreter) as well as the test's own machine.
Docs: SPEC S10.3 has the table and the convention, S11 gets the test row, and
README gets a short section plus the layout list. AGENTS records the examples
in the handoff baseline and the "verified" table.
It was written from a wrong diagnosis. Because the interpreters in this repo
read biz/rnz as a whole cell zero test, every packed byte program looked hung,
and the conclusion was "byte level arithmetic has to be one bit per cell".
With the interpreters fixed (86a54aa) that reason is gone: raw_add does the same
job with 6 cells instead of 32, and this repository had already deleted the same
approach once before for the same reason.
Removed: asm/byte_add.r8asm, asm/pack_byte.r8asm, examples/add8.r8asm,
examples/add8_inc.r8asm, tests/byte_add_test.cc and its CMake target.
AGENTS.md and README.md stop listing them and each keeps one paragraph saying
the direction was tried and dropped, so the next person does not add it back.
Still green after the deletion:
asm/test.r8asm 1666 characters, 7/7 cache hits
full_add 8/8 combinations
verify_raw_add_nc assembles
byte_op_test raw_add/and/or/xor 65536 each, raw_inc 512
fibonacci 1 1 2 3 5 8 13 21 34 55
The rotation based byte layer never ran. Measured with r8forge_derive -2:
raw_add A=0,B=0 / 1+1 / 3+5 / 1+0 out empty (step limit hit)
raw_add A=127,B=130 out 0 0 0 0 0, everything destroyed
raw_and 0xF0 and 0xCC, 1 and 1, 0 and 5 out empty
copy A=5 out empty (A=0 returns fine)
Not "only operand preservation is missing": set_0 (= [-]) cannot clear a cell
that holds more than one bit, and biz only answers "is this whole cell zero",
because ror does not change zero-ness. So the bits of a packed byte are
unreadable, and the whole ror + set_0 layer has no future. The docs now say
that instead of blaming operand preservation.
What replaces it is one bit per cell:
asm/byte_add.r8asm 8 bit adder. Bit i owns four adjacent cells at base+4i:
A, B, carry (in -> out), scratch. The synthesised four
cell slice bit_raw_add_nc does the bit, clb_bit_mov moves
the carry into the next quartet. A doubles as the
accumulator, so calling byte_add again continues the sum.
asm/pack_byte.r8asm eight flags -> one byte, the only direction that works.
bit_raw_flip_if consumes a flag into flipping bit 0 of an
accumulator that may already hold bits (no set_0 there).
examples/add8.r8asm a+b, 1308 characters. A shared carry cell layout needs
only 25 cells but was measured at 2517: paying .tp travel
eight times beats saving seven carry cells.
examples/add8_inc.r8asm add 1 three times, proving the block composes.
tests/byte_add_test.cc r8forge_byte_add_test: runs the tapes on the ROT-8
machine over every input pair, 0.3 s.
Also: AGENTS.md gains the measurement table, the third instruction set
constraint (packed bytes are unreadable), the new files, and the note that
build/ has to be rebuilt with the VS bundled cmake -- scoop's 4.4 reconfigures
it and dies with "No preprocessor test for PellesC".
Full_add_flat.r8asm and full_add_flat_spaced.r8asm had their comments turned
into question marks: they were written through a PowerShell Set-Content with
ASCII encoding, which cannot represent Chinese and substitutes '?'. Rewritten
as UTF-8, with the comments saying what the files are for.
Both still assemble from cache (95 characters) and still produce the same tape,
which is the point of the layout free metric.
A scan of the whole tree for '???' now comes back empty.
%synth could optimise the real tape characters, but that price depends on where
the cells sit, so the answer was only good for one layout and the cache could
only be shared between call sites with the same addresses.
metric chars tape characters including the .tp walk layout dependent
metric flat characters without the walk layout independent
metric blocks block count layout independent
'flat' is the step-free mode: it counts biz/flb/rnz and the ops, ignores how
far apart the cells are, so one search result and one cache entry serve every
layout. The price is a slightly longer tape when the layout happens to suit a
different program: 90 characters for chars, 95 for flat on the full adder.
Checked: examples/full_add_flat.r8asm hits the cache on the second run, and the
same block with 'layout 0 2 4 6 8 10' added hits the *same* entry and emits a
byte-identical tape (the key drops the layout for the layout-free metrics).
Both pass the eight combination check.
A synth block used to spell out which parameter is an input and which is an
output. That was redundant: with map, 2^K entries already mean %1..%K are the
inputs and the value's bits land on the parameters after them; with a raw
table, nothing needs saying at all. So 'inputs' and 'outputs' now fail with a
message pointing at map/stat, and the map form derives both.
Added 'stat' as the fully explicit form: 2^params values, one per input
combination, which is exactly the state table the search consumes.
examples/full_add_stat.r8asm is the same adder written that way and produces a
byte-identical tape to the map version (95 characters), both pass the eight
combination check.
%synth used to always run both searches, so every assembly of the full adder
sat there for twenty minutes. A block can now say 'mode layers' to stop after
the layer search (7.7 seconds) or 'mode tape' (the default) to pay for the
shortest tape. examples/full_add_layers.r8asm is the fast one, 95 characters
and still checked on the machine.
The lexer also no longer chokes on a UTF-8 BOM. Every Windows editor writes
one, and the first token came out as a garbage prefix, which crashed the
assembler with an access violation rather than saying anything useful.
README grew a getting-started walkthrough: build, a complete adder.r8asm, what
the two stderr lines mean, how to drop a synth block into a library, and the
three things that bite (inputs first, don't call them in/out, map length).
Five layers cost 95 characters; six layers cost 90. Both are in examples/ and
both pass the eight-combination check on the ROT-8 machine in
tests/synth_test.cc (which now takes a file argument).
sacrifice B, FLIP {S,T}
sacrifice A, FLIP {B}
sacrifice B, FLIP {A,Ci,S}
sacrifice Ci, FLIP {B,Co,T}
sacrifice S, SET1 {Ci,Co}
sacrifice T, FLIP {B,Ci,S,Co}
Cost 75 in the model, 90 on the tape once the inter-block hops and the two
output lines are counted. The goal was popped at 75 only after everything
below 75 had been expanded, so 75 is the minimum of this cost model.
Trading a layer for a shorter tape is not a contradiction: the layer search
cannot see that a small, cheap block can be worth more than one wide, expensive
one.
The searcher stops being a separate program: %synth is an assembly-time
directive. It describes a truth table, the assembler runs the search while
parsing, and the block list comes back as ready-to-paste r8asm.
Merging is what makes the cost model honest. The price of a layer is
cost = 2 (biz + rnz) + sum(move distance + op cost)
and the move distance depends on the call site's cell layout, not on anything
the assembler knows in advance: the same five-layer adder is 87 characters
with the cells adjacent and 136 with them two apart. Only the side that sees
the layout can price it, which is now the assembler itself.
Working: the assembler (asm/test.r8asm still assembles to the same 1714
characters), the searcher (bit planes + backward one-step lookup, full_add in
5 layers, proven shortest in 7.2s), and %synth parsing plus the search itself.
Not working yet: splicing the synthesised body into the tape -- a synth call
fails loudly with 'unknown macro' instead of emitting anything, so nothing can
silently assemble wrong. The two ways to finish it are in the README.
Also carries over the CMake fix: no set(CMAKE_CXX_FLAGS ...), which used to
drop /EHsc, push -O3 into Debug and fight /RTC1.