R8Forge had no spec of its own: the language lives in r8asm_rev/SPEC.md, the assembler
and the search were documented in README.md, and the macro contracts were only in the
comments above each %macro. This adds SPEC.md, pointed at the standard library:
* what this spec covers and what stays upstream (so the two do not drift);
* the five parameter types, the naming prefixes/suffixes, and the measurement
convention for tape lengths (a minimal driver, contiguous cells, no output lines);
* %synth: the full grammar, what map and stat mean, the three metrics, the cache key
and kModelVersion rule, and the four limits (8 params, 8 layers, no byte level
tables, no unconditional flip);
* all 41 macros in asm/ in tables with signature, which cells they eat, cell count,
tape length and implementation (hand written or %synth block + its stat table);
* the warts: clb_and leaves B & ~A behind while clb_or/clb_xor are clean, layout being
silently ignored when its length is not params, and set_0 clearing one bit only;
* a verification matrix saying which test proves what, and the known dead ends.
Every number in the tables was measured for this commit with one uniform driver
(measure_macros.ps1 shape, deleted afterwards), e.g. clb_not_ip 22, clb_add_ip 722,
clb_mul 3964 minimal vs 3977 through drv/mul_byte.r8asm. AGENTS.md and README.md now
point at SPEC.md instead of saying the %synth docs only live in the README.
23 KiB
R8Forge SPEC
R8Forge = R8ASM 汇编器 + %synth 搜索器 + 标准库。这份文件规定 R8Forge 自己这一层
的契约,重点在 asm/ 里的每个标准库宏:签名、参数类型、吃什么、留什么、占几个 cell、
纸带多长、由谁验证过。
不在这里的东西:
| 内容 | 在哪 |
|---|---|
R8ASM 语言本体(词法、运算符优先级、%macro/%rep/%include、.tp/.anchor/.var/.xor/.loop、作用域、标准宏前缀) |
r8asm_rev/SPEC.md(C:\Users\peng0\git\r8asm_rev-fork\SPEC.md,本仓库不重复) |
| ROT-8 指令集(8 条指令、LSB 语义) | ROT-8-viz/README.md |
| 踩过的坑、失败过的方案、交接话 | AGENTS.md、README.md |
本文的每个数字都是在 11 位 cell / 259 格、MSVC Release 构建上实测的;口径见 §1.3。
1. 术语与数字口径
1.1 参数类型(宏注释里只准用这五个)
| 类型 | 含义 |
|---|---|
Cell |
一个 cell 地址,装整个机器字(默认 11 位) |
CellBit |
一个 cell 地址,但只用它的 LSB 当一位用(biz/rnz 判的就是 cell & 1) |
Unit |
一个 cell 地址,它的 下一个 cell 是它的辅助格(SPEC:地址 n+1 是 n 的 aux) |
UnitBit |
同上,但按位用 |
Count |
纯数字,不是 cell 地址(比如 step 的重复次数、%rep 的轮数) |
1.2 机器几何
// include/r8forge/geometry.hh
inline constexpr size_t kDefaultCellSize = 11; // 一个 cell 多少 bit
inline constexpr size_t kDefaultMemoryCells = 259;
inline constexpr uint32_t kDefaultCellMask = (1u << kDefaultCellSize) - 1u;
汇编器把三个名字注入 .r8asm 程序的作用域,宏库靠它们与位宽解耦:
| 名字 | 值(11 位) | 用途 |
|---|---|---|
_CELL_SIZE |
11 | %rep _CELL_SIZE { … } 跟着位宽走 |
_CELL_MAX |
2047 | 全 1 的 cell |
_ROL_STEP |
10 | rol 要转的步数(= 位宽 − 1) |
1.3 纸带长度的口径
本文 §5–§9 的"纸带"列一律是最小驱动的长度:只 %include 该宏所在的库文件,
把形参按顺序摆到地址 0..N-1,宏调用一次,不带 output。
%this类宏(set_0、rol、copy…)的驱动先把.tp指向源 cell(地址 0), 所以不含"从别处走到操作数"的行走;宏内部自己的.tp都算在内。- 换布局、加
output、多摆几个 cell 都会让长度变;drv/*.r8asm里的驱动更长 (比如raw_add:最小驱动 1522,drv/raw_add_byte.r8asm2199)。 - 想复现:
r8forge <那个驱动>.r8asm | 数一下字符数。
步数(运行代价)是另一回事,只有 §9 的乘法器给了上界,因为它是唯一有明确界的。
2. 机器(汇编器眼里的实现)
'-' flb cells[dp] ^= 1 '+' ror cells[dp] = ror(cells[dp], cell_size)
'[' biz if (cells[dp] & 1) == 0 -> 跳到匹配的 ']' 之后
']' rnz if (cells[dp] & 1) == 1 -> 跳回匹配的 '['
'.' out 输出整个 cell 的值 ',' inp 读入并只留低 cell_size 位
'>' stp dp++ '<' btp dp--
两条必须记住的约束(标准库全部遵守,写新宏也得遵守):
biz/rnz判的是最低位,不是"整格为零"。 于是set_0=[-]只清 LSB:255 → 254、128 → 128、5 → 4。 要清整个 cell 得%rep _CELL_SIZE { set_0; ror },也就是erase。 反过来,字节里的任意一位都能读:ror若干次把目标位转到 LSB,再biz。- 每个条件块的身体必须回到它自己的条件 cell(净位移 0)。
dp是汇编期常量,而[...]的 body 运行期可能被跳过;跳过的路径和进入的路径 必须在同一个dp上会合,否则之后所有.tp全部错位(症状:dp跑到 1023 这种地方,r8forge_tape_run --trace能看见)。set_0的身体不动、clb_bit_mov的身体最后.tp before再flb,都是为了这一条。 附带的自然后果:biz/rnz是一对循环,不是 if/else —— body 必须把被测位吃掉 (最后那个flb),否则rnz看到还是 1 就跳回去。
3. %synth 指令
R8Forge 唯一的语言扩展:在汇编期现场搜出一段最短的块序列,拼成一个普通宏。
3.1 语法
%synth <名字>
params <N> ; 1..8
mode tape|layers ; 默认 tape
metric chars|flat|blocks ; 默认 chars
layout <addr> ... ; 可选,按 %1..%N 顺序给 cell 地址
map <2^K 项> ; 或者 stat <2^params 项>
%endsynth
stat= 整张状态表:每项是该输入组合下所有参数的取值(按%1..%N的位拼成一个数)。map= 只写输出位:项数2^K(必须是 2 的幂)就表示%1..%K是输入,值里 bit j 落到%(K+j+1),剩下的参数是必须结束为 0 的草稿位。layout只影响metric chars。给错个数不会报错:数量不等于params时静默退回0..N-1(想按真实布局算就得数对,metric flat下本来也无所谓布局)。- 定义完就是一个普通宏:
<名字> a1 a2 ... aN。
3.2 语义
- 目标是一张状态表:
2^N个输入组合,每个组合下 N 个 cell 的终值。 - 输入永远是排在最前面的参数(
%1..%K),搜索器拿真值表下标直接当输入值; 输入不在最前面就只能用stat。 - 生成的块是
sacrifice + mask模型:选中一个 cell(条件位),清掉它,然后按 mask 对其它 cell 做set_1(OR)或flb(XOR)。所以合成的块只适用于"每格一位"的世界, 高位不追踪。 mode layers:只求层数最少(快)。mode tape:接着按纸带长度做精确 Dijkstra 搜索, 用层数解的代价做上界。metric:chars(默认,按 layout 算真实字符数)、flat(不计.tp行走,结果与布局 无关、缓存可跨调用点复用;库里的块统一用 flat)、blocks(只数块)。- 生成的代码走正常宏展开:写成临时文件
<名字>.synth.r8asm(系统临时目录,写不进去就退到 当前目录并提示),再import_file,然后删掉。因此生成物不依赖lib.r8asm(set_1展开成biz/flb/rnz+flb)。
3.3 缓存
- 目录
.r8forge_cache/,已入库(克隆下来直接命中,第一次构建不用等搜索)。 - 键 = 模型版本 + params + mode + metric + 解析后的整张目标表(metric 是 chars 时再加 layout)。所以同一张表、任何写法、任何调用点,共用一份结果。
- 改指令模型必须 bump
kModelVersion(src/synth.cc),否则旧结果会被当成最优。 - 代价参考:
bit_raw_add的 flat 搜索 990,636,137 状态 / 680 秒 / 峰值 ~22 GB。
3.4 限制
| 限制 | 原因 / 后果 |
|---|---|
params 最大 8 |
状态是位平面塞进 64 位字 |
| 层数上限 8 | 5 会把一些可行表误判成不可能;再高搜索爆炸 |
字节级(2^16 项)真值表不可行 |
搜索空间 |
| 表达不出"无条件翻转" | 模型只会"牺牲一个 cell → 条件翻转别的 cell",输入为 0 时整块被跳过 |
原地写回的表(A←~A^Ci 等四个)无解 |
一个合成块只有一个条件 cell,区分不了 "A=1 且 Ci=0" 和 "A=1 且 Ci=1"(手写可以,见 §8) |
4. 标准库 asm/ —— 总则
4.1 命名
| 前缀 | 全称 | 含义 |
|---|---|---|
clb |
clobber | 破坏性:会破坏原始输入(多数情况是清零) |
bit |
bit | 对 cell 的 LSB 操作的宏 |
raw |
raw | 未经封装:草稿 cell 要调用者自己传 |
后缀(不是前缀):
| 后缀 | 含义 |
|---|---|
_nc |
历史命名(no carry),实际含义是"把操作数吃干净"的切片版 |
_ip |
in place:结果写回原来的 cell |
_synth |
%synth 生成的块本身,不是给人调用的;包装它的 %macro 才用不带后缀的名字 |
例:raw_add(保留操作数、要你自己给 Co/tmp)、clb_add_nc(吃 A/B、4 cell)、
clb_add_ip(原地、B 被吃)、bit_raw_add_synth(合成的块)+ bit_raw_add(包装宏)。
4.2 注释契约(机器检查)
asm/ 里每个 %macro 必须有注释块,r8forge_macro_docs_test 会逐条检查:
; Macro clb_bit_add_nc
; %1: CellBit A
; %2: CellBit B
; Macro <名字>必须和实际宏名一致;%N: <类型> <名字>条数必须等于 argc,类型必须是 §1.1 的五种之一;%this表示"dp 当前所指的 cell";- 注释块贴在
%macro上方或生成它的%synth块上方都行。
4.3 布局
标准库不假设 cell 地址。所有地址都是形参,由调用者自己排;宏内部的 .tp 行走算在
这个宏的纸带长度里(所以同样的宏在不同布局下长度不同)。宏返回时 dp 回到调用点的 cell。
5. 基础宏(asm/lib.r8asm)
| 宏 | 签名 | 干什么 | cell | 纸带 |
|---|---|---|---|---|
step |
step N |
N 次 stp stp(一个 Unit) |
0 | 2 |
back |
back N |
N 次 btp btp |
0 | 2 |
set_0 |
set_0(%this) |
清 %this 的 LSB(= [-]) |
1 | 3 |
set_1 |
set_1(%this) |
置 %this 的 LSB(= set_0 + flb) |
1 | 4 |
erase |
erase c |
清 c 的整个 cell(%rep _CELL_SIZE { set_0; ror }) |
1 | 44 |
rol |
rol(%this) |
左旋一格 = %rep _CELL_SIZE - 1 { ror } |
1 | 10 |
clb_bit_mov |
clb_bit_mov d(%this) |
把 %this 的 LSB 搬到 d 的 LSB,源被吃掉 |
2 | 11 |
bit_copy |
bit_copy d b(%this) |
位拷贝,b 是借来的缓冲,源保留 |
3 | 38 |
copy |
copy d b(%this) |
整个 cell 拷贝(位拷贝转满 _CELL_SIZE 圈) |
3 | 495 |
bit_copy_to_buffer |
bit_copy_to_buffer t(%this 是 UnitBit) |
位拷到 Unit 的辅助格,t 是缓冲 |
3 | 40 |
copy_to_buffer |
copy_to_buffer t(%this 是 Unit) |
整 cell 拷到 Unit 的辅助格 | 3 | 497 |
output |
output c |
.tp 到 c 再 out(输出整个 cell 的值) |
1 | 1 |
要点:
set_0只清一位,erase才清整格;别把set_0当"清零 cell"用。copy比bit_copy长十倍多,是因为它对每个 bit 调一次bit_copy并转圈 (copy495 vsbit_copy38)。只搬一位用clb_bit_mov(11)。clb_bit_mov会把源位清掉 —— 它顺手就"吃条件",这正是set_0/clb_bit_mov身体里那个flb的作用(见 §2 第 2 条)。
6. 位级宏(一个 cell 装一位)
6.1 总表
| 宏 | 签名 | 语义 | 吃什么 | cell | 纸带 | 实现 |
|---|---|---|---|---|---|---|
clb_bit_add_nc |
A B Ci S |
S = A^B^Ci,进位进→出 |
A、B | 4 | 66 | %synth |
clb_bit_inc_nc |
A Ci S |
S = A^Ci,进位 = A&Ci |
A | 3 | 50 | %synth |
clb_bit_and |
a b ans |
ans = a&b |
a;b 只在"两位都是 1"时清 | 3 | 25 | 手写 |
clb_bit_or |
a b ans |
ans = a|b |
a、b | 3 | 25 | %synth |
clb_bit_xor |
a b ans |
ans = a^b |
a、b | 3 | 20 | %synth |
bit_raw_add |
A B Ci S Co buf |
完整全加器:S=A^B^Ci,Co=maj(A,B,Ci);A、B 保留,buf 结束是垃圾 |
无(buf 草稿) | 6 | 106 | %synth |
bit_raw_and |
arg1 arg2 ans tmp |
ans = arg1&arg2,两个操作数保留 |
tmp | 4 | 57 | %synth |
bit_raw_or |
arg1 arg2 ans tmp |
ans = arg1|arg2,保留 |
tmp | 4 | 59 | %synth |
bit_raw_xor |
arg1 arg2 ans tmp |
ans = arg1^arg2,保留 |
tmp | 4 | 49 | %synth |
bit_raw_inc |
A Ci S Co tmp |
S = A^Ci,Co = A&Ci,A 保留 |
tmp | 5 | 77 | %synth |
所有位级宏都只碰低 1 位,喂进来的输入必须是 0/1;clb_bit_add_nc/clb_bit_inc_nc
的进位 cell 是"进→出"的同一个 cell。
6.2 为什么 clb_bit_and 是手写的
三个参数、没有草稿位,而"与"需要同时保住两个输入,只能靠嵌套 biz(一层一个条件)。
搜索器在 3 个平面、9 层内穷尽无解 —— 这是模型的表达力边界,不是搜索没跑够。
or/xor 可以先清一个操作数,所以能合成(0 4 4 4 / 0 4 4 0)。
6.3 %synth 块与它们的表
| 块 | params | 表(stat) |
用它的宏 |
|---|---|---|---|
bit_raw_add_synth |
6 | 0 9 10 19 12 21 22 31 ×8 |
bit_raw_add |
bit_raw_and_synth |
4 | 0 1 2 7 ×4 |
bit_raw_and |
bit_raw_or_synth |
4 | 0 5 6 7 ×4 |
bit_raw_or |
bit_raw_xor_synth |
4 | 0 5 6 3 ×4 |
bit_raw_xor |
bit_raw_inc_synth |
5 | 0 5 6 11 ×8 |
bit_raw_inc |
clb_bit_add_nc_synth |
4 | 0 8 8 4 8 4 4 12 ×2 |
clb_bit_add_nc |
clb_bit_inc_nc_synth |
3 | 0 4 4 2 ×2 |
clb_bit_inc_nc |
clb_bit_or_synth |
3 | 0 4 4 4 ×2 |
clb_bit_or |
clb_bit_xor_synth |
3 | 0 4 4 0 ×2 |
clb_bit_xor |
这些表不是手写的,是 r8forge_derive 从旧的手写实现上穷举出来的
(例:r8forge_derive drv/bit_raw_add.r8asm 6 → stat 0 9 10 19 …)。
所以合成结果与旧实现逐位一致,连"某个输入没被清掉"这类怪癖都保住了;要改语义就改表。
7. 字节级宏(一个 cell 一个机器字)
7.1 raw_* 家族:保留操作数
| 宏 | 签名 | 语义 | cell | 纸带 | 验证 |
|---|---|---|---|---|---|
raw_add |
A B Ci S Co tmp |
S = A+B+Ci,Co 进位出 |
6 | 1522 | drv/raw_add_byte.r8asm,65536/65536 |
raw_and |
arg1 arg2 ans tmp |
ans = arg1 & arg2 |
4 | 697 | 65536/65536 |
raw_or |
arg1 arg2 ans tmp |
ans = arg1 | arg2 |
4 | 719 | 65536/65536 |
raw_xor |
arg1 arg2 ans tmp |
ans = arg1 ^ arg2 |
4 | 609 | 65536/65536 |
raw_inc |
A Ci S Co tmp |
S = A + Ci,Co 进位出 |
5 | 1179 | 512/512(A 与 Ci) |
raw 的含义是"草稿 cell 你自己传":tmp 结束是垃圾(bit_raw_add 的 %6: buf 同理)。
raw_add 不吃操作数:实测 5+3 → A=5 B=3 S=8,255+255 → A=255 B=255 S=254 Co=1。
(历史注释里"每圈都要重新复印"是过度保守 —— 复印了也没错,但没必要。)
7.2 clb_*_nc 家族:把操作数吃干净
| 宏 | 签名 | 语义 | 吃什么 | cell | 纸带 | 验证 |
|---|---|---|---|---|---|---|
clb_add_nc |
A B S Ci |
S = A+B+Ci |
A、B | 4 | 741 | 65536/65536(drv/raw_add_nc_byte.r8asm) |
clb_inc_nc |
A S Ci |
S = A+Ci |
A | 3 | 552 | 256/256 |
clb_neg_nc |
A S Ci |
S = ~A+Ci(Ci=1 → -A) |
A | 3 | 574 | 256/256(Ci=1 取负、Ci=0 反码) |
clb_sub_nc |
A B S Ci |
S = A+~B+Ci(Ci=1 → A-B) |
A、B | 4 | 765 | 65536/65536 |
进位 cell 是真正的进位输入:宏自己不动它的初值,只把它变成进位输出。
调用者给 0 就是普通运算,给 1 就是"自带 +1",也可以把上一字节的进位输出接过来串多字节。
(这条踩过:早先加法里 set_0、自增里 set_1,那就不是输入了,还把串接堵死。)
补码那两条的做法是先原地取反、再走加法/自增:-A = ~A + 1、A - B = A + ~B + 1,
那个 +1 由调用者的 Ci 给。取反整个字节一次(clb_not_ip)比"每 bit 取反一次"短二十来个
字符,而且 B 本来就会被加法吃掉,取反它没有代价。
进位输出的附带语义:clb_sub_nc 的进位是没有借位(A >= B 时为 1)——顺带就是
无符号比较;clb_neg_nc 的进位只在 A 原本是 0 时为 1(-0 = 0,但确实进了位)。
7.3 clb_and / clb_or / clb_xor:半破坏,读清楚再用
| 宏 | 签名 | ans |
A 之后 | B 之后 | cell | 纸带 |
|---|---|---|---|---|---|---|
clb_and |
arg1 arg2 ans |
arg1 & arg2 |
0 | B & ~A(有残留!) |
3 | 352 |
clb_or |
arg1 arg2 ans |
arg1 | arg2 |
0 | 0 | 3 | 323 |
clb_xor |
arg1 arg2 ans |
arg1 ^ arg2 |
0 | 0 | 3 | 268 |
clb_and 是这三个里唯一不清零 B 的:每位只有在"A、B 都是 1"时才清 B,
所以 B 结束在 B & ~A(实测 240 & 204 → ans=192, A=0, B=12)。
别拿它当"两个操作数都能回收"的宏;要干净的与运算,就用 raw_and(保留操作数)
或者自己再 erase 一次。clb_or/clb_xor 是干净的。
7.4 三个家族怎么选
| 需求 | 用 |
|---|---|
| 操作数要还回来 | raw_*(6/4 cell,多的那个是草稿) |
| 操作数可以扔,要省 cell | clb_*_nc(4/3 cell) |
| 结果要写回原 cell | _ip 家族(§8) |
轮转驱动不吃亏:clb_*_nc 和 raw_* 的区别只在"要不要还操作数",两者都是
"读走 LSB → 丢掉 → ror" 的轮转驱动,吃掉操作数完全没问题。
8. 原地 _ip 家族(结果回到原来的 cell)
| 宏 | 签名 | 语义 | cell | 纸带 | 验证 |
|---|---|---|---|---|---|
clb_not_ip |
A |
A = ~A(反码) |
1 | 22 | 256/256 |
clb_inc_ip |
A T |
A = A + 1 |
2 | 88 | 256/256 |
clb_neg_ip |
A T |
A = -A(补码取负) |
2 | 110 | 256/256 |
clb_dec_ip |
A T |
A = A - 1 |
2 | 132 | 256/256 |
clb_nonzero |
B F T |
F = (B != 0),B 不动 |
3 | 280 | 256/256 |
clb_add_ip |
A B T F |
A += B,B 被吃 |
4 | 722 | 2048 抽样 |
对比写回 S 的切片版(clb_inc_nc 552 / clb_neg_nc 574,各 3 cell):
原地版短 5 倍、少一个 cell。
算法不是逐位测进位(那在两个 cell 里确实不行),而是:
- 用
[ ... ]的自然语义把最低位连续的 1 清掉(flb+ror),遇到第一个 0 退出; - 那个 0 翻成 1(输入全 1 时跳过,正好是回绕那一格);
- 剩下的位置只旋转,转满
_CELL_SIZE格。
"还要转几格"用 T 的位计数:T 先做成 _CELL_MAX,每转一格 set_0 + ror 消掉一个 1,
一串 1 的长度就是剩余圈数。于是两个 cell 够用 —— 关键认识是被测的是计数器,不是数据,
所以"[...] 跑一次就吃掉被测位"不是障碍。
clb_neg_ip=clb_not_ip+clb_inc_ip;clb_dec_ip=clb_neg_ip+clb_not_ip(恒等式B - 1 = ~(-B)),不用新算法;clb_nonzero每轮把 B 的一位搬进 T(clb_bit_mov顺手清掉 B 那一位),是 1 就把 F 置一(set_1,不是flb—— 翻转会被偶数个 1 翻回 0)并把 B 那一位还原;clb_add_ip不写逐位进位链,而是while B != 0: A += 1; B -= 1: 循环体在纸带里只出现一次,长度与 B 无关,代价是运行 O(B)(B=255 时约 30 万步)。
9. 乘法器(asm/mul.r8asm)
clb_mul MC MUL PL PH MCA S Ci T F NR:(PH:PL) = MC * MUL,10 个 cell,最小驱动
3964 字符(drv/mul_byte.r8asm 3977)。MC 保持原样,MUL 结束为 0。
算法是二进制移位-加法(竖式乘法),一位一位串:
A:PH = 0 ; C:F = 0 ; Q:PL = MUL
repeat _CELL_SIZE:
if Q & 1: (C:PH) += MC ; 一次 W 位加法,进位出到 F
(C:PH:PL) >>= 1 ; 跨格右移,最高位补 0,最低位(刚看的那位)丢掉
- 轮数 = 位宽,与两个操作数的值无关;11 位下最坏 26123 步(
2047*2047)。 - 纸带长度与 MUL 无关(循环体只出现一次)。
MCA/S/Ci/T是草稿;F是移位寄存器的最高位(进位),NR是轮数计数器 (%rep _CELL_SIZE { set_1; ror }做成全 1,每轮set_0+ror吃掉一个)。- 跨格移位:三格先各
ror,把要注入的位搬到 bit0(rol),clb_bit_mov搬过去,再ror回来;低位那对先搬(PH→PL 先做),否则 PH 的 bit0 已被 F 覆盖。
10. 拼起来是什么样
10.1 16 位加法:靠 clb_add_nc 的进位输出串
clb_add_nc PL B_lo T Ci ; 低字节相加,进位出到 Ci(A、B 被吃)
clb_add_ip PH Ci S F ; 把进位加进高字节(Ci 被吃)
10.2 asm/test.r8asm:一个滚动的 hash
h = (h + c) * 141 mod 2048,消息 "R8F"(82 56 70),只用 clb_add_nc + clb_mul:
先把消息字节加到 h 上,再乘 141,跑三轮。11 位下纸带 28729 字符,
r8forge_derive / r8forge_tape_run / ROT-8-viz 三份实现都给出
1322 1786 1600 5 94 127(前三 = 三轮的 h,后三 = 三轮的 PH,即 (h+c)*141 >> 11),
共 57330 步。
11. 验证矩阵
| 测试 | 覆盖 | 断言口径 |
|---|---|---|
r8forge_byte_op_test |
17 个测试项 = 16 个宏(clb_neg_nc 的 Ci=1 / Ci=0 各算一项),见 §7.1、§7.2、§8、§9 |
按返回值:穷举 0..255(clb_add_ip 2048 抽样、clb_mul 65536 全穷举),任一不符即退出码非 0 |
r8forge_synth_test examples/full_add.r8asm |
%synth 端到端:汇编 + 跑 8 种输入 |
all eight combinations ok |
r8forge verify_clb_bit_add_nc.r8asm |
4 cell 加法切片(进位进→出) | 单点:0+0+Ci |
r8forge verify_clb_bit_inc_nc.r8asm |
3 cell 自增切片 | 单点 |
r8forge verify_set_0.r8asm |
set_0 只清 LSB |
-1 0=255 → 254、0=128 → 128 |
r8forge_macro_docs_test |
asm/ 里 41 个宏的注释格式 |
全绿或报错行号 |
r8forge_tape_run <tape.rot8> |
第二个解释器,直接跑纸带 | 与 r8forge_derive 对答案 |
r8forge_derive <src> -1/-2 |
拿汇编源码跑,打印 out / 非零 cell |
人工/脚本比对 |
只有 r8forge_byte_op_test 是按返回值判断字节级对错的;其它要么只证明"汇编得出来"、
"位级正确",要么是单点探针。改宏之后跑 §11 前四个(外加 docs test)。
12. 已知边界(别重试)
| 想做的 | 结论 |
|---|---|
| 3 个 cell 做加法切片 | 层数上限 5 和 8 都报 no program up to N layers(自增/取负 3 cell 有解,两个操作数塞不进 3 个 cell) |
用 %synth 写"原地"表(A←~A^Ci 等四个) |
全部无解(原因见 §3.4);手写可以(§8 的 _ip 家族) |
| 让切片自己在输入上取反 | 无解(表达不出"无条件翻转");取反放在切片外面(一条 flb) |
| 4 cell 加法切片要保留 A、B | 无解;要留操作数用 6 cell 的 bit_raw_add |
字节级(2^16 项)交给 %synth |
搜索空间不可行 |
| "每个 bit 一个 cell" 拼字节级运算 | 能跑通但没意义(一个 cell 已经能放一个字节、位也读得出来);这份实现已删,别再加回来 |
13. 维护
- 改位宽/纸带长度:
include/r8forge/geometry.hh两个常量 + 四份虚拟机 (tests/synth_test.cc、tests/byte_op_test.cc、src/derive.cc、tests/tape_run.cc) 一起改;asm/里的宏靠_CELL_SIZE自动跟随,不用动。 - 加宏:先按 §4.1 选前缀/后缀,再写 §4.2 的注释块,跑
r8forge_macro_docs_test; 能进byte_op_test就进(那才有按返回值的验证)。 - 改指令模型(合成器的块集合、代价):必须 bump
kModelVersion,否则.r8forge_cache/里的旧结果会被当成最优。 - 改本文的数字:照 §1.3 的口径重新量,别把驱动长度和最小驱动长度混在一列。