Files
R8Forge/README.md
T
dsh 12a2254078 docs: a design note for building the machine out of silicon
docs/hardware.md turns the ISA into hardware requirements and works out what a
physical ROT-8 needs.  The load-bearing observation is that nothing in the
instruction set can observe time -- no counters, no interrupts, and the I/O
behaviours are "block until a character" and "latch the cell" -- so any
implementation that reproduces the same sequence of (ip, dp, cells, output) is
the same machine, at any clock rate and any number of cycles per instruction.
That is what makes the build tractable: a microcoded sequencer, slow memory or
even a drum are all legal.

The note pins the parts that are easy to get wrong: the exact scan boundaries
for [ and ] (the ] case jumps back onto the [ itself so it re-tests, which the
reference rot8.c gets right and a naive implementation gets wrong), the halt
condition, cells starting at zero, and the input convention -- , blocks until a
character arrives and an explicit EOF reads as 0, otherwise every interactive
read would return zero and the program would exit at once.

Budget: 3 bits per instruction, so the flagship tape is 23.4 KB of ROM and the
calculator at 11 bits is 27.6 KB; the data ring is 259 cells by W bits at most
518 bytes.  Two consequences: the instruction pointer needs at least 17 bits
because the calculator now assembles to 73624, past the historical INS_SIZE of
65536, and the 32 bit calculator (126 KB) does not fit the block RAM of the
small boards.

Three carriers are compared: FPGA first (Tang Nano 9K, about 58 KB of BSRAM, a
weekend of work), discrete TTL as the real machine (25-35 chips, 0.25-0.5 M
instructions per second, a few weeks) and electromechanical as the showpiece
(a drum with 11 tracks and 259 cells per track, read and write heads one cell
apart so a read-modify-write costs one cell time: 22 s for a whole calculator
session at 3000 rpm).  The verification plan leans on what already exists: a
packer into the 3 bit format, the RTL testbench compared against tape_run step
by step, then the panel single-stepped against an exported trace.

Nothing is implemented; the note ends with the decisions that come first --
which carrier, which width (8, 11 or 16), program storage, and whether the
physical tape form matters.  The first concrete step would be M0: the packer
plus a rot8.v testbench, which needs no hardware purchase and gives all three
carriers the same golden model.
2026-11-20 15:14:42 +08:00

7.5 KiB
Raw Blame History

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 对拍路线。