Files
R8Forge/examples/byte_raw_ops.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

129 lines
2.3 KiB
Plaintext

%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