dsh 9b31a51fec hardware: M0 -- the packer, the RTL, and a simulator that agrees byte for byte
The two things software cannot check by reading its own source are the 3 bit
packing and the bracket strategy, so both got a tool and a test.

New in the library (r8forge/tape.hh, src/tape.cc): the opcode numbering (taken
from ROT-8-viz enum, so the packed image and the hardware decoder cannot drift),
text <-> opcodes, opcodes <-> 3 bit bytes, the .r8t image with its trailer and
crc32, and a machine model that runs a packed tape the way a board would.  The
model takes the bracket strategy as an option: backward scan with loop stack or
not, and jump-back-onto-the-[ (the contract) or past it (what the interpreters
do).  All four combinations print the same thing, and the step count differs by
exactly the number of taken ] instructions -- which is what the test asserts.

Found and fixed while writing it: the loop stack discipline depends on the jump
convention.  Jumping onto the [ means the [ re-pushes, so ] must pop on the jump;
jumping past it means the entry must stay until the loop exits.  Mixing them up
emptied the stack on the second iteration of the calculator main loop -- caught
by the equivalence test on examples/calc.r8asm, not by reading the code.

Tools: r8forge_tape_pack (text tape -> image + --hex for $readmemh + --verify,
727 instructions become 273 bytes for hello, 62%, and the trailer sits past the
halt so address 0 of a ROM is instruction 0), and r8forge_tape_run now reads an
image directly and takes --loop-stack / --retest.

hardware/rot8.v: the 8 bit / 64 cell machine -- 3 bit opcodes from a byte
addressed memory read as a 16 bit window, a 6 bit dp with free wrap, the loop
stack bracket jump, blocking input, halt on ip == length, and a step counter that
counts instructions rather than cycles.  hardware/tb_rot8.v loads a --hex image
and prints the OUT stream in tape_run format.

Verified with Icarus Verilog 14 (the RTL against tape_run --loop-stack --retest):
  hello        577 instructions  417 steps  10 outs
  term         16414            17643      11 (fed "lhi")
  calc         51378           166741      19 (fed "12 34 + .": prints the prompt,
                                                046 and the next prompt)
  flagship     43676           100142      93
Every OUT stream identical.  ctest -R rtl_sim runs that comparison from an 8 bit
build (11 tests in the default build now, where the RTL test self-skips because
the RTL is the 8 bit machine).

Two traps worth remembering: Icarus passes plusargs through as raw bytes, so an
absolute +HEX path containing non-ASCII (this checkout is under a Chinese
directory name) arrives mangled, $readmemh silently leaves the memory empty and
the machine obediently runs LEN steps of opcode 0 printing nothing -- run vvp
from the directory holding the hex with a relative name.  And in_ready must not
be qualified with !in_valid or the input handshake deadlocks.
2026-11-20 16:25:54 +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 只剩纸带
r8forge --opt asm/test.r8asm > t.rot8     # 纸带窥孔优化:62351 -> 56338 字符

-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/                          标准库(55 个宏,含 8 个 %synth 合成块)
drv/                          单点验证驱动(喂固定输入跑一个宏,看 out/stat)
examples/                     19 个能跑的例程:每组宏一份 + %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、clb_digits_signed、clb_divmod_signed 乘、除、整数 ↔ 4 位 ASCII;带 signed 的两个是二补码包装(负数显示/截断除法)

契约(签名、参数类型、cell 数、纸带长度、由哪个测试验证)在 SPEC.md §5–§9 (有符号数在 §5.4 + §7.10);为什么是现在这样(以及那些失败尝试)在 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              # 全家桶:除两个 signed 包装宏外每个标准宏至少一次
build/Release/r8forge_synth_test examples/full_add.r8asm   # 合成的块 + 虚拟机自检
build/Release/r8forge_byte_op_test                # 字节级库穷举(23 项,含带符号数的全扫)
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 -C Release -j 4 --output-on-failure # 上面这些一次跑完(8 条,约 12 秒)

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 —— 还没做的事:迷你 printf、纸带优化器、 --profile、缓存体检、CI。
  • docs/calc.md —— 桌上计算器:命令协议、3 格 RPN 栈、终端外壳(回显/ 退格/提示符)、分阶段计划。
  • docs/hardware.md —— 造一台真的 ROT-8:硬件需求、ROM/RAM 预算、 FPGA / 分立 TTL / 机电三档载体、打包器与 RTL 对拍路线。
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%