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
2026-04-18 20:15:58 +08:00
2026-06-12 21:08:08 +08:00

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即可.
例如本项目以输入/输出十进制整数作为INP/OUT.

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

使用

  rot8_test tape

可视化内存

虚拟机可以一边执行 tape,一边把整条纸带(默认 259 个 Cell x 11 bit,--mem / --cell 可改) 画成一张实时视图:

  ./build/rot8_test --live tapes/wave.rot8
+--------------------------------------------------------+
| ROT-8 memory watch                     tapes/wave.rot8 |
+--------------------------------------------------------+
| step    500   pc 01F4/0527   op ROR                    |
+--------------------------------------------------------+
| cell  90/256   value  16 = 0x10  '.'                   |
|    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 |
|   30 | 01 02 04 08 10 20 40 80 01 02 04 08 10 20 40 80 |
|   40 | 01 02 04 08 10 20 40 80 01 02 04 08 10 20 40 80 |
|   50 | 01 02 04 08 10 20 40 80 01 02 10 00 00 00 00 00 |
|      |                               ^^                |
|   60 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
|   70 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
|   80 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
|   90 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
|   A0 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
|   B0 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
|   C0 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
|   D0 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
|   E0 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
|   F0 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
+--------------------------------------------------------+
| out (0)  none yet                                      |
+--------------------------------------------------------+

画面从上到下:

区域 内容
step / pc / op 已经执行的指令数,程序计数器,以及 pc 处即将执行的指令
cell ... value 指针所指 Cell 的编号、十进制值与十六进制值
b7 ... b0 该 Cell 的各位,# 为 1,. 为 0;宽 Cell 改画一行按 4 位分组的数据
纸带 每行 16 个 Cell(宽 Cell 会变少),行首是十六进制地址,^^ 标出数据指针;纸带比画面长时只画指针附近的一窗,末行注明窗口范围
out 到此刻为止 OUT 输出的值(保留最近 10 个)

参数:

选项 说明
-l, --live 运行动画,原地刷新
-d, --dump 结束时打印一张静态快照
-e, --every <n> 每 n 条指令画一帧;0(默认)表示整段动画大约 300 帧
-f, --fps <n> 刷新率上限,默认 30;0 表示不限速
-t, --tty / --no-tty 强制当成/不当成终端(见下)
-k, --compact / --full 强制精简画面/完整画面
-c, --color / --no-color 强制开/关 ANSI 颜色(默认跟随终端)
-i, --input <v...> 预先喂给 INP 的值(空格或逗号分隔)
-m, --mem <n> 纸带长度(单位 Cell),任意值,默认 259,范围 1..1048576
-b, --cell <bits> Cell 位宽,任意值,默认 11,范围 1..32
-h, --help 帮助

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

画面高度是自动挑的:终端不足 30 行用 24 行的精简版,测不出高度时也先按 24 行来(猜你屏幕不大),--full 可以强制完整版. 用 --tty 之前那套原地重绘才生效,所以如果你的终端其实是通过管道接进来的 (网页版终端、某些 IDE 的面板,程序 _isatty 看不出来),画面会变成一帧帧往下滚 —— 加个 -t 就好了.

纸带尺寸与 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
  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 一样是个环), 不会越界. 末行不满一行时右边留空.

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

场景 表现
位宽 ≤ 8 每位一列(b7 … b0),8 bit 与以前一模一样
位宽 > 8 一行按 4 位分组的字串(bits b15 .. b0 .... .... .... ..1.)
一格宽度 每格 ceil(bits/4) 个十六进制位;一格占的列数由宽度算出,所以画面永远 56 字符宽
纸带 ≤ 16 行 整条画出来
纸带 > 16 行 只画指针附近的一窗(指针始终在窗口里),末行注明 window A..B of N cells

内嵌用法:

  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 并且什么都不改. 把默认几何显式写出来(--mem 256 --cell 8)时,行为与改默认值之前逐字节一致:--dump 的 画面、OUT 的输出都没有变 —— 所以拿旧基准对比时记得把这两个参数带上.

注意:按 8 bit 写死的 tape 拿到 11 bit 下不只是算错,还可能永远跑不完 —— 那些 %rep 8 的循环只转了 8 圈,cell 没转回原位,"转到某位清零"的条件于是永远不成立. 实测旧 test.r8asm 的纸带在 11 bit 下 --dump 会一直跑下去. 换位宽请重新汇编纸带.

输入

INP 现在按这个顺序取值:先吃 --input 排好的队列,再问现场(live 模式),最后才回落到 stdin —— 所以不带 --input、也不开 --live 时行为与以前完全一样.

  rot8_test --input 7,5 tapes/full_adder.rot8    # 脚本/测试:一次喂完
  rot8_test --live tapes/echo.rot8               # 现场:画面下方问 input>

live 模式下画面分两层,框里只记录已经产生的输入输出,提示在框外面:

+--------------------------------------------------------+
| in (2) 123 65                                         |   <- 框里: 单行汇总
| out (2) 123 65                                        |   <- 框里: 单行汇总
+--------------------------------------------------------+
input> 123                                                   <- 框外: 逐事件日志
output> 123
input> 65
output> 65

框里那两行是单行汇总(各记全部值),框外是逐事件日志 —— 每次 INP/OUT 各占一行, 所以输入和输出的先后顺序看得一清二楚. 因为日志已经记了输出,--live 结束时不再重复打印一遍 原始输出.

轮到输入时,最下面会多出一行空的 input> 当提示,光标停在那里 —— 敲的数字落在窗口外面, 不会和画面挤在一起;回车之后提示消失,值进到上面日志里. 提示永远在最下面,所以不会出现 "后来的输出跑到提示上面"这种次序错乱. 日志只留最近 6 条,更早的用 .. 表示.

一开头就是 INP 的 tape 也没问题:提示会先把第一帧画出来再问,所以内存的初始状态是看得到的 (为此输入回调拿到了迭代器).

精简画面没有 in/out 框,框外的日志照旧. 只产生输出、不读输入的 tape 也会有 output> 日志.

stdin 已经关掉(管道读完)时喂 0 并照常跑完,不会卡住. tapes/echo.rot8(内容就是 ,.)是 拿来试这个的最小例子.

串行 I/O:7 位 ASCII 模式

-s / --serial 把 INP/OUT 从"十进制整数"切成"一个字符":

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

第 8 位(bit 7)以及更高的位不归 I/O 管:INP 只改低 7 位,把原来的高半个 cell 原样留着 —— 所以 tape 可以拿 bit 7 当标志位、长度位或者别的什么,而读写字符时它不会被冲掉. 想要 char 以外的数据,就放在那上面.

要求 cell 至少 8 位;不够会直接报错退出(exit 2),因为 7 位字符加 1 位标志才勉强放得下:

  rot8_test --serial --input "R8F" tapes/serial_echo.rot8   # 打 R8F
  echo A | rot8_test -s tapes/echo.rot8                     # 管道里喂一个字符
  rot8_test -s --live --input "hi" tapes/serial_echo.rot8   # 画面里也显示成字符

tapes/serial_echo.rot8 就是 ,.,.,.(读三个字符、原样打三个字符). 串行模式下字符是连着显示的 (字符流不该被空格拆开),数字模式才用空格分隔;画面里长这样:

| in (3) R8F                                             |
| out (3) R8F                                            |
output> 'R' 82
output> '8' 56
output> 'F' 70

--input 喂进去的值现在也会进 in 那一行(以前只有 live 现场提问才记),所以脚本跑完跟现场 敲的一样能看出输入输出怎么交错.

不可打印的字符(以及 0)在画面里写成 \x0A 这种转义,免得把帧撑坏;真正写到 stdout 时当然 还是原字节. 因为字符输出不带换行,程序跑完后 CLI 会补一个换行,免得提示符粘在后面.

想验证 bit 7 真的没被动过:把 cell 预置成 0x80 再读一个 A,cell 会是 0xC1 (-+ 在 8 位下就是把 bit0 的 1 转到 bit7,然后 ,. 读一个字符再打出来,--dump 能看到).

构建与测试

构建

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

运行(测试)


  ./build/rot8_test tapes/and.rot8
  ./build/rot8_test tapes/or.rot8
  ./build/rot8_test tapes/full_adder.rot8

  ./build/rot8_test --dump tapes/full_adder.rot8      # 跑完看一眼纸带
  ./build/rot8_test --live tapes/wave.rot8           # 看它把纸带刷成一道波

S
Description
ROT-8 with the live memory visualiser
Readme
407 KiB
0 Stars 1 Watchers 0 Forks
Languages
C 99.6%
CMake 0.4%