examples: one runnable routine per macro group

SPEC is the contract and drv/ is what the tests sweep, but there was no place
that showed a reader how a group is actually used.  examples/ now has one stand
alone program per group, each ending in output calls:

    base_macros.r8asm    S5   set_0 vs erase, rol/ror, copy vs bit_copy vs
                              clb_bit_mov, step
    bit_adder.r8asm      S6   4 bit ripple carry adder built from
                              clb_bit_add_nc, then bit_raw_add for the
                              preserving variant
    byte_raw_ops.r8asm   S7.1 raw_add/raw_inc/raw_and/raw_or/raw_xor/raw_sub,
                              printing the operands afterwards to show the
                              whole point of the family: they survive
    byte_clobber.r8asm   S7.2 clb_add/sub/neg/inc_nc (operands eaten) and the
                              S7.3 clb_and residue (240 & 204 -> B = 12)
    byte_in_place.r8asm  S8   not/inc/neg/dec/add_ip and clb_nonzero
    sum_loop.r8asm       S5.1 clb_ones + loop/endloop: 1+2+...+N, count from
                              data rather than from the assembler
    mul_demo.r8asm       S9   82*141 and 2047*2047
    divmod_demo.r8asm    S7.6 2047/10 and 2047/1 (the case that used to hang),
                              reusing the scratch block on purpose
    digits_demo.r8asm    S7.7 1234 and 7 -> four ASCII digits

Every header carries a `;   out 1 2 3` line: the expected OUT stream, so the
file itself says what it prints.  The new r8forge_examples_test target runs all
of examples/*.r8asm and compares that line with the real output (a file without
the marker counts as a failure), printing the tape length and step count on the
way.  That makes examples the second place after byte_op_test that checks
behaviour instead of just "it assembles", and keeps the examples from rotting as
the macros change.  The six %synth examples get the marker too: their inputs are
all zero, so they print 0 0.

All 15 examples pass.  The values in the headers were checked with
r8forge_tape_run (the second interpreter) as well as the test's own machine.

Docs: SPEC S10.3 has the table and the convention, S11 gets the test row, and
README gets a short section plus the layout list.  AGENTS records the examples
in the handoff baseline and the "verified" table.
This commit is contained in:
dsh committed 2026-11-07 22:34:15 +08:00
1 parent c2cd0e827f
commit 3f4149c9d0
20 files changed
+921 -3

No files matched your search

+2
View File
@@ -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` 全部跑一遍逐项核对(缺那行也算失败),顺带打印纸带长度和步数 |
## 已经确认走不通的(别重试)
+5
View File
@@ -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)
+27 -1
View File
@@ -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 的六种写法
```
+29 -2
View File
@@ -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)。
---
+74
View File
@@ -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
+71
View File
@@ -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 ; 保留
+124
View File
@@ -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
+60
View File
@@ -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
+128
View File
@@ -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
+43
View File
@@ -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
+43
View File
@@ -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
+2
View File
@@ -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
+2
View File
@@ -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
+2
View File
@@ -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
+2
View File
@@ -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
+3
View File
@@ -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
+3
View File
@@ -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
+64
View File
@@ -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
+41
View File
@@ -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
+196
View File
@@ -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 <algorithm>
#include <cstdint>
#include <cstdlib>
#include <filesystem>
#include <fstream>
#include <iostream>
#include <sstream>
#include <string>
#include <vector>
namespace {
struct machine {
std::vector<uint16_t> cells = std::vector<uint16_t>(kDefaultMemoryCells, 0);
std::vector<uint16_t> 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<int> &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<int> 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<int> &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<std::filesystem::path> 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<int> 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<int> 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;
}