Files
R8Forge/README.md
T
dsh 026ad82455 The nc macros take a real carry in, they do not seed it themselves
They used to write the carry cell themselves -- set_0 inside clb_add_nc, set_1
inside clb_inc_nc / clb_neg_nc / clb_sub_nc -- which made the parameter a lie: a
cell the caller passes and the callee overwrites is not a carry input, it is a
scratch cell wearing a carry's name.  It also ruled out the thing a carry is for:
multi byte arithmetic.  The carry out of the low byte could not be handed to the
high byte, because the high byte's call would zero (or one) it first.

Now the macros only read it, and the caller decides:

    clb_add_nc A B S Ci     S = A + B + Ci      Ci = 0 plain add, or chained
    clb_inc_nc A S Ci       S = A + Ci          Ci = 1 gives A + 1
    clb_neg_nc A S Ci       S = ~A + Ci         Ci = 1 gives -A, Ci = 0 gives ~A
    clb_sub_nc A B S Ci     S = A + ~B + Ci     Ci = 1 gives A - B, Ci = 0 A-B-1

which also turns the negate into two operations for free: two's complement
negation at Ci=1 and the ones' complement (~A) at Ci=0.  The second one has its
own driver and test now (drv/raw_not_nc_byte.r8asm).

The drivers set the bit explicitly before the call, which is where that
instruction belongs -- the tapes end up the same length as before (688/430/468/725
instead of 693/433/471/730: one setup instruction moved out of the macro).

All nine byte level operations still pass, and the docs (AGENTS.md, README.md and
the four file headers) now state the carry in contract instead of describing a
constant.
2026-11-07 09:12:47 +08:00

16 KiB
Raw Blame History

R8Forge

R8ASM 汇编器 + R8Veritas 搜索器,合成一个仓库。

搜索器不再是独立程序:%synth 是汇编期指令,描述一张真值表,汇编器现场搜出最短的块 序列直接拼进纸带。代价模型和发射器从此是同一份代码,不用再维护两套「这个块要花多少条 指令」的估算。

用法

%include "asm/lib.r8asm"

%synth fulladd
	params 6
	map  0 1 1 2 1 2 2 3    ; 8 个输入组合各自的输出位取值,%1..%3 是输入
	layout 0 1 2 3 4 5      ; 可选:各参数所在 cell 的地址(默认 0..n-1)
%endsynth

.var A 0
.var B 1
.var Ci 2
.var S 3
.var Co 4
.var T 5

fulladd A B Ci S Co T       ; 这一行展开成汇编期合成的最短纸带
output S
output Co

%synth 会跑两遍:先用层数搜索拿到一个解(7 秒),再拿它的代价当上界跑纸带长度搜索 (Dijkstra)。第二遍是精确的,弹出目标即停,所以 full_add 大约 12 分钟 —— 汇编时间换最短纸带。

layout 写的是真实地址时,搜索按真实 .tp 距离算代价;不写就假设参数 cell 紧邻。

汇编:

$ r8forge examples/full_add.r8asm
r8asm: %synth fulladd: 5 layers (shortest), 20388515 states, 7.7s
r8asm: %synth fulladd: tape cost 75 in 6 blocks (layer answer was 82), 415041596 states, 1280s
> [-]-...    (90 字符纸带)

第一行是层数搜索(7.7 秒),第二行是按纸带长度的精确搜索(约 21 分钟,4.15 亿状态,峰值约 10 GB),最后发射的是第二行的解。tests/synth_test.cc 把纸带丢进一台小 ROT-8 虚拟机, 8 种组合全对:

tape: 90 characters
  000 -> 00  expect 00  ok
  ...
  111 -> 11  expect 11  ok
all eight combinations ok

map 的项数决定输入个数:2^K 项就是 %1..%K 为输入,值的第 j 位落到 %(K+j+1),剩下 的参数是必须结束为 0 的草稿。想要完全显式(或输入不在最前面)就改用 stat,那是整张状态表。

三种代价口径

标准库现在统一用 metric flat(步长无关),结果全部预先生成并提交在 .r8forge_cache/ 里, 所以第一次构建不用等搜索。

%synth 里用 metric 选优化目标:

metric 优化什么 依赖 cell 布局? 缓存能否跨调用点复用
chars(默认) 真实纸带字符数,含 .tp 行走 是(可用 layout 指定) 同一个布局才能
lat 字符数,但不计 .tp 行走 否 能
locks 块数 否 能

lat 就是"步长无关模式":它只数 iz/ lb/ nz 和 op 本身,不看 cell 之间隔多远, 所以同一张真值表在任何布局下都用同一份结果、同一份缓存。代价是纸带会比按实际布局最优的 长一点 —— full_add 上 chars 是 90 字符, lat 是 95 字符。

%synth fulladd_flat params 6 map 0 1 1 2 1 2 2 3 metric flat %endsynth

同一个 metric flat 的块配上 layout 0 2 4 6 8 10 再汇编,会直接命中同一份缓存并且 发射出完全相同的纸带(已验证)。

从零开始

cmake -S . -B build -G "Visual Studio 18 2026" -A x64   # 或者用 Ninja / Makefile
cmake --build build --config Release

写一个 adder.r8asm:

%include "asm/lib.r8asm"

%synth fulladd
	params 6
	map  0 1 1 2 1 2 2 3    ; 8 个输入组合各自的输出位取值
	mode tape               ; tape = 最短纸带(默认),layers = 只求层数最少(快)
%endsynth

.var A 0
.var B 1
.var Ci 2
.var S 3
.var Co 4
.var T 5

fulladd A B Ci S Co T
output S
output Co

map 一项就说明了谁是谁:项数是 2^K,就意味着 %1..%K 是输入;值里的第 j 位 落到 %(K+j+1);剩下的参数都是必须结束为 0 的草稿。所以不需要再声明 inputs/outputs。

要完全显式也可以,直接给整张状态表(每个输入组合下 6 个参数的取值),一个声明都不用:

%synth fulladd_stat
	params 6
	stat 0 1 2 3 4 5 6 ...
	mode layers
%endsynth

examples/full_add.r8asm 是 map 版,examples/full_add_stat.r8asm 是 stat 版, 两者合成的纸带逐字节相同(95 字符)。

汇编:

build/Release/r8forge adder.r8asm > adder.rot8

stderr 上会告诉你它查到了什么,stdout 就是纸带:

r8asm: %synth fulladd: 5 layers (shortest), 20388515 states, 7.7s
r8asm: %synth fulladd: tape cost 75 in 6 blocks (layer answer was 82), 415041596 states, 1280s

mode layers 只跑第一行(7.7 秒),mode tape(默认)会接着跑第二行。结果按真值表缓存在 .r8forge_cache/ 里,所以同一张表只贵一次;要重算就删掉那个目录。

标准库现在也是合成的

asm/ 里的 8 个 bit 宏(clb_bit_and、bit_raw_and、clb_bit_or、bit_raw_or、 clb_bit_xor、bit_raw_xor、bit_raw_inc、bit_raw_add)全部换成了 %synth 块,宏名、 参数顺序、调用方式都没动,上层的 %rep 驱动照旧。

stat 那张表不是手写的,是 r8forge_derive 从旧实现本身跑出来的:

build/Release/r8forge_derive drv/bit_raw_add.r8asm 6
# stat 0 9 10 19 12 21 22 31 0 9 10 ...

它把 6 个参数摆到 cell 0..5,穷举 64 个输入组合各跑一遍旧纸带,读回 6 个 bit 的终值。 所以合成结果与旧实现逐位一致(连旧实现里"某个输入没被清掉"这类怪癖都保住了),只是更短。 要改语义,改那张表就行,不用碰代码。

放进自己的库里

%synth 块定义完就是一个普通宏,所以在库里写一次即可:

; asm/my_adder.r8asm
%synth bit_add
	params 6
	map 0 1 1 2 1 2 2 3
%endsynth

调用点和普通宏调用一样:bit_add A B Ci S Co tmp —— 替换掉现有实现就是改这一行。

三条要注意的

  1. 输入永远是排在最前面的参数(%1..%K,K 由 map 项数得出)。搜索器把真值表索引直接 当输入值,靠的就是这个顺序;输入不在最前面就用 stat。
  2. map 一项里的 bit0 落在 %(K+1)、bit1 落在 %(K+2)……超出 params 会直接报错。
  3. stat 必须给 2^params 项,每项是那个输入组合下所有参数的取值。

字节级运算:一个 cell 一个字节

%include "asm/raw_add.r8asm"

.var A 0
.var B 2
.var Ci 4
.var S 6
.var Co 8
.var tmp 1

raw_add A B Ci S Co tmp     ; S = A + B,Co = 进位,A、B 保留

output A
output B
output Ci
output S
output Co

raw_add 把 A、B、S 各当一个字节:每轮把当前最低位送进 4~6 cell 的位级切片, 然后把整个字节 ror 一格,8 轮走完。raw_and / raw_or / raw_xor / raw_inc 同理。

r8forge_byte_op_test 在 ROT-8 虚拟机上把每种输入都跑一遍(0.7 秒):

raw_xor: 463 characters     all 65536 combinations ok
raw_or: 575 characters      all 65536 combinations ok
raw_and: 639 characters     all 65536 combinations ok
clb_sub_nc: 725 characters  all 65536 combinations ok
clb_neg_nc (carry 0): 467   all 256 combinations ok      ~A
clb_neg_nc: 468 characters  all 256 combinations ok      -A
clb_inc_nc: 430 characters  all 256 combinations ok
clb_add_nc: 688 characters  all 65536 combinations ok
raw_inc: 1214 characters    all 512 combinations ok
raw_add: 1647 characters    all 65536 combinations ok
byte level library ok

省 cell 的那一族:clb_*_nc

raw_add 要 6 个 cell(A、B、进位、S、进位输出、草稿)是因为它保留 A、B。 如果调用者不在乎操作数被吃掉,4 个 cell 就够:

宏 含义 cell 纸带
clb_add_nc A B S Ci S = A + B + Ci 4 688
clb_inc_nc A S Ci S = A + Ci(Ci=1 就是自增) 3 430
clb_neg_nc A S Ci S = ~A + Ci(Ci=1 → -A,Ci=0 → ~A) 3 468
clb_sub_nc A B S Ci S = A + ~B + Ci(Ci=1 → A-B) 4 725

进位 cell 是真正的进位输入:宏不动它的初值,由调用者给。所以可以串 —— 上一字节的 进位输出直接接到下一字节的进位输入,多字节加法/减法/取负都能这么拼。 clb_sub_nc 的进位输出是"没有借位"(A >= B 时为 1),顺带就是无符号比较。

asm/fibonacci.r8asm 也是这条路上的:8761 字符,跑出 1 1 2 3 5 8 13 21 34 55。

一个坑:biz/rnz 看的是最低位

biz:  最低位 == 0 -> 跳到匹配的 ']' 之后
rnz:  最低位 == 1 -> 跳回匹配的 '['

不是 Brainfuck 那种"整格是否为零"。所以 set_0 = [-] 是清最低位:255 → 254、 128 → 128、5 → 4;要清整个字节得 %rep _CELL_SIZE { set_0; ror }(就是 erase)。

仓库里曾经有三份解释器把它写成整格零判断,于是所有字节级程序看起来都在死循环 —— 顺着那个错误还得出过"字节级运算只能一位一 cell"的结论,是错的。权威语义见 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) { ... } }

顺带一个被删掉的方向

"每个 bit 一个 cell 再拼字节级运算"能跑通(32 cell,1308 字符,65536 组合全对),但既然 一个 cell 就能放一个字节、位也读得出来,就没必要为每个 bit 花一个 cell —— 那份实现已经 删了,要拼字节级运算就用 raw_*。

实现方式

%synth 在 parse() 里被读成一张真值表,随即调用搜索器;得到的块序列写成

%macro fulladd 6
.tp %1
biz
...
%endmacro

这样一个临时文件(<名字>.synth.r8asm),再 import_file 进来、删掉。于是合成出来的代码 走的是正常宏展开路径,不是手工拼 AST —— 少一套容易写错的代码。

生成的块体里 set_1 展开成 biz/flb/rnz + flb(即 set_0 + 翻转),所以生成文件不依赖 lib.r8asm。

搜索器

  • 状态 = 位平面真值表,只留影响答案的输入(加法器类问题通常 3 个,48 bit 一个 uint64_t)
  • 前向 BFS 到 d−1 层,最后一层不展开:枚举目标的一步前驱反查表
  • proven_optimal 为真表示长度已被穷尽证明

full_add(r8veritas<6>):5 层,2038 万状态,7.7 秒,穷尽搜索下最短。

比它更宽松的指令语义也没有 4 层解(都做过穷尽搜索):

放宽 指令数 搜索规模 4 层?
每目的地独立 OR/XOR 1,458 前向 3 层 173 万 + 反向 20,096 前驱 无
再加 set_0 6,144 前向 3 层 956 万 + 反向 40,928 无
参数 6 → 7 → 8 个 2,040 穷尽 540 万 / 4410 万状态 无
条件位 ≠ 牺牲位 2,304 前向 3 层 317 万 + 反向 1,280 无

按纸带长度搜(solve_cost)

结论先说:full_add 上 5 层那版是 95 字符,代价搜索找到的 6 块版是 90 字符。两个都在 examples/ 里,都跑过那台 ROT-8 虚拟机,8 种输入组合全对:

版本 层数 模型代价 真实纸带
层数最优(full_add.r8asm) 5 82 95 字符
代价最优(full_add_cost.r8asm) 6 75 90 字符

代价最优解:

sacrifice B,  FLIP {S,T}
sacrifice A,  FLIP {B}
sacrifice B,  FLIP {A,Ci,S}
sacrifice Ci, FLIP {B,Co,T}
sacrifice S,  SET1 {Ci,Co}
sacrifice T,  FLIP {B,Ci,S,Co}

层数最优不等于纸带最优:多一层反而少 5 个字符。Dijkstra 在弹出代价 75 之前已经把 < 75 的 区域穷尽,所以 75 是模型内的最小值。

层数最少不等于纸带最短。solve_cost 用同一张状态图跑 Dijkstra,边权就是这个块汇编出来 多少字符:

w(block) = 3 (biz + flb + rnz) + 2 × span(cell 地址) + Σ op   # flb=1, set_1=4

桶队列(Dial),按代价递增弹出,第一次弹出目标态就是最短纸带。给一个 max_cost 上界就变成 分支限界,超出上界的状态不入队。

full_add、6 个 cell 紧邻时,搜索推进到某个代价时已经攒下的状态数:

代价 状态数
20 1,086
40 128,528
50 999,448
58 80,000,000
62 140,000,000
66 220,000,000
70 280,000,000

每状态约 27 字节(8 key + 2 距离 + 4 父 + 2 指令 + 哈希表),到代价 70 约 7.5 GB,速度约 65 万状态/秒。所以这台机器上能跑到的上限大约就是「代价 75 左右 / 4.5 亿状态 / 12 GB」, 再往上就超出内存了 —— 这正是当初估的 13 GB 量级。

因为 Dijkstra 按代价递增弹出,停在哪儿就证明了「比它更短的纸带不存在」:跑到代价 d 就 停,等于给出「没有短于 d 字符的程序」这个下界。

注意:模型里的 w 不含「上一块的牺牲位跳到这一块」的那几步(|s_i − s_{i−1}|),因为那让 代价依赖历史、Dijkstra 就不能用了。发射器会把这部分加上再报真实长度,5 层程序是模型 82 / 实际 87。

为什么合在一起

代价 = 汇编出来多少条指令,而这只有发射器知道:

cost(layer) = 2                   # biz + rnz
            + Σ (|Δ| 移动 + op)   # flb=1, set_0=3, set_1=4

|Δ| 来自调用点的 cell 布局:同一份 5 层程序,cell 紧邻是 87 字符,隔两格是 136 字符。 这是「程序 × 布局」的属性,只有看得见调用点的那一方算得出来 —— 也就是汇编期。

坑

  • ROT-8 的字符映射是 "><+-[].,",也就是 - 是 flb,+ 是 ror。写仿真器时按常识 猜会反(我第一次就反了,纸带看起来「死循环」)。
  • %synth 的名字不能和 ROT-8 助记符重名(out、flb、biz…),否则词法先认成指令。

下一次要做的事

  1. 搜索的代价从「1/层」换成真实指令数(Dijkstra + 每层目的地访问顺序的 TSP),这样嵌套条件 块(A AND B 门控)也能公平参与竞争。注意嵌套会降低层数但拉长纸带 —— 层数不是长度 的好代理。
  2. 缓存:现在每次汇编都要重跑搜索(full_add 是 7.7 秒)。按真值表 + 布局落盘缓存。
  3. %synth 只支持 8 位以内的参数(状态要塞进 64 位字里)。

给接手的 agent / 新会话

先读 AGENTS.md。那里有这个仓库实测过的指令集语义、%synth 用法、缓存机制, 以及一列已经确认走不通的方案(3 cell 加法切片、轮转配合成切片、字节级真值表交给搜索……)。 那些都是失败换来的结论,别重试。

构建

cmake -S . -B build -G "Visual Studio 18 2026" -A x64
cmake --build build --config Release
build\Release\r8forge.exe asm\test.r8asm > test.rot8
build\Release\r8forge_synth_test.exe    # 合成 + 跑虚拟机自检
build\Release\r8forge_byte_op_test.exe  # 字节级库穷举:65536×4 + 512 全对
build\Release\r8forge_macro_docs_test.exe # 宏注释格式(asm/ 下每个 %macro)

build/ 已经有生成器了,重编译时别用 PATH 上的另一个 cmake(版本不一致会重新配置, 然后死在 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

CMakeLists.txt 里没有 set(CMAKE_CXX_FLAGS ...):那会把默认 flag 整个换掉,MSVC 下丢 /EHsc、还把 -O3 塞进 Debug 和 /RTC1 打架。

布局

include/r8forge/r8asm.hh      汇编器 + %synth 指令
include/r8forge/r8veritas.hh  搜索器
src/r8asm.cc                  汇编器实现
src/synth.cc                  真值表 -> 搜索
tests/asm_test.cc             汇编器自检(纸带不变)
tests/synth_test.cc           合成 + ROT-8 虚拟机自检
tests/byte_op_test.cc         字节级库穷举自检(65536×4 + 512)
tests/macro_docs_test.cc      宏注释格式自检(asm/ 下每个 %macro)
tests/tape_run.cc             第二个 ROT-8 解释器,直接跑 .rot8 交叉验证
asm/                          标准库与既有实现
examples/full_add.r8asm       汇编期合成全加器