Files
ROT-8-viz/README.md
T
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

9.5 KiB
Raw Blame History

ROT-8

以无 ALU 为前提设计的 1-Bit Brainfuck 变体,以及用于测试该指令集的、以 C 实现的简单虚拟机。

概述

ROT-8 ([rəʊˈteɪt]) 提供了一套简洁的指令集,使利用无 ALU 的各种奇葩元件(如类似差分机的 机械计算机、红石电路,甚至是水槽水闸与水车)进行计算变得可行且通用 —— 对,就是蒸汽朋克里最常见的那类东西,不过这个真的可以运行。

指令集

ROT-8 指令 对应 BF 字符 行为
STP > 数据指针右移 1 Cell
BTP < 数据指针左移 1 Cell
ROR + 当前 Cell 循环右移 1 bit
FLB - 翻转当前 Cell 的 LSB(最低位)
BIZ [ 如果当前 Cell 的 LSB 为 0,跳到匹配的 ] 之后
RNZ ] 如果当前 Cell 的 LSB 不为 0,跳回匹配的 [ 之后
OUT . 输出当前 Cell
INP , 从输入读取到当前 Cell

INP/OUT 的实现不做规定,只要 INP 能改变整个 Cell、OUT 能读取整个 Cell 即可。本项目默认 按 7 位 ASCII 串行做 I/O(8 位及以上的 cell,一个字符一次);更窄的 cell 和 -n / --numbers 用"整格十进制整数"的老行为 —— 见「I/O 模式」。

Cell 的位宽不属于指令集:任何位宽都成立(LSB 永远是那一位,ROR 在这个位宽里循环)。 本项目默认 11 bit,位宽和纸带长度都能在运行时改 —— 见「纸带尺寸与 Cell 位宽」。

快速开始

mkdir build && cd build && cmake .. && make -j$(nproc)

./build/rot8_test --input R8F tapes/serial_echo.rot8   # 默认串行:读字符、原样打出来
./build/rot8_test -n tapes/and.rot8               # 要十进制整数就加 -n
./build/rot8_test --live tapes/wave.rot8          # 一边跑一边画内存
./build/rot8_test --live --skip-moves tapes/wave.rot8  # 移动不单独出帧,只累计

I/O 模式:默认串行(7 位 ASCII),-n 切回十进制

INP/OUT 默认按一个字符走(8 位及以上的 cell):tape 里放一个 'R'(82)出去就是一个 R。以前那套"整格十进制整数 + 换行"还在,用 -n / --numbers 打开:

串行(默认,cell ≥ 8 位) 十进制(-n / --numbers)
OUT 低 7 位当字符,直接 putchar,不加换行 整格的值 + 换行
INP 读一个字符,只写低 7 位 读一个十进制数,整格覆盖
--input 字符串,一个字符一个 INP 数字列表 7,5

默认由位宽决定:cell ≥ 8 位走串行(7 位字符 + 1 位余量),< 8 位走数值 I/O —— 所以 1 bit 那种机器照旧跑,不需要额外参数。显式写了 -s / --serial 又不够宽会报错退出(exit 2); -n 跟串行选项一起写也会被拒(exit 2)—— 两种模式互斥。--input 照模式解释,顺序无所谓。

  rot8_test --input "R8F" tapes/serial_echo.rot8    # 打 R8F
  echo A | rot8_test tapes/echo.rot8                # 管道里喂一个字符
  rot8_test -n --input 65 tapes/echo.rot8           # 要十进制:65,不是 A
  rot8_test --7e1 --input "A" tapes/serial_echo.rot8   # 一个 cell 装一整帧 7E1

bit 7 及更高位不归 I/O 管(INP 只改低 7 位)、字符流为什么不分隔、7E1 帧怎么算校验位, 细节在 docs/serial.md。

可视化内存

--live 一边执行一边把整条纸带画成实时视图,--dump 只在结束时打一张静态快照。 连续的 >/< 合成一帧(状态栏写 ptr +5 cell 91,即这次访问走了多远、落到哪一格), 加 --skip-moves 则移动完全不渲染、只累计。移动永不跨 [/] 合并。 环境变量 ROT8_VIZ_FRAMES=1 会让运行结束时向 stderr 打一行 draws/steps/moves/runs 计数,用来量"合并省了多少帧":

  ./build/rot8_test --live tapes/wave.rot8
  ./build/rot8_test --dump tapes/wave.rot8
+--------------------------------------------------------+
| ROT-8 memory watch                     tapes/wave.rot8 |
+--------------------------------------------------------+
| step    500   pc 01F4/0527   op ROR                    |
+--------------------------------------------------------+
| cell   16/259   value  128 = 0x80  '.'                 |
|    b7  b6  b5  b4  b3  b2  b1  b0                      |
|     #   .   .   .   .   .   .   .                      |
+--------------------------------------------------------+
|      | +0 +1 +2 +3 +4 +5 +6 +7 +8 +9 +A +B +C +D +E +F |
|   00 | 01 02 04 08 10 20 40 80 01 02 04 08 10 20 40 80 |
|   10 | 01 02 04 08 10 20 40 80 01 02 04 08 10 20 40 80 |
|   20 | 01 02 04 08 10 20 40 80 01 02 04 08 10 20 40 80 |
+--------------------------------------------------------+
| out (0)  none yet                                      |
+--------------------------------------------------------+

(纸带按每行 16 格铺开,指针那一格反显;长纸带只画指针附近的一窗,末行注明窗口范围。)

区域 内容
step / pc / op 已执行的指令数、程序计数器、pc 处即将执行的指令
cell ... value 指针所指 Cell 的编号、十进制值与十六进制值
b7 ... b0 该 Cell 的各位(# 为 1,. 为 0);宽 Cell 改画一行按 4 位分组的数据
纸带 每行 16 格(宽 Cell 会变少),行首是十六进制地址;指针那格反显,终端没颜色时值后面跟 *
out 到此刻为止 OUT 输出的值(保留最近 10 个)

不加 --live 与 --dump 时直接跑完,只留下 OUT 的输出。--live 期间 OUT 被画面接管, 程序结束后再原样补打出来,所以重定向到文件依然拿到完整输出。输出不是终端时 --live 退化成 逐帧打印(可以直接 less 着看),程序也会在 stderr 提一句。

画面高度自动挑:终端不足 30 行用精简版,测不出高度时也按 24 行来,--full 可以强制完整版。 如果你的终端其实是通过管道接进来的(网页版终端、某些 IDE 面板,_isatty 看不出来),画面会 一帧帧往下滚 —— 加 -t 就恢复原地重绘。

完整参数表见 ./build/rot8_test --help(-e 每帧指令数、-f 帧率上限、-c 颜色、 -k 精简画面、-i 输入、-m/-b 几何)。

纸带尺寸与 Cell 位宽

两者都不在指令集里 —— 纸带是任意长的环,Cell 是任意宽的一圈位,所以运行时随便给:

  rot8_test --mem 300 tapes/wave.rot8           # 300 格(不是 2 的幂也行)
  rot8_test --mem 1000 --cell 16 tapes/wave.rot8
  rot8_test --mem 64 --cell 1 tapes/wave.rot8   # 1 bit 的 Cell(默认走数值 I/O)
  rot8_test --mem 100 --cell 12 --live tapes/wave.rot8
  • 位宽 1..32,任意值:ROR 在这个位宽里循环(16 bit 时 bit0 转到 bit15),FLB 翻 LSB, BIZ/RNZ 仍然只看 LSB,INP 的值截到该位宽。同一条 -++++(置位后转 4 次)在 8 / 16 / 32 bit 下分别是 0x10 / 0x1000 / 0x10000000。
  • 纸带长度 1..1048576,任意值:指针走出纸带会绕回另一端(和 Cell 的 ROR 一样是个环), 不会越界;末行不满一行时右边留空。

画面完全跟着几何走,每帧高度只由几何决定,不随指针移动变化(原地重绘因此不会拖影):

场景 表现
位宽 ≤ 8 每位一列(b7 … b0)
位宽 > 8 一行按 4 位分组的字串(bits b15 .. b0 .... .... .... ..1.)
一格宽度 每格 ceil(bits/4) 个十六进制位,画面永远 56 字符宽
纸带 > 16 行 只画指针附近的一窗(指针始终在窗口里)

内嵌用法:

  rot8_config cfg = {1000, 12};   /* 纸带长度, Cell 位宽 */
  rot8_config_apply(&cfg);        /* 之后创建的机器都用这个几何 */
  rot8_config_default(&cfg);      /* 恢复默认 259 x 11 */
  size_t cells = rot8_mem_cells(iter);
  unsigned bits = rot8_cell_width(iter);

rot8_config_apply 只在越界(0 格 / 位宽 0 或 >32 / 长度 >1048576)时返回 false 并且什么都不改。

按 8 bit 写死的 tape 拿到 11 bit 下不只是算错,还可能永远跑不完:那些 %rep 8 的循环只 转了 8 圈,cell 没转回原位,"转到某位清零"的条件于是永远不成立。换位宽请重新汇编纸带。

7E1 帧:7 数据位 + 偶校验 + 1 停止位

--7e1 = --serial --parity even --stop,一个 11 位 cell 装一整帧还剩 2 位给 tape 用:

bit 8 7 6..0
含义 停止位(恒 1) 偶校验位 7 位字符

INP 负责填这两个帧位,OUT 负责查;帧不对时字符照样打出去(和真 UART 一样),但 stderr 会记 parity error / framing error,进程退出码 4。校验位怎么用硬件算出来、 为什么停止位是 cell 里的一个 bit,见 docs/serial.md。

构建与测试

mkdir build && cd build && cmake .. && make -j$(nproc)

./build/rot8_test -n tapes/and.rot8            # 与门
./build/rot8_test -n tapes/or.rot8             # 或门
./build/rot8_test -n tapes/full_adder.rot8     # 全加器
./build/rot8_test --dump tapes/full_adder.rot8 # 跑完看一眼纸带
./build/rot8_test --live tapes/wave.rot8       # 看它把纸带刷成一道波

tapes/serial_echo.rot8 就是 ,.,.,.(读三个字符、原样打三个字符),拿来试串行 I/O 和 --input 最小;tapes/echo.rot8 是 ,.。