diff --git a/AGENTS.md b/AGENTS.md index b39dbe8..b42ad7e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,7 @@ ```sh r8forge asm/test.r8asm # 28729 字符 r8forge_byte_op_test # 20 项(clb_divmod 16384 组、clb_digits 2048 个值) +r8forge_examples_test # examples/ 里 15 个程序,头部 `; 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 @@ -480,6 +481,7 @@ W 轮之后 `(PH:PL)` 就是积;`PL`(原来的 Q)被移空,所以 **MUL | `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 的表)+ 6 个 `%synth` 例子。每个都是能跑的程序,头部 `; out ...` 是它打印什么;`r8forge_examples_test` 全部跑一遍逐项核对(缺那行也算失败),顺带打印纸带长度和步数 | ## 已经确认走不通的(别重试) diff --git a/CMakeLists.txt b/CMakeLists.txt index 4154e6f..535c02d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -38,6 +38,11 @@ target_link_libraries(r8forge_byte_op_test r8forge_core) # Checks that every %macro in asm/ carries a doc comment in the house format. add_executable(r8forge_macro_docs_test tests/macro_docs_test.cc) +# Runs every examples/*.r8asm as a stand alone program and compares its OUT +# stream with the `; out ...` line in the file header. +add_executable(r8forge_examples_test tests/examples_test.cc) +target_link_libraries(r8forge_examples_test r8forge_core) + add_executable(r8forge_cost_par tests/cost_par.cc) target_link_libraries(r8forge_cost_par r8forge_core) diff --git a/README.md b/README.md index 8a4dde3..2136d81 100644 --- a/README.md +++ b/README.md @@ -342,6 +342,31 @@ void rot8_rnz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 1) { ... } } 一个 cell 就能放一个字节、位也读得出来,就没必要为每个 bit 花一个 cell —— 那份实现已经 删了,要拼字节级运算就用 `raw_*`。 +## 例程:`examples/` 里每组宏一份 + +`examples/` 下每个 `.r8asm` 都是**能跑的程序**,头部 `; out ...` 写它打印什么: + +```sh +build/Release/r8forge examples/digits_demo.r8asm > t.rot8 +build/Release/r8forge_tape_run t.rot8 # 打印 out 和步数 +``` + +| 文件 | 演示什么 | +|---|---| +| `base_macros.r8asm` | `set_0` 只清一位 / `erase` 清整格 / `rol`/`ror` 转圈 / `copy`/`bit_copy` 保留源 / `clb_bit_mov` 吃源 / `step` | +| `bit_adder.r8asm` | 用 `clb_bit_add_nc` 串 4 位行波加法器;再对比 `bit_raw_add` 保留操作数 | +| `byte_raw_ops.r8asm` | `raw_add` / `raw_inc` / `raw_and` / `raw_or` / `raw_xor` / `raw_sub`:操作数都还回来 | +| `byte_clobber.r8asm` | `clb_add_nc` / `clb_sub_nc` / `clb_neg_nc` / `clb_inc_nc`:操作数被吃;`clb_and` 的 B 残留 | +| `byte_in_place.r8asm` | `clb_not_ip` / `inc` / `neg` / `dec` / `clb_add_ip` / `clb_nonzero` | +| `sum_loop.r8asm` | `clb_ones` + `loop`/`endloop` 算 `1+2+...+N`(次数来自数据) | +| `mul_demo.r8asm` | 82×141、2047×2047 的 `(PH:PL)` | +| `divmod_demo.r8asm` | 2047/10、2047/1(旧版会 HANG) | +| `digits_demo.r8asm` | 1234 和 7 的 4 位 ASCII | +| `full_add*.r8asm` | `%synth` 的六种写法(`map` / `stat` / `flat` / `layout` / `layers` / 手写) | + +`r8forge_examples_test` 会把它们全跑一遍,实跑的 `out` 和头部那行逐项比 —— 例程不会悄悄腐掉。 +宏的契约(吃什么、留什么、几个 cell、纸带多长)看 `SPEC.md`。 + ## 实现方式 `%synth` 在 `parse()` 里被读成一张真值表,随即调用搜索器;得到的块序列写成 @@ -502,7 +527,8 @@ tests/asm_test.cc 汇编器自检(纸带不变) tests/synth_test.cc 合成 + ROT-8 虚拟机自检 tests/byte_op_test.cc 字节级库穷举自检(65536×4 + 512) tests/macro_docs_test.cc 宏注释格式自检(asm/ 下每个 %macro) +tests/examples_test.cc 例程自检(examples/ 每个程序的 `; out` 与实跑逐项比) tests/tape_run.cc 第二个 ROT-8 解释器,直接跑 .rot8 交叉验证 asm/ 标准库与既有实现 -examples/full_add.r8asm 汇编期合成全加器 +examples/*.r8asm 能跑的程序:每组宏一份例程 + %synth 的六种写法 ``` diff --git a/SPEC.md b/SPEC.md index 1424bb4..5eccfac 100644 --- a/SPEC.md +++ b/SPEC.md @@ -613,6 +613,32 @@ clb_add_ip PH Ci S F ; 把进位加进高字节(Ci 被吃) `1322 1786 1600 5 94 127`(前三 = 三轮的 h,后三 = 三轮的 PH,即 `(h+c)*141 >> 11`), 共 **57330 步**。 +### 10.3 `examples/` 里的例程:每组宏一份 + +`examples/` 下每个 `.r8asm` 都是**能跑的程序**,头部一行 `; out ...` 写它打印什么: + +```sh +r8forge examples/<名字>.r8asm > t.rot8 +r8forge_tape_run t.rot8 # 打印 out 和步数 +``` + +| 文件 | 演示哪一组 | 打印 / 说明 | +|---|---|---| +| `base_macros.r8asm` | §5 基础宏 | `set_0` 只清一位、`erase` 清整格、`rol`/`ror` 转圈、`copy`/`bit_copy` 保留源、`clb_bit_mov` 吃源、`step` | +| `bit_adder.r8asm` | §6 位级宏 | 4 位行波加法器(`clb_bit_add_nc` 串进位链),再对比 `bit_raw_add` 保留操作数 | +| `byte_raw_ops.r8asm` | §7.1 + §7.8 | `raw_add`/`raw_inc`/`raw_and`/`raw_or`/`raw_xor`/`raw_sub`,每个都把操作数打出来证明没被吃 | +| `byte_clobber.r8asm` | §7.2 + §7.3 | `clb_add_nc`/`clb_sub_nc`/`clb_neg_nc`/`clb_inc_nc`(操作数被吃),以及 `clb_and` 的 B 残留 | +| `byte_in_place.r8asm` | §8 | `clb_not_ip` / `inc` / `neg` / `dec` / `clb_add_ip` / `clb_nonzero` | +| `sum_loop.r8asm` | §5.1 + §7.5 | `clb_ones` + `loop`/`endloop` 算 `1+2+...+N`(次数来自数据,不是汇编期常数) | +| `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 | +| `full_add*.r8asm` | §3 `%synth` | 六种写法(`map` / `stat` / `flat` / `layout` / `layers` / 手写);输入全 0,所以 `out 0 0` | + +`r8forge_examples_test` 会把 `examples/` 里所有 `.r8asm` 跑一遍,实跑的 `out` 和头部那行 +逐项比(顺带打印纸带长度和步数)。它保证例程既**汇编得出来**、又**还是那样输出**; +`r8forge_synth_test` 另外用 8 种输入查 `full_add` 的正确性。 + --- ## 11. 验证矩阵 @@ -621,6 +647,7 @@ clb_add_ip PH Ci S F ; 把进位加进高字节(Ci 被吃) |---|---|---| | `r8forge_byte_op_test` | 20 个测试项 = 19 个宏(`clb_neg_nc` 的 Ci=1 / Ci=0 各算一项),见 §7.1、§7.2、§7.5、§7.6、§7.7、§8、§9 | **按返回值**:穷举 0..255(`clb_add_ip` 2048 抽样、`clb_mul` 65536 全穷举、`clb_ones` 12 个计数全穷举、`clb_divmod` 8 个除数 × 全部 2048 个被除数 = 16384 组全穷举、`clb_digits` 全部 2048 个值全穷举),任一不符即退出码非 0 | | `r8forge_synth_test examples/full_add.r8asm` | `%synth` 端到端:汇编 + 跑 8 种输入 | `all eight combinations ok` | +| `r8forge_examples_test` | `examples/` 里全部 15 个程序(9 组宏例程 + 6 个 `%synth` 例子,见 §10.3) | **按返回值**:每个头部 `; out ...` 与实跑 `out` 逐项相等,缺这一行也算失败 | | `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` | @@ -636,8 +663,8 @@ clb_add_ip PH Ci S F ; 把进位加进高字节(Ci 被吃) `could not assemble` 并返回 1。**看到 `out` 结果"太整齐"就先看 stderr 有没有这句。** -只有 `r8forge_byte_op_test` 是**按返回值**判断字节级对错的;其它要么只证明"汇编得出来"、 -"位级正确",要么是单点探针。改宏之后跑 §11 前四个(外加 docs test)。 +只有 `r8forge_byte_op_test` 和 `r8forge_examples_test` 是**按返回值**判断的;其它要么只证明 +"汇编得出来"、"位级正确",要么是单点探针。改宏之后跑 §11 前几个(外加 docs test)。 --- diff --git a/examples/base_macros.r8asm b/examples/base_macros.r8asm new file mode 100644 index 0000000..2426d6d --- /dev/null +++ b/examples/base_macros.r8asm @@ -0,0 +1,74 @@ +%include "asm/lib.r8asm" + +; §5 基础宏(`asm/lib.r8asm`)的例程:set_0 / erase / rol / ror / copy / +; bit_copy / clb_bit_mov / step / back / output。 +; +; 这一组的主题是"**一位**和**一整格**别搞混": +; * set_0 是 `[-]`,只清 cell 的**最低位**(255 -> 254),erase 才清整格; +; * ror / rol 是**转圈**,不是移位(1 转一格是 1024,再转回来还是 1); +; * copy / bit_copy **保留源**,clb_bit_mov 把源的那一位**搬走**; +; * step N 走 2N 格(Unit = 两个 cell),back 走回来。 +; +; 纸带:r8forge examples/base_macros.r8asm > /tmp/b.rot8 +; r8forge_tape_run /tmp/b.rot8 +; (r8forge_derive 只接受"按参数跑"的驱动,看输出用 tape_run 或 derive 0) +; +; 期望输出见下面的 `; out` 行,`r8forge_examples_test` 会跑一遍核对。 +; +; out 254 0 1024 1 5 5 1 5 0 1 7 + +.var A 0 ; 主力 cell +.var B 1 ; copy 的源 +.var buf 2 ; copy / bit_copy 借来的缓冲(必须是干净的) +.var D 3 ; clb_bit_mov 的目标 +.var E 4 ; 被搬走那一位的源 +.var F 5 ; step 的起点(step 1 会走到 F+2) + +; ---- 1. set_0 只清最低位:255 -> 254 +.tp A +.xor 255 +.tp A +set_0 +output A + +; ---- 2. erase 才清整格 +.tp A +erase A +output A + +; ---- 3. ror / rol 是转圈:1 -> 1024 -> 1 +.tp A +.xor 1 +.tp A +ror +output A +.tp A +rol +output A + +; ---- 4. copy 保留源:A = B,B 还是 5 +.tp B +.xor 5 +.tp B +copy A buf +output A +output B + +; ---- 5. bit_copy 也保留源:E = B 的 LSB,B 不动 +.tp B +bit_copy E buf +output E +output B + +; ---- 6. clb_bit_mov 把源吃掉:E 的 LSB 搬给 D,E 变成 0 +.tp E +clb_bit_mov D +output E +output D + +; ---- 7. step 走 Unit(两格):从 F 走一格是 F+2 +.tp F +step 1 +.xor 7 +output F+2 +back 1 diff --git a/examples/bit_adder.r8asm b/examples/bit_adder.r8asm new file mode 100644 index 0000000..9010fc3 --- /dev/null +++ b/examples/bit_adder.r8asm @@ -0,0 +1,71 @@ +%include "asm/raw_add_nc.r8asm" +%include "asm/raw_add.r8asm" + +; §6 位级宏(一个 cell 装一位)的例程: +; * 用 `clb_bit_add_nc A B Ci S` 串一个 **4 位行波加法器**(进位进->出); +; * 再用 `bit_raw_add` 算一位,展示 6 cell 版**保留 A、B** 的代价。 +; +; 11 + 6 = 17: A = 1011、B = 0110,和是 10001(4 位和 0001 + 进位 1)。 +; +; 两种切片的区别(§6.1): +; clb_bit_add_nc A B Ci S 4 cell,吃 A、B,进位在同一个 cell 里进、出; +; bit_raw_add A B Ci S Co buf 6 cell,保留 A、B,还多给一个 Co。 +; 位级宏只碰低 1 位,喂进来的输入必须是 0/1。 +; +; 纸带:r8forge examples/bit_adder.r8asm > /tmp/ba.rot8 +; r8forge_tape_run /tmp/ba.rot8 +; +; out 1 0 0 0 1 1 1 1 1 + +; 4 位行波加法器:A 的位在 0..3、B 的位在 4..7、和的位在 8..11,进位链在 12 +.var A0 0 +.var B0 4 +.var S0 8 +.var Ci 12 + +; 一位全加器(保留操作数的版本)的格子 +.var RA 13 +.var RB 14 +.var RCi 15 +.var RS 16 +.var RCo 17 +.var Rbuf 18 + +; ---- A = 1011(11),B = 0110(6) +.tp A0 +.xor 1 +.tp A0 + 1 +.xor 1 +.tp A0 + 3 +.xor 1 +.tp B0 + 1 +.xor 1 +.tp B0 + 2 +.xor 1 + +; ---- 进位输入从 0 开始;低位先加,carry 顺着 Ci 往高位传 +.tp Ci +set_0 +%for k 4 + clb_bit_add_nc A0 + k B0 + k Ci S0 + k +%endfor + +; 4 位和(低位在前),最后是进位出 +output S0 +output S0 + 1 +output S0 + 2 +output S0 + 3 +output Ci + +; ---- 同一个全加器,换成保留操作数的 6 cell 版:1 + 1 + 1 = 1,进位 1 +.tp RA +.xor 1 +.tp RB +.xor 1 +.tp RCi +.xor 1 +bit_raw_add RA RB RCi RS RCo Rbuf +output RS +output RCo +output RA ; 保留 +output RB ; 保留 diff --git a/examples/byte_clobber.r8asm b/examples/byte_clobber.r8asm new file mode 100644 index 0000000..7ce09ad --- /dev/null +++ b/examples/byte_clobber.r8asm @@ -0,0 +1,124 @@ +%include "asm/raw_add_nc.r8asm" +%include "asm/raw_sub_nc.r8asm" +%include "asm/raw_neg_nc.r8asm" +%include "asm/raw_inc_nc.r8asm" +%include "asm/raw_and.r8asm" +%include "asm/raw_or.r8asm" +%include "asm/raw_xor.r8asm" + +; §7.2 `clb_*_nc` 家族 + §7.3 `clb_and/or/xor` 的例程。 +; +; 这一组把操作数**吃干净**(换来少一个草稿 cell): +; clb_add_nc A B S Ci S = A+B+Ci,A、B 结束为 0 +; clb_inc_nc A S Ci S = A+Ci +; clb_neg_nc A S Ci S = ~A+Ci(Ci=1 就是 -A) +; clb_sub_nc A B S Ci S = A+~B+Ci(Ci=1 就是 A-B) +; 进位 cell 是**真正的进位输入**:给 0 是普通运算,给 1 是"自带 +1"。 +; 每个宏后面把被吃掉的操作数打出来,顺便看进位输出的附带语义: +; `clb_sub_nc` 的进位是"没有借位"(A >= B 时为 1),`clb_neg_nc` 只在 A 原本是 0 时为 1。 +; +; §7.3 那三个是**半破坏**的:clb_or / clb_xor 干净地吃掉 A、B,而 +; `clb_and` 只在"A、B 都是 1"的那几位清 B —— 所以 B 结束在 `B & ~A`, +; 不是 0(240 & 204 -> ans=192、A=0、B=12)。这个例程把残留打出来。 +; +; 纸带:r8forge examples/byte_clobber.r8asm > /tmp/c.rot8 +; r8forge_tape_run /tmp/c.rot8 +; +; out 300 0 0 52 1 5 1 2043 0 2043 0 0 1 192 0 12 252 0 0 60 0 0 + +.var A 0 +.var B 1 +.var S 2 +.var Ci 3 + +; ---- clb_add_nc:200 + 100 = 300,A、B 被吃干净 +.tp A +.xor 200 +.tp B +.xor 100 +.tp Ci +set_0 +clb_add_nc A B S Ci +output S +output A +output B + +; ---- 进位出:2000 + 100 = 2100 -> S = 52,进位 1 +.tp A +.xor 2000 +.tp B +.xor 100 +.tp Ci +set_0 +clb_add_nc A B S Ci +output S +output Ci + +; ---- clb_sub_nc:15 - 10 = 5,进位 = "没有借位" = 1 +.tp A +.xor 15 +.tp B +.xor 10 +.tp Ci +set_1 +clb_sub_nc A B S Ci +output S +output Ci + +; ---- 反过来:10 - 15 = -5 = 2043,进位 0(有借位) +.tp A +.xor 10 +.tp B +.xor 15 +.tp Ci +set_1 +clb_sub_nc A B S Ci +output S +output Ci + +; ---- clb_neg_nc:5 的补码是 2043,进位 0(A 不是 0) +.tp A +.xor 5 +.tp Ci +set_1 +clb_neg_nc A S Ci +output S +output Ci + +; ---- clb_inc_nc:2047 + 1 回绕成 0,进位 1 +.tp A +.xor 2047 +.tp Ci +set_1 +clb_inc_nc A S Ci +output S +output Ci + +; ---- clb_and 的 B 残留:240 = 0b11110000,204 = 0b11001100 +.tp A +.xor 240 +.tp B +.xor 204 +clb_and A B S +output S ; 192 +output A ; 0 +output B ; 12 = 204 & ~240,不是 0! + +; ---- clb_or / clb_xor 是干净的 +.tp A +.xor 240 +erase B ; clb_and 把 B 留成 12,这里要的是 204 +.tp B +.xor 204 +clb_or A B S +output S ; 252 +output A ; 0 +output B ; 0 +.tp A +.xor 240 +.tp B +.xor 204 +clb_xor A B S +output S ; 60 +output A ; 0 +output B ; 0 diff --git a/examples/byte_in_place.r8asm b/examples/byte_in_place.r8asm new file mode 100644 index 0000000..d512b35 --- /dev/null +++ b/examples/byte_in_place.r8asm @@ -0,0 +1,60 @@ +%include "asm/add_ip.r8asm" + +; §8 原地 `_ip` 家族(`asm/inc_ip.r8asm`、`asm/not_ip.r8asm`、`asm/add_ip.r8asm`)的例程。 +; +; 这一组的共同点:**结果写回原来的 cell**,草稿只有一个 `T`(clb_add_ip 多一个 F): +; clb_not_ip A A = ~A(反码) +; clb_inc_ip A T A = A + 1 +; clb_neg_ip A T A = -A(补码取负) +; clb_dec_ip A T A = A - 1 +; clb_add_ip A B T F A += B,B 被吃干净 +; clb_nonzero B F T F = (B != 0),B 不动 +; 对比写回 S 的切片版(clb_inc_nc 3 cell、clb_neg_nc 3 cell),原地版少一个 cell、短五倍: +; `clb_add_ip` 是"while B != 0: A += 1; B -= 1",所以运行是 O(B),纸带和 B 无关。 +; +; 纸带:r8forge examples/byte_in_place.r8asm > /tmp/i.rot8 +; r8forge_tape_run /tmp/i.rot8 +; +; out 2042 2043 5 4 14 0 0 0 1 7 + +.var A 0 ; 主力 cell +.var T 1 ; 所有 _ip 宏共用的草稿 +.var B 2 ; clb_add_ip 的加数 / clb_nonzero 的被测值 +.var F 3 ; clb_add_ip、clb_nonzero 的标志位 + +; ---- clb_not_ip:5 -> ~5 = 2042 +.tp A +.xor 5 +clb_not_ip A +output A + +; ---- clb_inc_ip:2042 + 1 = 2043 +clb_inc_ip A T +output A + +; ---- clb_neg_ip:-2043 = 5(-A = ~A + 1) +clb_neg_ip A T +output A + +; ---- clb_dec_ip:5 - 1 = 4(B - 1 = ~(-B)) +clb_dec_ip A T +output A + +; ---- clb_add_ip:A += B,B 被吃掉(4 + 10 = 14) +.tp B +.xor 10 +clb_add_ip A B T F +output A +output B + +; ---- clb_nonzero:B == 0 时 F = 0(B 不动) +clb_nonzero B F T +output F +output B + +; ---- clb_nonzero:B = 7 时 F = 1(注意是 set_1 不是 flb,见 §8) +.tp B +.xor 7 +clb_nonzero B F T +output F +output B diff --git a/examples/byte_raw_ops.r8asm b/examples/byte_raw_ops.r8asm new file mode 100644 index 0000000..f3cdcbc --- /dev/null +++ b/examples/byte_raw_ops.r8asm @@ -0,0 +1,128 @@ +%include "asm/raw_add.r8asm" +%include "asm/raw_inc.r8asm" +%include "asm/raw_and.r8asm" +%include "asm/raw_or.r8asm" +%include "asm/raw_xor.r8asm" +%include "asm/raw_sub.r8asm" + +; §7.1 `raw_*` 家族(`asm/raw_*.r8asm`)的例程:raw_add / raw_inc / raw_and / +; raw_or / raw_xor,外加 §7.8 的 raw_sub。 +; +; 这一组的契约是"**操作数原样还回来**"(代价是每个宏多要一个草稿 cell): +; raw_add A B Ci S Co tmp S = A+B+Ci,Co = 进位出,A、B 不动 +; raw_inc A Ci S Co tmp S = A+Ci +; raw_and/or/xor A B S tmp 按位运算,A、B 不动 +; raw_sub A B S Bo Bc Ci buf S = A-B,A、B 不动,Bo = 没借位(1 表示 A >= B) +; +; 每个宏后面都把操作数打出来,用来确认"它们真的没被吃"。 +; `tmp` / `Bc` / `Ci` / `buf` 是草稿:raw_add 要求 tmp 干净,raw_sub 要求 +; Bc、Ci、buf 干净(重复调用时它自己会重写它们,这里还是先擦一遍)。 +; +; 纸带:r8forge examples/byte_raw_ops.r8asm > /tmp/r.rot8 +; r8forge_tape_run /tmp/r.rot8 +; +; out 300 0 200 100 52 1 201 0 200 192 240 204 252 60 5 1 15 10 2043 0 + +.var A 0 +.var B 1 +.var Ci 2 +.var S 3 +.var Co 4 +.var tmp 5 +.var Bc 6 +.var Bo 7 +.var buf 8 + +; ---- raw_add:200 + 100 = 300,没有进位,A、B 还是 200 / 100 +.tp A +.xor 200 +.tp B +.xor 100 +.tp Ci +set_0 +raw_add A B Ci S Co tmp +output S +output Co +output A +output B + +; ---- 进位出:2000 + 100 = 2100 -> S = 52(2100 - 2048),Co = 1 +.tp A +erase A +.tp A +.xor 2000 +.tp B +erase B +.tp B +.xor 100 +erase S +erase Co +raw_add A B Ci S Co tmp +output S +output Co + +; ---- raw_inc:200 + 1 = 201,A 不动 +.tp A +erase A +.tp A +.xor 200 +.tp Ci +set_1 +raw_inc A Ci S Co tmp +output S +output Co +output A + +; ---- 按位运算:240 = 0b11110000,204 = 0b11001100 +erase S +.tp A +erase A +.tp A +.xor 240 +.tp B +erase B +.tp B +.xor 204 +raw_and A B S tmp +output S ; 192 +output A ; 240,保留 +output B ; 204,保留 +raw_or A B S tmp +output S ; 252 +raw_xor A B S tmp +output S ; 60 + +; ---- raw_sub:15 - 10 = 5,Bo = 1(没借位);A、B 不动 +erase S +erase Bo +erase Bc +erase Ci +erase buf +.tp A +erase A +.tp A +.xor 15 +.tp B +erase B +.tp B +.xor 10 +raw_sub A B S Bo Bc Ci buf +output S +output Bo +output A +output B + +; ---- 反过来:10 - 15 -> S = 2043(mod 2^11 的 -5),Bo = 0(有借位) +erase S +erase Bo +.tp A +erase A +.tp A +.xor 10 +.tp B +erase B +.tp B +.xor 15 +raw_sub A B S Bo Bc Ci buf +output S +output Bo diff --git a/examples/digits_demo.r8asm b/examples/digits_demo.r8asm new file mode 100644 index 0000000..bba3e8a --- /dev/null +++ b/examples/digits_demo.r8asm @@ -0,0 +1,43 @@ +%include "asm/digits.r8asm" + +; §7.7 `clb_digits`(整数 -> 4 位 ASCII 十进制,18 cell)的例程。 +; +; clb_digits N REG S ; REG..REG+3 = '0'..'9',高位在前,定长 4 位 +; +; 做法是"divmod 只出现一次":外面套一个跑 4 次的运行期循环,每轮把已经写好的 +; 数字整体往高地址挪一格,新数字永远写 REG+0。所以输出是**定长 4 位、左边补 '0'**, +; 11 位 cell(0..2047)正好 4 位十进制。 +; +; 两个用例:1234 -> "1234"、7 -> "0007"。第二个用另一块干净的 REG/S +; (第一个用过的格子已经被写脏了,而 clb_digits 要求 REG 和 S 进来是干净的)。 +; +; 纸带:r8forge examples/digits_demo.r8asm > /tmp/dg.rot8 +; r8forge_tape_run /tmp/dg.rot8 +; (输出是 ASCII 码:48 = '0'、49 = '1'、...) +; +; out 49 50 51 52 48 48 48 55 + +.var N 0 ; 值(被吃干净) +.var REG 1 ; REG..REG+3 是第一个输出区 +.var S 5 ; 第一块草稿(S..S+12) + +.var REG2 18 ; 第二个输出区 +.var S2 22 ; 第二块草稿(S2..S2+12) + +; ---- 1234 -> '1' '2' '3' '4' +.tp N +.xor 1234 +clb_digits N REG S +output REG + 0 +output REG + 1 +output REG + 2 +output REG + 3 + +; ---- 7 -> '0' '0' '0' '7' +.tp N +.xor 7 +clb_digits N REG2 S2 +output REG2 + 0 +output REG2 + 1 +output REG2 + 2 +output REG2 + 3 diff --git a/examples/divmod_demo.r8asm b/examples/divmod_demo.r8asm new file mode 100644 index 0000000..6e035b4 --- /dev/null +++ b/examples/divmod_demo.r8asm @@ -0,0 +1,43 @@ +%include "asm/divmod.r8asm" + +; §7.6 除法/取模(`clb_divmod`,11 cell)的例程。 +; +; clb_divmod N D Q R S ; Q = N div D,R = N mod D +; +; 二进制长除法,固定跑 `_CELL_SIZE` 轮(11 轮),**跟 N、D 的值无关**。 +; 旧版是重复减法、O(N/D),下面第二个例子(`D = 1`)在旧版上会直接撞 +; 500 万步上限;现在两个用例都是十一轮(约三万步)。 +; +; 契约:N、D 保持原样(可以反复用),Q 由宏清零后累加,R 自己一格, +; S 起 7 个连续草稿格。**草稿格进来不要求干净**(只有 S+5 的拷贝缓冲要在 +; 第一次用之前是干净的),所以同一个 S 块连续用两次没问题 —— 这里就是这么做的。 +; +; 纸带:r8forge examples/divmod_demo.r8asm > /tmp/d.rot8 +; r8forge_tape_run /tmp/d.rot8 +; +; out 204 7 2047 10 2047 0 + +.var N 0 +.var D 1 +.var Q 2 +.var R 3 +.var S 4 ; S..S+6 是 7 格草稿 + +; ---- 2047 / 10 = 204 余 7 +.tp N +.xor 2047 +.tp D +.xor 10 +clb_divmod N D Q R S +output Q +output R +output N ; 保留 +output D ; 保留 + +; ---- 把 D 换成 1,再算一次:2047 / 1 = 2047 余 0(旧版在这里 HANG) +erase D +.tp D +.xor 1 +clb_divmod N D Q R S +output Q +output R diff --git a/examples/full_add.r8asm b/examples/full_add.r8asm index 9c3c361..e94b217 100644 --- a/examples/full_add.r8asm +++ b/examples/full_add.r8asm @@ -7,6 +7,8 @@ ; ; map 的每一项是那个输入组合下 %4%5 的取值(bit0 = %4, bit1 = %5), ; 顺序是输入组合 000,001,...,111。 +; 这个文件本身也是个能跑的程序:输入 cell 全 0(A=B=Ci=0),所以 S=0、Co=0。 +; out 0 0 %synth fulladd params 6 map 0 1 1 2 1 2 2 3 diff --git a/examples/full_add_cost.r8asm b/examples/full_add_cost.r8asm index cffc8a9..da10fee 100644 --- a/examples/full_add_cost.r8asm +++ b/examples/full_add_cost.r8asm @@ -2,6 +2,8 @@ ; 按纸带长度搜索得到的最优解:6 个块,模型代价 75(5 层那版是 82)。 ; 这个文件不走 %synth,直接手写,用来实测真实长度并跑虚拟机。 +; 输入全 0,所以 S=0、Co=0。 +; out 0 0 .var A 0 .var B 1 .var Ci 2 diff --git a/examples/full_add_flat.r8asm b/examples/full_add_flat.r8asm index d60b6cd..0fb79b2 100644 --- a/examples/full_add_flat.r8asm +++ b/examples/full_add_flat.r8asm @@ -2,6 +2,8 @@ ; 步长无关:metric flat 不计 .tp 的行走代价,结果与 cell 布局无关, ; 所以一份缓存能用在任何调用点(代价是纸带比按实际布局最优的长一点)。 +; 输入全 0,所以 S=0、Co=0(组合全查靠 r8forge_synth_test)。 +; out 0 0 %synth fulladd_flat params 6 map 0 1 1 2 1 2 2 3 diff --git a/examples/full_add_flat_spaced.r8asm b/examples/full_add_flat_spaced.r8asm index 49a06b7..5c5f7d9 100644 --- a/examples/full_add_flat_spaced.r8asm +++ b/examples/full_add_flat_spaced.r8asm @@ -3,6 +3,8 @@ ; 同一个 metric flat 块,只是额外写了 layout 0 2 4 6 8 10。 ; flat 不看布局,所以它命中 full_add_flat.r8asm 的同一份缓存,发射出完全相同的纸带 ; —— 这正是"步长无关、可跨调用点复用"的证据。 +; 输入全 0,所以 S=0、Co=0。 +; out 0 0 %synth fulladd_flat params 6 map 0 1 1 2 1 2 2 3 diff --git a/examples/full_add_layers.r8asm b/examples/full_add_layers.r8asm index 82763e8..c4d3f9d 100644 --- a/examples/full_add_layers.r8asm +++ b/examples/full_add_layers.r8asm @@ -1,5 +1,8 @@ %include "asm/lib.r8asm" +; mode layers:只要层数最少(快),不按纸带长度搜。 +; 输入全 0,所以 S=0、Co=0。 +; out 0 0 %synth fulladd_fast params 6 map 0 1 1 2 1 2 2 3 diff --git a/examples/full_add_stat.r8asm b/examples/full_add_stat.r8asm index 76d1ba2..5d6409b 100644 --- a/examples/full_add_stat.r8asm +++ b/examples/full_add_stat.r8asm @@ -1,5 +1,8 @@ %include "asm/lib.r8asm" +; stat 直接给整张状态表(2^6 项),不经过 map 的"输入在前"约定。 +; 输入全 0,所以 S=0、Co=0。 +; out 0 0 %synth fulladd_stat params 6 stat 0 9 10 19 12 21 22 31 0 9 10 19 12 21 22 31 0 9 10 19 12 21 22 31 0 9 10 19 12 21 22 31 0 9 10 19 12 21 22 31 0 9 10 19 12 21 22 31 0 9 10 19 12 21 22 31 0 9 10 19 12 21 22 31 diff --git a/examples/mul_demo.r8asm b/examples/mul_demo.r8asm new file mode 100644 index 0000000..e99cbc1 --- /dev/null +++ b/examples/mul_demo.r8asm @@ -0,0 +1,64 @@ +%include "asm/mul.r8asm" + +; §9 乘法器(`clb_mul`,10 cell)的例程。 +; +; clb_mul MC MUL PL PH MCA S Ci T F NR ; (PH:PL) = MC * MUL +; +; 算法是**移位-加法**(竖式乘法),固定跑 `_CELL_SIZE` 轮,跟乘数的值无关: +; A:PH = 0 ; C:F = 0 ; Q:PL = MUL +; 每轮: if Q 的最低位: (C:PH) += MC ;然后 (C:PH:PL) >>= 1 +; W 轮之后 (PH:PL) 就是积;PL 原来装乘数,被移空,所以 **MUL 结束为 0**, +; MC 保持原样。积可能超过一个 cell(11 位),高半在 PH 里。 +; +; 这里算两个:82 * 141 = 11562(低半 1322、高半 5),以及 +; 2047 * 2047(11 位域里最大的一对,旧版重复加法到这儿直接 HANG)。 +; 两轮各用一块 cell,互不干扰。 +; +; 纸带:r8forge examples/mul_demo.r8asm > /tmp/m.rot8 +; r8forge_tape_run /tmp/m.rot8 +; +; out 1322 5 82 0 1 2046 + +; 82 * 141 +.var MC 0 +.var MUL 1 +.var PL 2 +.var PH 3 +.var MCA 4 +.var S 5 +.var Ci 6 +.var T 7 +.var F 8 +.var NR 9 + +; 2047 * 2047(整块换一份干净草稿) +.var MC2 10 +.var MUL2 11 +.var PL2 12 +.var PH2 13 +.var MCA2 14 +.var S2 15 +.var Ci2 16 +.var T2 17 +.var F2 18 +.var NR2 19 + +; ---- 82 * 141 = 11562 = 5 * 2048 + 1322 +.tp MC +.xor 82 +.tp MUL +.xor 141 +clb_mul MC MUL PL PH MCA S Ci T F NR +output PL +output PH +output MC ; 被乘数保留 +output MUL ; 乘数被移空 + +; ---- 2047 * 2047 = 4190209 = 2046 * 2048 + 1 +.tp MC2 +.xor 2047 +.tp MUL2 +.xor 2047 +clb_mul MC2 MUL2 PL2 PH2 MCA2 S2 Ci2 T2 F2 NR2 +output PL2 +output PH2 diff --git a/examples/sum_loop.r8asm b/examples/sum_loop.r8asm new file mode 100644 index 0000000..b4892d2 --- /dev/null +++ b/examples/sum_loop.r8asm @@ -0,0 +1,41 @@ +%include "asm/ones.r8asm" + +; §5.1 动态循环(`clb_ones` + `loop`/`endloop`)+ §7.5 `clb_ones` 的例程: +; 算 1 + 2 + ... + N,N 是**运行期**的值(不是汇编期常数)。 +; +; clb_ones N C T F ; C = N 个 1,N 被吃掉 +; loop C ... endloop C ; 每圈吃掉 C 里的一个 1 —— 跑几圈由数据决定 +; +; 11 位 cell 装得下 0..2047,这里取 N = 10(1+...+10 = 55)。N = 0 时 `biz` +; 直接跳过,一圈不跑(和也是 0)—— 这就是"次数来自数据"和 `%rep` 的区别。 +; 循环体只出现一次,所以纸带长度和 N 无关,运行是 O(N);`clb_add_ip` 自己又是 +; O(当前项),整体 O(N^2),N <= 2047 时几十万步以内。 +; +; 纸带:r8forge examples/sum_loop.r8asm > /tmp/s.rot8 +; r8forge_tape_run /tmp/s.rot8 +; +; out 55 0 0 + +.var N 0 ; 项数(会被 clb_ones 吃掉,结束为 0) +.var C 1 ; 循环配额:N 个 1,跑完是 0 +.var I 2 ; 当前项 +.var S 3 ; 累加和 +.var T 4 ; _ip 家族的草稿 +.var F 5 ; clb_add_ip 的标志 +.var buf 6 ; copy 的缓冲(必须是干净的) +.var tmp 7 ; 当前项的副本 + +.tp N +.xor 10 +clb_ones N C T F ; C = 10 个 1,N 变成 0 + +loop C + clb_inc_ip I T ; I += 1 + .tp I + copy tmp buf ; tmp = I(copy 保留 I;缓冲自己会转干净) + clb_add_ip S tmp T F ; S += tmp,tmp 被吃掉 +endloop C + +output S +output C +output N diff --git a/tests/examples_test.cc b/tests/examples_test.cc new file mode 100644 index 0000000..17c6823 --- /dev/null +++ b/tests/examples_test.cc @@ -0,0 +1,196 @@ +// Runs every program in examples/ and compares its OUT stream with the one +// written in the file header: +// +// ; out 254 0 1024 ... +// +// The marker is part of the example's documentation -- a reader sees at a +// glance what the program prints -- and this test is what keeps the doc true: +// an example that stops printing what its header says is a broken example, and +// one that does not assemble at all would otherwise rot silently. +// +// It is also the only place that runs examples/*.r8asm: the %synth ones are +// covered combination by combination by r8forge_synth_test, but every file in +// examples/ is still a stand alone program, so it has to keep running. +// +// r8forge_examples_test [examples dir] default: examples +#include "r8forge/r8asm.hh" +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace { + +struct machine { + std::vector cells = std::vector(kDefaultMemoryCells, 0); + std::vector out; + size_t dp = 0; + size_t steps = 0; + bool finished = true; // false: the step limit ran out + + static uint16_t ror(uint16_t v) { + return uint16_t((v >> 1) | ((v & 1u) << (kDefaultCellSize - 1))); + } + + void run(const std::string &tape, size_t limit = 5'000'000) { + for (size_t pc = 0; pc < tape.size(); pc++) { + if (++steps > limit) { + finished = false; + return; + } + switch (tape[pc]) { + case '>': + dp = (dp + 1) % cells.size(); + break; + case '<': + dp = (dp + cells.size() - 1) % cells.size(); + break; + case '-': // flb + cells[dp] ^= 1; + break; + case '+': // ror + cells[dp] = ror(cells[dp]); + break; + // biz / rnz test the LOW BIT, not "is the cell zero" (ROT-8-viz + // src/rot8.c). Reading them as a Brainfuck style zero test makes every + // byte level program look like an endless loop. + case '[': + if ((cells[dp] & 1) == 0) { + int depth = 1; + while (depth) { + pc++; + if (tape[pc] == '[') + depth++; + else if (tape[pc] == ']') + depth--; + } + } + break; + case ']': + if ((cells[dp] & 1) == 1) { + int depth = 1; + while (depth) { + pc--; + if (tape[pc] == ']') + depth++; + else if (tape[pc] == '[') + depth--; + } + } + break; + case '.': + out.push_back(cells[dp]); + break; + default: // ',' (input) is not modelled + break; + } + } + } +}; + +// import_file() only reports what the parser found; an unknown macro is found +// while the tree is expanded, and a truncated tape still runs and prints +// something plausible. Same order as r8forge's own main. +bool assemble(const std::filesystem::path &file, std::string &tape) { + r8asm assembler; + if (!assembler.import_file(file.string(), kDefaultCellSize)) { + std::cerr << " could not assemble " << file.string() << "\n"; + return false; + } + tape = assembler.export_rot8(); + if (assembler.failed()) { + std::cerr << " could not assemble " << file.string() << "\n"; + return false; + } + return true; +} + +// The `; out 1 2 3` line in the header. Returns false when it is missing or +// carries no numbers -- the marker is required, not optional. +bool expected_out(const std::filesystem::path &file, std::vector &want) { + std::ifstream in(file); + std::string line; + while (std::getline(in, line)) { + if (!line.empty() && line.back() == '\r') + line.pop_back(); + const size_t at = line.find_first_not_of(" \t"); + if (at == std::string::npos || line[at] != ';') + continue; + std::istringstream rest(line.substr(at + 1)); + std::string word; + if (!(rest >> word) || word != "out") + continue; + std::vector values; + int v; + while (rest >> v) + values.push_back(v); + if (values.empty()) + continue; + want = values; + return true; + } + return false; +} + +std::string join(const std::vector &v) { + std::ostringstream os; + for (size_t i = 0; i < v.size(); i++) + os << (i ? " " : "") << v[i]; + return os.str(); +} + +} // namespace + +int main(int argc, char **argv) { + const std::filesystem::path dir = argc > 1 ? argv[1] : "examples"; + std::error_code ec; + std::vector files; + for (const auto &entry : std::filesystem::directory_iterator(dir, ec)) { + if (entry.path().extension() == ".r8asm") + files.push_back(entry.path()); + } + if (ec || files.empty()) { + std::cerr << "cannot read " << dir.string() << " (" << ec.message() << ")\n"; + return 2; + } + std::sort(files.begin(), files.end()); + + int failures = 0; + for (const std::filesystem::path &file : files) { + const std::string name = file.filename().string(); + std::vector want; + if (!expected_out(file, want)) { + std::cout << name << ": no '; out ...' line in the header\n"; + failures++; + continue; + } + std::string tape; + if (!assemble(file, tape)) { + failures++; + continue; + } + machine m; + m.run(tape); + std::vector got; + for (uint16_t v : m.out) + got.push_back(int(v)); + const bool ok = m.finished && got == want; + std::cout << name << ": " << tape.size() << " characters, " << m.steps + << " steps, out " << join(got) << (ok ? " ok" : " FAILED"); + if (!ok) { + std::cout << " (want " << join(want) << (m.finished ? "" : ", HANG") << ")"; + failures++; + } + std::cout << "\n"; + } + + std::cout << (failures ? "FAILED: " + std::to_string(failures) + " example(s)\n" + : "all " + std::to_string(files.size()) + + " examples print what their headers say\n"); + return failures ? 1 : 0; +}