Files
R8Forge/AGENTS.md
T
dsh 0c75772cbb geometry: the ring size becomes a build option, and the machine takes 64 cells
259 was never part of the machine, just the historical default, so
kDefaultMemoryCells is now R8FORGE_MEMORY_CELLS (1..65536, default 259) with a
range guard in CMake, the same way the cell width already worked.  All five VMs
read it from geometry.hh, so nothing else had to change.

Measured the highest cell each tape in the tree actually touches by walking its
> and < and recording the peak (no tape does a < at cell 0, so none of them
depend on wrapping): calc 51, hello 49, signed_demo 34, term 27, and the
asm/test.r8asm self test 155, because it lays every macro cell block out side by
side.  So a 64 cell ring runs every program we ship; only the self test needs
the default.

Verified: the full ctest suite is 8/8 at both 128 and 64 cells (11 bit); at the
hardware geometry of 8 bit plus 64 cells the widthfree label is 5/5, and the
calculator tape is byte for byte identical to the 259 cell build and its
sessions take the same 166348 steps.  The self test also produces identical
output at 64 cells but 216 more steps, because its high cells fold back onto low
ones -- which is why SPEC section 1.2 states the rule: ring size must be at
least the highest cell a program touches plus one.

Hardware payoff: at 64 cells dp is a 6 bit counter whose wrap is free, so the
TTL build loses its modulo-259 comparator logic (four to five chips), the RAM
needs 64 bytes, and the drum shrinks to 8 tracks by 64 cells (at 3000 rpm that
is 52 s for a calculator session, so it wants to spin faster).  hardware.md is
updated to the 8 bit / 64 cell machine throughout.
2026-11-20 15:34:03 +08:00

15 KiB
Raw Blame History

给接手的 agent 的话

这是 R8Forge 的工作手册:怎么干活、哪些坑已经踩过、现在交接到哪儿。契约和数字不在 这里 —— 那在 SPEC.md;设计推理的长文在 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。

构建与自检

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 --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:

    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%、翻转 46%。这台机器没有随机寻址,每次访问的代价就是 |Δ地址|,所以布局才是性能旋钮:clb_digits 的 13 格草稿重排一轮,全家桶 64513 -> 62351 字符、236439 -> 202159 步(SPEC §7.7);--opt 再省 1415% 步数,正是因为它砍的是往返移动。

  • 一次会话很难把结论留在对话里 —— 落进 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; SPEC.md §12 是"别试"的结论,不是待办。眼下最靠前的是 TODO 里的"交互计算": 迷你 printf(终端纸带和计算器外壳都做完之后用处要重新评估)、以及栈要不要再深一格 (3 → 4 格现在没有预算障碍了)。

硬件那条线单独放在 docs/hardware.md:ISA 已经全部实现,机器语义 里没有任何东西能看见时间,所以"状态序列一致"就是同一台机器;文档里钉了硬件需求(含 biz/rnz 扫描的确切边界)、ROM/RAM 预算(ip 至少要 17 位 —— 计算器 73624 已经越过 历史 INS_SIZE)、FPGA / 分立 TTL / 机电三档载体,以及"先写 r8forge tape pack + RTL testbench 对拍"的 M0~M4 路线。没开工,等选档。

索引

想查 去哪儿
%synth 语法语义、几何、宏契约、验证矩阵、边界、维护清单 SPEC.md
除法为什么这么写、实测步数、没做的优化 docs/divmod.md
字节级库的取舍、原地补码的突破、乘法器那一课 docs/byte-ops.md
计算器的协议 / RPN 栈 / 终端外壳与三个坑 docs/calc.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