The two things software cannot check by reading its own source are the 3 bit
packing and the bracket strategy, so both got a tool and a test.
New in the library (r8forge/tape.hh, src/tape.cc): the opcode numbering (taken
from ROT-8-viz enum, so the packed image and the hardware decoder cannot drift),
text <-> opcodes, opcodes <-> 3 bit bytes, the .r8t image with its trailer and
crc32, and a machine model that runs a packed tape the way a board would. The
model takes the bracket strategy as an option: backward scan with loop stack or
not, and jump-back-onto-the-[ (the contract) or past it (what the interpreters
do). All four combinations print the same thing, and the step count differs by
exactly the number of taken ] instructions -- which is what the test asserts.
Found and fixed while writing it: the loop stack discipline depends on the jump
convention. Jumping onto the [ means the [ re-pushes, so ] must pop on the jump;
jumping past it means the entry must stay until the loop exits. Mixing them up
emptied the stack on the second iteration of the calculator main loop -- caught
by the equivalence test on examples/calc.r8asm, not by reading the code.
Tools: r8forge_tape_pack (text tape -> image + --hex for $readmemh + --verify,
727 instructions become 273 bytes for hello, 62%, and the trailer sits past the
halt so address 0 of a ROM is instruction 0), and r8forge_tape_run now reads an
image directly and takes --loop-stack / --retest.
hardware/rot8.v: the 8 bit / 64 cell machine -- 3 bit opcodes from a byte
addressed memory read as a 16 bit window, a 6 bit dp with free wrap, the loop
stack bracket jump, blocking input, halt on ip == length, and a step counter that
counts instructions rather than cycles. hardware/tb_rot8.v loads a --hex image
and prints the OUT stream in tape_run format.
Verified with Icarus Verilog 14 (the RTL against tape_run --loop-stack --retest):
hello 577 instructions 417 steps 10 outs
term 16414 17643 11 (fed "lhi")
calc 51378 166741 19 (fed "12 34 + .": prints the prompt,
046 and the next prompt)
flagship 43676 100142 93
Every OUT stream identical. ctest -R rtl_sim runs that comparison from an 8 bit
build (11 tests in the default build now, where the RTL test self-skips because
the RTL is the 8 bit machine).
Two traps worth remembering: Icarus passes plusargs through as raw bytes, so an
absolute +HEX path containing non-ASCII (this checkout is under a Chinese
directory name) arrives mangled, $readmemh silently leaves the memory empty and
the machine obediently runs LEN steps of opcode 0 printing nothing -- run vvp
from the directory holding the hex with a relative name. And in_ready must not
be qualified with !in_valid or the input handshake deadlocks.
213 lines
16 KiB
Markdown
213 lines
16 KiB
Markdown
# 给接手的 agent 的话
|
||
|
||
这是 R8Forge 的工作手册:怎么干活、哪些坑已经踩过、现在交接到哪儿。**契约和数字不在
|
||
这里** —— 那在 [`SPEC.md`](SPEC.md);设计推理的长文在 [`docs/`](docs/)。
|
||
|
||
这份文件**入库**,只写项目事实。只对某台机器/某个会话成立的东西(VS 的 cmake 路径、
|
||
PowerShell 的编码坑、git 身份和 push 提权、临时目录抽风……)放在 `AGENTS.local.md`,
|
||
它被 `.gitignore` 忽略、换机器重新写一份。**新接手的环境先看那份。**
|
||
|
||
> 动手前请把这份文件读完(约 5 分钟),需要细节时再按索引跳。历史教训里最贵的一条是:
|
||
> 有一轮把"移位-加法乘法器更快"当成新发现重推了一遍,其实早被否过又复活过 —— 结论都在
|
||
> `docs/byte-ops.md` 和 SPEC §12 里,先读再推翻。
|
||
|
||
## 现在是什么状态
|
||
|
||
* 汇编器 + 搜索器 + 标准库都齐了:`%synth` 汇编期合成、位级/字节级/原地/乘除/数字
|
||
转换(`clb_digits` ↔ `clb_undigits`)、动态循环、串行 ASCII I/O 都能跑。
|
||
* **有符号数已经做完**(SPEC §5.4 的约定、§7.10 的实现):`clb_digits_signed`(`-0042`
|
||
这种显示)、`clb_divmod_signed`(截断除法、余数随被除数)、计算器的一元负号
|
||
(`examples/calc.r8asm`)。加、减、乘按二补码天然正确,没有改。
|
||
* **计算器是 3 格 RPN 栈 + 终端外壳**(73624 字符):数字压栈、运算符立刻算(弹二压一)、
|
||
`.` 显示栈顶但不动栈;打字有回显、退格能改数字、回车提交并补提示符。旧的两寄存器版
|
||
算不了嵌套(`1 2 + 3 4 * + .` 打 `0007`,现在 `0015`)。终端的实现与三个坑见
|
||
`docs/calc.md` §8;代价是**超过旧 INS_SIZE(65536)**(现在 viz 按纸带长度分配缓冲,
|
||
16 位 112802、32 位 336304 都照跑)。
|
||
* **`examples/term.r8asm` 是行编辑终端**(21721 字符):4 格行缓冲 + 退格编辑 + 回车/EOF
|
||
提交 + 按行首字符分派命令(`l` 长度、`r` 反着打、`q` 退出)。表头那组 `in lhi` 就能
|
||
测到整条分派链(EOF 会把没提交的行也提交掉)。
|
||
* 全绿基线(这台机器约 1 分钟;命令见下)。
|
||
* 另一个仓库 `../ROT-8-viz`(fork `dsh/ROT-8-viz`,分支 `main`)是权威虚拟机 +
|
||
可视化:**默认 I/O 是串行 ASCII**(cell ≥ 8 位),数值 I/O 用 `-n` / `--numbers`,
|
||
另有 7E1 帧(`--parity` / `--stop` / `--7e1`)。`clb_digits` 产出的 ASCII 直接喂它的 `OUT`。
|
||
|
||
## 构建与自检
|
||
|
||
```sh
|
||
cmake -S . -B build -G "Visual Studio 18 2026" -A x64
|
||
cmake --build build --config Release
|
||
|
||
# 注意:必须用给 build/ 配的那个 cmake(PATH 上的另一个版本会重新配置,然后死在
|
||
# "No preprocessor test for PellesC")。本机路径见 AGENTS.local.md。
|
||
|
||
# 当前基线:都通过,别弄坏(`ctest --test-dir build -C Release -j 4` 一次跑完 8 条,约 12 秒。
|
||
# VS 是多配置生成器,**`-C Release` 不能省**,否则 8 条全报 "Not Run")
|
||
r8forge asm/test.r8asm # 62351 字符(除两个有符号包装宏外每个宏一次 + 每个语言特性)
|
||
r8forge_byte_op_test # 23 项(divmod 16384 组、digits 2048、digits_signed 2048、divmod_signed 4202、undigits 4096);8/11/16 位真跑,17 位以上打印 skipped
|
||
r8forge_examples_test # 19 个 example + asm/test.r8asm,核对头部 `; out`/`; in`
|
||
r8forge_macro_docs_test # 55 macros in 23 files
|
||
r8forge_tape_pack hello.rot8 -o hello.r8t --hex hello.hex --verify # 文本纸带 -> 3 bit 打包镜像,--hex 是 $readmemh 用的
|
||
r8forge_tape_pack_test # 打包/解包往返 + 括号四种实现输出一致(含循环栈 + retest)
|
||
r8forge_tape_run hello.r8t --loop-stack --retest # 直接跑打包镜像;这两个开关对应板子的实现
|
||
# 8 位 + 64 格是物理机的几何(-DR8FORGE_CELL_SIZE=8 -DR8FORGE_MEMORY_CELLS=64):
|
||
# ctest -R rtl_sim 在那里会真编 hardware/rot8.v 跑 iverilog 对拍,其它几何打印 SKIP
|
||
r8forge --opt asm/test.r8asm # 纸带窥孔优化 62351 -> 56338(>< 净位移、+ mod W、- mod 2)
|
||
r8forge_tape_opt in.rot8 out.rot8 # 同一优化,但作用在已有纸带上
|
||
r8forge_tape_run t.rot8 --profile # 剖面:指针移动占 66~73% 步数(实测,见下)
|
||
r8forge_synth_test examples/full_add.r8asm # all eight combinations ok
|
||
r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0
|
||
powershell -File tests\widths.ps1 # 位宽矩阵:每个位宽一套工具链 + 断言(约 20 分钟)
|
||
powershell -File tests\widths.ps1 -Widths 32 # 32 位:整套 10 个 target 能建,byte_ops 只打印 skipped
|
||
```
|
||
|
||
**位宽上限是 32**(每份 VM 的 cell 都是 `uint32_t`;CMake 里 `-DR8FORGE_CELL_SIZE` 越界直接
|
||
`FATAL_ERROR`,所以别再指望 C++ 报错才发现)。想往上要按 SPEC §13 的清单同时改五份 VM、
|
||
`geometry.hh`、汇编器的立即数类型和 ROT-8-viz 的 `rot8_data`。`drv/` 里的驱动**必须**
|
||
用 `.var D _CELL_SIZE * 30103 / 100000 + 1` 算位数 —— 写死 4 格导致 digits 三项在 8/16 位
|
||
一直挂着,2026-11 才修。
|
||
|
||
`asm/test.r8asm` 的纸带**必须留在 65536 条指令以下**(ROT-8-viz 的 `INS_SIZE`;现在的
|
||
虚拟机缓冲是按纸带长度现算的,这条是历史口径 + 交叉验证,别指望它)所以里面只有"每个宏
|
||
一次 + 两轮 hash",现在离上限只剩 ~3.2k。**两个有符号包装宏不在里面**:它们各自要把
|
||
`clb_digits` / `clb_divmod` 再展开一份(+12.1k / +5.6k)。它们的回归是
|
||
`examples/signed_demo.r8asm`(`examples_test` 会跑),穷举在 `r8forge_byte_op_test`。
|
||
|
||
`r8forge_byte_op_test` 是**唯一按返回值判断字节级对错的**;其它自检只证明"汇编得出来"或
|
||
"位级正确"。`r8forge_derive` 会检查汇编错误(漏 `%include` 时纸带是截断的,以前不看 error
|
||
位会跑出一个看起来正常的错答案)。
|
||
|
||
## 工作方式(踩过的)
|
||
|
||
* **写结论之前先对虚拟机**:字节级结论必须能被 ROT-8-viz 复现。**先确认那台机器的 viz 是重编过的**——
|
||
旧二进制的串行 `INP` 只改低 7 位(2026-11 改成整格写入),症状是交互程序打出 `> 0000`,
|
||
曾经被误判成"纸带坏了"。注意它现在默认串行输出,
|
||
要比数值流就加 `-n`:
|
||
|
||
```sh
|
||
ROT-8-viz/build/Release/rot8_test.exe -n <tape.rot8> # 每个 OUT 打一行十进制
|
||
r8forge_derive <src.r8asm> -1 # 另一份实现,out 逐位比
|
||
r8forge_tape_run <tape.rot8> [addr=value...] # 直接喂纸带的第二份实现
|
||
```
|
||
|
||
* **提交身份是 `dsh`,不是仓库主人**:两个仓库都用 `dsh <dsh@gitea.local>`(仓库主人的
|
||
`StarCells <peng080306@foxmail.com>` 别用)。具体命令和本机的 git 配置见 `AGENTS.local.md`。
|
||
* **数字要能被别人复现**:§1.3 的口径写死了怎么量(最小驱动、不带 `output`);改宏之后
|
||
顺手跑一遍基线,别只信自己这次跑出来的数。
|
||
* **交互程序这样测**:`r8forge_tape_run t.rot8 -i "12+34="`(字符喂给 `inp`,低 7 位,读空后为 0),
|
||
`r8forge_derive <src> 0 -i "..."` 是同一份输入的第二个实现;例程把输入写在头部
|
||
`; in ...`,`r8forge_examples_test` 会自动喂。实时终端那一侧在 ROT-8-viz(默认串行)。
|
||
* **代价的大头是"走"不是"算"**:`tape_run --profile` 实测,计算器 71.1%、全家桶 73.0% 的步数是 `>`/`<`,旋转只占 7%、翻转 4~6%。这台机器没有随机寻址,每次访问的代价就是 `|Δ地址|`,所以**布局才是性能旋钮**:`clb_digits` 的 13 格草稿重排一轮,全家桶 64513 -> 62351 字符、236439 -> 202159 步(SPEC §7.7);`--opt` 再省 14~15% 步数,正是因为它砍的是往返移动。
|
||
* 一次会话很难把结论留在对话里 —— **落进 commit message 和文件注释**。
|
||
|
||
## 一条硬规矩:不许动机器语义
|
||
|
||
**除了 `INP`/`OUT` 的语义(那是宿主接口,允许按需定义),机器语义在没有明确要求的情况下一个字都
|
||
不许改**:8 条指令的行为、`biz`/`rnz` 判 `LSB`、`+` 是右旋、`-` 翻最低位、步数怎么算、
|
||
内存是环、纸带从第一条指令跑到尾 —— 全部冻结。
|
||
|
||
**几何(位宽 / 环大小)不是语义**,它是 `geometry.hh` 的构建选项:`-DR8FORGE_CELL_SIZE`
|
||
(1..32)、`-DR8FORGE_MEMORY_CELLS`(1..65536,默认 259)。换它们不算改语义,但**必须**按
|
||
SPEC §13 走:先看目标纸带的最高格号(SPEC §1.2 有实测表:程序峰值 calc 51 / hello 49 /
|
||
term 27,全家桶自检 155),再跑整轮自检确认。物理机取 **8 位 + 64 格**(见
|
||
`docs/hardware.md`);64 格在硬件上白送一个简化 —— `dp` 是 6 位计数器,回绕免费。
|
||
|
||
这条规矩是有来由的:三份实现(`derive` / `tape_run` / ROT-8-viz)互为对拍,任何一边"顺手修一下"
|
||
都会让另外两边看起来是错的,而我们没有第二份规格可以裁决。要改语义,先在 SPEC 里写清楚、
|
||
再四份一起改(见 §13),否则只改`工具`和`视图`。
|
||
|
||
## 语义上会咬人的几条
|
||
|
||
|
||
```
|
||
'-' flb 翻转最低位 cell ^= 1
|
||
'+' ror 右旋整个 cell (注意:和 Brainfuck 的 +/- 不一样,写仿真器时别按常识猜)
|
||
'[' biz 最低位 0 -> 跳到匹配的 ']' 之后
|
||
']' rnz 最低位 1 -> 跳回匹配的 '['
|
||
```
|
||
|
||
1. **`biz`/`rnz` 判的是 `cell & 1`,不是"整格是否为零"**。所以 `set_0` = `[-]` 只清最低位
|
||
(255→254、128 原样、5→4),清整格要 `%rep _CELL_SIZE { set_0; ror }`(`erase`)。
|
||
2. **条件块的身体必须回到它自己的条件 cell**(净位移 0):`dp` 是汇编期常量,跳过/进入两条
|
||
路径的 `dp` 不一致之后所有 `.tp` 全部错位(症状:`dp` 跑到 1023)。`set_0` 的身体不移动、
|
||
`clb_bit_mov` 最后 `.tp before` 再 `flb`(顺便吃掉条件)。
|
||
3. **合成块只保证"输出位初值为 0"** 的调用点(`compress_stat_space` 把初值无关的位清成 0),
|
||
所以位级包装宏里的 `set_0` **不能删** —— 删了 `clb_mul` 62064/65536 错、`clb_divmod`
|
||
14742/16384 错、`clb_digits` 2048/2048 错(其中一个 HANG)。见 SPEC §3.6。
|
||
4. 位宽是 `_CELL_SIZE`(默认 11),宏里写 `%rep _CELL_SIZE` 就与位宽无关;改几何要照
|
||
SPEC §13 的清单**四份虚拟机一起改**。换位宽后旧纸带要重新汇编(写死的 `%rep 8` 在新位宽下
|
||
可能永远跑不完)。
|
||
|
||
## 已经确认走不通的(别重试,理由见 SPEC §12)
|
||
|
||
* **3 个 cell 的加法切片**:层数 5/8 都报 `no program up to N layers`(3 cell 的**自增/取负**
|
||
切片有解,两个操作数塞不进 3 个 cell)。
|
||
* **原地写回的 `%synth` 表**(`A←~A^Ci` 等四个)全部无解 —— 一个合成块只有一个条件 cell,
|
||
区分不了 "A=1 且 Ci=0" 和 "A=1 且 Ci=1"。**但手写可以**:`clb_inc_ip` 是 89 字符。
|
||
* **让切片自己在输入上取反**、**4 cell 加法切片保留 A、B**:都无解。想保留操作数用 6 cell 的
|
||
`bit_raw_add`。
|
||
* **字节级真值表(2^16 项)交给 `%synth`**:搜索空间不可行。
|
||
* **"每个 bit 一个 cell"再拼字节级运算**:能跑通但没有意义,实现已删(一个 cell 能放一个字节、
|
||
位也读得出来)。要拼字节级就用 `raw_*` / `clb_*_nc` / `clb_*_ip`。
|
||
* **字节级程序"跑不动"先怀疑虚拟机**:仓库里曾有三份解释器把 `biz` 写成整格零判断,于是
|
||
所有字节级程序看起来都在死循环 —— 别再把库判成坏的。
|
||
|
||
## 刚做完的四件事:有符号数、RPN 栈、终端纸带、终端接上计算器
|
||
|
||
二补码、`-0042` 显示、截断除法、静默溢出,约定在 SPEC §5.4、实现在 §7.10。
|
||
`clb_digits_signed` / `clb_divmod_signed` 都是包装(真活还是 `clb_digits` /
|
||
`clb_divmod` 干的),加、减、乘一个字没改。**两条容易踩的**:
|
||
|
||
* 符号位靠 `rol` + `bit_copy` + `ror` 读(49 字符)。**别换 `clb_bit_mov`** —— 它吃掉源位,
|
||
于是 `1024` 会打成 `0000`(`examples/signed_demo.r8asm` 就是这条例子的回归)。
|
||
* 标志位在 `biz`/`rnz` 里必须被吃掉才能退出,所以"用完还要留"的符号位要搬到另一格
|
||
(`clb_bit_mov`),这就是为什么 `clb_divmod_signed` 要 T1、T2、F 三格。
|
||
|
||
计算器接着换成了 **3 格 RPN 栈**(`S0` 栈顶 / `S1` / `S2`):运算符立刻算、`.` 是真 peek、
|
||
一元负号按**栈深**判(`DEPTH == 0`)。旧的"两寄存器 + 待结算 OP"版本算不了嵌套
|
||
(`1 2 + 3 4 * + .` 打 `0007`,现在是 `0015`)。**3 格是当时的纸带预算逼出来的**:
|
||
一格一次 `copy`(约 500 字符),4 格就顶上 65536 —— 现在接了终端、纸带已经 73624,
|
||
所以这条预算不再是硬约束(4 格 = ~74.1k)。挪栈的**次序不能反**(从高往低搬)。
|
||
|
||
计算器最后接上了终端外壳(**不是**把 `term.r8asm` 的行缓冲搬进去):回显每个字符、
|
||
退格删数字窗口最后一位、回车提交并补 `> `。三个坑值得记住:判据用的常量格会被
|
||
`clb_sub_nc` 吃掉 / 被运算整块 `erase`(要"用之前现装");`set_1` 只保证最低位是 1;
|
||
回车提示符必须赶在命令分派和运算之前打(`EH` 借的 `SC+3` 会被 `mul` 写掉)。
|
||
细节在 `docs/calc.md` §8。
|
||
|
||
`examples/term.r8asm` 又是另一种东西:**行缓冲(左对齐 + LEN)+ 退格编辑 + 回车/EOF 提交
|
||
+ 命令分派**(`l` 长度、`r` 反着打、`q` 退出)。三条硬教训:
|
||
|
||
* **"else" 必须用标志格写**:`biz` 只在最低位是 1 时进身体,"没命中就做 B"不能靠推断 ——
|
||
先 `set_1` 一个 FLAG,命中那支清 0,出块再看。而且 `biz` 的条件格是**当前 dp**,
|
||
所以顺序必须是"先 set FLAG、再 `.tp` 到条件格、再 biz"(写反了就是每轮都命中)。
|
||
* **被减数会被吃掉**:分类用的 `clb_sub_nc` 吃操作数,所以回显/追加都要用副本 CE;
|
||
拿 C 当追加源的那一版,行缓冲永远是空的。
|
||
* **热单元格要挨着排**:`copy`/`clb_sub_nc`/`clb_nonzero` 内部都有 `.tp`,有的还在
|
||
`%rep _CELL_SIZE` 里 —— 常数格排到 22..28 时整条纸带 33k,挤进 0..27 就回到 21.7k。
|
||
|
||
## 下一步
|
||
|
||
候选、想清楚但没做的优化、以及工具侧的小尾巴都收在 [`TODO.md`](TODO.md);
|
||
`SPEC.md` §12 是"别试"的结论,不是待办。眼下最靠前的是 TODO 里的"交互计算":
|
||
迷你 `printf`(终端纸带和计算器外壳都做完之后用处要重新评估)、以及栈要不要再深一格
|
||
(3 → 4 格现在没有预算障碍了)。
|
||
|
||
**硬件那条线**单独放在 [`docs/hardware.md`](docs/hardware.md) 和 [`hardware/`](hardware/):ISA
|
||
已经全部实现,机器语义里没有任何东西能看见时间,所以"状态序列一致"就是同一台机器。已定
|
||
**8 位 / 64 格**;**M0 做完了** —— `r8forge_tape_pack` 出 3 bit 打包镜像,`hardware/rot8.v`
|
||
(循环栈括号 + 就地执行)在 iverilog 里跑,`hello` / `term` / `calc` / 全家桶的 OUT 流与
|
||
步数和 `tape_run --loop-stack --retest` **逐字节一致**,`ctest -R rtl_sim` 固化(8 位构建)。
|
||
上板(M1)还没开始,缺引脚约束、串口和面板。
|
||
|
||
## 索引
|
||
|
||
| 想查 | 去哪儿 |
|
||
|---|---|
|
||
| `%synth` 语法语义、几何、宏契约、验证矩阵、边界、维护清单 | [`SPEC.md`](SPEC.md) |
|
||
| 除法为什么这么写、实测步数、没做的优化 | [`docs/divmod.md`](docs/divmod.md) |
|
||
| 字节级库的取舍、原地补码的突破、乘法器那一课 | [`docs/byte-ops.md`](docs/byte-ops.md) |
|
||
| 计算器的协议 / RPN 栈 / 终端外壳与三个坑 | [`docs/calc.md`](docs/calc.md) |
|
||
| 造一台真机器:硬件需求、预算、三档载体、对拍路线 | [`docs/hardware.md`](docs/hardware.md) |
|
||
| 上游语言规格(`%synth` 不在里面) | `r8asm_rev/SPEC.md`(本机路径见 `AGENTS.local.md`) |
|
||
| ROT-8 指令集(`BIZ`/`RNZ` 判 LSB) | `../ROT-8-viz/README.md` 与 `src/rot8.c` |
|