Files
R8Forge/examples/base_macros.r8asm
T
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

75 lines
1.7 KiB
Plaintext

%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