Files
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

188 lines
9.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 是 `,.`。