clb_puts REG LEN prints LEN consecutive cells as characters (the low 7 bits, which
is what serial OUT sends). LEN has to be an assembly time constant: .tp takes a
literal address here, so "print until the cell is zero" is not expressible -- the
walk would leave the data pointer somewhere else. Each character costs two .tp
plus one out (three or four tape characters), uses no extra cell and leaves the
source cells alone.
load N V is the helper every driver was writing by hand (erase then .xor): .xor is
an exclusive or, so a second load without the erase would mix with the old value.
drv/puts.r8asm 198 chars, in-family check: out 72 73 33 72 (HI! plus the
untouched source cell)
examples/hello.r8asm 727 chars, out 72 69 76 76 79 44 32 82 56 33, and the
reference machine prints "HELLO, R8!"
Both are documented in SPEC 5.2; the macro count goes 48 -> 50 and the examples 16
-> 17. The flagship tape is untouched (64513) because asm/test.r8asm still has its
own local load -- same body, and lib's definition comes first, so nothing changed.
6.8 KiB
R8Forge
ROT-8(1-Bit Brainfuck)的汇编器 + 汇编期合成器,一个仓库一份进程。
搜索器不再是独立程序:%synth 是汇编期指令,你给它一张真值表,它现场搜出最短的块序列
直接拼进纸带。代价模型和发射器从此是同一份代码,不用再维护两套"这个块要花多少条指令"
的估算。
细节(契约、数字、坑)都在别的文件里,这份 README 只负责"怎么跑起来"和"去哪儿看":
| 想查什么 | 去哪儿 |
|---|---|
%synth 完整语法、机器几何、每个宏的契约(吃什么留什么、几个 cell、纸带多长、谁验证) |
SPEC.md |
| 怎么干活、踩过的坑、当前交接、别动清单 | AGENTS.md |
| 设计推理长文(为什么这么写、失败的尝试) | docs/ |
| 还没做的事(候选、优化、工具) | TODO.md |
30 秒上手
cmake -S . -B build -G "Visual Studio 18 2026" -A x64 # 或者 Ninja / Makefile
cmake --build build --config Release
build/Release/r8forge examples/full_add.r8asm > adder.rot8 # 纸带进 stdout,说明进 stderr
build/Release/r8forge_tape_run.exe adder.rot8 # 跑一遍,打印 out 和步数
examples/ 里每个 .r8asm 头部都有一行 ; out ...,写着它应该打印什么;跑出来的
out 和那行一致才算对。
%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
三条要注意的:
map的项数决定输入个数:2^K 项就是%1..%K为输入,值的第 j 位落到%(K+j+1),剩下的参数是必须结束为 0 的草稿。要完全显式(或输入不在最前面)就用stat(整张状态表,2^params 项)。- 默认按"布局无关"口径搜(flat):结果与 cell 布局无关,缓存能跨调用点复用。
想按真实
.tp行走重新搜,加--synth-chars。full_add 上两种口径是 95 / 90 字符。 mode layers只求层数最少(快),mode tape(默认)求纸带最短。
结果按"真值表 + 口径"缓存在 .r8forge_cache/(已入库,克隆下来直接命中);要重算就删
那个目录。缓存键里带 kModelVersion,改指令模型必须 bump 它(src/synth.cc)。
常用开关
r8forge asm/test.r8asm # 汇编,stdout 是纸带
r8forge --synth-chars examples/full_add.r8asm # 按真实布局重新搜
r8forge -j 4 examples/full_add.r8asm # 纸带搜索最多 4 个 worker(默认每硬件线程一个)
r8forge -q examples/full_add.r8asm > full_add.rot8 # stdout 只剩纸带
-j 只影响纸带搜索(层数搜索是串行的);-q 只压 stdout,错误照旧进 stderr、退出码不变。
目录结构
include/r8forge/r8asm.hh 汇编器 + %synth 指令
include/r8forge/r8veritas.hh 搜索器
include/r8forge/geometry.hh 默认几何(11 位 × 259 格)
src/r8asm.cc 汇编器实现
src/synth.cc 真值表 -> 搜索
asm/ 标准库(50 个宏,含 8 个 %synth 合成块)
drv/ 单点验证驱动(喂固定输入跑一个宏,看 out/stat)
examples/ 17 个能跑的例程:每组宏一份 + %synth 的几种写法 + 一个交互例程
tests/ 汇编器 / 虚拟机 / 字节级 / 例程 / 文档格式 自检
docs/ 设计笔记(长文)
.r8forge_cache/ 合成结果缓存(已入库)
SPEC.md AGENTS.md README.md 契约 / 工作手册 / 本文件
标准库
asm/ 分四层,全部位宽无关(宏里写 %rep _CELL_SIZE,改几何自动跟着变):
| 层 | 代表 | 一句话 |
|---|---|---|
| 位级(一个 cell 装一位) | clb_bit_add_nc、bit_raw_add |
8 个块是 %synth 合成的,与手写逐位一致 |
| 字节级(一个 cell 一个机器字) | raw_add、clb_add_nc |
raw_* 保留操作数、clb_*_nc 吃掉它们换 cell |
| 原地 | clb_inc_ip、clb_add_ip |
结果回到原 cell,2~4 个 cell 就够 |
| 大宏 | clb_mul、clb_divmod、clb_digits、clb_undigits |
乘、除、整数 ↔ 4 位 ASCII |
契约(签名、参数类型、cell 数、纸带长度、由哪个测试验证)在 SPEC.md §5–§9;
为什么是现在这样(以及那些失败尝试)在 docs/byte-ops.md。
例子
examples/ 里每个 .r8asm 都是能跑的程序,头部 ; out ... 写它打印什么:
build/Release/r8forge examples/digits_demo.r8asm > t.rot8
build/Release/r8forge_tape_run.exe t.rot8 # 打印 out 和步数
r8forge_examples_test 会把它们全跑一遍、逐项核对头部那行 —— 例程不会悄悄腐掉。要喂输入的例程\n在头部多写一行 ; in ...(examples/echo_chars.r8asm 是最小的例子),测试会先把那串字符\n交给 inp。每份例程
演示哪一组宏见 SPEC.md §10.3。
构建与自检
cmake -S . -B build -G "Visual Studio 18 2026" -A x64
cmake --build build --config Release
build/Release/r8forge asm/test.r8asm # 全家桶:每个标准宏至少一次
build/Release/r8forge_synth_test examples/full_add.r8asm # 合成的块 + 虚拟机自检
build/Release/r8forge_byte_op_test # 字节级库穷举
build/Release/r8forge_examples_test # 例程 + 全家桶,核对 `; out`
build/Release/r8forge_macro_docs_test # 宏注释格式
build/Release/r8forge_derive verify_loop.r8asm -1 0=5 # 动态循环:out 应该是 5 0
ctest --test-dir build -j 4 --output-on-failure # 上面这些一次跑完(8 条,约 9 秒)
build/ 已经配好生成器:重编译请用给它配的那个 cmake(PATH 上的另一个版本会重新配置,
然后死在 No preprocessor test for "PellesC"),命令和"当前基线"的数字见
AGENTS.md。
细节去哪看
SPEC.md—— 唯一事实源:%synth语法语义、几何、每个宏的契约、验证矩阵、 边界、维护清单。AGENTS.md—— 工作手册:构建/自检命令、硬规则、坑、当前交接。docs/divmod.md——clb_divmod的移位-恢复除法:每轮状态、坑、实测。docs/byte-ops.md—— 字节级库的设计推理与教训。TODO.md—— 还没做的事:交互计算器、纸带优化器、--profile、缓存体检、CI。