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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
--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.
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.
-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.
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).
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.
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.
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.
The log lines are not padded, so when a row got shorter than it had been in the
previous frame (the ' ..' trim marker is three characters, a value line is
more) the tail of the old row survived and read as one garbled line, e.g.
'.. t> 123'.
Each console row now ends with an erase-to-end-of-line when the view owns the
terminal, and the frames stop leaving debris behind.
Checked with ',.,.,.' fed 1 2 3 4: the trim marker shows as a clean ' ..' above
the last six events, and no row carries text from the frame before it.
requested change: keep the in (n) / out (n) inside the frame as single line
summaries, but log every event outside the frame so the interleaving of inputs
and outputs is readable:
| in (2) 123 65 |
| out (2) 123 65 |
input> 123
output> 123
input> 65
output> 65
The log keeps the last 6 events (older ones show as '..') so a long run does not
grow the console without bound; the prompt is still a separate empty 'input> '
line at the very bottom, which keeps the cursor the last thing on screen.
Tapes that only produce output now get the output> log too, which is what
replaces the replay that used to be printed after the run.
Three fixes from looking at a real run:
* input> showed only the last value. Both console lines now record every
value (with the same '..' trim as the out box), so a run that read 123 then
65 shows input> 123 65.
* output> was printed above input> even though the output happened later.
The order is now chronological: input record first, output record second,
and the prompt is a separate empty 'input> ' line under both, so the cursor
is always the very last thing and nothing can appear above it afterwards.
* with the console showing output>, replaying every OUT value after the run
was just noise: replay_output is off now (live still mutes OUT while the
frame is being drawn, so the values only appear in the console).
Checked with tapes/echo2.rot8 (',.,.'), fed 123 then 65 through a pipe: while
waiting for the second value the console reads 'output> 123' then an empty
'input> ', and at the end 'input> 123 65' / 'output> 123 65' with nothing
printed after. --input and --dump paths unchanged.
Two things were wrong with the first attempt:
* a tape that starts with INP never drew its opening frame, because the
prompt ran before the hook and there was no iterator to render with. The
input callback now receives the iterator, so it can paint the frame and
then ask -- the initial memory state is visible again.
* putting the prompt inside the frame left the cursor at the end of the
frame, which reads badly. The records stay inside:
| in (1) 13 |
| out (1) 13 |
and the prompt moved below the window, like a shell prompt under it:
output> 13
input> 13
output> grows with every OUT; input> is the prompt while INP waits and
becomes the value just given afterwards. The cursor sits right after
'input> ', outside the frame, so typing does not fight the drawing.
Tapes that never read input get none of the lines outside the frame, and the
existing tapes look exactly as before.
Checked: echo.rot8 first frame now shows step 0 / pc 0000 / op INP with the
memory grid, then input> below; --input 42 still prints 42; --dump and the
piped live run are unchanged.
Printing 'input> ' where the cursor happened to be made a mess of the frame, so
the prompt is now part of it:
| in (1) 13 |
| out (1) 13 |
While INP waits the line reads 'input> ' and the cursor is left at its end, so
the number is typed in place; afterwards the line turns into the record of what
was fed in, mirroring the out box. A tape that never reads input gets no extra
line at all, so nothing changes for the existing tapes.
The frame also got a redraw helper, because the prompt has to repaint the frame
before asking; the live hook now goes through the same helper.
One case cannot use the frame: a tape like tapes/echo.rot8 (just ',.') reaches
INP before the first frame is drawn, so there is nothing to hang the prompt
above and it falls back to a plain 'input> ' on the current line. Longer tapes
show it inside the frame.
Checked: --full frame shows in above out, compact frame shows the in line too,
wave/and/or/full_adder are unchanged, and the value still reaches the program.
INP read straight from stdin with scanf, which the live view cannot offer: the
view owns the terminal, and a tape that wants input either ate a number nobody
typed or blocked on a pipe.
INP now takes its value from, in order:
1. a queue filled by --input "7,5" (spaces or commas, scripts and tests)
2. a hook the live view installs: it prints 'input> ' under the frame and
reads a line, redraws on the next tick, and feeds 0 when stdin is done so
a tape behind a pipe still finishes
3. stdin, exactly as before
So nothing changes for a plain run, and --live can drive programs that need
input. tapes/echo.rot8 (just ',.') is the smallest tape that exercises it.
rot8_test --input 42 tapes/echo.rot8 -> 42
rot8_test --live tapes/echo.rot8 -> asks under the view
Tests: --input with one value, with a list, a live run fed through a pipe
(prints 5), and a live run with stdin already closed (feeds 0, terminates).
The --dump path and the untouched tapes (and, or, full_adder, wave) still work.
A terminal can be a pipe: web terminals and IDE panels hand the program a
pipe for stdout, so isatty() says no, --live quietly fell back to printing
one frame after another and -f was ignored. Add -t to say "there is a
terminal at the other end anyway" (and --no-tty for the opposite), and say
so on stderr when the fallback happens, so the flag can be found.
Frames no longer end with a newline, so a frame of N lines needs N rows
instead of N+1 and a 24 row terminal shows the whole compact frame. The
size heuristics follow from that: shorter than 30 rows -> compact, size
unknown (behind a pipe) -> compact, LINES is honoured when the console
cannot be asked, and --full forces the tall frame.
Colour is now only switched off for a real console that cannot do VT, not
for every stream that is not a console: behind a pipe the far end may be
perfectly capable.
The machine can now hand a hook the whole execution, and rot8_viz draws
what it sees: the 256 cell tape as a hex map, the cell under the pointer
with its eight bits, the program counter and the values OUT produced.
rot8_test --live tapes/wave.rot8 # redraw in place while it runs
rot8_test --dump tapes/and.rot8 # one static snapshot at the end
Frames are plain ASCII, so the view survives pipes, ssh and logs; colour
is ANSI and only used when the terminal can take it. Running without
--live or --dump behaves exactly as before: the tape just runs.
rot8.h gains rot8_run_hooked() plus read-only accessors for the tape,
the program counter and the step count, so that tools do not have to
reach into rot8_iter. read_tape() now reports a missing file and stops
at the end of the buffer instead of writing past it. Also fixes the
ROR/FLB opcode comments, which had the BF characters the wrong way round.
tapes/wave.rot8 is a small demo: it walks a single set bit across 240
cells, which looks like a wave moving over the tape.