Files
dsh 9b31a51fec hardware: M0 -- the packer, the RTL, and a simulator that agrees byte for byte
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.
2026-11-20 16:25:54 +08:00

213 lines
16 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.
# 给接手的 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` |