asm: drop the design-story comments, leave the contract (and a pointer)

Seven files still opened with a paragraph about how they came to be -- "the first
version cleared the same bit four times", "the older repeated-subtraction divmod
needed 1.48M steps", "last round rejected shift-and-add because it was longer",
nested with measured step counts.  None of that tells a caller how to use the
macro, and it is exactly the material that goes stale (raw_sub's figure had been
retracted, and the numbers are SPEC's job now).  The stories already live in
docs/divmod.md and docs/byte-ops.md, so:

    digits    119 -> 80 lines     mul      125 -> 98
    divmod    106 -> 80           inc_ip    81 -> 72
    undigits   95 -> 73           raw_sub   52 -> 38
    dec_ip     21 -> 18

Each now opens with two lines: what the macro computes and where the contract
lives (SPEC section, plus docs/ when there is a design write-up).  Everything
from the `;   Macro <name>` block down -- parameter types, preconditions,
what-is-eaten, the non-obvious invariants -- is untouched, which is what
r8forge_macro_docs_test checks and what a caller actually reads.

Baseline unchanged: tape 64513, 21 byte-op items, 15 examples, 48 macros.
This commit is contained in:
dsh committed 2026-11-09 17:20:44 +08:00
1 parent ae268b9442
commit d9689f81ba
7 files changed
+21 -161

No files matched your search

+3 -6
View File
@@ -1,11 +1,8 @@
; clb_dec_ip:原地自减 A = A - 1(补码恒等式,= clb_neg_ip + clb_not_ip)。
; 契约见 SPEC §8。
;
%include "asm/inc_ip.r8asm"
; 原地自减:A <- A - 1。
;
; 没写新的位级算法,而是用补码的恒等式:
; B - 1 = ~(-B)
; 先原地取负(clb_neg_ip),再原地取反(clb_not_ip),两步都是原地、都只要一个草稿 cell。
; Macro clb_dec_ip
; %1: Cell A
; %2: Cell T
+3 -42
View File
@@ -1,48 +1,9 @@
; clb_digits:整数 -> 4 位 ASCII 十进制(高位在前、定长 4 位)。
; 契约和纸带长度见 SPEC §7.7,设计说明见 docs/byte-ops.md。
;
%include "asm/divmod.r8asm"
%include "asm/add_ip.r8asm"
; 整数 -> 十进制字符串:把值展开成 4 个连续 cell,每格低 8 位放一个 ASCII 数字。
;
; clb_digits N REG S ; REG..REG+3 得到 "2047" 那样的 4 个字节
;
; 目标形态:**ASCII '0'..'9'、高位在前、定长 4 位、左边补 '0'**。
; 11 位 cell 装得下 0..2047,也就是 4 位十进制,所以 L 写死 4。
;
; 朴素做法是 4 份 divmod(4x4499 ≈ 18k)。这里让 **divmod 只出现一次**:外面套一个
; 跑 4 次的运行期循环,而且**不做"写哪一格"的分派** —— 每轮把已经写好的数字整体
; 往高地址挪一格,新数字永远写 REG+0:
;
; 第 1 轮: 挪(空的) ; REG+0 = 个位
; 第 2 轮: 挪(个位 -> REG+1) ; REG+0 = 十位
; ...
; 第 4 轮: 挪(三位 -> 高位) ; REG+0 = 千位
;
; 挪的顺序必须**从高到低**(REG+2 -> REG+3、REG+1 -> REG+2、REG+0 -> REG+1),
; 否则先把低位搬上去会盖掉还没搬的高位。这样最后 REG+0..3 正好是千、百、十、个,
; 也就是"高位在前"的字符串,不用倒序、不用 4 个分支。
;
; **位数、挪位链、常数构建三者都跟着 `_CELL_SIZE` 走**:位数和链长用
; `%for k <count>`(见 SPEC §3.5),常数构建的尾部转数写成 `_CELL_SIZE - 5` /
; `_CELL_SIZE - 3`。11 位 -> 4 位十进制 / 3 轮挪位;16 位 -> 5 位 / 4 轮
; (实测 16 位下 `4660 -> "04660"`、`7 -> "00007"`)。
;
; (第一版是 4 个分支 + one-hot flag 分派,只跑对了第一支 —— 甩掉分派之后不仅
; 正确,还少了两层嵌套和 4 个 cell。)
;
; 三个踩过的坑:
; * **`copy` 的缓冲格必须是干净的**:缓冲带垃圾时拷贝结果是 0(实测)。
; * **`%synth` 那句老话反过来**:造常数不能"置一位转到位、再置一位转到位" ——
; 第二次旋转会把第一次放好的位一起带走;要**绕整圈走一次**。
; * **`clb_divmod` 的 N、D 现在都保留**,余数是单独一格;下一轮的 N 还是靠
; `copy` 从商搬回去(旧版是"余数就在 N 里",这里多一格、少一次搬)。
;
; 前提:N = 值(结束时为 0);REG 起 4 格、S 起 13 格连续且干净。没有负数。
;
; S 起的格子是这么排的(divmod 要一块 7 格的连续草稿,所以它挪到 S+3):
; S+0 TEN(除数) ; S+1 商 ; S+2 余数(这一位的数字)
; S+3..S+9 clb_divmod 的草稿块(Rhi、Sd、Bo、Cm、Ci、buf、NR)
; S+10 轮数计数器(loop) ; S+11/S+12 clb_add_ip 的 T、F
; Macro clb_digits
; %1: Cell N
; %2: Cell REG
+3 -29
View File
@@ -1,35 +1,9 @@
; clb_divmod:二进制长除法(移位-恢复),商 Q、余数 R 各占一格,N、D 保留。
; 契约见 SPEC §7.6,设计推理和实测见 docs/divmod.md。
;
%include "asm/raw_sub.r8asm"
%include "asm/raw_or.r8asm"
; 除法/取模:Q = N div D,R = N mod D。
;
; 算法是**二进制长除法(移位-恢复)**,从被除数的最高位往下一位一位串:
;
; R = 0 ; Q = 0
; while 还剩一位没看:
; R = (R << 1) | (N 的下一位)
; if R >= D: R -= D ; 商位 = 1 else: 商位 = 0
;
; 轮数 = 位宽(11 轮),**跟 N、D 的值无关** —— 这是它取代"重复减法"的唯一理由:
; 旧版 O(N/D),`2047/1` 要 2047 轮、直接撞 500 万步上限(实测 HANG;`2047/2` 是
; 246 万步)。现在 2047/10 和 2047/1 一样是十一轮。
;
; 三个细节(都是设计时推过、实测确认的):
;
; 1. **W+1 位的比较拆成"一个 W 位减法 + 一个布尔"**:R 左移一格之后最多 W+1 位,
; 最高位就是 Rlo 左旋绕回来的那一位(记 H)。H = 1 时 R >= 2^W > D 必然提交,
; 而且 R - D 的低 W 位正好就是 S = Rlo - D(mod 2^W);H = 0 时就是普通的
; "Rlo >= D 才提交"。所以**提交条件 = H | Bo**,一条 clb_bit_or 就够,不用真去
; 做 W+1 位减法。H 只在轮内活着:提交之后 R < D < 2^W,下一轮开头高位是 0
; (所以 docs/divmod.md §2 里那个"新高位 = H & Bo"恒为 0,不用算、也不用留 cell)。
; 2. **R 的跨格左移**:rol 把 Rlo 的最高位绕回 bit0,所以先 clb_bit_mov 把它搬进
; Rhi(搬的同时清掉绕回位),再 bit_copy 把 N 的 LSB 注进 Rlo 的 bit0。
; 顺序反了就丢位 —— `clb_mul` 当年在这里返工两轮。
; 3. **N 不被消耗**:每轮 rol 一次,转满 W 轮自己复原;注入用 bit_copy(保留源)。
; D 每轮都要拿去比/减,所以用保留操作数的 raw_sub(这就是它存在的理由)。
;
; 除零没有定义:调用者保证 D >= 1(D = 0 时 R >= 0 恒成立,商会变成全 1)。
; Macro clb_divmod
; %1: Cell N
; %2: Cell D
+3 -12
View File
@@ -1,17 +1,8 @@
; clb_inc_ip:原地自增 A = A + 1(A、T 两个 cell)。
; 契约见 SPEC §8。
;
%include "asm/not_ip.r8asm"
; 原地自增:A <- A + 1,结果留在 A 里,只要两个 cell(A 和草稿 T)。
;
; 关键是把"还要转多少格"这个计数塞进 T 的低位那一串 1 里:
; T 先做成 0xFF,每转一格就 `set_0` + `ror` 消掉一个 1 —— 一串 1 的长度就是剩余圈数。
; 于是不需要第三个 cell,也不需要"无条件翻转"(那在 ROT-8 里表达不出来)。
;
; 三步:
; 1. 最低位连续的 1 逐个清掉(边清边转,同时消计数器);遇到第一个 0 停下;
; 2. 那个 0 翻成 1(输入是 0xFF 时计数器正好是 0,这一步跳过 —— 结果就是 0);
; 3. 剩下的位置只旋转,转到整圈走完为止。
; 三段合起来 A 正好转八格,所以位置对得上。
; Macro clb_inc_ip
; %1: Cell A
; %2: Cell T
+3 -30
View File
@@ -1,36 +1,9 @@
; clb_mul:二进制移位-加法乘法器,(PH:PL) = MC * MUL。
; 契约见 SPEC §9,设计说明见 docs/byte-ops.md。
;
%include "asm/lib.r8asm"
%include "asm/raw_add_nc.r8asm"
; 一个 cell × 一个 cell -> 两个 cell 的积(11 位下是 22 位)。
;
; 算法是**二进制里最朴素的那条:移位-加法**,从乘数的最低位往上走一位一位串:
;
; A:PH = 0 ; C:F = 0 ; Q:PL = MUL
; while 还剩一位没看:
; if Q 的最低位 == 1: (C:PH) += MC ; 一次 W 位加法,进位出到 F
; (C:PH:PL) 右移一位 ; 最高位补 0,C 移进 PH 的最高位
;
; 这就是竖式乘法:被乘数不动,每轮只看乘数的一位,是 1 就把被乘数加到积的高半上,
; 然后把整个积往右挪一位,乘数也一起挪。W 轮之后 (PH:PL) 就是积,Q 的位被吃干净
; (所以 MUL 结束为 0,和原来的约定一样)。
;
; **为什么换掉原来的重复加法**:重复加法的轮数 = MUL 的值,所以运行代价 ∝ MUL
; (MUL=255 时约 100 万步,2047 时直接撞 500 万步上限,HANG)。移位-加法固定做
; _CELL_SIZE 轮,每轮一次 W 位加法(乘数那一位是 0 时整段跳过),所以总步数有个
; 上界:11 位下最坏 26123 步(2047 * 2047),**不随操作数的大小增长** ——
; 乘数再大也跑得完。代价是小乘数(0、1)反而比旧的重复加法慢一点点。
;
; 两个 cell 的细节:
; * (C:PH:PL) 得当成一个 2W+1 位的移位寄存器,**跨格移位**这么拼:先 ror 三格,
; 再把各自要注入的那一位搬到 bit0 用 clb_bit_mov 搬过去,最后 ror 回来 ——
; F 的那一位进 PH 的最高位,PH 的最低位进 PL 的最高位,PL 的最低位(刚看过的
; 乘数位)丢掉。顺序必须是"低位那对先搬",否则搬完 PH 的 bit0 就没了。
; * 进位不能丢:W 位加法的进位出到 F,下一轮右移时它正好被移进 PH 的最高位。
; 所以 F 不是草稿,是移位寄存器最高那一位。
;
; 计数器 NR:_CELL_SIZE 个 1,每轮 set_0 + ror 吃掉一个(和 clb_inc_ip 的计数法子一样),
; 一串 1 的长度就是剩余轮数 —— 于是"做几轮"这件事不占纸带长度,只占纸带的运行时间。
; Macro clb_mul
; %1: Cell MC
; %2: Cell MUL
+3 -17
View File
@@ -1,23 +1,9 @@
; raw_sub:保留 A、B 的减法 S = A - B;Bo = 1 表示 A >= B(没借位)。
; 契约见 SPEC §7.8。
;
%include "asm/raw_add.r8asm"
%include "asm/not_ip.r8asm"
; 保留操作数的减法:S = A - B,而且 **A、B 都不动**,另外给出借位 Bo。
;
; 为什么需要它:`clb_sub_nc` 会把 A 和 B 都吃干净,所以旧的"重复减法"除法器
; 每一轮都得 copy 出两个副本(每个 495 字符、每次约五百步),轮数还随商长大
; (`2047/10` 实测 495,986 步、`2047/1` 直接 HANG)。二进制长除法每一轮都要拿
; 同一个除数去比/减,必须有个"不破坏操作数"的减法。
;
; 做法就是把 `raw_add`(它本来就保留 A、B)套上补码:
;
; S = A + ~B + 1 = A - B
;
; 于是进位输出 Co 就是"没有借位"——`clb_sub_nc` 也是这样,但那个是破坏性的。
; **Bo 就是 Co,不取反**:Bo = 1 表示 A >= B(实测 15-10 -> Bo=1、10-15 -> Bo=0)。
; (早先这里写过"Bo = 1 表示 A < B",是错的;底下那段注释解释了为什么不能取反。)
;
; 前提:A、B 的值 < 2^_CELL_SIZE(B 取反后和 A 相加不会溢出到第 W+1 位以外的解释)。
; Macro raw_sub
; %1: Cell A
; %2: Cell B
+3 -25
View File
@@ -1,31 +1,9 @@
; 十进制数字 -> 整数:clb_digits 的逆操作。
; clb_undigits:4 位 ASCII 十进制 -> 整数,clb_digits 的逆。
; 契约见 SPEC §7.9。
;
; clb_undigits REG N S
; clb_digits N REG S ; 反方向,位数和格子约定一样
;
; REG 起 D 个连续 cell,每个 cell 的低 7 位当成一个 ASCII 数字('0'..'9');
; 拼出来的整数写进 N。D = _CELL_SIZE*30103/100000 + 1,也就是
; floor(W*log10(2)) + 1 —— 11 位下是 4 位十进制,和 clb_digits 写的位数
; 完全一致,所以 digits -> undigits 能原样转回来(实测 0..2047 全部)。
;
; **不做合法性判定**(和 clb_digits 一样):每个 cell 只取低 7 位,再和 48
; 异或 —— 对 '0'..'9' 来说 x^48 正好是 x-48(高两位相同),所以不需要减法。
; 超出 '0'..'9' 的输入会算出一个确定但没有意义的数;高位(第 7 位以上)
; 直接忽略,所以格子里的垃圾不会影响结果。
;
; REG 起 D 格被吃干净(每轮把当前位当加数用掉,其余整体下移一格),
; N 被覆盖写入。S 起 11 格草稿:
; S+0 TEN(乘数 10) ; S+1 轮数计数器 ; S+2 copy 的缓冲
; S+3..S+10 clb_mul 的草稿(PL、PH、MCA、S、Ci、T、F、NR)
;
; 算法是 Horner:
; N = 0
; repeat D: N = N*10 + 当前位 ; 数字整体下移一格
; 乘 10 用现成的 clb_mul(纸带里它只出现一次),所以整条纸带 ~6.6k,
; 比 clb_digits 小一半 —— 反方向不需要除法,一位一位乘上去就够了。
%include "asm/lib.r8asm"
%include "asm/mul.r8asm"
;
; Macro clb_undigits
; %1: Cell REG
; %2: Cell N