24 Commits
Author SHA1 Message Date
dsh 14b3acf66b live: a run of pointer moves is one frame, not one per cell
The live view drew a frame per instruction, so watching clb_digits walk its 13 cell
scratch block meant dozens of frames of "pointer moved one cell".  Now a run of
STP/BTP closes into a single frame whose status line says where the pointer went
(`ptr +5 cell 91`), and `--skip-moves` does not render moves at all, only counts
them until the next data instruction.

Both are view-only: src/rot8.c, rot8_mem.c, the instruction behaviour, the step
count and the tape reader are untouched (git diff shows rot8_viz.c, rot8_viz.h --
one bool -- and vm_test.c's option parsing).  The live path cannot be compared byte
for byte with a non-live run, because live mode sets quiet + replay_output=false on
purpose (the frames are the output); the checks are therefore:

  * non-live stdout before and after: `--input R8F tapes/serial_echo.rot8` -> R8F,
    the calculator tape at cell 11 with `12 34 + .` -> "> 0046" -- both unchanged;
  * executed instructions: 280616 for that calculator run, identical to before;
  * frames at -e 1 on that tape: 280616 -> 104423 (-63%) draws, and 65234 (-77%)
    with --skip-moves; 215382 of the 280616 instructions are moves, in 39189 runs;
  * at the default auto rate (every=1592 here) the draw count is 627 either way: a
    frame that falls due inside a run is deferred to the run's end, never dropped.

ROT8_VIZ_FRAMES=1 makes a run print `draws/steps/moves/runs` to stderr, which is how
the numbers above were taken; it is documented in the README next to --live.
2026-11-18 19:21:00 +08:00
dsh c18021bdf7 mem: size the bytecode buffer from the tape, not from INS_SIZE
INS_SIZE was not a bracket table -- the run loop is the primitive for plus the
counter scan, as designed -- but rot8_ins_init allocated the *translated* tape
with a fixed 65536 entries, and rot8_run_hooked then wrote one entry per
instruction.  A 97307 character tape (examples/calc.r8asm assembled at cell 16)
therefore wrote 32000 entries past the end of the heap block and died with
0xC0000005, which is why the wide calculators could not be cross checked here.

rot8_ins_init now takes the length and mallocs it, rot8_run_hooked passes `step`,
and read_tape_alloc's guard is back to ROT8_MAX_TAPE (16 M instructions) instead
of INS_SIZE.  Measured:

  cell 11, 62585 chars   ->  > 0046
  cell 16, 97307 chars   ->  > 00046   (same as derive's 62 32 48 48 48 52 54 10)
  smoke unchanged: serial R8F, -n 512 1536 512

So the reference machine and both R8Forge machines now agree at a non default
width as well, which is the first time the three implementations could be
compared above 11 bits.
2026-11-15 18:14:14 +08:00
dsh e2faeba011 io: INP writes the whole cell -- the calculator now runs in this machine
The serial INP deliberately kept bits 7 and above ("they belong to the frame,
leave everything above alone").  That made a tape depend on whatever happened to
be in the cell before the read, and the two R8Forge machines do not do it: their
-i assignment replaces the whole cell.  Measured consequence: examples/calc.r8asm
(a 62585 character tape, cell 11, well inside the limit) printed

    > 0000 / > 0000 / > 0000

here instead of "> 0046", while r8forge_tape_run and r8forge_derive agreed on
62 32 48 48 52 54 10.  The digit window and the display were not at fault:
drv/calc_disp.r8asm already printed correctly in both machines.

INP now writes `frame` (character + parity/stop if framing is on, zeros above)
and no longer ORs the old cell back in.  With that:

    rot8_test --cell 11 --input "12 34 + ." calc.rot8   ->   > 0046

and the smoke checks are unchanged: serial R8F, -n 512 1536 512, 7E1 A.  README
and docs/serial.md said bits above the character stay untouched; they now say INP
writes the whole cell, which is what every implementation does.
2026-11-15 18:05:50 +08:00
dsh c3ab2f1ac0 viz: size the tape buffer from the file, and refuse a too long tape loudly
read_tape filled a fixed INS_SIZE buffer and stopped at the limit without saying
anything, so a longer tape ran half a program and produced a plausible wrong
answer (a 112797 character calculator tape from a 17 bit build, for instance).

read_tape_alloc now allocates from the file size, filters the instruction
characters and returns the length, so nothing is ever cut in half.  Verified the
short tapes are unaffected (the smoke checks still pass: serial R8F, -n
512 1536 512, 7E1 A).

It also found the next wall: a 97307 character tape **crashes** the machine with
0xC0000005 (access violation) even though rot8_ins_size is uint32_t -- rot8.c
still has a fixed size assumption of its own somewhere.  Until that is found and
widened, read_tape_alloc refuses anything above INS_SIZE and the CLI says so,
which is strictly better than the silent truncation.  TODO gets the rest.
2026-11-15 17:51:20 +08:00
dsh 1aa895ff77 drop the CI workflow
The runner image has no cmake and the network would not cooperate with installing
it per run.  The smoke checks the workflow encoded still run by hand against a
local build (see the README); they can come back as a script whenever there is a
working runner.
2026-11-11 10:07:44 +08:00
dsh d594efe447 ci: install the toolchain from a domestic mirror
ci / smoke (push) Failing after 1m42s
2026-11-10 19:56:14 +08:00
dsh aafe105612 ci: assume a prepared image instead of apt-get per run
ci / smoke (push) Failing after 16s
Same reasoning as R8Forge: build the toolchain into the runner image once
(R8Forge/ci/Dockerfile works for this repo too), and let the job only check it is
present.
2026-11-10 19:52:35 +08:00
dsh c170627ed9 ci: install cmake and g++ before configuring
ci / smoke (push) Canceled after 0s
The runner image has no cmake (exit 127 on the first step), so the toolchain is
installed up front; the versions and core count land in the log.
2026-11-10 19:51:08 +08:00
dsh b4be8f6bae ci: cancel the previous run of the same ref when a new push arrives
ci / smoke (push) Failing after 15s
2026-11-10 19:44:36 +08:00
dsh 7f049e9f67 ci: keep the push tier cheap, add timeouts, skip docs-only commits
ci / smoke (push) Failing after 15s
2026-11-10 19:42:13 +08:00
dsh 570ad91958 ci: drop the schedule trigger
ci / smoke (push) Failing after 15s
Same reason as R8Forge: this repository is not touched nightly, so the workflow
runs on push, PR and by hand only.
2026-11-10 19:10:56 +08:00
dsh c1e4e166e4 ci: a smoke workflow for the promises the README makes
ci / smoke (push) Failing after 1m39s
The machine has no tests of its own -- tests/vm_test.c is the CLI -- so the new
.gitea/workflows/ci.yml checks the behaviours the README advertises instead:
serial ASCII by default (--input R8F prints R8F), -n still printing decimal
words (and.rot8 -> 512 1536 512), a 1 bit cell defaulting to numeric, the two
contradictory flag combinations exiting 2, 7E1 round tripping one character, and
--dump still drawing the 259 cell window.  --help has to keep documenting both
modes.

All of those were run by hand against the built binary before the workflow was
written; keep them in sync with the README when a mode changes.
2026-11-10 19:09:04 +08:00
dsh a4df21a47e docs: README down to the essentials, serial/7E1 details into docs/serial.md
The README had grown to 305 lines while features kept getting appended to it: a
35-line frame dump, a full option table, and three paragraphs of essays about
parity hardware. Split by what a reader needs first:

  README.md       intro + instruction table + quick start + I/O modes + live
                  view (trimmed sample) + geometry + 7E1 in five lines +
                  build/test                            305 -> 181 lines
  docs/serial.md  bit 7 not owned by I/O, why characters are not space
                  separated, the frame layout, why a stop bit is a bit in the
                  cell, and the "parity costs one latch" essay

Verified the commands the new quick start and test sections show against the
build: --input R8F on serial_echo (prints R8F), -n on and/or/full_adder (numbers),
--dump on wave (259 cells), --7e1 with input A.
2026-11-09 16:34:20 +08:00
dsh a083a3422c I/O: serial ASCII by default, numeric I/O behind -n/--numbers
The library can now print decimal digits (ROT-8's clb_digits/undigits), so a tape
usually wants characters out -- and serial was the one mode you had to remember
to ask for.  Flip that around:

    rot8_test tape          serial ASCII (cell >= 8 bits)
    rot8_test -n tape       the old decimal numbers

The default follows the geometry: a serial character needs 8 bits (7 data + 1
spare), so a 1..7 bit cell gets the numeric I/O instead -- 1-bit tapes keep
working with no extra flag.  Asking for -s/--serial (or --parity/--stop/--7e1) on
such a cell is still an error (exit 2), and -n together with a serial option is
now rejected as contradictory (exit 2).

--input follows the mode: text in serial, numbers with -n.  It was already
deferred until the whole command line was parsed, so order does not matter.

Docs: the README's I/O section is rewritten around the new default, the option
table gains -n/--numbers, the examples that feed numbers now pass -n, and the
INP/OUT note at the top explains the two modes.  --7e1 is unchanged apart from
being an explicit frame on top of a default that is already serial.

Also fixes the usage() printf: the examples had seven %s and only six program
arguments, one short (a stale bug, now matched up).
2026-11-09 16:25:02 +08:00
dsh 6e51df5240 Live view: highlight the pointer cell instead of a caret row under it
The grid already painted the pointer cell in reverse video, and then drew a
second line under the tape with a ^^ under the same cell -- the mark said the
same thing twice on a colour terminal, and it cost the frame a line.

The caret row is gone: the cell itself is the marker.  A terminal without
colour cannot show reverse video, so in that case the cell gets a star in the
separator column it would have used anyway -- same width, no extra line, and a
redirected --dump still says where the pointer is.

    |   00E7 | 400 001 010 020 040 080 100 200 400*000 000   |    --no-color
    |   00E7 | ESC[1;7m400 ESC[0m 001 010 ...                 |    colour

Checked on the 8, 11 and 32 bit geometries and in compact mode: the frame is
one line shorter (30 lines at the default 259x11, 24 compact), every line is
still 56 characters between the bars, and there is exactly one pointer mark
per frame.  The tapes (and/or/full_adder) still print what they printed.

README: the sample frame loses the caret row (the pointer cell shows the star,
which is what a piped --dump looks like) and the frame table says how the
pointer is marked now.
2026-11-07 22:47:13 +08:00
dsh 754f885a64 7E1 framing in serial mode: bit 7 parity, bit 8 stop
--7e1 is --serial --parity even --stop.  One cell carries a whole frame:
bits 0..6 the character, bit 7 the even parity bit, bit 8 the stop bit, which
leaves two bits of an 11 bit cell to the tape.

  * --parity none|even|odd: INP fills bit 7 from the character it read, OUT
    checks it.  --stop does the same for bit 8 being 1.  Both imply --serial,
    and a stop bit needs cell_size >= 9 (7+1+1).
  * OUT still sends the character when a frame is bad, like a UART flagging and
    carrying on, but says 'parity error' / 'framing error' on stderr, prints a
    summary at the end and exits 4, so a script can test the frame with \True.
  * The 7E1 round trip is checked: --7e1 --input A leaves 0x141 = 321 in the
    cell (0x41 data, parity 0 because 'A' has two bits set, stop 1) and OUT
    accepts it; flipping one data bit gives a parity error, and outputting a
    cell with bit 8 clear gives a framing error.
  * README: the frame layout, the switches, why the stop bit is one cell bit
    (no bit clock: one INP/OUT is a whole frame) and what parity costs in
    hardware -- one latching toggle driven by the read head, and the very same
    circuit checks a frame if you feed it all 8 bits and expect 0.
2026-11-07 16:14:30 +08:00
dsh d179aed54e Serial I/O: characters in the frame are not space separated
A character stream reads as text, so the in/out boxes now paste the run of them
together (one space after the label, none between characters): 'out (3) R8F'.
Decimal mode keeps its separators, where '789' would be a different number.

While looking at that: queued --input values never reached the frame at all,
only values typed at the live prompt did, because the recording lived inside
rot8_viz_ask.  It now happens in the hook when the INP actually executes, so
the queue, a typed answer and stdin all show up the same way -- and each INP
is recorded exactly once (the ask path no longer logs on its own).

Checked: --serial --input R8F gives 'in (3) R8F' / 'out (3) R8F'; the decimal
run still gives 'in (3) 7 8 9'; live prompting still logs one line per INP.
2026-11-07 16:01:51 +08:00
dsh 593e1c3b70 Serial ASCII mode: OUT writes one character, INP reads one
-s / --serial switches INP and OUT from decimal numbers to characters.  The
character is the low 7 bits of the cell, so the 8th bit stays the tape's own:
INP writes bits 0..6 and leaves everything from bit 7 up untouched, which is
where a flag, a length or a counter can live without the I/O trampling it.
Checked by hand: a cell preset to 0x80 that then reads 'A' ends at 0xC1, at 8
and at 11 bits per cell.

  * include/rot8/rot8_io.h, src/rot8_io.c: the mode itself, plus
    rot8_io_wrote_serial() so the CLI can close the line (a serial OUT writes
    no newline, that is the point); stdin is read as characters as well, and
    EOF feeds 0 instead of blocking.
  * src/rot8_viz.c: the frame shows characters in this mode -- the out/in
    boxes list them, the console prints output> 'R' 82, unprintables become
    \x0A so a frame stays one line of ASCII, and the live prompt takes the
    first character typed instead of parsing a number.
  * tests/vm_test.c: -s/--serial, a cell_size < 8 check (a 7 bit character
    plus a flag does not fit in fewer bits), --input becomes the text itself
    (one INP per character, which is why the arguments are now collected and
    pushed after the whole command line is known), and one trailing newline
    at the end because serial OUT has none.
  * tapes/serial_echo.rot8: ,.,.,. -- read three characters, echo them.
  * README: what the mode does, the bit 7 rule, and three ways to run it.

Decimal mode is unchanged: --input 7,5 still prints 7 and the existing demos
still print their numbers.
2026-11-07 15:58:06 +08:00
dsh c298bdca3b Rename the cell width to cell_size
The geometry was half renamed: mem_size was already lowercase, but the width
was still cell_bits, ROT8_DEFAULT_CELL_BITS and ROT8_MAX_CELL_BITS.  It is now
cell_size / ROT8_DEFAULT_CELL_SIZE / ROT8_MAX_CELL_SIZE, which is also what
R8Forge calls it on the C++ side, so one number has one name on both machines.

No behaviour change: 19 cell_bits, 4 ROT8_DEFAULT_CELL_BITS and 6
ROT8_MAX_CELL_BITS across include/rot8/rot8.h, src/rot8.c and tests/vm_test.c.
The CLI option stays --cell <bits>, because a bit count is what it takes, and
rot8_cell_width() keeps its name for the same reason: it answers "how wide",
it is not the geometry field.

Drive-by: the comment above parse_geometry claimed --cell only takes 8, 16 or
32; it accepts 1..ROT8_MAX_CELL_SIZE, and the README says so too.

Checked: the default geometry (11 bit cells, 259 cell tape) still runs
R8Forge's hash tape to 1322 1786 1600 5 94 127, which is exactly what the
assembler's own derive prints, and --cell 16 / --cell 8 --mem 256 still work
with the view laying itself out from the width (bits b15 .. b0, four hex
digits per cell).
2026-11-07 12:29:04 +08:00
dsh 348e64ec97 Centre the caret inside the cell it points at 2026-11-07 11:20:11 +08:00
dsh 83f18d46bb Put the caret under the cell it points at 2026-11-07 11:12:43 +08:00
dsh dde545d0d5 Geometry defaults: 11 bit cells on a 259 cell tape
Both knobs already existed (--mem / --cell, rot8_config_apply).  This only moves
the defaults off the historical 256 x 8, which is the interesting case: a tape
written for byte cells now means something else, and nothing crashes.

    rot8_test --dump tapes/and.rot8                     # 512 1536 512
    rot8_test --mem 256 --cell 8 --dump tapes/and.rot8  # 13 7 5, as before

What follows the width without being touched:

* ROR rotates inside the cell, so a single set bit walks 11 places instead of 8
  (the wave tape's view shows 001 010 .. 400 over 11 columns).
* FLB, BIZ and RNZ only look at the low bit, so they need no change at all.
* INP masks to the width and config validation covers 1..32.

What the view does with it: ceil(11/4) = 3 hex digits per cell, 11 columns a
row, and 259 cells is 24 rows, so the grid is a window around the pointer with
its range on the last line.

--mem 256 --cell 8 reproduces every earlier number byte for byte, so the
machinery is unchanged; only the default moved.
2026-11-07 10:56:15 +08:00
dsh 5a23ffd64d Any cell width, any tape length, and the frame follows both
The previous commit still treated the geometry as a small menu: 8/16/32 bits and
a grid whose column count was hard wired per width.  ROT-8 does not work that
way -- the tape is a ring of any length and a cell is a ring of any width -- so
both are open now:

    --cell 1 .. 32     (any value, not just 8/16/32)
    --mem  1 .. 1048576 (any value, not just powers of two)

What had to change for that:

* A cell needs ceil(bits/4) hex digits, at least one, so a 1 bit cell prints
  "0x1" instead of nothing and a 12 bit cell prints three digits.
* The number of cells per dump row is computed from the space the gutter leaves
  (VIZ_INNER - addr_digits - 5) divided by one cell's field width, capped at 16.
  Every geometry therefore lays out inside the 56 character frame: 16 columns at
  8 bits, 9 at 16, 5 at 32, 12 at 12 bits, and a ragged last row just ends early.
* rot8_config_apply accepts any cell_bits in 1..32 instead of three values.

Live mode needed nothing beyond that, but it is worth stating why it stays
stable: the frame height depends only on the geometry -- rows are
min(ceil(cells/cols), 16), the window line exists exactly when the tape is taller
than that, and the caret row is always drawn because the pointer is always on the
tape (it is a ring).  So every frame of a run is the same height and the in place
redraw cannot smear.  Width is capped at 58 characters for the same reason.

Checked: --dump for and, or, full_adder, wave and test is still byte identical to
the build before any of this, and -++++ gives 0x10 / 0x1000 / 0x100 / 0x10000000
at 8 / 16 / 12 / 32 bits.
2026-11-07 10:38:56 +08:00
dsh 4ae4bea2dd Tape length and cell width are chosen at run time
MEM_SIZE and CELL_SIZE were compile time constants: 256 cells of 8 bits, with
rot8_data pinned to uint8_t.  Both now come from a rot8_config that a machine
takes a copy of when it is created:

    rot8_config cfg = {4096, 16};   /* cells, bits per cell */
    rot8_config_apply(&cfg);        /* machines from now on */

    rot8_test --mem 4096 --cell 16 --dump tapes/wave.rot8

8, 16 and 32 bit cells are supported.  ROR rotates inside the configured width
(four rotations of a set bit give 0x10, 0x1000 and 0x10000000), FLB, BIZ and RNZ
still work on the low bit, and INP masks what it is given (70000 becomes 4464 in
a 16 bit cell and 112 in an 8 bit one).  rot8_data is uint32_t now so that a
cell holds the widest case.

The tape is a ring: stepping off either end lands on the other, which is what
makes a short tape safe to watch and matches what ROR already does inside a
cell.

The view follows the geometry.  A cell takes 2, 4 or 8 hex digits and a row
holds 16, 8 or 4 of them, so the frame stays 56 characters wide; wider cells get
a nibble grouped bit string instead of one column per bit.  A tape longer than
16 rows is drawn as a window around the pointer, with its range on the last
line.

Nothing changes for the default geometry: --dump output for and, or,
full_adder, wave and test is byte identical to before, and so is plain OUT
output.  The places that printed a cell with %d/%u print unsigned long now, so a
32 bit cell cannot come out negative.
2026-11-07 10:38:56 +08:00