dsh 1200880d4d TODO: drop the finished items, add what the last rounds turned up
Done and removed: the desk calculator (examples/calc.r8asm -- 62585 characters at
11 bits, three implementations agree, width matrix in tests/widths.ps1), the INP
whole-cell semantic fix, and the reference machine's support for tapes above
64k.  In their place, under "interactive computing": the RPN stack (fixed depth,
because .tp is an assembly time constant -- 16 deep is about 12k of tape, 200 deep
would be 100k per push), the terminal tape (prompt, echo, line editing, one
session per `;   in` header), and clb_puts / printf so a program can print a
sentence.

New tail: ROT-8-viz still has zero tests, and its old fixed-buffer read_tape is
now unused; INS_SIZE is a historical constant next to ROT8_MAX_TAPE (16M
instructions).
2026-11-17 16:14:42 +08:00

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

三条要注意的:

  1. map 的项数决定输入个数:2^K 项就是 %1..%K 为输入,值的第 j 位落到 %(K+j+1),剩下的参数是必须结束为 0 的草稿。要完全显式(或输入不在最前面)就用 stat(整张状态表,2^params 项)。
  2. 默认按"布局无关"口径搜(flat):结果与 cell 布局无关,缓存能跨调用点复用。 想按真实 .tp 行走重新搜,加 --synth-chars。full_add 上两种口径是 95 / 90 字符。
  3. 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/                          标准库(48 个宏,含 8 个 %synth 合成块)
drv/                          单点验证驱动(喂固定输入跑一个宏,看 out/stat)
examples/                     16 个能跑的例程:每组宏一份 + %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。
S
Description
R8ASM assembler with the searcher built in
Readme
2 MiB
0 Stars 1 Watchers 0 Forks
Languages
C++ 86.5%
CMake 5.8%
Verilog 5.4%
PowerShell 2.3%