Files
R8Forge/SPEC.md
T
dsh 4a5bd836a8 clb_divmod: nine parameters down to four
Complaint received and agreed with: nine cells to pass for a division is not an
interface anybody wants to type.  Two things made it possible to shrink:

  * .tp and macro arguments accept address expressions (measured: .tp A+1
    assembles, and set_0 A+1 expands to .tp A+1 inside the callee).  So the
    four scratch cells can be passed as one block: clb_divmod N D Q S uses S,
    S+1, S+2 and S+3.
  * BUF and X were unnecessary: copy already has sources and destinations to
    spare that are dead at the moment they are needed, and clb_inc_ip can take
    a cell that the probe is about to overwrite.

So the signature is now clb_divmod N D Q S -- three data cells and one scratch
base -- and the tape dropped from 5839 to 4189 characters on the way, because
the scratch cells now sit next to each other and every .tp walk got shorter.

Still correct: all 76 sampled pairs (2047/10 = 204 7, 7/10 = 0 7, 10/10 = 1 0,
1234/100 = 12 34, 999/7 = 142 5, 2047/2047 = 1 0), and the O(N/D) limit is
unchanged.
2026-11-07 16:53:27 +08:00

29 KiB
Raw Blame History

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.r8asm 2199)。
  • 想复现: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--

两条必须记住的约束(标准库全部遵守,写新宏也得遵守):

  1. biz/rnz 判的是最低位,不是"整格为零"。 于是 set_0 = [-] 只清 LSB:255 → 254、128 → 128、5 → 4。 要清整个 cell 得 %rep _CELL_SIZE { set_0; ror },也就是 erase。 反过来,字节里的任意一位都能读:ror 若干次把目标位转到 LSB,再 biz。
  2. 每个条件块的身体必须回到它自己的条件 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
loop loop c 动态循环开口:按 c 里 1 的个数跑,每轮吃掉一个 1 1 4 + .tp
endloop endloop c 动态循环收口(rnz 判 c 的最低位) 1 1 + .tp

要点:

  • set_0 只清一位,erase 才清整格;别把 set_0 当"清零 cell"用。
  • copy 比 bit_copy 长十倍多,是因为它对每个 bit 调一次 bit_copy 并转圈 (copy 495 vs bit_copy 38)。只搬一位用 clb_bit_mov(11)。
  • clb_bit_mov 会把源位清掉 —— 它顺手就"吃条件",这正是 set_0/clb_bit_mov 身体里那个 flb 的作用(见 §2 第 2 条)。

5.1 动态循环:clb_ones 配 loop/endloop

%rep 是汇编期的。要按运行期算出来的次数循环,用这一对:

clb_ones N C T F      ; C = N 个 1(N 被吃掉,§7.5)
loop C
    ... body ...      ; 想干几次就干几次
endloop C
  • loop c = .tp c + biz + set_0 + ror:进来时测最低位,进去就把这一位吃掉再转一格, 把下一个 1 送到最低位。于是"配额"就是那串 1 的长度,一圈用掉一个。
  • endloop c = .tp c + rnz。
  • 三条约定:循环体不许碰 c;不开 .anchor,所以能嵌套;endloop 之后 dp 停在 c 上(不管循环体把 dp 指到哪儿,收口都会指回来)。
  • 跑完 c 是 0。n = 0 时 biz 直接跳过,一圈不跑 ✓。

实测(verify_loop.r8asm,939 字符):n = 0..11 循环体正好跑 n 次,A = n、C = 0。 嵌套也验过:内层每轮用 copy 重新造一份计数器,NO × MI 得到 121(11×11)、MI = 0 时 0、 NO = 0 时 0 —— 就是普通的双层循环。

纸带代价是 loop 4 字符 + endloop 1 字符 + 两次 .tp(跟布局有关),和次数无关; 运行是 O(n)。

在 .r8asm 源码里循环要写 biz / rnz,不是 [ / ] —— 后者是纸带上的编码。 直接手写 [ 会报 unknown macro '['(lib.r8asm 里就是这么踩的)。

别拿它去替代汇编期常数。clb_mul 的轮数计数器是 _CELL_SIZE 个 1,汇编期就能做:

%rep _CELL_SIZE { set_1; ror }        ; 55 字符(4+1 各 11 份)

换成运行期那条路要 clb_ones(≈770)+ loop/endloop(≈10)+ 先把常数 _CELL_SIZE 做成运行期的值,约 850 字符 —— 15 倍,还多 4 个 cell 和几万步运行时间。 所以规则是:次数在汇编期就知道 → 汇编期造计数器;只有次数来自数据才用 clb_ones。 (loop/endloop 两种都吃:它们只要求"某个 cell 里现在有 n 个 1",不关心这些 1 是谁造的。)

顺带一个坑:%rep N { set_1; ror } 造出来的 N 个 1 落在高位(bit W-1 往下), biz 看到的 bit0 是 0,循环一圈都不跑 —— N < W 时要在 %endrep 后面补一条 rol (10 字符),把那串 1 转到含 bit0 的位置。clb_mul 没踩这个坑,是因为它的 N 正好等于 _CELL_SIZE,整格全 1,bit0 天然是 1。


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" 的轮转驱动,吃掉操作数完全没问题。

7.5 clb_ones:把数量展开成一串 1

clb_ones A B T F:B = 2^A - 1,也就是从末位起 A 个连续的 1;A 当计数器被吃干净 (结束为 0),T、F 结束也都是 0。前提 A <= _CELL_SIZE,不做检查(A 更大时 2^A−1 会绕回)。

输入 A 0 1 4 7 11
输出 B 0 1 0x0F 0x7F 0x7FF(全 1)

4 个 cell、纸带 828 字符(drv/ones.r8asm 是 742,因为它的布局更近), A 的 12 个取值全对(r8forge_byte_op_test 的 test_ones)。

算法就是"边转边在低位补 1":

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

2B+1 在这台机器上等于 rol + set_1:左旋把 B 的最高位带回末位,紧接着的 set_1 正好把它盖成 1,于是等价于"左移补 1"。A 直接当计数器吃掉(省一次 copy,那是 495 字符), 循环体只出现一次,所以长度和 A 无关;代价是运行 O(A),而 A ≤ _CELL_SIZE。

两个可以拿来写别的东西的恒等式:

  • clb_inc_ip 作用在"n 个 1"上得到 2^n(末位起第 n+1 位是 1);
  • 反过来先摆一个 2^n 再 clb_dec_ip,也得到 n 个 1(这条比上面的循环短 128 字符的 clb_dec_ip 反而更长,因为循环体里要一直 set_1,见 asm/ones.r8asm 的注释)。

7.6 clb_divmod:除法与取模

clb_divmod N D Q S:Q = N div D、N 结束时就是余数 R,D 被吃干净。 7 个 cell(3 个数据 + S 起的 4 个连续草稿),纸带 4189 字符 (drv/divmod.r8asm 是 4195),76 组抽样全对(r8forge_byte_op_test 的 test_divmod)。

算法是最钝的那招:

Q = 0
while N >= D:  N -= D ; Q += 1

三处踩出来的设计:

  1. clb_sub_nc 会把 N 和 D 都吃掉,而减法不能用 S == A 的别名 —— 实测 clb_sub_nc A B A Ci(A=15 B=10 Ci=1)直接给出 0。所以每轮都得 copy 出 S = N、 S+1 = D 再减,三个 copy 里有两个是"过路费"。
  2. 首轮要能什么都不做:S+2 预置成 N、Q 预置成 -1。于是第一轮"提交 S+2 -> N"是 空操作,Q += 1 正好把 −1 补回 0;探测放在循环体末尾,所以零轮(N < D)和一轮 (N == D)都对,而且探测代码只出现一次(不这么写要多 1.3k)。
  3. 草稿参数只给基址:.tp 和宏实参都接受地址表达式(S+1 能编译,copy %4+2 %4 就是 .tp S+2 + copy S S),所以 4 个草稿格当一个块传。一开始写成 9 个参数 (每个草稿单列 + 单独的拷贝缓冲和自增草稿),压成基址后顺带短了 1.6k。

O(N/D) 的代价要记住:2047 / 1 会撞 500 万步上限(实测 HANG),每轮约 2.4k 步, 所以 N/D 最多到 1500 左右;2047 / 2 是 1023 轮,正常返回 1023 1。 除零没有定义,调用者保证 D >= 1。


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. 用 [ ... ] 的自然语义把最低位连续的 1 清掉(flb + ror),遇到第一个 0 退出;
  2. 那个 0 翻成 1(输入全 1 时跳过,正好是回绕那一格);
  3. 剩下的位置只旋转,转满 _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 19 个测试项 = 18 个宏(clb_neg_nc 的 Ci=1 / Ci=0 各算一项),见 §7.1、§7.2、§7.5、§7.6、§8、§9 按返回值:穷举 0..255(clb_add_ip 2048 抽样、clb_mul 65536 全穷举、clb_ones 12 个计数全穷举、clb_divmod 76 组抽样),任一不符即退出码非 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_derive verify_loop.r8asm -1 0=N 动态循环:N=0..11 时循环体跑 N 次(A = N、C = 0) 逐值 out
r8forge verify_set_0.r8asm set_0 只清 LSB -1 0=255 → 254、0=128 → 128
r8forge_macro_docs_test asm/ 里 45 个宏的注释格式 全绿或报错行号
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 的口径重新量,别把驱动长度和最小驱动长度混在一列。