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
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 即可。本项目默认 按 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          # 一边跑一边画内存

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 只在结束时打一张静态快照:

  ./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 是 ,.。

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%