# 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 位宽」。 ## 快速开始 ```sh 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` 照模式解释,顺序无所谓。 ```sh 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`](docs/serial.md)。 ## 可视化内存 `--live` 一边执行一边把整条纸带画成实时视图,`--dump` 只在结束时打一张静态快照。 连续的 `>`/`<` **合成一帧**(状态栏写 `ptr +5 cell 91`,即这次访问走了多远、落到哪一格), 加 `--skip-moves` 则移动完全不渲染、只累计。移动永不跨 `[`/`]` 合并。 环境变量 `ROT8_VIZ_FRAMES=1` 会让运行结束时向 stderr 打一行 `draws/steps/moves/runs` 计数,用来量"合并省了多少帧": ```sh ./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 是任意宽的一圈位,所以运行时随便给: ```sh 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 行 | 只画指针附近的一窗(指针始终在窗口里) | 内嵌用法: ```c 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`](docs/serial.md)。 ## 构建与测试 ```sh 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` 是 `,.`。