Files
R8Forge/AGENTS.md
T
dsh 6e8e33e455 test.r8asm now multiplies as well as adds
The file was the library smoke test: it set up a few cells, called raw_add and
printed five values.  It now also calls clb_mul and prints the two product bytes,
so one tape exercises both of the expensive paths and the self check runs a
result rather than only an assembly.

    127 + 130 = 257        -> S = 1, Co = 1
    200 * 200 = 40000      -> PL = 0x40 = 64, PH = 0x9C = 156
    whole tape             5417 characters (was 1666)

Both interpreters agree on `out 127 130 0 1 1 64 156`: r8forge_derive from the
source and r8forge_tape_run from the assembled tape, 427343 steps.

The multiply half lives at cells 16 and up so it cannot disturb the add half, and
the file's existing cell layout is untouched.
2026-11-07 10:15:58 +08:00

25 KiB
Raw Blame History

给接手的 agent 的话

这个文件是给下一个会话(或者下一个 agent)看的交接说明。内容都是这个仓库里实测过的结论, 不是推测;每条后面基本都跟着一次失败的尝试,别再踩。

工作方式(上一轮踩到的)

  • 超过 ~30 秒的命令一律丢后台(run_in_background),前台只做短轮询。 一次搜索可以跑 680 秒、缓存预热 885 秒,前台干等会撞上客户端和 API 的传输超时。

  • 别让大段 stderr 进上下文。PowerShell 遇到原生命令出错会吐一整套 NativeCommandError 堆栈;用 2>$null 收干净,判断结果靠 $LASTEXITCODE 和 stdout。

  • 写含中文的文件用编辑工具(UTF-8)。不要用 PowerShell 做"读-改-写":这台机器上 Get-Content 默认按 GBK 读 UTF-8 文件,再 Set-Content -Encoding utf8 写回去就是 二次转码、整篇变乱码(AGENTS.md 就这么被我毁过一次,靠 git checkout -- AGENTS.md 救回来)。Set-Content -Encoding ascii 更糟,汉字直接变 ? (examples/full_add_flat*.r8asm 就这么坏过一次)。

  • 构建要用 VS 自带的 cmake:build/ 是 Visual Studio 18 2026 生成器配的, 直接敲 PATH 上的 scoop cmake(4.4)会因为版本不一致重新配置,然后死在 No preprocessor test for "PellesC"。用这个:

    "C:/Program Files/Microsoft Visual Studio/18/Community/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe" \
        --build build --config Release
    
  • %synth 的临时文件:汇编器把生成的宏写到系统临时目录再 import,然后删掉。这台机器上 这一步偶尔会失败(r8asm: cannot open 'C:\Users\...\Temp\xxx.synth.r8asm';同目录下 cmd 能写、r8forge 不能,原因没查清,重跑一次可能就好了)。现在代码会退回到当前工作 目录重试,stderr 留一句 <临时目录> is not writable, using <cwd>。看到这句不用管; 看到 cannot write the synthesised macro anywhere 才是真坏了。*.synth.r8asm 已在 .gitignore 里。

  • 会话很长时传输容易失败,重要结论要落到 commit message 和文件注释里,别只留在对话里。

  • 写结论之前先对虚拟机:这个仓库最贵的一次事故就是虚拟机语义写错,然后在错的东西上 写了一整套"实测结论"(见「字节级运算」)。字节级结论必须能被 ROT-8-viz (C:\Users\peng0\git\ROT-8-viz,权威实现)复现。

  • 推代码:origin = https://gitea.starcells.ltd/dsh/R8Forge.git。这台机器上 schannel 会报 schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS, fetch / push 都得走 openssl 后端 —— 已经写在这个 repo 的 local config 里 (git config http.sslBackend openssl),正常 git push 就行。 如果当前会话的沙箱是 workspace-write,push 还要一次提权:git 的凭证助手要开命名管道, 沙箱会拒绝(sh.exe: fatal error - couldn't create signal pipe, Win32 error 5 + could not read Username);danger-full-access 下不需要。fetch 两种模式都不需要 (仓库可匿名读)。

构建与自检

# MSVC Release
cmake -S . -B build -G "Visual Studio 18 2026" -A x64
cmake --build build --config Release

# clang-cl(scoop 的 llvm,比 MSVC 严格,能抓出模板推导问题)
clang-cl /nologo /std:c++20 /EHsc /O2 /I include src/r8asm.cc src/synth.cc tests/asm_test.cc /Fe:r8forge.exe

自检:

r8forge asm/test.r8asm                            # 应 exit 0,5417 字符(加法 + 乘法各一段)
r8forge_synth_test examples/full_add.r8asm        # all eight combinations ok
r8forge verify_clb_bit_add_nc.r8asm               # 4 cell 加法切片(进位进->出)
r8forge verify_clb_bit_inc_nc.r8asm               # 3 cell 自增切片,进位同样进->出
r8forge_byte_op_test                              # 字节级库:17 个操作穷举/抽样,1.5 秒
r8forge_macro_docs_test                           # asm/ 里每个宏的注释格式

r8forge_byte_op_test 是唯一按返回值判断字节级对错的;前三个只证明"汇编得出来"或 "位级正确"。

r8forge_derive 是验证工具:

r8forge_derive <file.r8asm> 4 0 2         # 按输入组合跑,打印 stat
r8forge_derive <file.r8asm> -1 0=100 1=50 # 指定 cell 初值跑一遍,打印 out
r8forge_derive <file.r8asm> -2 0=100      # 同上,另外倒出所有非零 cell

注意 -1/-2 是拿汇编源码跑的(内部会先 import_file),不能直接喂 .rot8 纸带。 r8forge_tape_run <file.rot8> [addr=value...] 是第二个实现,直接喂纸带,用来交叉验证 derive(两个实现同时写错的可能性比一个低)。

指令集语义(这些搞错会浪费一整轮)

'-'  flb  翻转最低位        cells[dp] ^= 1
'+'  ror  右旋整个 cell
'['  biz  最低位为 0 -> 跳到匹配的 ']' 之后
']'  rnz  最低位为 1 -> 跳回匹配的 '['

最后两条的关键在"最低位"三个字:biz/rnz 判的是 cell & 1,不是"整格是否为零"。 权威实现是 ROT-8-viz/src/rot8.c:

void rot8_biz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 0) { ... } }
void rot8_rnz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 1) { ... } }

由此推出两条关键约束:

  1. set_0 = [-] 清的是最低位,不是整个 cell。 set_0 把 255 变成 254、把 128 原样留着、把 5 变成 4。要清整个字节就 %rep _CELL_SIZE { set_0; ror }(erase 就是这么写的)。一个字节的位能读: ror 若干次把目标位转到最低位,再 biz。
  2. 合成的程序只碰每个 cell 的低 K 位(K = 参与运算的输入位数),高位不追踪。 所以 %synth 出来的块只适用于"每格一位"的世界。

写手写宏还有第三条:dp 是汇编期算的常量,而 [...] 的 body 在运行期可能被跳过。 所以每个条件块的身体必须回到它自己的条件 cell(净位移 0),否则跳过路径和进入路径的 dp 会不一致,之后所有 .tp 全部错位 —— 症状是 dp 跑到 1023 这种地方( r8forge_tape_run --trace 能直接看到)。库里的宏都遵守:set_0 的身体不移动、clb_bit_mov 的身体最后 .tp before 再 flb(顺便把条件吃掉)。

曾经这里还写过第三条("多字节 cell 的位读不出来")—— 那是把 biz 当成 Brainfuck 的 整格零判断推出来的,错的,已删。

字节级运算(一个 cell 一个字节)

结论:库里的字节级宏是对的,穷举全过。r8forge_byte_op_test 实测(1.5 秒):

宏 驱动 纸带 结果
raw_add(a+b,含进位) drv/raw_add_byte.r8asm 1647 字符 65536/65536
raw_and drv/raw_and_byte.r8asm 639 字符 65536/65536
raw_or drv/raw_or_byte.r8asm 575 字符 65536/65536
raw_xor drv/raw_xor_byte.r8asm 463 字符 65536/65536
raw_inc(a+进位) drv/raw_inc_byte.r8asm 1214 字符 512/512
clb_add_nc(a+b+进位,4 cell) drv/raw_add_nc_byte.r8asm 688 字符 65536/65536
clb_inc_nc(a+进位,3 cell) drv/raw_inc_nc_byte.r8asm 430 字符 256/256
clb_neg_nc(~a+进位,3 cell) drv/raw_neg_nc_byte.r8asm 448 字符 256/256(取负)
同上,进位 0 drv/raw_not_nc_byte.r8asm 447 字符 256/256(反码 ~a)
clb_sub_nc(a-b,4 cell) drv/raw_sub_nc_byte.r8asm 707 字符 65536/65536
clb_not_ip(~a,原地,1 cell) drv/not_ip_byte.r8asm 17 字符 256/256
clb_inc_ip(a+1,原地,2 cell) drv/inc_ip_byte.r8asm 74 字符 256/256
clb_neg_ip(-a,原地,2 cell) drv/neg_ip_byte.r8asm 90 字符 256/256
clb_dec_ip(a-1,原地,2 cell) drv/dec_ip_byte.r8asm 106 字符 256/256
clb_nonzero(a!=0 的标志,原地) drv/nonzero_byte.r8asm 209 字符 256/256
clb_add_ip(a+=b,原地,4 cell) drv/add_ip_byte.r8asm 558 字符 2048 抽样全过(O(b) 运行)
clb_mul(mc×mul → 16 位积,10 cell) drv/mul_byte.r8asm 3729 字符 64 抽样全过(O(mul) 运行)
asm/fibonacci.r8asm — 8761 字符 跑出 1 1 2 3 5 8 13 21 34 55,和文件注释一致

raw_* 保留操作数(A、B 原样还回来),clb_*_nc 把 A、B 吃干净 —— 所以后者能省掉 Co 和 tmp:4 cell 加法/减法、3 cell 自增/取负。两者都用轮转驱动,差别只在 "操作数要不要还回去"。

clb_*_nc 的进位 cell 是真正的进位输入:宏自己不动它的初值(曾经写错过 —— 加法里 set_0、自增里 set_1,那就不是输入了,而且把多字节串接堵死了)。 调用者给 0 就是普通运算,给 1 就是"自带 +1"的那种,或者把上一字节的进位输出接过来串。

补码

-A = ~A + 1、A - B = A + ~B + 1,所以取负/减法都是"取反 + 加法/自增", 那个 +1 由调用者通过进位输入给:

宏 做法 Ci=1 Ci=0
clb_neg_nc A S Ci 先 clb_not_ip A 把整个字节原地取反,再走 clb_inc_nc -A(补码取负) ~A(反码)
clb_sub_nc A B S Ci 先 clb_not_ip B 把整个字节原地取反,再走 clb_add_nc A - B A - B - 1

取调整字节一次、提到循环外面,比"每 bit 取反一次"更短(也少两个 flb 包装): clb_neg_nc 468 → 448、反码那一版 467 → 447、clb_sub_nc 725 → 707。 B 本来就会被加法吃掉,所以在原地取反它没有任何代价。

clb_sub_nc 的进位输出是没有借位(A >= B 时为 1),所以它顺带就是无符号比较; clb_neg_nc 的进位输出只在 A 原本是 0 时为 1(-0 = 0 但确实进了位)。

取反必须发生在切片外面:想让 %synth 自己取反(表 S=~A^Ci、进位 ~A&Ci,3 参数) 报 no program up to 8 layers。原因是模型只会"牺牲一个 cell → 条件翻转别的 cell", A=0 时整块跳过、S 只能留在 0,而取反要求 A=0 时 S=1 —— "无条件翻转"表达不出来。

原地(结果回到原来的 cell)

宏 干什么 cell 纸带 穷举
clb_not_ip A A = ~A(反码) 1 17 256/256
clb_inc_ip A T A = A + 1 2 74 256/256
clb_neg_ip A T A = -A(补码取负) 2 90 256/256
clb_dec_ip A T A = A - 1 2 106 256/256
clb_nonzero B F T F = (B != 0),B 不动 3 209 256/256
clb_add_ip A B T F A += B,B 被吃掉 4 558 2048 抽样

对比写回 S 的切片版:clb_inc_nc 430(3 cell)、clb_neg_nc 448(3 cell)—— 原地版短 5 倍、少一个 cell。clb_neg_ip 就是 clb_not_ip + clb_inc_ip。

"原地补码不可能"这个结论是错的,这里记一下它是怎么错的(别再复现同样的推理):

  • %synth 的四个原地表(A←~A^Ci、A←A^Ci、A←A^B^Ci、A←A^~B^Ci)确实全部报 no program up to 8 layers,原因是一个合成块只有一个条件 cell,区分不了 "A=1 且 Ci=0" 和 "A=1 且 Ci=1"。这一步是实测,没问题。
  • 错在把它当成了整条路的结论。手写不一定要照逐位进位链写。

真正可行的算法换个思路,不去逐位测进位:

  1. 用 [ ... ] 的自然语义(最低位非零就继续)把最低位连续的 1 清掉(flb + ror), 遇到第一个 0 时退出循环;
  2. 那个 0 翻成 1 —— 输入是全 1(0xFF)时跳过,正好就是回绕那一格;
  3. 剩下的位置只旋转,转满八格为止。

卡点变成"还要转几格",而 cell 只有两个。解法是把计数塞进 T 的位里:T 先做成 0xFF, 每转一格就 set_0 + ror 消掉一个 1 —— 一串 1 的长度就是剩余圈数(每步 3 字符的移位寄存器 计数器,一圈正好数八格)。于是两个 cell 够用,而且比切片版短得多。

顺带纠正另一半:[ ... ] 的"跑了就必然消耗被测位"不是死路 —— 只要被测的是计数器, 不是数据。这条以前被写成"手写也做不到(2 cell)",错的。

原地取反仍然是最便宜的一个:%rep _CELL_SIZE { flb; ror },一个 cell、17 字符。 自减用补码恒等式拼出来,不用新算法:B - 1 = ~(-B),所以 clb_dec_ip = clb_neg_ip + clb_not_ip(106 字符)。

原地加法,以及"只有纸带长度是目标"这条

clb_add_ip A B T F:A += B,原地,4 个 cell(A、B、T、F),558 字符, B 被吃干净。对比:raw_add 1647(6 cell,保留操作数)、clb_add_nc 688 + 每轮 copy 364。

没有去写逐位的进位链加法:全加器的进位是 maj(a,b,c),也就是两两的合取,而每个条件测试 都会吃掉被测的那一位,所以要么先拷贝好几份位、要么嵌套测试 —— 又长又脆。

改成利用一件在本仓库里成立的事:只有纸带长度是目标,运行步数不是。

while B != 0:  A += 1 ; B -= 1

循环体在纸带里只出现一次,所以长度和 B 的大小无关;代价是运行 O(B)(B=255 时约 30 万步, r8forge 的上限是 500 万)。这个取舍在别处也能用 —— 凡是"长度优先"的地方都可以想 "能不能用循环把代码压掉"。

剩下的难点是"B != 0"怎么测(biz 只测最低位)。clb_nonzero B F T 的做法:每位先把它 搬进工作位 T(这一步清掉 B 的那一位),若 T 是 1 就把 F 置一并还原 B 的那一位, 转一格看下一位;八轮后 B 原样、F = (B != 0)。注意是 set_1 不是 flb —— 这里踩过: flb 是翻转,偶数个 1 位会把标志翻回 0(3、5、255 都测错过)。

乘法器(asm/mul.r8asm)

clb_mul MC MUL PL PH MCA S Ci T F NR:(PH:PL) = MC * MUL,10 个 cell,3729 字符, r8forge_byte_op_test 抽 64 组全对(含 255*255 = 0xFE01),最坏运行约 100 万步。

用的是重复加法,不是移位-加法:

(PH:PL) = 0
while MUL != 0:  (PH:PL) += MC ; MUL -= 1

理由还是「只有纸带长度是目标」:循环体在纸带里只出现一次,所以长度和 MUL 无关, fibonacci(8761)都比它长。

16 位累加靠 clb_add_nc 的进位输出:低字节相加拿到进位,再用 clb_add_ip 把这一位加进高字节。 clb_add_nc 会把操作数吃干净,所以每轮先 copy 一份被乘数(clb_add_ip 不输出进位, 所以低字节那一步只能用会吃操作数的那条)。

设计上的教训:我一开始以为乘法器缺"跨字节移位"和"条件累加"两件,实际上一件都不需要 —— 换成重复加法之后,移位整个消失了。缺的那件(保留加数的原地加)反而是关键,它逼出了 clb_add_ip 和 clb_nonzero。先看目标函数(长度)再选算法,别先照着硬件乘法的样子拼。

顺带纠正一个流传下来的说法:raw_add 不吃掉操作数。实测 5+3 → A=5 B=3 S=8, 255+255 → A=255 B=255 S=254 Co=1。asm/fibonacci.r8asm 里"每圈都要重新复印"的注释 是过度保守(它确实复印了,但不复印也对)。

这次差点被写进文档的错误诊断(别再犯)

有一轮里,raw_add / raw_and / copy / fibonacci 全被判定"运行时是坏的", 理由是 set_0 对多字节 cell 不收敛、纸带跑到步数上限。那是虚拟机写错了: 仓库里有三份解释器(tests/synth_test.cc、src/derive.cc、tests/tape_run.cc) 把 biz/rnz 实现成了"整格是否为零"(Brainfuck 直觉),于是每个字节级程序 都变成死循环。改回 & 1 之后全部通过。

为什么之前没被发现:位级程序在两种语义下行为完全一样(0/1 的最低位就是它自己), %synth 的表、asm/test.r8asm、full_add 全都不受影响;只有字节级驱动能区分。 所以以后凡是"字节级看起来跑不动",第一个怀疑对象是虚拟机,不是库。

验证方法:拿 ROT-8-viz/build/rot8_test.exe 跑同一条纸带对答案。 tests/tape_run.cc 现在是正确语义(& 1),可以直接对。

另一位一 cell 的实现在这里被删过一次(别再加回来)

"每个 bit 一个 cell、用 clb_bit_add_nc 串成 8 位加法器"这条路能跑通(32 cell, 1308 字符,65536 组合全对),但它是上面那个错误诊断的产物:既然一个 cell 能放一个字节、 位读得出来,就没必要为每个 bit 花一个 cell。R8Forge 之前也删过一次同样的东西 (交接文档原话:"8 位加法 25 个 cell,没有实用价值")。 要拼字节级运算就用 raw_* / clb_*_nc / clb_*_ip。

%synth 相关

  • 语法:params N + mode tape|layers + metric chars|flat|blocks + layout ...(可选)
    • 目标表 stat ... 或 map ...。stat 的项数必须是 2^params(3 参数要 8 项)。 参数是输入位 %1..%K、输出位、剩余草稿位(草稿位必须结束为 0,语义见 compress_stat_space)。
  • metric flat:不计 .tp 行走代价 → 结果与 cell 布局无关、缓存可跨调用点复用。 metric chars 才是按实际布局最优。库里的块统一用 flat。
  • 缓存:.r8forge_cache/(已入库,克隆下来直接命中)。键 = 模型版本 + params + mode + metric + 解析后的整张目标表(+ layout,仅 chars)。改指令模型时要 bump kModelVersion(src/synth.cc)。
  • 缓存代价参考:bit_raw_add 的 flat 搜索 990,636,137 状态 / 680 秒 / ~22 GB 内存。 层数上限现在是 8(原来是 5,5 会把一些可行的表误判成不可能)。

已经验证可行的东西

东西 结论
库里的 7 个位运算块(and/or/xor/inc/add) 合成版比手写短:asm/test.r8asm 1714 → 1666 字符
asm/test.r8asm 也演乘法 现在 1666 → 5417 字符(raw_add 一段 + clb_mul 一段),跑出 127 130 0 1 1 64 156(= 127+130 和 200×200),derive 与 tape_run 两个实现一致
clb_bit_add_nc(4 cell 忽略进位切片) flat 代价 27,完整全加器切片是 38;8/8 组合正确
clb_bit_inc_nc(3 cell 自增切片) 表 0 4 4 2 0 4 4 2(3 参数)缓存里就有,4 blocks;纸带 54 字符,4/4 组合正确
clb_add_nc(4 cell 字节加法) 688 字符,65536 组合全对;比 6 cell 的 raw_add 少 2 个 cell、短 959 字符
clb_inc_nc(3 cell 字节自增/加 0-1) 430 字符,256 组合全对;比 5 cell 的 raw_inc 少 2 个 cell
clb_neg_nc(3 cell 取负/取反) 448 / 447 字符,各 256 组合全对(Ci=1 取负、Ci=0 反码)
clb_sub_nc(4 cell 减法) 707 字符,65536 组合全对;进位输出顺带是无符号比较(A >= B)
clb_not_ip(1 cell 原地取反) 17 字符,256 组合全对;比走切片那条路快 26 倍
clb_inc_ip(2 cell 原地自增) 74 字符,256 组合全对;切片版 clb_inc_nc 是 430
clb_neg_ip(2 cell 原地取负) 90 字符,256 组合全对;切片版 clb_neg_nc 是 448
clb_dec_ip(2 cell 原地自减) 106 字符 = neg + not(B-1 = ~(-B)),256 全对
clb_nonzero(非零标志) 209 字符,256 全对,B 保持原样
clb_add_ip(4 cell 原地加) 558 字符,2048 抽样全对;raw_add 1647 / clb_add_nc+copy 1052
clb_mul(10 cell 8 位乘法,16 位积) 3729 字符,64 抽样全对;比 fibonacci(8761)短,和 MUL 大小无关
bit_raw_add(6 cell 全加器切片) 保留 A、B;字节级 raw_add 1647 字符,65536 组合全对
raw_and / raw_or / raw_xor / raw_inc 639 / 575 / 463 / 1214 字符,各 65536(inc 512)全对
asm/fibonacci.r8asm 8761 字符,跑出 10 项斐波那契,和注释一致

已经确认走不通的(别重试)

  • 3 个 cell 做加法切片:层数上限 5 和 8 都报 no program up to N layers (3 cell 的自增/取负切片是有解的,两个操作数塞不进 3 个 cell)。
  • 原地写回的 %synth 表:A←~A^Ci、A←A^Ci、A←A^B^Ci、A←A^~B^Ci 四个表全部报 no program up to 8 layers。原因是一个合成块只有一个条件 cell,区分不了 "A=1 且 Ci=0" 和 "A=1 且 Ci=1"。但手写可以:换成"清连续 1 + 计数器旋转"的算法,2 cell 就够 (clb_inc_ip 74 字符、clb_neg_ip 90 字符,见「原地」)。别把这条读成"手写也不行"。
  • 让切片自己在输入上取反(表 S=~A^Ci、进位 ~A&Ci,3 参数):no program up to 8 layers。 模型只会"牺牲一个 cell → 条件翻转别的 cell",输入为 0 时整块被跳过、S 只能保持 0, 表达不出"无条件翻转"。取反只能放在切片外面(一条 flb)。
  • 4 cell 的加法切片要做到"保留 A、B":表改成保留 A、B 后报 no program up to 8 layers。 想拿回操作数只能用 6 cell 的 bit_raw_add。 但这不等于"轮转需要保留操作数" —— 这句以前写错过。轮转只是 "读走最低位 → 丢掉 → ror",吃掉操作数完全没问题:clb_add_nc(4 cell)就是这么跑的, 65536 组合全过。
  • 字节级(2^16 项真值表)交给 %synth:搜索空间不可行。

命名与注释格式(照 SPEC.md,别自己发明)

R8ASM 的语言规格不在这个仓库里:

  • SPEC.md:C:\Users\peng0\git\r8asm_rev-fork\SPEC.md(r8asm_rev 里那份一模一样)。 语言、内建指令、运算符优先级、作用域、标准宏前缀都在里面。%synth 不在里面 —— 那是 R8Forge 自己的扩展,只有本仓库的 README 有文档。
  • ROT-8 指令集规格:C:\Users\peng0\git\ROT-8-viz\README.md("1-Bit Brainfuck 变体", 指令表里写明 BIZ/RNZ 判 LSB)。

SPEC 第 136-150 行的标准宏前缀:

前缀 全称 含义
clb clobber 破坏性宏,会破坏原始输入(多数情况是清零)
bit bit 对 cell 的 LSB 操作的宏
raw raw 未经封装的宏,通常要手动传入 tmp cell 作为实参

raw 不是"暴露 cell 作为参数"(这条以前写错过):raw_add 之所以叫 raw, 是因为它要你自己给 Co 和 tmp 那两个草稿 cell。bit 则说明所有 CellBit 形参 指的都是最低位 —— 这跟 biz/rnz 判 & 1 是同一件事:整套语言是围绕"1 位"设计的。

既有宏对号入座:

宏 为什么这么叫
raw_add / raw_and / raw_or / raw_xor / raw_inc 字节级,且草稿 cell 由调用者传
bit_raw_add(6 cell) 位级,且 %6: buf 是真正的草稿:内容无关,结束是垃圾
clb_bit_add_nc(4 cell) 四个 cell 都有意义,没有草稿 cell(所以没 raw),而 A、B 被吃掉(所以有 clb):第 3 个是"进→出"的进位,A=0 B=0 进位入=1 时 S=1
clb_bit_inc_nc(3 cell) 同样:A 被吃掉,进位进→出,没有草稿 cell
clb_add_nc(4 cell)/ clb_inc_nc(3 cell) 字节级版本,同样吃 A、B
clb_neg_nc(3 cell)/ clb_sub_nc(4 cell) 补码取负/减法,同样吃 A(和 B)
clb_not_ip / clb_inc_ip / clb_neg_ip / clb_dec_ip / clb_add_ip 同上再加 _ip(in place):结果回到原来的 cell,草稿 cell 由调用者传
clb_nonzero 破坏性的纯计算(把 B 抄成"非零"标志),不带 _ip 后缀
clb_bit_mov 位级搬运,并且把源吃掉
bit_copy / copy 位级/字节级拷贝,缓冲由调用者传(历史命名,少了 raw)
set_0 / set_1 / erase / rol / step / back / output 基础操作,不带前缀

%synth 块名 = <宏名>_synth,包装的 %macro 用不带 _synth 的名字。

后缀不是前缀:_nc 是手写库留下的历史命名,_ip 是本仓库加的(in place,结果写回原来的 cell)。选名字时先按 SPEC 的三个前缀定位,再挑后缀。

宏里的注释:

;   Macro clb_bit_add_nc
;   %1: CellBit A
;   %2: CellBit B
  • %this 表示"dp 当前所指的 cell"(set_0、clb_bit_mov 都这么写)。
  • 新宏先按上表选前缀。套不上的(块级、自己管草稿 cell 的)就在注释里写清吃什么、留下什么。
  • 参数类型只用这五个:Cell、CellBit、Unit、UnitBit、Count(纯数字,比如 step 的重复次数)。注释块贴在 %macro 上方,或者贴在生成它的 %synth 块上方,都行。
  • r8forge_macro_docs_test 会检查 asm/ 里每个 %macro:有没有注释块、 ; Macro <名字> 和实际宏名是否一致、参数条数是否等于 argc、类型是否在上面这五个里。 加完新宏跑一下,别让它的输出从全绿变红。