Files
R8Forge/examples/bit_adder.r8asm
dsh 3f4149c9d0 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.
2026-11-07 22:34:15 +08:00

72 lines
1.6 KiB
Plaintext

%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 ; 保留