diff --git a/AGENTS.md b/AGENTS.md index 970d678..b68e20f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,9 @@ PowerShell 的编码坑、git 身份和 push 提权、临时目录抽风…… * 汇编器 + 搜索器 + 标准库都齐了:`%synth` 汇编期合成、位级/字节级/原地/乘除/数字 转换(`clb_digits` ↔ `clb_undigits`)、动态循环、串行 ASCII I/O 都能跑。 +* **有符号数已经做完**(SPEC §5.4 的约定、§7.10 的实现):`clb_digits_signed`(`-0042` + 这种显示)、`clb_divmod_signed`(截断除法、余数随被除数)、计算器的一元负号 + (`examples/calc.r8asm`)。加、减、乘按二补码天然正确,没有改。 * 全绿基线(这台机器约 1 分钟;命令见下)。 * 另一个仓库 `../ROT-8-viz`(fork `dsh/ROT-8-viz`,分支 `main`)是权威虚拟机 + 可视化:**默认 I/O 是串行 ASCII**(cell ≥ 8 位),数值 I/O 用 `-n` / `--numbers`, @@ -29,12 +32,13 @@ cmake --build build --config Release # 注意:必须用给 build/ 配的那个 cmake(PATH 上的另一个版本会重新配置,然后死在 # "No preprocessor test for PellesC")。本机路径见 AGENTS.local.md。 -# 当前基线:都通过,别弄坏(`ctest --test-dir build -j 4` 一次跑完 8 条,约 9 秒) -r8forge asm/test.r8asm # 62513 字符(除 raw_puts_dyn 外每个宏一次 + 每个语言特性) -r8forge_byte_op_test # 21 项(divmod 16384 组、digits 2048、undigits 4096) -r8forge_examples_test # 18 个 example + asm/test.r8asm,核对头部 `; out`/`; in` -r8forge_macro_docs_test # 53 macros in 23 files -r8forge --opt asm/test.r8asm # 纸带窥孔优化 62513 -> 56350(>< 净位移、+ mod W、- mod 2) +# 当前基线:都通过,别弄坏(`ctest --test-dir build -C Release -j 4` 一次跑完 8 条,约 12 秒。 +# VS 是多配置生成器,**`-C Release` 不能省**,否则 8 条全报 "Not Run") +r8forge asm/test.r8asm # 62351 字符(除两个有符号包装宏外每个宏一次 + 每个语言特性) +r8forge_byte_op_test # 23 项(divmod 16384 组、digits 2048、digits_signed 2048、divmod_signed 4202、undigits 4096) +r8forge_examples_test # 19 个 example + asm/test.r8asm,核对头部 `; out`/`; in` +r8forge_macro_docs_test # 55 macros in 23 files +r8forge --opt asm/test.r8asm # 纸带窥孔优化 62351 -> 56338(>< 净位移、+ mod W、- mod 2) r8forge_tape_opt in.rot8 out.rot8 # 同一优化,但作用在已有纸带上 r8forge_tape_run t.rot8 --profile # 剖面:指针移动占 66~73% 步数(实测,见下) r8forge_synth_test examples/full_add.r8asm # all eight combinations ok @@ -42,8 +46,11 @@ r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0 powershell -File tests\widths.ps1 # 位宽矩阵:每个位宽一套工具链 + 断言(约 20 分钟) ``` -`asm/test.r8asm` 的纸带**必须留在 65536 条指令以下**(ROT-8-viz 的 `INS_SIZE`),所以里面 -只有"每个宏一次 + 两轮 hash",现在离上限只剩 ~3k。加东西前先算长度。 +`asm/test.r8asm` 的纸带**必须留在 65536 条指令以下**(ROT-8-viz 的 `INS_SIZE`;现在的 +虚拟机缓冲是按纸带长度现算的,这条是历史口径 + 交叉验证,别指望它)所以里面只有"每个宏 +一次 + 两轮 hash",现在离上限只剩 ~3.2k。**两个有符号包装宏不在里面**:它们各自要把 +`clb_digits` / `clb_divmod` 再展开一份(+12.1k / +5.6k)。它们的回归是 +`examples/signed_demo.r8asm`(`examples_test` 会跑),穷举在 `r8forge_byte_op_test`。 `r8forge_byte_op_test` 是**唯一按返回值判断字节级对错的**;其它自检只证明"汇编得出来"或 "位级正确"。`r8forge_derive` 会检查汇编错误(漏 `%include` 时纸带是截断的,以前不看 error @@ -69,7 +76,7 @@ powershell -File tests\widths.ps1 # 位宽矩阵:每个位宽一 * **交互程序这样测**:`r8forge_tape_run t.rot8 -i "12+34="`(字符喂给 `inp`,低 7 位,读空后为 0), `r8forge_derive 0 -i "..."` 是同一份输入的第二个实现;例程把输入写在头部 `; in ...`,`r8forge_examples_test` 会自动喂。实时终端那一侧在 ROT-8-viz(默认串行)。 -* **代价的大头是"走"不是"算"**:`tape_run --profile` 实测,计算器 71.1%、全家桶 73.0% 的步数是 `>`/`<`,旋转只占 7%、翻转 4~6%。这台机器没有随机寻址,每次访问的代价就是 `|Δ地址|`,所以**布局才是性能旋钮**:`clb_digits` 的 13 格草稿重排一轮,全家桶 64513 -> 62513 字符、236439 -> 206491 步(SPEC §7.7);`--opt` 再省 14~15% 步数,正是因为它砍的是往返移动。 +* **代价的大头是"走"不是"算"**:`tape_run --profile` 实测,计算器 71.1%、全家桶 73.0% 的步数是 `>`/`<`,旋转只占 7%、翻转 4~6%。这台机器没有随机寻址,每次访问的代价就是 `|Δ地址|`,所以**布局才是性能旋钮**:`clb_digits` 的 13 格草稿重排一轮,全家桶 64513 -> 62351 字符、236439 -> 202159 步(SPEC §7.7);`--opt` 再省 14~15% 步数,正是因为它砍的是往返移动。 * 一次会话很难把结论留在对话里 —— **落进 commit message 和文件注释**。 ## 一条硬规矩:不许动机器语义 @@ -118,17 +125,22 @@ powershell -File tests\widths.ps1 # 位宽矩阵:每个位宽一 * **字节级程序"跑不动"先怀疑虚拟机**:仓库里曾有三份解释器把 `biz` 写成整格零判断,于是 所有字节级程序看起来都在死循环 —— 别再把库判成坏的。 -## 下一件大事:有符号数 +## 刚做完的一件大事:有符号数 -约定已定(二补码、`-0042` 显示、截断除法、静默溢出),见 SPEC §5.4;三个包装宏的清单 -和每步验收在 [`TODO.md`](TODO.md) 的"有符号数(三步走)"。**加、减、乘不用改**,缺的是 -带符号显示、带符号除法、以及计算器里的一元负号。 +二补码、`-0042` 显示、截断除法、静默溢出,约定在 SPEC §5.4、实现在 §7.10。 +`clb_digits_signed` / `clb_divmod_signed` 都是包装(真活还是 `clb_digits` / +`clb_divmod` 干的),加、减、乘一个字没改。**两条容易踩的**: + +* 符号位靠 `rol` + `bit_copy` + `ror` 读(49 字符)。**别换 `clb_bit_mov`** —— 它吃掉源位, + 于是 `1024` 会打成 `0000`(`examples/signed_demo.r8asm` 就是这条例子的回归)。 +* 标志位在 `biz`/`rnz` 里必须被吃掉才能退出,所以"用完还要留"的符号位要搬到另一格 + (`clb_bit_mov`),这就是为什么 `clb_divmod_signed` 要 T1、T2、F 三格。 ## 下一步 - 候选、想清楚但没做的优化、以及工具侧的小尾巴都收在 [`TODO.md`](TODO.md); -`SPEC.md` §12 是"别试"的结论,不是待办。 +`SPEC.md` §12 是"别试"的结论,不是待办。眼下最靠前的是 TODO 里的"交互计算":RPN 栈、 +终端纸带、迷你 `printf`。 ## 索引 diff --git a/README.md b/README.md index 0b43ca6..3e6f1b3 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ 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 # 纸带窥孔优化:62513 -> 56350 字符 +r8forge --opt asm/test.r8asm > t.rot8 # 纸带窥孔优化:62351 -> 56338 字符 ``` `-j` 只影响纸带搜索(层数搜索是串行的);`-q` 只压 stdout,错误照旧进 stderr、退出码不变。 @@ -83,9 +83,9 @@ include/r8forge/r8veritas.hh 搜索器 include/r8forge/geometry.hh 默认几何(11 位 × 259 格) src/r8asm.cc 汇编器实现 src/synth.cc 真值表 -> 搜索 -asm/ 标准库(53 个宏,含 8 个 %synth 合成块) +asm/ 标准库(55 个宏,含 8 个 %synth 合成块) drv/ 单点验证驱动(喂固定输入跑一个宏,看 out/stat) -examples/ 18 个能跑的例程:每组宏一份 + %synth 的几种写法 + 一个交互例程 +examples/ 19 个能跑的例程:每组宏一份 + %synth 的几种写法 + 交互例程 tests/ 汇编器 / 虚拟机 / 字节级 / 例程 / 文档格式 自检 docs/ 设计笔记(长文) .r8forge_cache/ 合成结果缓存(已入库) @@ -101,10 +101,11 @@ SPEC.md AGENTS.md README.md 契约 / 工作手册 / 本文件 | 位级(一个 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 | +| 大宏 | `clb_mul`、`clb_divmod`、`clb_digits`、`clb_undigits`、`clb_digits_signed`、`clb_divmod_signed` | 乘、除、整数 ↔ 4 位 ASCII;带 `signed` 的两个是二补码包装(负数显示/截断除法) | -契约(签名、参数类型、cell 数、纸带长度、由哪个测试验证)在 [`SPEC.md`](SPEC.md) §5–§9; -为什么是现在这样(以及那些失败尝试)在 [`docs/byte-ops.md`](docs/byte-ops.md)。 +契约(签名、参数类型、cell 数、纸带长度、由哪个测试验证)在 [`SPEC.md`](SPEC.md) §5–§9 +(有符号数在 §5.4 + §7.10);为什么是现在这样(以及那些失败尝试)在 +[`docs/byte-ops.md`](docs/byte-ops.md)。 ## 例子 @@ -124,13 +125,13 @@ build/Release/r8forge_tape_run.exe t.rot8 # 打印 out 和步数 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 asm/test.r8asm # 全家桶:除两个 signed 包装宏外每个标准宏至少一次 build/Release/r8forge_synth_test examples/full_add.r8asm # 合成的块 + 虚拟机自检 -build/Release/r8forge_byte_op_test # 字节级库穷举 +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 -j 4 --output-on-failure # 上面这些一次跑完(8 条,约 9 秒) +ctest --test-dir build -C Release -j 4 --output-on-failure # 上面这些一次跑完(8 条,约 12 秒) ``` `build/` 已经配好生成器:重编译请用**给它配的那个 cmake**(PATH 上的另一个版本会重新配置, diff --git a/SPEC.md b/SPEC.md index d3e8f1d..2a5833f 100644 --- a/SPEC.md +++ b/SPEC.md @@ -354,20 +354,26 @@ endloop C 只剩约一千。 -### 5.4 有符号数(约定已定,实现待做) +### 5.4 有符号数(约定 + 实现在 §7.10) 表示法用**二补码**:值 `v` 为负当且仅当第 `_CELL_SIZE-1` 位是 1(11 位时 1024..2047 = -−1024..−1,8 位时 128..255 = −128..−1)。范围对称,所以不存在"最小负数取反溢出"。 +−1024..−1,8 位时 128..255 = −128..−1)。 -四条已定的约定: +**范围是不对称的**:11 位能表示 −1024..1023。−1024 的绝对值 1024 放不进**有符号** +范围,却放得进**无符号**范围 —— 所以 `1024` 这个位型要能打成 `-1024`(`clb_digits` +本来就是无符号展开)。这条把"取绝对值"的实现路子钉死了:**必须真的取负** +(`clb_neg_ip`),不能靠"清掉第 W-1 位"—— 那种写法在 1024 上会打出 0 +(`examples/signed_demo.r8asm` 就是这条例子的回归)。 + +四条约定: * **加、减、乘不需要改**:模 2^W 运算天然按二补码正确。 * **显示**:`-0042`,即字符 45 加现有的定宽补零数字;正数不打印加号。 -* **除法**:截断(C 语义)—— `q = trunc(a/b)`,`r = a - q*b`,余数与被除数同号。 -* **溢出**:静默回绕,不显示错误。 +* **除法**:截断(C 语义)—— `q = trunc(a/b)`、`r = a - q*b`,余数与被除数同号。 +* **溢出**:静默回绕,不显示错误(`-1024 / -1` 这种"商出了有符号范围"也一样)。 -待做的是三个包装宏(`clb_digits_signed`、`clb_divmod_signed`、计算器里的一元负号), -清单和验收在 [`TODO.md`](TODO.md)。 +实现:§7.10 的两个包装宏(`clb_digits_signed`、`clb_divmod_signed`)+ +`examples/calc.r8asm` 里的一元负号(判据是 cell `NEED`,见那个文件开头)。 ## 6. 位级宏(一个 cell 装一位) @@ -686,6 +692,59 @@ N 被吃干净;`REG` 起 4 格、`S` 起 **13 格**必须连续且干净。纸 `~D` 再走 `raw_add`"的写法(同样的纸带、每轮少一次 copy,单轮 2019 → 973 步), 但 `docs/divmod.md` §3 的设计指名用 `raw_sub`、而且它是上一轮专门为长除法加的,所以没有换。 +### 7.10 有符号数包装宏:`clb_digits_signed` / `clb_divmod_signed` + +约定在 §5.4(二补码、`-0042` 这种显示、截断除法、静默回绕)。两个宏都只是**包装**, +真正的活还是 `clb_digits` / `clb_divmod` 干的 —— 所以纸带的大头没变,代价是取符号位 +和四次条件取负。 + +| 宏 | 签名 | 语义 | 吃什么 | cell | 纸带 | 验证 | +|---|---|---|---|---|---|---| +| `clb_digits_signed` | `N REG S T F` | 负数先打 45('-'),再打 **\|N\|** 的四位 | N | 4 + 13 + 2 | 12151 | 2048 个值全扫 | +| `clb_divmod_signed` | `N D Q R S T1 T2 F` | `Q = trunc(N/D)`、`R = N - Q*D`(余数随被除数) | N、D 变成 \|N\|、\|D\| | 4 + 7 + 3 | 6030 | 4202 组全扫 | + +纸带是 `drv/` 驱动下的实测值;同一个驱动布局下 `clb_digits` 是 11579、`clb_divmod` +是 4481,**包装本身花 572 / 1191 字符**。验证在 `r8forge_byte_op_test` 的 +`test_digits_signed`(2048 个值)和 `test_divmod_signed`(\|a\|,\|b\| ≤ 32 全组合 +4225 组 + 0/±1/±1023/±1024 的边界组合,最坏 35,202 步)。 + + clb_digits_signed: 7 -> "0007" 2047 -> "-0001" 1024 -> "-1024" 0 -> "0000" + clb_divmod_signed: 7/2 -> 3 r 1 -7/2 -> -3 r -1 7/-2 -> -3 r 1 -7/-2 -> 3 r -1 + +契约(细节见两个宏的文件注释): + +* **`clb_digits_signed N REG S T F`**:N 被吃干净;`REG` 起 4 格、`S` 起 13 格、 + `T` 进来都必须干净(和 `clb_digits` 一样);`F` 只用最低位、进来最低位要是 0。 + 结束 `T`、`F` 都是 0。 +* **`clb_divmod_signed N D Q R S T1 T2 F`**:S 起的 7 格只要 `S+6`(buf)干净; + `T1`、`T2`、`F` 进来必须干净,结束都是 0。**N、D 被吃成绝对值**(要原值自己留副本)。 + +五个设计点: + +1. **符号位怎么读**:`rol`(= W-1 次 `ror`)把 bit `W-1` 转到 bit0,`bit_copy` 抄进标志格, + 再 `ror` 把 N 原样还回去 —— 三段一共 49 字符。 + **不能用 `clb_bit_mov`**:它顺手吃掉源位,于是 N 少了符号位、转回去就成了 + `N - HALF`。负数是拿 N 去取负的,少了这一位 `-1024` 就变成 0(`1024 -> "0000"`), + 而 `bit_copy` 走缓冲格、源位原样保留,正是它多出来的 27 个字符买的东西。 + **也不用 `clb_sub_nc T HALF` 那种比较**:`clb_sub_nc` 展开一次就是 765 字符,还要 + 再造一个 HALF 常数格(≈60)。 +2. **`clb_digits_signed` 的 '-' 放在 `S+10`**(`clb_divmod` 的商格):第一轮 `clb_divmod` + 进来第一件事就是 `erase` 它,所以这个常数格不用调用者事后擦,也不破坏"S 起 13 格 + 干净"的入口契约。 +3. **标志位要活过 `clb_divmod`**:符号在除法**前**(决定取不取负)和除法**后**(决定 + Q、R 的符号)都要用,而 `biz`/`rnz` 是循环对 —— 块的身体必须把那个条件位清掉才能 + 退出。所以"用完还要留"的那一位要搬到另一格存着(`clb_bit_mov`,11 字符): + `T2 = sign(N)`、`F = sign(D)`;第 5 步的 `flb` 把 `F` 从 `sign(D)` 翻成 + `sign(N)^sign(D)`(那一支进来就说明 `sign(N)=1`),商的符号就齐了。 +4. **取负用的草稿格借 `S+6`**:`clb_neg_ip` 要求草稿格干净,而 S 里只有 `S+6`(buf) + 有"干净"这个契约;`clb_neg_ip` 用完它就归零,所以 `clb_divmod` 进场时它照样干净。 +5. **四次取负**:|N|、|D|、R、Q 各一次,没有一次是多余的(Q 的符号靠第 3 条折成一次)。 + 单次 `clb_neg_ip` 是 110 字符,所以包装的 1191 里有 440 是这四次。 + +配 `examples/calc.r8asm` 用时只剩"一元负号"一件:字符 45 在 cell `NEED`(在等一个新 +操作数:开头 / 刚结算 / 刚打完运算符 / 刚 `','`)时置 `NEG`、清 `ISCMD`,下一个打进 +窗口的数在 flush 里被 `clb_neg_ip` 取负。 + --- ## 8. 原地 `_ip` 家族(结果回到原来的 cell) @@ -765,10 +824,14 @@ clb_add_ip PH Ci S F ; 把进位加进高字节(Ci 被吃) E 大宏(`clb_ones` / `loop` / `clb_digits` + `clb_undigits`)→ F 语言特性(自定义 `%macro` + `%rep` + `%for` + 两份 `%synth`)→ G 两轮 hash(`clb_add_nc` + `clb_mul`)。 -11 位下纸带 **62513 字符**、**206491 步**、93 个 `out`。两个约束值得记住: +11 位下纸带 **62351 字符**、**202159 步**、93 个 `out`。两个约束值得记住: -* **必须留在 65536 条指令以下**:ROT-8-viz 的 `INS_SIZE`(`include/rot8/rot8.h`)是 65536, - 超了 `read_tape` 会截断,交叉验证就废了。所以 hash 只留两轮、每个宏只调一次。 +* **必须留在 65536 条指令以下**:ROT-8-viz 的 `INS_SIZE`(`include/rot8/rot8.h`)是 65536 + (现在的缓冲是从纸带长度现算的,`INS_SIZE` 只是历史常量,但交叉验证仍按这条走), + 超了旧 `read_tape` 会截断。所以 hash 只留两轮、每个宏只调一次。 +* **两个有符号包装宏不在全家桶里**(§7.10):它们各自要把 `clb_digits` / `clb_divmod` + 再展开一份(+12.1k / +5.6k),而全家桶离 65536 只剩约 3k。它们的单点回归是 + `examples/signed_demo.r8asm`,穷举在 `r8forge_byte_op_test`(§11)。 * 三个实现(`r8forge_derive`、`r8forge_tape_run`、ROT-8-viz 的 `rot8_test -n`)对这份 `out` 逐位一致;最后 6 个值 `1322 5 82 0 1786 94` 是老 hash 的指纹 (`1322`/`1786` = 两轮的 h,`5`/`94` = 两轮的 PH,`82` = 被乘数保留、`0` = 乘数被吃)。 @@ -793,6 +856,7 @@ r8forge_tape_run t.rot8 # 打印 out 和步数 | `mul_demo.r8asm` | §9 | 82×141、2047×2047 的 `(PH:PL)` | | `divmod_demo.r8asm` | §7.6 | 2047/10、2047/1(旧版第二个会 HANG),顺带证明 N、D 保留、草稿可以反复用 | | `digits_demo.r8asm` | §7.7 | 1234 和 7 的 4 位 ASCII | +| `signed_demo.r8asm` | §7.10 | `-7/2` 的商和余数(`-0003`、`-0001`)、以及 `1024 -> "-1024"` 那个绝对值边界 | | `undigits_demo.r8asm` | §7.9 | `"1234"` → 1234、`"0007"` → 7,以及 2047 的 `digits → undigits` 往返 | | `full_add*.r8asm` | §3 `%synth` | 四种写法(`map` / `stat` / `layers` / 手写);输入全 0,所以 `out 0 0` | @@ -806,14 +870,14 @@ r8forge_tape_run t.rot8 # 打印 out 和步数 | 测试 | 覆盖 | 断言口径 | |---|---|---| -| `r8forge_byte_op_test` | 21 个测试项 = 20 个宏(`clb_neg_nc` 的 Ci=1 / Ci=0 各算一项),见 §7.1、§7.2、§7.5、§7.6、§7.7、§7.9、§8、§9 | **按返回值**:穷举 0..255(`clb_add_ip` 2048 抽样、`clb_mul` 65536 全穷举、`clb_ones` 12 个计数全穷举、`clb_divmod` 8 个除数 × 全部 2048 个被除数 = 16384 组全穷举、`clb_digits` 全部 2048 个值全穷举、`clb_undigits` 2048 个值 × 干净/高位垃圾 2 种 = 4096 组全穷举),任一不符即退出码非 0 | +| `r8forge_byte_op_test` | 23 个测试项 = 22 个宏(`clb_neg_nc` 的 Ci=1 / Ci=0 各算一项),见 §7.1、§7.2、§7.5、§7.6、§7.7、§7.9、§7.10、§8、§9 | **按返回值**:穷举 0..255(`clb_add_ip` 2048 抽样、`clb_mul` 65536 全穷举、`clb_ones` 12 个计数全穷举、`clb_divmod` 8 个除数 × 全部 2048 个被除数 = 16384 组全穷举、`clb_digits` 全部 2048 个值全穷举、`clb_digits_signed` 全部 2048 个值全穷举(含 1024 → `-1024`)、`clb_divmod_signed` \|a\|,\|b\| ≤ 32 全组合 + 边界 = 4202 组全穷举(与 C 的 `/` 和 `%` 逐项比)、`clb_undigits` 2048 个值 × 干净/高位垃圾 2 种 = 4096 组全穷举),任一不符即退出码非 0 | | `r8forge_synth_test examples/full_add.r8asm` | `%synth` 端到端:汇编 + 跑 8 种输入 | `all eight combinations ok` | -| `r8forge_examples_test` | `examples/` 里全部 18 个程序(10 组宏例程 + 4 个 `%synth` 例子 + 交互例程 + 计算器,见 §10.3)**加上 `asm/test.r8asm`**(§10.2) | **按返回值**:每个头部 `; out ...` 与实跑 `out` 逐项相等,缺这一行也算失败;写了 `; in ...` 的先把那串字符喂给 `inp` | +| `r8forge_examples_test` | `examples/` 里全部 19 个程序(11 组宏例程 + 4 个 `%synth` 例子 + 交互例程 + 计算器 + 有符号例程,见 §10.3)**加上 `asm/test.r8asm`**(§10.2) | **按返回值**:每个头部 `; out ...` 与实跑 `out` 逐项相等,缺这一行也算失败;写了 `; in ...` 的先把那串字符喂给 `inp` | | `r8forge verify_clb_bit_add_nc.r8asm` | 4 cell 加法切片(进位进→出) | 单点:`0+0+Ci` | | `r8forge verify_clb_bit_inc_nc.r8asm` | 3 cell 自增切片 | 单点 | | `r8forge_derive verify_loop.r8asm -1 0=N` | 动态循环:`N=0..11` 时循环体跑 `N` 次(`A = N`、`C = 0`) | 逐值 `out` | | `r8forge verify_set_0.r8asm` | `set_0` 只清 LSB | `-1 0=255 → 254`、`0=128 → 128` | -| `r8forge_macro_docs_test` | `asm/` 里 47 个宏的注释格式 | 全绿或报错行号 | +| `r8forge_macro_docs_test` | `asm/` 里 55 个宏的注释格式 | 全绿或报错行号 | | `r8forge_tape_run ` | 第二个解释器,直接跑纸带 | 与 `r8forge_derive` 对答案 | | `r8forge_derive -1/-2` | 拿汇编源码跑,打印 `out` / 非零 cell | 人工/脚本比对 | diff --git a/TODO.md b/TODO.md index fdd20b7..c54832a 100644 --- a/TODO.md +++ b/TODO.md @@ -4,26 +4,11 @@ **从哪开始**;做完就删掉(历史在 git log 里)。`SPEC.md` §12 那张"已经确认走不通"的表是 **结论**,不是待办,别混进来。 -已经做完、从这份清单里移出去的:桌上计算器(`examples/calc.r8asm`,11 位 62585 字符、三方 -一致、位宽矩阵见 `tests/widths.ps1`)、`INP` 整格写入的语义修正、参考虚拟机支持 >64k 纸带。 - -## 有符号数(三步走,约定见 SPEC §5.4) - -表示法、显示格式、除法语义、溢出行为都已经定死,剩下三个**可独立验收**的步骤: - -1. **`clb_digits_signed N REG S T F`**:`T` = |N| 的副本,`F` = 符号位。判负用 - `clb_sub_nc T HALF`(`HALF = 2^(_CELL_SIZE-1)`,**必须 `%rep _CELL_SIZE`,写死 11 会 - 在 8 位机器上把符号位判错**),负数先 `output 45` 再对副本 `clb_neg_ip`,最后走现有 - `clb_digits`。验收:2048 个值全扫,期望串在 C++ 里按 `x >= 2^(W-1) ? x - 2^W : x` 算, - `2047 -> -0001`、`1024 -> -1024`、`0 -> 0000`。 -2. **`clb_divmod_signed N D Q R S T1 T2 F`**:取符号 → 各自绝对值 → 调 `clb_divmod` → - 商的符号按异或、余数取被除数的符号(截断语义自动成立)。验收:`|a|,|b| <= 32` 全组合 - + 边界(0、正负 1、正负 1023、正负 1024),与 C 的除法和取余逐项比。 -3. **计算器的一元负号**:字符 45 在 `HAVE == 0` 时置 `NEG` 标志,flush 时对 - `clb_undigits` 的结果取反;`HAVE == 1` 时仍是减号。验收:`3 5 - .` -> `-0002`、 - `-5 2 * .` -> `-0010`、`-7 -2 / .` -> `0003`。 - -每步做完都能停在可用状态(第 1 步之后 `clb_digits_signed` 就能单独用)。 +已经做完、从这份清单里移出去的:桌上计算器(`examples/calc.r8asm`,11 位 62624 字符、三方 +一致、位宽矩阵见 `tests/widths.ps1`)、`INP` 整格写入的语义修正、参考虚拟机支持 >64k 纸带、 +**有符号数三步走**(`clb_digits_signed` / `clb_divmod_signed` / 计算器的一元负号,契约在 +SPEC §5.4、实现在 §7.10,穷举在 `r8forge_byte_op_test` 的 `test_digits_signed` 2048 个值 +和 `test_divmod_signed` 4202 组)。 ## 交互计算(下一步) @@ -42,14 +27,23 @@ ## 工具 +* **纸带级的"合并重复段落"**(这条原来的标题在交接时丢了,剩下的正文原样留着): 重复清位…… 要能重算跳转偏移。配套 `r8forge_tape_diff`(比较两条纸带的 OUT 流和步数) 证明等价 —— 一次改动全库受益。 +* **全家桶要不要把两个有符号包装宏收回去**:`asm/test.r8asm` 现在是"每个宏至少调一次", + 但 `clb_digits_signed` / `clb_divmod_signed` 被排除在外(各要多展开一份 `clb_digits` / + `clb_divmod`,+12.1k / +5.6k,而 65536 的预算只剩 ~3.2k)。两条路:把全家桶拆成两条 + 纸带,或者承认 65536 只是历史口径(viz 现在按纸带长度分配缓冲;实测 16 位的 calc 是 + **96052** 字符、在 viz 里照跑,见 `tests/widths.ps1`)。现在的兜底是 + `examples/signed_demo.r8asm` + `byte_op_test` 的穷举。 + * **`%synth --verify`**:把 `.r8forge_cache/` 里每条结果按对应表的所有输入重跑一遍, 给"缓存已入库"兜底 —— 一条坏条目会让每次构建静默用错块。 -* **CI**:暂时不做。本地 `ctest --test-dir build -j 4`(8 条,9 秒)和 `tests/widths.ps1` - (位宽矩阵,约 20 分钟)都能手动跑;act_runner 的镜像装不出 cmake,先放着。 - **ROT-8-viz 仍然零测试**:串行默认 / `-n` / 几何 / 7E1 全靠手测 —— 哪天真要接 CI,先补它。 +* **CI**:暂时不做。本地 `ctest --test-dir build -C Release -j 4`(8 条,12 秒)和 + `tests/widths.ps1`(位宽矩阵,约 20 分钟)都能手动跑;act_runner 的镜像装不出 cmake, + 先放着。**ROT-8-viz 仍然零测试**:串行默认 / `-n` / 几何 / 7E1 全靠手测 —— 哪天真要接 + CI,先补它。 * **`src/r8asm.cc:154`** 有个上游留下的 `// TODO: FILL THE BLANK`(`ROT8_NODE` 宏的 children 是空的)。那是继承来的实现,先记着,别顺手改。 @@ -76,4 +70,7 @@ * viz 的 `read_tape`(固定缓冲那版)在 `vm_test.c` 改用 `read_tape_alloc` 之后应该没人用了: 要么删掉,要么在头注释里标 deprecated。 * viz 的 `INS_SIZE` 现在只是历史常量(真正的上限是 `ROT8_MAX_TAPE` = 16 M 条指令), - README 里可以说明一句。 + README 里可以说明一句。实测证据:16 位的 `examples/calc.r8asm` 是 **96052** 字符, + `rot8_test --cell 16 --input "12 34 + ."` 照样打出 `> 00046`(`tests/widths.ps1`)。 + 顺带:viz 只有在 cell **≥ 8 位**时才走串行 ASCII,7 位下每个 OUT 打一行数字 —— + `tests/widths.ps1` 的 viz 断言现在按这条跳过了 7 位(那一档由 `r8forge_derive` 兜)。 diff --git a/docs/calc.md b/docs/calc.md index e7e7766..5d2d7b5 100644 --- a/docs/calc.md +++ b/docs/calc.md @@ -18,8 +18,8 @@ | 输入 | 动作 | |---|---| | `'0'..'9'` | 攒进 4 位数字缓冲(遇到终止符一次性 `clb_undigits` 换成整数,压栈) | -| `'*'` `'+'` `'-'` `'/'` | 弹两个、算、压回 | -| `'.'` | 打印栈顶(`clb_digits` + 4 个 `output`) | +| `'*'` `'+'` `'-'` `'/'` | 弹两个、算、压回;`'-'` 在"还在等操作数"时是一元负号(§7) | +| `'.'` | 打印栈顶(`clb_digits_signed` + 4 个 `output`) | | `','` | 清栈 | | 其它(空格/回车) | 忽略(作为数字的终止符) | | **0**(EOF) | `erase` 掉循环计数器,主循环结束,纸带自然跑完 | @@ -57,6 +57,8 @@ t = C - 0x2A ; 命令: 0..5 数字: 6..15 3. **`drv/calc_disp.r8asm`**:整数 → `> ` 提示符 + 4 位 ASCII + 换行。 4. **`drv/calc_op.r8asm`**:`12 34 +` → 46(`+ - * /` 各一次)。 5. **`examples/calc.r8asm`**:主循环 + EOF 退出 + `; in`/`; out` 头部,进 `examples_test`。 +6. **有符号数**(做完,见 §7):显示换 `clb_digits_signed`、除法换 `clb_divmod_signed`、 + 加一元负号。`3 5 - .` → `-0002`、`-5 2 * .` → `-0010`、`-7 -2 / .` → `0003`。 ## 4. 栈:v1 固定 4 深,不用指针 @@ -74,11 +76,12 @@ t = C - 0x2A ; 命令: 0..5 数字: 6..15 | 攒一个数(`clb_undigits`) | ≤ 36,481 | | `+`/`-`(`clb_add_nc`/`clb_sub_nc`) | ~2.5k | | `*`(`clb_mul`) | ≤ 20,300 | -| `/`(`clb_divmod`) | ~28,600 | -| 打印(`clb_digits`) | ≤ 123,755 | +| `/`(`clb_divmod_signed`) | ≤ 35,202(`byte_op_test` 全扫的最坏值;无符号版是 31,579) | +| 打印(`clb_digits_signed`) | ≤ 117,606(`byte_op_test` 2048 个值的最坏值;无符号版 119,431) | -一行 `12 34 + .` ≈ 36k×2 + 2.5k + 124k ≈ **200k 步**。`examples_test` 的上限是 2000 万步, -所以会话控制在 10 行左右(或把打印换成"里程表"版本,见下)。 +一行 `12 34 + .` 实测 **280,645** 步(有符号之前是 314,777 之类,`examples/calc.r8asm` +的头部写着这一轮的全部实测值)。`examples_test` 的上限是 2000 万步,所以会话控制在 +十几行以内(或把打印换成"里程表"版本,见下)。 ## 6. 已知的坑(都在库里踩过) @@ -87,3 +90,29 @@ t = C - 0x2A ; 命令: 0..5 数字: 6..15 * 用 `loop`/`endloop` 计数器时,`erase` 计数器就能提前退出(EOF 就这么退); * 库宏每轮都重建 `TEN` 和轮数计数器 —— 这个终端的**常量区**(cell 32..43)就是为了把这些 搬到循环外,v2 再让 `clb_undigits`/`clb_digits` 支持"外部常量"版本。 + +## 7. 有符号数(第 6 步,做完) + +约定在 SPEC §5.4、宏在 SPEC §7.10。计算器这边只动三处: + +1. **显示**:`clb_digits` → `clb_digits_signed`(负数自己打 '-',然后打 |A| 的定宽四位)。 +2. **除法**:`clb_divmod` → `clb_divmod_signed`(截断、余数随被除数)。加、减、乘不用动, + 二补码的模 2^W 运算天然对。 +3. **一元负号**:这是唯一需要新状态的地方。判据是 cell `NEED`: + + > `NEED = 1` 表示"在等一个新操作数"(表达式开头 / 刚结算完 / 刚打完运算符 / 刚 `','`)。 + > 这时字符 45 是一元负号:置 `NEG`、清 `ISCMD`(第 3 步据此这一轮不改 `OP`);下一个 + > 打进窗口的数在 flush 里被 `clb_neg_ip` 取负。`NEED = 0` 说明 P 里已经有一个数等着 + > 结算,45 就是二元减号。 + +**为什么不用"`HAVE == 0` 就当作一元负号"**(最初的计划就是那样):`HAVE` 只表示"正在攒 +数字",打完运算符之后它也是 0,于是 `2 * -5 .` 里的负号会被判成二元减号,`OP` 被改成 +2(减),结果错。`NEED` 多出来的信息就是"这个位置本来该出现一个操作数"。 + +**作废的旧例子**:`2047 3 / .` → `0682` 是无符号时代的。有符号之后 2047 的位型是 -1, +`-1/3` 截断成 0,现在打 `> 0000`;要 341 就写 `1023 3 / .`。能打的整数范围从 0..2047 +变成 **-1024..1023**。 + +实测(`r8forge_tape_run`):`3 5 - .` → `> -0002`、`-5 2 * .` → `> -0010`、 +`-7 -2 / .` → `> 0003`、`-1024 2 / .` → `> -0512`、`0 3 - .` → `> -0003`。 +纸带 59519 → **62624** 字符(两套包装宏 + 判据,约 +3.1k)。 diff --git a/tests/widths.ps1 b/tests/widths.ps1 index 1f62b61..0703b08 100644 --- a/tests/widths.ps1 +++ b/tests/widths.ps1 @@ -11,7 +11,11 @@ # width that silently did not take effect fails this, because it would print # four digits; # * if the reference machine is built next door, it prints the same thing -# (`rot8_test --cell `), which is the three way check. +# (`rot8_test --cell `), which is the three way check. That one only +# runs for W >= 8: the viz switches to serial ASCII only when a cell is at +# least 8 bits wide, and below that it prints one number per OUT -- so a +# "> 046" comparison at 7 bits would fail for a reason that has nothing to +# do with the tape (the calc itself is still checked there). # Widths under 7 cannot hold '0' (48) in a cell, so they get the library tests # only. # A comma separated string rather than [int[]]: `powershell -File ... -Widths 11,16` @@ -49,13 +53,22 @@ foreach ($w in ($Widths.Split(",") | ForEach-Object { [int]$_.Trim() })) { else { Write-Host " calc ok: $want" } if (Test-Path $viz) { - $tmp = Join-Path $env:TEMP "calc$w.rot8" - [System.IO.File]::WriteAllText($tmp, $tape, (New-Object System.Text.UTF8Encoding($false))) - $serial = (& $viz "--cell" $w "--input" "12 34 + ." $tmp 2>$null | Out-String).Trim() - $wantSerial = "> " + ("0" * ($d - 2)) + "46" - if ($serial -ne $wantSerial) { Write-Host " viz FAILED: want '$wantSerial' got '$serial'"; $failed += $w } - else { Write-Host " viz ok: $wantSerial" } - Remove-Item $tmp -ErrorAction SilentlyContinue + # The viz only speaks serial ASCII when a cell is at least 8 bits wide + # (bit 7 doubles as the 7E1 parity/stop bit; below that it prints one + # number per OUT). Comparing a 7 bit tape with "> 046" therefore says + # nothing: at 7 bits the same tape legitimately prints numbers. The + # calc check above already covers 7 bits, so skip the viz there. + if ($w -lt 8) { + Write-Host " viz skipped: serial I/O needs >= 8 bit cells" + } else { + $tmp = Join-Path $env:TEMP "calc$w.rot8" + [System.IO.File]::WriteAllText($tmp, $tape, (New-Object System.Text.UTF8Encoding($false))) + $serial = (& $viz "--cell" $w "--input" "12 34 + ." $tmp 2>$null | Out-String).Trim() + $wantSerial = "> " + ("0" * ($d - 2)) + "46" + if ($serial -ne $wantSerial) { Write-Host " viz FAILED: want '$wantSerial' got '$serial'"; $failed += $w } + else { Write-Host " viz ok: $wantSerial" } + Remove-Item $tmp -ErrorAction SilentlyContinue + } } Remove-Item -Recurse -Force $dir