`metric chars|flat|blocks` inside %synth meant the same truth table could be
searched twice for two call sites, and every library block had to spell out
`metric flat` to avoid the default. The cost model belongs to the whole
assembly, so it is one now:
r8forge <file.r8asm> flat (layout free), the default
r8forge --synth-chars <file.r8asm> charge the real .tp walk
flat stays the default because a library block is expanded at dozens of call
sites with different layouts: only a layout free result can share one cache
entry, and it is usually within a few percent (full_add: 95 vs 90 characters).
The chars search is far more expensive (full_add: 415M states, ~21 minutes,
~10 GB), which is exactly why it should be asked for on the command line.
`metric blocks` goes with it: block count is a poor proxy for tape length (and
it was only another way to ask for mode layers).
Implementation: the metric lives in the assembler (ast::synth_metric, default
1) and is set through r8asm::set_synth_metric() before import_file; the CLI in
tests/asm_test.cc parses --synth-chars / --synth-flat. The cache key already
carried metric, so the committed entries still hit: assembling the library and
asm/test.r8asm gives byte identical tapes (28729 characters, byte_op_test all
green, all 13 examples green, synth_test still 8/8).
A `metric` line now fails with a message that names the flag instead of being
silently ignored. examples/full_add_flat.r8asm and full_add_flat_spaced.r8asm
are removed: they only existed to demonstrate the per block metric (the flat
default makes them copies of full_add.r8asm).
Also repairs the mojibake in README's metric section: an earlier tool wrote
\x0c / \x08 / \x0d where \f, \b and \r belonged, which ate characters out of
"flat", "blocks", "biz/flb/rnz" and "rnz". The section is rewritten for the
flag, and the %synth numbers in README/SPEC/AGENTS now match what the tree
prints.
New cache entry c16bf083bb0ccbc8.txt is full_add's stat table with mode layers
+ flat, which full_add_stat.r8asm now produces.
578 lines
41 KiB
Markdown
578 lines
41 KiB
Markdown
# 给接手的 agent 的话
|
||
|
||
## 下一轮从这里开始(2026-11-07 交接:移位-恢复除法已落地)
|
||
|
||
**上一轮的任务做完了**:`clb_divmod` 已经是二进制长除法(`asm/divmod.r8asm`)。
|
||
契约看 `SPEC.md §7.6`,设计推理、踩过的坑和实测数据看 `§14`。摘要:
|
||
|
||
* 签名变成 `clb_divmod N D Q R S`:`Q` = 商、`R` = 余数,**N 和 D 都保持原样**,
|
||
`S` 起 **7 个连续草稿格**。11 个 cell,最小驱动纸带 **4499**(旧 4189)。
|
||
* 固定 **11 轮(位宽)**,`2047/1` 不再 HANG。步数(`drv/divmod.r8asm`):
|
||
`2047/10` 49.6 万 → **2.86 万**、`2047/2` 246 万 → **3.2 万**、`999/7` 34 万 →
|
||
**2.87 万**、`2047/1` HANG → **3.24 万**;16384 组里最坏 **32,383** 步。
|
||
**小 N/D 反而慢**(旧版 N/D 轮就结束)——和 `clb_mul` 一样的取舍。
|
||
* `clb_digits` 跟着换了布局(`S` 起 **13 格**,divmod 的草稿块从 `S+3` 开始):
|
||
`0=2047` 从 74 万降到 **14.5 万**步(最坏 164,867),`test_digits` 现在**穷举
|
||
全部 2048 个值**。纸带 10829 → 13717。
|
||
* 单点验证驱动:`drv/div_shift.r8asm`(跨格左移 + 注入那一步,`SPEC §14.4` 第 1 条)。
|
||
* 顺带修了两处**会骗人的东西**:`r8forge_derive` 以前不看汇编器的 error 位,漏
|
||
`%include`(`unknown macro`)时会拿**截断的纸带**跑出一个看起来正常的错答案
|
||
(这轮踩过一次,四个数字全变成 `'0'`);`raw_sub` 注释里把 Bo 的语义写反了
|
||
(Bo = 1 是"没借位"= `A >= B`,实测 15-10 → 1、10-15 → 0)。
|
||
|
||
**下一步可以做的(这轮没做)**:
|
||
|
||
* 想再快一档:`SPEC §14.6` 那条"开循环前预计算 `~D`、每轮走 `raw_add`",按单轮实测
|
||
差值估计 `clb_divmod` 28.6k → 约 17.6k 步,纸带基本不变;没换是因为 §14.3 指名
|
||
用 `raw_sub`,而它是上一轮专门为长除法加的。
|
||
* 纸带还能短:`clb_digits` 的布局没优化过(13 格草稿跨得很开,`.tp` 行走占了纸带的
|
||
七成);`clb_divmod` 里提交时那个 495 字符的 `copy` 也还是全展开的。
|
||
* 小 N/D 的慢是"固定 W 轮"的必然代价。真要治,得加"跳过前导 0 轮"(`R == 0` 的轮
|
||
只剩 Q 的旋转),但那会给**每一轮**加一次 `clb_nonzero`(约 300 步),大数反而更慢
|
||
—— 这轮权衡过,没做。
|
||
|
||
**别动**:`asm/` 里其它宏;`%synth` 的指令模型(改了就 bump `kModelVersion`);
|
||
`geometry.hh` 的位宽(真要改照 SPEC §13 的清单,四份虚拟机一起)。
|
||
|
||
|
||
**当前基线(都通过,别弄坏)**:
|
||
|
||
```sh
|
||
r8forge asm/test.r8asm # 28729 字符
|
||
r8forge_byte_op_test # 20 项(clb_divmod 16384 组、clb_digits 2048 个值)
|
||
r8forge_examples_test # examples/ 里 13 个程序,头部 `; out` 逐个核对
|
||
r8forge_macro_docs_test # 47 macros in 21 files
|
||
r8forge_synth_test examples/full_add.r8asm # all eight combinations ok
|
||
r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0
|
||
```
|
||
|
||
**另一个仓库**:`../ROT-8-viz`(fork `dsh/ROT-8-viz`,`main` = `6e51df5`)有串行 7E1
|
||
(`-s` / `--parity` / `--stop` / `--7e1`),`clb_digits` 产出的 ASCII 正好能直接喂它的
|
||
`OUT`。那边的工作树也是干净的。
|
||
|
||
> **动手之前,先把这份文件从头读完**,再看 `SPEC.md`(本仓库自己的:`%synth` 指令 +
|
||
> `asm/` 里每个宏的契约、纸带长度、验证口径)、上游语言规格
|
||
> (`C:\Users\peng0\git\r8asm_rev-fork\SPEC.md`)和 `asm/lib.r8asm` 里的宏注释。
|
||
> 这条不是客套:上一轮我没先读,把「位移-加法乘法器比重复加法快」当成新发现又推了一遍。
|
||
> 那次它被否掉了(当时只认纸带长度),后来乘数一大就撞 500 万步上限,真的换成了移位-加法
|
||
> —— **而且它比重复加法还短**(5007 → 3977 字符),见「乘法器」。
|
||
> 下面「乘法器」「指令集语义」两节把要命的地方都写了 ——
|
||
> `dp` 净位移、`flb` 吃条件、`rol` = 10 次 `ror`、
|
||
> 位串行要的跨格移位该怎么拼。**尤其把「已经确认走不通的」那节看完**,
|
||
> 别把别人踩过的坑再踩一遍;想推翻某条结论,先照它写的验证方法实测一遍再改文字。
|
||
|
||
这个文件是给下一个会话(或者下一个 agent)看的交接说明。内容都是这个仓库里**实测过**的结论,
|
||
不是推测;每条后面基本都跟着一次失败的尝试,别再踩。
|
||
|
||
## 工作方式(上一轮踩到的)
|
||
|
||
* **超过 ~30 秒的命令一律丢后台**(`run_in_background`),前台只做短轮询。
|
||
一次搜索可以跑 680 秒、缓存预热 885 秒,前台干等会撞上客户端和 API 的传输超时。
|
||
* **别让大段 stderr 进上下文**。PowerShell 遇到原生命令出错会吐一整套 `NativeCommandError`
|
||
堆栈;用 `2>$null` 收干净,判断结果靠 `$LASTEXITCODE` 和 stdout。
|
||
* 写含中文的文件用编辑工具(UTF-8)。**不要用 PowerShell 做"读-改-写"**:这台机器上
|
||
`Get-Content` 默认按 GBK 读 UTF-8 文件,再 `Set-Content -Encoding utf8` 写回去就是
|
||
二次转码、整篇变乱码(`AGENTS.md` 就这么被我毁过一次,靠 `git checkout -- AGENTS.md`
|
||
救回来)。`Set-Content -Encoding ascii` 更糟,汉字直接变 `?`
|
||
(`examples/` 里那些带中文注释的 `.r8asm` 就这么坏过一次)。
|
||
* **构建要用 VS 自带的 cmake**:`build/` 是 `Visual Studio 18 2026` 生成器配的,
|
||
直接敲 PATH 上的 scoop cmake(4.4)会因为版本不一致重新配置,然后死在
|
||
`No preprocessor test for "PellesC"`。用这个:
|
||
|
||
```sh
|
||
"C:/Program Files/Microsoft Visual Studio/18/Community/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe" \
|
||
--build build --config Release
|
||
```
|
||
* **`%synth` 的临时文件**:汇编器把生成的宏写到系统临时目录再 import,然后删掉。这台机器上
|
||
这一步**偶尔**会失败(`r8asm: cannot open 'C:\Users\...\Temp\xxx.synth.r8asm'`;同目录下
|
||
`cmd` 能写、`r8forge` 不能,原因没查清,重跑一次可能就好了)。现在代码会退回到**当前工作
|
||
目录**重试,stderr 留一句 `<临时目录> is not writable, using <cwd>`。看到这句不用管;
|
||
看到 `cannot write the synthesised macro anywhere` 才是真坏了。`*.synth.r8asm` 已在
|
||
`.gitignore` 里。
|
||
* 会话很长时传输容易失败,重要结论要落到 **commit message 和文件注释**里,别只留在对话里。
|
||
* **写结论之前先对虚拟机**:这个仓库最贵的一次事故就是虚拟机语义写错,然后在错的东西上
|
||
写了一整套"实测结论"(见「字节级运算」)。字节级结论必须能被 ROT-8-viz
|
||
(`C:\Users\peng0\git\ROT-8-viz`,权威实现)复现。
|
||
* **提交身份**:这个 repo 和 `C:\Users\peng0\git\ROT-8-viz` 的 local config 都是
|
||
`user.name = dsh`、`user.email = dsh@gitea.local`(凭证里那条 `git:https://gitea.starcells.ltd`
|
||
就是 `dsh@gitea.local`)。**agent 的提交用 dsh,不要用 `StarCells <peng080306@foxmail.com>`**
|
||
—— 那是仓库主人的身份。这条踩过:ROT-8-viz 一开始没配 user.name,我照抄了历史作者,
|
||
结果两个 repo 的提交都挂在了主人名下,后来用 `rebase --reset-author` / `filter-branch`
|
||
改回 dsh 并 force-push 才修好。`git commit` 报 `Author identity unknown` 就是这条配置又没了,
|
||
补 `git config user.name dsh` + `git config user.email dsh@gitea.local` 就行。
|
||
ROT-8-viz 上这个 local config 被清掉过两次(原因没查清),所以那边提交时更稳的写法是
|
||
直接带上:`git -c user.name=dsh -c user.email=dsh@gitea.local commit ...`。
|
||
* **推代码**:`origin` = `https://gitea.starcells.ltd/dsh/R8Forge.git`。这台机器上
|
||
schannel 会报 `schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS`,
|
||
`fetch` / `push` 都得走 openssl 后端 —— 已经写在这个 repo 的 local config 里
|
||
(`git config http.sslBackend openssl`),正常 `git push` 就行。
|
||
如果当前会话的沙箱是 workspace-write,`push` 还要一次提权:git 的凭证助手要开命名管道,
|
||
沙箱会拒绝(`sh.exe: fatal error - couldn't create signal pipe, Win32 error 5` +
|
||
`could not read Username`);danger-full-access 下不需要。`fetch` 两种模式都不需要
|
||
(仓库可匿名读)。
|
||
|
||
## 构建与自检
|
||
|
||
```sh
|
||
# MSVC Release
|
||
cmake -S . -B build -G "Visual Studio 18 2026" -A x64
|
||
cmake --build build --config Release
|
||
|
||
# clang-cl(scoop 的 llvm,比 MSVC 严格,能抓出模板推导问题)
|
||
clang-cl /nologo /std:c++20 /EHsc /O2 /I include src/r8asm.cc src/synth.cc tests/asm_test.cc /Fe:r8forge.exe
|
||
```
|
||
|
||
自检:
|
||
|
||
```sh
|
||
r8forge asm/test.r8asm # 应 exit 0,28729 字符(3 轮 hash)
|
||
r8forge_synth_test examples/full_add.r8asm # all eight combinations ok
|
||
r8forge verify_clb_bit_add_nc.r8asm # 4 cell 加法切片(进位进->出)
|
||
r8forge verify_clb_bit_inc_nc.r8asm # 3 cell 自增切片,进位同样进->出
|
||
r8forge_derive verify_loop.r8asm -1 0=5 # 动态循环:跑 5 次,out 应该是 5 0
|
||
r8forge_byte_op_test # 字节级库:20 个操作穷举/抽样,这台机器约 10 秒
|
||
r8forge_macro_docs_test # asm/ 里每个宏的注释格式
|
||
```
|
||
|
||
`r8forge_byte_op_test` 是**唯一按返回值判断字节级对错的**;前三个只证明"汇编得出来"或
|
||
"位级正确"。
|
||
|
||
**`r8forge_derive` 会检查汇编错误**(2026-11 修的):`import_file` 只表示"文件打开了",
|
||
漏一条 `%include` 时汇编器会报 `unknown macro '...'` 并把 error 位置上、纸带是**截断**的。
|
||
以前 `derive` 不看这个标志,于是拿半截纸带跑出一个看起来正常的错答案(这轮实测踩到:
|
||
`clb_digits` 少了 `add_ip` 的 include,四个数字全变成 `'0'`)。现在它会打印
|
||
`could not assemble` 并返回 1 —— **看到 `out` 结果"太整齐"就先看 stderr**。
|
||
|
||
`r8forge_derive` 是验证工具:
|
||
|
||
```sh
|
||
r8forge_derive <file.r8asm> 4 0 2 # 按输入组合跑,打印 stat
|
||
r8forge_derive <file.r8asm> -1 0=100 1=50 # 指定 cell 初值跑一遍,打印 out
|
||
r8forge_derive <file.r8asm> -2 0=100 # 同上,另外倒出所有非零 cell
|
||
```
|
||
|
||
注意 `-1/-2` 是拿**汇编源码**跑的(内部会先 `import_file`),不能直接喂 `.rot8` 纸带。
|
||
`r8forge_tape_run <file.rot8> [addr=value...]` 是第二个实现,直接喂纸带,用来交叉验证
|
||
`derive`(两个实现同时写错的可能性比一个低)。
|
||
|
||
## 指令集语义(这些搞错会浪费一整轮)
|
||
|
||
```
|
||
'-' flb 翻转最低位 cells[dp] ^= 1
|
||
'+' ror 右旋整个 cell
|
||
'[' biz 最低位为 0 -> 跳到匹配的 ']' 之后
|
||
']' rnz 最低位为 1 -> 跳回匹配的 '['
|
||
```
|
||
|
||
**最后两条的关键在"最低位"三个字**:`biz`/`rnz` 判的是 `cell & 1`,不是"整格是否为零"。
|
||
权威实现是 `ROT-8-viz/src/rot8.c`:
|
||
|
||
```c
|
||
void rot8_biz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 0) { ... } }
|
||
void rot8_rnz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 1) { ... } }
|
||
```
|
||
|
||
由此推出两条**关键约束**:
|
||
|
||
1. **`set_0` = `[-]` 清的是最低位,不是整个 cell。**
|
||
`set_0` 把 255 变成 254、把 128 原样留着、把 5 变成 4。要清整个字节就
|
||
`%rep _CELL_SIZE { set_0; ror }`(`erase` 就是这么写的)。一个字节的位能读:
|
||
`ror` 若干次把目标位转到最低位,再 `biz`。
|
||
2. **合成的程序只碰每个 cell 的低 K 位**(K = 参与运算的输入位数),高位不追踪。
|
||
所以 `%synth` 出来的块只适用于"每格一位"的世界。
|
||
|
||
**写手写宏还有第三条**:`dp` 是**汇编期**算的常量,而 `[...]` 的 body 在运行期可能被跳过。
|
||
所以**每个条件块的身体必须回到它自己的条件 cell**(净位移 0),否则跳过路径和进入路径的
|
||
`dp` 会不一致,之后所有 `.tp` 全部错位 —— 症状是 `dp` 跑到 1023 这种地方(
|
||
`r8forge_tape_run --trace` 能直接看到)。库里的宏都遵守:`set_0` 的身体不移动、`clb_bit_mov`
|
||
的身体最后 `.tp before` 再 `flb`(顺便把条件吃掉)。
|
||
|
||
曾经这里还写过第三条("多字节 cell 的位读不出来")—— 那是把 `biz` 当成 Brainfuck 的
|
||
整格零判断推出来的,**错的**,已删。
|
||
|
||
## cell_size 与纸带长度是怎么用的
|
||
|
||
位宽叫 **`cell_size`**(一个 cell 多少 bit),纸带长度叫 `kDefaultMemoryCells`;
|
||
搜索器里"有多少个 CellBit 形参"叫 **`cell_argc`**(`r8veritas<cell_argc>`)。这三个名字
|
||
在两边的仓库里是统一的:C/C++ 侧 `cell_size`、搜索器侧 `cell_argc`、`.r8asm` 程序里看到的
|
||
常量仍是 `_CELL_SIZE`(那是源语言的常量,属于宏库的公开词汇,不要跟着改)。
|
||
|
||
两个默认值集中在 **`include/r8forge/geometry.hh`**,现在是 **11 位 / 259 格**:
|
||
|
||
```cpp
|
||
inline constexpr size_t kDefaultCellSize = 11;
|
||
inline constexpr size_t kDefaultMemoryCells = 259;
|
||
inline constexpr uint32_t kDefaultCellMask = (1u << kDefaultCellSize) - 1u;
|
||
```
|
||
|
||
位宽和长度**都不在指令集里**(`ROR` 只是在一个 cell 里转圈,纸带是环),所以它们只以
|
||
"参数 + 常量"的形式存在,落在三处。改位宽时照这个清单走:
|
||
|
||
1. **汇编器**:`import_file(path, cell_size)` 的第二个参数就是位宽,6 个调用点都传
|
||
`kDefaultCellSize`。`set_cell_size` 顺手把三个名字注入程序作用域:
|
||
`_CELL_SIZE`(位宽)、`_CELL_MAX = (1 << 位宽) - 1`、`_ROL_STEP = 位宽 - 1`。
|
||
宏里写 `%rep _CELL_SIZE { … }` 就自动跟着位宽走(`erase`、`rol`、所有字节级驱动都这么写),
|
||
所以**位级宏、`%synth` 切片、位运算天然与位宽无关** —— 实测 `r8forge_synth_test` 在
|
||
11 位下照样 8/8 全过。
|
||
2. **四份虚拟机**(`tests/synth_test.cc`、`tests/byte_op_test.cc`、`src/derive.cc`、
|
||
`tests/tape_run.cc`):cell 存 `uint16_t`、数组长 `kDefaultMemoryCells`、
|
||
旋转必须是 `(v >> 1) | ((v & 1) << (kDefaultCellSize - 1))`、输入输出掩码用
|
||
`kDefaultCellMask`。**四份要一起改**,少改一份就会出现"两个实现不一致"的假象。
|
||
3. **测试期望**:一律用 `kCellMask` / `kCellSize` 写,不要出现 `0xff`、`>> 8`、`256 - a`。
|
||
**注意 2048 % 256 == 0**,所以不少 8 位期望在 11 位下碰巧还成立(and/or/xor/not/dec/sub
|
||
就是),别把"没报错"当成"不用改" —— `neg`、`add`、`inc`、`mul` 一改位宽当场就错。
|
||
|
||
踩过的坑:
|
||
|
||
* **`.xor` 的常数按当前位宽解释**。`asm/test.r8asm` 原来写 `.xor (~126)+1` 想置 130,
|
||
11 位下变成 `2048-126 = 1922`;改成直接写 `.xor 130`。
|
||
* **纸带会变长**:`%rep _CELL_SIZE` 从 8 轮变 11 轮,`raw_add` 1647 → **2199** 字符,
|
||
`fibonacci` 8761 → **11959**。写死的长度断言要跟着改。
|
||
* **`output` 打印整个 cell 的值**,不再是一个字节;`out` 里出现 257、1088 这种数是对的
|
||
(`127+130 = 257`、`200*200 = 19*2048 + 1088`)。
|
||
* **交叉验证要先对齐几何**:几何一致时同一条纸带输出完全相同(`asm/test.r8asm` 两边都是
|
||
`1322 1786 1600 5 94 127`);不一致时不是谁错了,是两台不同的机器。workspace 里的
|
||
`ROT-8-viz/` 是 upstream `starcells/ROT-8` 的 fork(`origin` = `dsh/ROT-8-viz`,`main`),
|
||
默认 **11 位 x 259 格**,几何还能运行期改(`--cell` / `--mem`;默认值与字段在
|
||
`include/rot8/rot8.h`,名字就是 `cell_size` / `mem_size`)。对答案的办法:
|
||
`ROT-8-viz/build/Release/rot8_test.exe <tape.rot8>` 把每个 `OUT` 按行打出来,
|
||
和 `r8forge_derive <src.r8asm> -1` 的 `out` 逐位比即可。
|
||
* 位宽变大还有个正面效果:`fibonacci` 不再在 256 处回绕,现在跑出 **13 项**(到 233)。
|
||
* **旧 tape 换到新位宽上不只是算错,还可能永远跑不完**:按 8 位写死的程序里
|
||
`%rep 8` 只转了 8 圈,在 11 位下 cell 没转回原位,"循环到某位清零"的条件于是永远不成立。
|
||
实测把改默认值之前的 `test.r8asm` 纸带喂给 11 位的 `rot8_test --dump`,它会一直跑
|
||
(ROT-8-viz 的普通/`--dump` 模式没有步数上限)。**换位宽就重新汇编,别复用旧纸带。**
|
||
|
||
## 字节级运算(一个 cell 一个机器字,默认 11 位)
|
||
|
||
结论:**库里的字节级宏是对的,穷举全过**。`r8forge_byte_op_test` 实测(这台机器约 10 秒;
|
||
2026-11 把 `clb_divmod` 扩到 16384 组、`clb_digits` 扩到全部 2048 个值之后)。
|
||
下面的纸带长度都是 **11 位 cell** 下的值(8 位时代的数字见 git 历史):
|
||
|
||
| 宏 | 驱动 | 纸带 | 结果 |
|
||
|---|---|---|---|
|
||
| `raw_add`(a+b,含进位) | `drv/raw_add_byte.r8asm` | 2199 字符 | **65536/65536** |
|
||
| `raw_and` | `drv/raw_and_byte.r8asm` | 870 字符 | **65536/65536** |
|
||
| `raw_or` | `drv/raw_or_byte.r8asm` | 782 字符 | **65536/65536** |
|
||
| `raw_xor` | `drv/raw_xor_byte.r8asm` | 628 字符 | **65536/65536** |
|
||
| `raw_inc`(a+进位) | `drv/raw_inc_byte.r8asm` | 1619 字符 | **512/512** |
|
||
| **`clb_add_nc`(a+b+进位,4 cell)** | `drv/raw_add_nc_byte.r8asm` | **937 字符** | **65536/65536** |
|
||
| **`clb_inc_nc`(a+进位,3 cell)** | `drv/raw_inc_nc_byte.r8asm` | **586 字符** | **256/256** |
|
||
| **`clb_neg_nc`(~a+进位,3 cell)** | `drv/raw_neg_nc_byte.r8asm` | **610 字符** | **256/256**(取负) |
|
||
| 同上,进位 0 | `drv/raw_not_nc_byte.r8asm` | **609 字符** | **256/256**(反码 `~a`) |
|
||
| **`clb_sub_nc`(a-b,4 cell)** | `drv/raw_sub_nc_byte.r8asm` | **962 字符** | **65536/65536** |
|
||
| **`clb_not_ip`(~a,原地,1 cell)** | `drv/not_ip_byte.r8asm` | **23 字符** | **256/256** |
|
||
| **`clb_inc_ip`(a+1,原地,2 cell)** | `drv/inc_ip_byte.r8asm` | **89 字符** | **256/256** |
|
||
| **`clb_neg_ip`(-a,原地,2 cell)** | `drv/neg_ip_byte.r8asm` | **111 字符** | **256/256** |
|
||
| **`clb_dec_ip`(a-1,原地,2 cell)** | `drv/dec_ip_byte.r8asm` | **133 字符** | **256/256** |
|
||
| **`clb_nonzero`(a!=0 的标志,原地)** | `drv/nonzero_byte.r8asm` | **284 字符** | **256/256** |
|
||
| **`clb_add_ip`(a+=b,原地,4 cell)** | `drv/add_ip_byte.r8asm` | **726 字符** | **2048 抽样全过**(O(b) 运行) |
|
||
| **`clb_mul`(mc×mul → 两 cell 积,10 cell)** | `drv/mul_byte.r8asm` | **3977 字符** | **65536/65536**(O(位宽) 运行) |
|
||
| **`clb_ones`(数量 → 从末位起 N 个 1,4 cell)** | `drv/ones.r8asm` | **742 字符**(带 output)/ **828**(最小驱动) | **12 个计数全对**(N=0..11) |
|
||
| **`clb_divmod`(N div D / N mod D,11 cell)** | `drv/divmod.r8asm` | **4499 字符**(最小驱动)/ 4511(带 output) | **16384 组全对**(8 个除数 × 全部 2048 个被除数;固定 11 轮,最坏 32,383 步,`2047/1` 不再挂) |
|
||
| **`clb_digits`(整数 → 4 位 ASCII 十进制,18 cell)** | `drv/digits.r8asm` | **13717 字符**(最小驱动)/ 13741(带 output) | **全部 2048 个值全对**(最坏 164,867 步;2047 是 14.5 万步) |
|
||
| **`raw_sub`(A-B,**保留 A、B**,Bo = 没借位,7 cell)** | `drv/raw_sub.r8asm` | **≈2900 字符** | **9 组抽样全对**;长除法要用它(`clb_sub_nc` 会把操作数吃掉) |
|
||
| `asm/fibonacci.r8asm` | — | 11959 字符 | 跑出 13 项 `1 1 2 3 5 8 13 21 34 55 89 144 233` |
|
||
|
||
`raw_*` 保留操作数(A、B 原样还回来),`clb_*_nc` 把 A、B 吃干净 —— 所以后者能省掉
|
||
`Co` 和 `tmp`:**4 cell 加法/减法、3 cell 自增/取负**。两者都用轮转驱动,差别只在
|
||
"操作数要不要还回去"。
|
||
|
||
**`clb_*_nc` 的进位 cell 是真正的进位输入**:宏自己**不动**它的初值(曾经写错过 ——
|
||
加法里 `set_0`、自增里 `set_1`,那就不是输入了,而且把多字节串接堵死了)。
|
||
调用者给 0 就是普通运算,给 1 就是"自带 +1"的那种,或者把上一字节的进位输出接过来串。
|
||
|
||
### 补码
|
||
|
||
`-A = ~A + 1`、`A - B = A + ~B + 1`,所以取负/减法都是"取反 + 加法/自增",
|
||
那个 +1 由调用者通过进位输入给:
|
||
|
||
| 宏 | 做法 | Ci=1 | Ci=0 |
|
||
|---|---|---|---|
|
||
| `clb_neg_nc A S Ci` | 先 `clb_not_ip A` 把整个字节原地取反,再走 `clb_inc_nc` | `-A`(补码取负) | `~A`(反码) |
|
||
| `clb_sub_nc A B S Ci` | 先 `clb_not_ip B` 把整个字节原地取反,再走 `clb_add_nc` | `A - B` | `A - B - 1` |
|
||
|
||
**取调整字节一次、提到循环外面**,比"每 bit 取反一次"更短(也少两个 `flb` 包装):
|
||
8 位时代是 468 → 448、467 → 447、725 → 707;11 位下的实测值见上表(610 / 609 / 962)。
|
||
B 本来就会被加法吃掉,所以在原地取反它没有任何代价。
|
||
|
||
`clb_sub_nc` 的进位输出是**没有借位**(`A >= B` 时为 1),所以它顺带就是无符号比较;
|
||
`clb_neg_nc` 的进位输出只在 `A` 原本是 0 时为 1(`-0 = 0` 但确实进了位)。
|
||
|
||
取反必须发生在切片**外面**:想让 `%synth` 自己取反(表 `S=~A^Ci`、进位 `~A&Ci`,3 参数)
|
||
报 `no program up to 8 layers`。原因是模型只会"牺牲一个 cell → 条件翻转别的 cell",
|
||
A=0 时整块跳过、S 只能留在 0,而取反要求 A=0 时 S=1 —— "无条件翻转"表达不出来。
|
||
|
||
### 原地(结果回到原来的 cell)
|
||
|
||
| 宏 | 干什么 | cell | 纸带(11 位) | 穷举 |
|
||
|---|---|---|---|---|
|
||
| `clb_not_ip A` | `A = ~A`(反码) | 1 | **23** | 256/256 |
|
||
| `clb_inc_ip A T` | `A = A + 1` | 2 | **89** | 256/256 |
|
||
| `clb_neg_ip A T` | `A = -A`(补码取负) | 2 | **111** | 256/256 |
|
||
| `clb_dec_ip A T` | `A = A - 1` | 2 | **133** | 256/256 |
|
||
| `clb_nonzero B F T` | `F = (B != 0)`,B 不动 | 3 | **284** | 256/256 |
|
||
| `clb_add_ip A B T F` | `A += B`,B 被吃掉 | 4 | **726** | 2048 抽样 |
|
||
|
||
对比写回 S 的切片版:`clb_inc_nc` 586(3 cell)、`clb_neg_nc` 610(3 cell)——
|
||
**原地版短 5 倍、少一个 cell**。`clb_neg_ip` 就是 `clb_not_ip` + `clb_inc_ip`。
|
||
|
||
**"原地补码不可能"这个结论是错的,这里记一下它是怎么错的**(别再复现同样的推理):
|
||
|
||
* `%synth` 的四个原地表(`A←~A^Ci`、`A←A^Ci`、`A←A^B^Ci`、`A←A^~B^Ci`)确实全部报
|
||
`no program up to 8 layers`,原因是**一个合成块只有一个条件 cell**,区分不了
|
||
"A=1 且 Ci=0" 和 "A=1 且 Ci=1"。这一步是实测,没问题。
|
||
* 错在把它当成了整条路的结论。手写**不一定要照逐位进位链写**。
|
||
|
||
真正可行的算法换个思路,不去逐位测进位:
|
||
|
||
1. 用 `[ ... ]` 的自然语义(最低位非零就继续)把**最低位连续的 1 清掉**(`flb` + `ror`),
|
||
遇到第一个 0 时退出循环;
|
||
2. 那个 0 翻成 1 —— 输入是全 1(0xFF)时跳过,正好就是回绕那一格;
|
||
3. 剩下的位置只旋转,转满八格为止。
|
||
|
||
卡点变成"还要转几格",而 cell 只有两个。解法是**把计数塞进 T 的位里**:T 先做成 0xFF,
|
||
每转一格就 `set_0` + `ror` 消掉一个 1 —— 一串 1 的长度就是剩余圈数(每步 3 字符的移位寄存器
|
||
计数器,一圈正好数八格)。于是两个 cell 够用,而且比切片版短得多。
|
||
|
||
顺带纠正另一半:`[ ... ]` 的"跑了就必然消耗被测位"不是死路 —— 只要被测的是**计数器**,
|
||
不是数据。这条以前被写成"手写也做不到(2 cell)",错的。
|
||
|
||
原地取反仍然是最便宜的一个:`%rep _CELL_SIZE { flb; ror }`,一个 cell、23 字符。
|
||
自减用补码恒等式拼出来,不用新算法:`B - 1 = ~(-B)`,所以 `clb_dec_ip` = `clb_neg_ip` + `clb_not_ip`(133 字符)。
|
||
|
||
### 原地加法,以及"只有纸带长度是目标"这条
|
||
|
||
`clb_add_ip A B T F`:`A += B`,原地,4 个 cell(A、B、T、F),**726 字符**,
|
||
B 被吃干净。对比:`raw_add` 2199(6 cell,保留操作数)、`clb_add_nc` 937 + 每轮一次 `copy`。
|
||
|
||
**没有去写逐位的进位链加法**:全加器的进位是 `maj(a,b,c)`,也就是两两的合取,而每个条件测试
|
||
都会吃掉被测的那一位,所以要么先拷贝好几份位、要么嵌套测试 —— 又长又脆。
|
||
|
||
改成利用一件在本仓库里成立的事:**只有纸带长度是目标,运行步数不是**。
|
||
|
||
while B != 0: A += 1 ; B -= 1
|
||
|
||
循环体在纸带里只出现一次,所以长度和 B 的大小无关;代价是运行 O(B)(B=255 时约 30 万步,
|
||
`r8forge` 的上限是 500 万)。**这个取舍在别处也能用** —— 凡是"长度优先"的地方都可以想
|
||
"能不能用循环把代码压掉"。
|
||
|
||
剩下的难点是"B != 0"怎么测(`biz` 只测最低位)。`clb_nonzero B F T` 的做法:每位先把它
|
||
搬进工作位 T(这一步清掉 B 的那一位),若 T 是 1 就把 F **置一**并还原 B 的那一位,
|
||
转一格看下一位;八轮后 B 原样、F = (B != 0)。注意是 `set_1` 不是 `flb` —— 这里踩过:
|
||
`flb` 是翻转,偶数个 1 位会把标志翻回 0(3、5、255 都测错过)。
|
||
|
||
### 乘法器(`asm/mul.r8asm`)
|
||
|
||
`clb_mul MC MUL PL PH MCA S Ci T F NR`:`(PH:PL) = MC * MUL`,10 个 cell,**3977 字符**,
|
||
`r8forge_byte_op_test` 现在**穷举 65536 组**(0..255 × 0..255)全对,最坏运行 **26123 步**
|
||
(`2047 * 2047`,11 位下的整个域)。
|
||
|
||
用的是**二进制移位-加法**(竖式乘法),一位一位串:
|
||
|
||
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,最低位(刚看的那位)丢掉
|
||
|
||
W 轮之后 `(PH:PL)` 就是积;`PL`(原来的 Q)被移空,所以 **MUL 结束为 0**,和原来的约定一样。
|
||
|
||
**为什么换掉重复加法**:重复加法的轮数 = `MUL` 的值,成本 ∝ MUL。`MUL = 2047` 时实测直接
|
||
`HANG after 5000000 steps`——也就是大乘数根本算不完。移位-加法的轮数 = 位宽,**跟操作数的
|
||
值无关**,11 位下封顶 26123 步:
|
||
|
||
| 算式 | 重复加法(旧) | 移位-加法(现在) |
|
||
|---|---|---|
|
||
| `82 * 141`(MC=82, MUL=141) | 358586 步 | **8374 步** |
|
||
| `82 * 141`(MC=141, MUL=82) | 214741 步 | **6974 步** |
|
||
| `255 * 255` | 733428 步 | **17785 步** |
|
||
| `100 * 403` | 1026648 步 | **10208 步** |
|
||
| `2047 * 2047` | **HANG**(>500 万步) | **26123 步** |
|
||
| `2047 * 0` | 270 步 | 1863 步 |
|
||
|
||
纸带同时短了:**5007 → 3977 字符**。代价只有一条:乘数是 0/1 这种小值时反而慢一点点
|
||
(旧版循环 0/1 次就完了,新版固定要转满 `_CELL_SIZE` 轮)——拿它换「乘数再大也不会挂」。
|
||
所以 `asm/test.r8asm` 里那条"永远把小操作数放 MUL"的规矩**已经没用了**(保留 141 只是
|
||
为了跟历史结果对得上)。
|
||
|
||
拼法上踩过两个坑:
|
||
|
||
* **跨格移位**:`(C:PH:PL) >>= 1` 得当成一个 2W+1 位的寄存器来移。做法是三格先各 `ror`
|
||
一格,把要注入的那一位搬到 bit0(`rol` 回来),用 `clb_bit_mov` 搬过去,再 `ror` 回去。
|
||
顺序必须是**低位那对先搬**(PH→PL 先做),否则 PH 的 bit0 已经被 F 覆盖了。
|
||
* **`biz`/`rnz` 是循环对,不是 if/else**:条件块的身体必须把被测位吃掉(最后一条 `flb`),
|
||
否则 `rnz` 看到还是 1 就跳回去 —— 第一版就是这么写成死循环的(现象:`out` 一个都没有、
|
||
计数器停在 0x7ff 没动)。被测的正好是 `PL` 的最低位,而它本来就要被右移丢掉,吃掉它
|
||
不影响移位。`set_0` / `clb_bit_mov` 身体里那个 `flb` 是同一个道理。
|
||
|
||
轮数用什么数:计数器 `NR` 先做成 `_CELL_SIZE` 个 1(`%rep _CELL_SIZE { set_1; ror }`),
|
||
每轮 `set_0` + `ror` 吃掉一个 —— 和 `clb_inc_ip` 数圈数是同一个法子。一串 1 的长度就是
|
||
剩余轮数,所以"做几轮"不占纸带长度,只占运行时间。
|
||
|
||
**设计上的教训(这一版)**:上一轮把"移位-加法"否掉了,理由是「只有纸带长度是目标」——
|
||
可那只说明**当时**的取舍,而且结论其实反了:移位-加法不但更短(3977 < 5007),
|
||
步数还少一到两个数量级。真正的原因不是它更长,而是把"跨格移位 + 条件累加"想复杂了 ——
|
||
`rol`/`ror` 加一条 `clb_bit_mov` 就能拼,三行的事。
|
||
**先看目标函数再选算法**这条本身没错,但目标函数里得把「500 万步上限」写进去:
|
||
长度优先的循环写法(`clb_add_ip`、旧的 `clb_mul`)在纸带上不吃亏,运行时间上会随值线性长大。
|
||
|
||
|
||
顺带纠正一个流传下来的说法:`raw_add` **不**吃掉操作数。实测 `5+3 → A=5 B=3 S=8`,
|
||
`255+255 → A=255 B=255 S=254 Co=1`。`asm/fibonacci.r8asm` 里"每圈都要重新复印"的注释
|
||
是过度保守(它确实复印了,但不复印也对)。
|
||
|
||
### 这次差点被写进文档的错误诊断(别再犯)
|
||
|
||
有一轮里,`raw_add` / `raw_and` / `copy` / `fibonacci` 全被判定"运行时是坏的",
|
||
理由是 `set_0` 对多字节 cell 不收敛、纸带跑到步数上限。**那是虚拟机写错了**:
|
||
仓库里有三份解释器(`tests/synth_test.cc`、`src/derive.cc`、`tests/tape_run.cc`)
|
||
把 `biz`/`rnz` 实现成了"整格是否为零"(Brainfuck 直觉),于是每个字节级程序
|
||
都变成死循环。改回 `& 1` 之后全部通过。
|
||
|
||
为什么之前没被发现:位级程序在两种语义下行为完全一样(0/1 的最低位就是它自己),
|
||
`%synth` 的表、`asm/test.r8asm`、`full_add` 全都不受影响;只有字节级驱动能区分。
|
||
**所以以后凡是"字节级看起来跑不动",第一个怀疑对象是虚拟机,不是库。**
|
||
|
||
验证方法:拿 `ROT-8-viz/build/rot8_test.exe` 跑同一条纸带对答案。
|
||
`tests/tape_run.cc` 现在是正确语义(`& 1`),可以直接对。
|
||
|
||
### 另一位一 cell 的实现在这里被删过一次(别再加回来)
|
||
|
||
"每个 bit 一个 cell、用 `clb_bit_add_nc` 串成 8 位加法器"这条路能跑通(32 cell,
|
||
1308 字符,65536 组合全对),但它是上面那个错误诊断的产物:既然一个 cell 能放一个字节、
|
||
位读得出来,就没必要为每个 bit 花一个 cell。R8Forge 之前也删过一次同样的东西
|
||
(交接文档原话:"8 位加法 25 个 cell,没有实用价值")。
|
||
**要拼字节级运算就用 `raw_*` / `clb_*_nc` / `clb_*_ip`。**
|
||
|
||
## %synth 相关
|
||
|
||
* 语法:`params N` + `mode tape|layers` + `layout ...`(可选,只在 `--synth-chars` 下有用)
|
||
+ 目标表 `stat ...` 或 `map ...`。`stat` 的项数必须是 `2^params`(3 参数要 8 项)。
|
||
参数是输入位 `%1..%K`、输出位、剩余草稿位(草稿位必须结束为 0,语义见 `compress_stat_space`)。
|
||
* **代价口径是隐式的**(源码里没有 `metric` 行了,写了会报错):默认 flat —— 不计 `.tp`
|
||
行走、结果与 cell 布局无关、缓存可跨调用点复用;`r8forge --synth-chars <file>` 才对这次
|
||
汇编里的**所有**块按真实布局算(`r8asm::set_synth_metric(0)`,CLI 在 `tests/asm_test.cc`)。
|
||
full_add 上两个口径分别是 95 / 90 字符。`metric blocks` 已删(块数不是纸带长度的好代理)。
|
||
* 缓存:`.r8forge_cache/`(**已入库**,克隆下来直接命中)。键 = 模型版本 + params + mode +
|
||
metric + **解析后的整张目标表**(+ layout,仅 chars)。改指令模型时要 bump
|
||
`kModelVersion`(`src/synth.cc`)。
|
||
* 缓存代价参考:`bit_raw_add` 的 flat 搜索 990,636,137 状态 / 680 秒 / ~22 GB 内存。
|
||
层数上限现在是 8(原来是 5,5 会把一些可行的表误判成不可能)。
|
||
|
||
## 已经验证可行的东西
|
||
|
||
| 东西 | 结论 |
|
||
|---|---|
|
||
| 库里的 7 个位运算块(and/or/xor/inc/add) | 合成版比手写短(8 位时代 1714 → 1666;位宽改了以后位级块不受影响,长度变的是字节级那层) |
|
||
| `asm/test.r8asm` 现在是一个 hash | 11 位下 **28729 字符**,`h = (h + c) * 141 mod 2048` 滚过 "R8F",跑出 `1322 1786 1600 5 94 127`(前三 = 三轮的 h,后三 = 三轮的 PH,即 `(h+c)*141 >> 11`)。只用 `clb_add_nc` + `clb_mul`,没有位运算 —— "会加减乘就能算 hash"的最小证明。`derive` 与 ROT-8-viz 两边逐位一致,**57330 步**(乘法器换成移位-加法之后,原来约 207 万步) |
|
||
| `clb_bit_add_nc`(4 cell 忽略进位切片) | flat 代价 **27**,完整全加器切片是 38;8/8 组合正确(与位宽无关) |
|
||
| `clb_bit_inc_nc`(3 cell 自增切片) | 表 `0 4 4 2 0 4 4 2`(3 参数)缓存里就有,4 blocks;4/4 组合正确(与位宽无关) |
|
||
| `clb_add_nc`(4 cell 加法) | 11 位下 937 字符,65536 组合全对;比 6 cell 的 `raw_add` 少 2 个 cell |
|
||
| `clb_inc_nc`(3 cell 自增/加 0-1) | 586 字符,256 组合全对;比 5 cell 的 `raw_inc` 少 2 个 cell |
|
||
| `clb_neg_nc`(3 cell 取负/取反) | 610 / 609 字符,各 256 组合全对(Ci=1 取负、Ci=0 反码) |
|
||
| `clb_sub_nc`(4 cell 减法) | 962 字符,65536 组合全对;进位输出顺带是无符号比较(A >= B) |
|
||
| `clb_not_ip`(1 cell 原地取反) | **23 字符**,256 组合全对 |
|
||
| `clb_inc_ip`(2 cell 原地自增) | **89 字符**,256 组合全对;切片版 `clb_inc_nc` 是 586 |
|
||
| `clb_neg_ip`(2 cell 原地取负) | **111 字符**,256 组合全对;切片版 `clb_neg_nc` 是 610 |
|
||
| `clb_dec_ip`(2 cell 原地自减) | **133 字符** = `neg` + `not`(`B-1 = ~(-B)`),256 全对 |
|
||
| `clb_nonzero`(非零标志) | **284 字符**,256 全对,B 保持原样 |
|
||
| `clb_add_ip`(4 cell 原地加) | **726 字符**,2048 抽样全对;`raw_add` 2199 |
|
||
| `clb_mul`(10 cell 乘法,积占两个 cell) | **3977 字符**,65536 组穷举全对;轮数只跟位宽有关(最坏 26123 步),跟 MUL 的值无关 |
|
||
| `clb_ones`(4 cell,数量 → 从末位起 N 个 1) | **828 字符**(最小驱动),N=0..11 全对;`rol` + `set_1` 就是 `B = 2B + 1`,A 当计数器吃干净 |
|
||
| `clb_ones` + `loop`/`endloop` | **动态循环**:次数由运行期数据决定。`verify_loop.r8asm` **939 字符**,N=0..11 正好跑 N 次(A=N、C=0,N=0 一圈不跑);嵌套也对(NO×MI,11×11=121)。见 SPEC §5.1 |
|
||
| `bit_raw_add`(6 cell 全加器切片) | 保留 A、B;字节级 `raw_add` 2199 字符,65536 组合全对 |
|
||
| `raw_and` / `raw_or` / `raw_xor` / `raw_inc` | 870 / 782 / 628 / 1619 字符,各 65536(inc 512)全对 |
|
||
| `asm/fibonacci.r8asm` | 11959 字符,跑出 13 项(`… 89 144 233`),比 8 位时代多 3 项 |
|
||
| `examples/` 里的例程 | **每组宏一份**,9 个程序(§10.3 的表)+ 4 个 `%synth` 例子。每个都是能跑的程序,头部 `; out ...` 是它打印什么;`r8forge_examples_test` 全部跑一遍逐项核对(缺那行也算失败),顺带打印纸带长度和步数 |
|
||
|
||
## 已经确认走不通的(别重试)
|
||
|
||
* **3 个 cell 做加法切片**:层数上限 5 和 8 都报 `no program up to N layers`
|
||
(3 cell 的**自增/取负**切片是有解的,两个操作数塞不进 3 个 cell)。
|
||
* **原地写回的 `%synth` 表**:`A←~A^Ci`、`A←A^Ci`、`A←A^B^Ci`、`A←A^~B^Ci` 四个表全部报
|
||
`no program up to 8 layers`。原因是一个合成块只有一个条件 cell,区分不了 "A=1 且 Ci=0"
|
||
和 "A=1 且 Ci=1"。**但手写可以**:换成"清连续 1 + 计数器旋转"的算法,2 cell 就够
|
||
(`clb_inc_ip` 89 字符、`clb_neg_ip` 111 字符,见「原地」)。别把这条读成"手写也不行"。
|
||
* **让切片自己在输入上取反**(表 `S=~A^Ci`、进位 `~A&Ci`,3 参数):`no program up to 8 layers`。
|
||
模型只会"牺牲一个 cell → 条件翻转别的 cell",输入为 0 时整块被跳过、S 只能保持 0,
|
||
表达不出"无条件翻转"。取反只能放在切片外面(一条 `flb`)。
|
||
* **4 cell 的加法切片要做到"保留 A、B"**:表改成保留 A、B 后报 `no program up to 8 layers`。
|
||
想拿回操作数只能用 6 cell 的 `bit_raw_add`。
|
||
**但这不等于"轮转需要保留操作数"** —— 这句以前写错过。轮转只是
|
||
"读走最低位 → 丢掉 → `ror`",吃掉操作数完全没问题:`clb_add_nc`(4 cell)就是这么跑的,
|
||
65536 组合全过。
|
||
* 字节级(2^16 项真值表)交给 `%synth`:搜索空间不可行。
|
||
* **删掉位级包装宏里的 `set_0`**(想法是"`%synth` 的 `stat` 已经把初值算进去了,
|
||
输出位不用先清"):**错的**。`stat` 表对输出位的初值是周期的(旧实现先清再算),
|
||
而 `compress_stat_space()` 把"初值不影响终值"的位从搜索初态里清成 0 —— 搜出来的块
|
||
只保证**初值为 0** 的调用点。2026-11 实测删掉 9 处 `set_0`:`raw_add`/`raw_and`/
|
||
`raw_or`/`raw_xor` 照样全过(轮转驱动每轮把结果写在 bit0 上就转走,输出位的 LSB
|
||
一直是 0),但 `clb_mul` 62064/65536 错、`clb_divmod` 14742/16384 错、
|
||
`clb_digits` 2048/2048 错(其中一个 HANG)。见 SPEC §3.6。
|
||
|
||
## 命名与注释格式(照 `SPEC.md`,别自己发明)
|
||
|
||
规格分两份:
|
||
|
||
* **本仓库的 `SPEC.md`**:`%synth` 指令、机器几何、**`asm/` 里每个宏的契约**
|
||
(签名 / 参数类型 / 吃什么留什么 / cell 数 / 纸带长度 / 由哪个测试验证)、
|
||
纸带长度的测量口径。加宏、改宏、写文档之前先看它。
|
||
* **上游语言规格**:`C:\Users\peng0\git\r8asm_rev-fork\SPEC.md`(`r8asm_rev` 里那份一模一样)。
|
||
语言、内建指令、运算符优先级、作用域、标准宏前缀都在里面。`%synth` 不在里面 ——
|
||
那是 R8Forge 自己的扩展,看本仓库的 `SPEC.md`。
|
||
* **ROT-8 指令集规格**:`C:\Users\peng0\git\ROT-8-viz\README.md`("1-Bit Brainfuck 变体",
|
||
指令表里写明 `BIZ`/`RNZ` 判 **LSB**)。
|
||
|
||
SPEC 第 136-150 行的标准宏前缀:
|
||
|
||
| 前缀 | 全称 | 含义 |
|
||
|---|---|---|
|
||
| `clb` | clobber | 破坏性宏,会破坏原始输入(多数情况是清零) |
|
||
| `bit` | bit | 对 cell 的 **LSB** 操作的宏 |
|
||
| `raw` | raw | 未经封装的宏,**通常要手动传入 tmp cell 作为实参** |
|
||
|
||
**`raw` 不是"暴露 cell 作为参数"**(这条以前写错过):`raw_add` 之所以叫 raw,
|
||
是因为它要你自己给 `Co` 和 `tmp` 那两个草稿 cell。`bit` 则说明所有 `CellBit` 形参
|
||
指的都是最低位 —— 这跟 `biz`/`rnz` 判 `& 1` 是同一件事:整套语言是围绕"1 位"设计的。
|
||
|
||
既有宏对号入座:
|
||
|
||
| 宏 | 为什么这么叫 |
|
||
|---|---|
|
||
| `raw_add` / `raw_and` / `raw_or` / `raw_xor` / `raw_inc` | 字节级,且草稿 cell 由调用者传 |
|
||
| `bit_raw_add`(6 cell) | 位级,且 `%6: buf` 是真正的草稿:内容无关,结束是垃圾 |
|
||
| `clb_bit_add_nc`(4 cell) | 四个 cell 都有意义,没有草稿 cell(所以没 `raw`),而 A、B 被吃掉(所以有 `clb`):第 3 个是"进→出"的进位,`A=0 B=0 进位入=1` 时 `S=1` |
|
||
| `clb_bit_inc_nc`(3 cell) | 同样:A 被吃掉,进位进→出,没有草稿 cell |
|
||
| `clb_add_nc`(4 cell)/ `clb_inc_nc`(3 cell) | 字节级版本,同样吃 A、B |
|
||
| `clb_neg_nc`(3 cell)/ `clb_sub_nc`(4 cell) | 补码取负/减法,同样吃 A(和 B) |
|
||
| `clb_not_ip` / `clb_inc_ip` / `clb_neg_ip` / `clb_dec_ip` / `clb_add_ip` | 同上再加 `_ip`(in place):结果回到原来的 cell,草稿 cell 由调用者传 |
|
||
| `clb_nonzero` | 破坏性的纯计算(把 B 抄成"非零"标志),不带 `_ip` 后缀 |
|
||
| `clb_ones` | 破坏性的纯计算(把"数量"展开成从末位起的一串 1,输入被吃干净);结果写在另一个 cell 里,所以也不带 `_ip` |
|
||
| `clb_divmod` | 破坏性的纯计算(除/取模,商 Q、余数 R 各落在自己的 cell 里,`S` 起 7 格草稿由调用者传);N、D 现在**保留**,`clb` 指的是 Q 和草稿块会被覆盖 |
|
||
| `clb_digits` | 破坏性的纯计算(整数 → 一串 ASCII 数字),输入被吃干净、结果写在连续区域里,所以不带 `_ip` |
|
||
| `loop` / `endloop` | 结构性的**宏对**(开/收一个运行时循环),不带前缀;不开 anchor 所以能嵌套,收口后 dp 停在计数器上 |
|
||
| `clb_bit_mov` | 位级搬运,并且把源吃掉 |
|
||
| `bit_copy` / `copy` | 位级/字节级拷贝,缓冲由调用者传(历史命名,少了 `raw`) |
|
||
| `set_0` / `set_1` / `erase` / `rol` / `step` / `back` / `output` | 基础操作,不带前缀 |
|
||
|
||
`%synth` 块名 = `<宏名>_synth`,包装的 `%macro` 用不带 `_synth` 的名字。
|
||
|
||
**后缀不是前缀**:`_nc` 是手写库留下的历史命名,`_ip` 是本仓库加的(in place,结果写回原来的
|
||
cell)。选名字时先按 SPEC 的三个前缀定位,再挑后缀。
|
||
|
||
宏里的注释:
|
||
|
||
```asm
|
||
; Macro clb_bit_add_nc
|
||
; %1: CellBit A
|
||
; %2: CellBit B
|
||
```
|
||
|
||
* `%this` 表示"dp 当前所指的 cell"(`set_0`、`clb_bit_mov` 都这么写)。
|
||
* 新宏先按上表选前缀。套不上的(块级、自己管草稿 cell 的)就在注释里写清吃什么、留下什么。
|
||
* **参数类型只用这五个**:`Cell`、`CellBit`、`Unit`、`UnitBit`、`Count`(纯数字,比如
|
||
`step` 的重复次数)。注释块贴在 `%macro` 上方,或者贴在生成它的 `%synth` 块上方,都行。
|
||
* `r8forge_macro_docs_test` 会检查 `asm/` 里每个 `%macro`:有没有注释块、
|
||
`; Macro <名字>` 和实际宏名是否一致、参数条数是否等于 argc、类型是否在上面这五个里。
|
||
加完新宏跑一下,别让它的输出从全绿变红。
|