Files
R8Forge/docs/calc.md
T
dsh 0c218abf32 calc: a 3 cell RPN stack -- nesting now works
The two register machine (A accumulator + P pending operand) could not nest:
"1 2 + 3 4 * + ." printed 0007 because the second operator overwrote the
first.  The calculator now keeps a 3 cell stack (S0 is the top), operators run
immediately (pop two, push one), '.' is a real peek (repeated '.' shows the
same value, and it no longer flushes anything), and ',' clears both the stack
and the depth.

Depth is counted in DEPTH because the unary minus rule needs it: '-' is unary
iff the stack is empty.  The previous "the previous character was an operator"
rule is wrong for a stack machine -- in "1 2 + -" the minus has to be a binary
subtraction (popping an empty cell yields 0, and 0 - top is exactly a
negation); treating it as unary would silently swallow the sign.  The
"have == 0" rule from the original plan was already wrong for the old machine
("2 * -5" would lose its minus).

Sizing was driven by the tape: every push/pop is one copy per stack cell
(~500 characters), and the file has to stay under 65536.  So 3 cells instead
of the 16 the TODO dreamed of: push is two copies (S2<-S1, S1<-S0), an
operator is two more (S1<-S2, then the result), and the new number is written
straight into clb_undigits' target cell (it erases N itself) so the extra
"result -> top" copy disappears -- that one was worth 540 characters.  S2 sits
in cell 33, the freed OP cell: putting it at 51 cost 3.7k in walking alone.

64983 characters (was 62624) and 246142 steps for "12 34 + ." (was 280645 --
the old settle-the-pending-OP block is gone).  The file header carries the
measured session list, the nesting cases, the stack move order (high to low,
or the source gets overwritten) and the older "2047 3 / ." caveat; docs/calc.md
gets the stack section, and SPEC 5.4/7.10 now point at DEPTH instead of NEED.
2026-11-18 21:45:00 +08:00

7.2 KiB
Raw Blame History

桌上计算器(RPN)设计与分阶段计划

目标:examples/calc.r8asm —— 一条长驻的纸带,跑了就是一个 RPN 计算器 (3 格栈,S0 是栈顶;有符号数):

> 12 34 + .
0046
> 1 2 + 3 4 * + .
0015
> -5 2 * .
-0010
> ,

条件已经齐了:inp 在三份 VM 里都有实现、tape_run/derive 能用 -i 喂输入、例程头部能写 ; in(examples_test 会把那串字符交给 inp)。

1. 命令协议

输入 动作
'0'..'9' 攒进 4 位数字缓冲(遇到终止符一次性 clb_undigits 换成整数,压栈)
'*' '+' '-' '/' 弹两个、算、压回;'-' 在栈空时是一元负号(§7)
'.' 打印栈顶,不动栈(clb_digits_signed + 4 个 output)
',' 清栈(内容和深度一起归零)
其它(空格/回车) 忽略(作为数字的终止符)
0(EOF) erase 掉循环计数器,主循环结束,纸带自然跑完

六个命令字符 * + , - . / 正好是 0x2A..0x2F 连续,数字是 0x30..0x39,所以:

t = C - 0x2A                     ; 命令: 0..5  数字: 6..15
数字  <=> C 的 bit4 == 1         ; 一次 ror×4 + biz
命令号 = t                       ; 0=* 1=+ 2=, 3=- 4=. 5=/

2. 内存地图

2. 内存地图

这张表是设计时的草图(stage 1 那会儿的格号)。真的地图在 examples/calc.r8asm 的 .var 段里,比这张表细得多(每个格都有注释:栈、窗口、运算草稿、一次性标志、 带符号数的三格)。两处已经对不上了,照文件走:A/B 现在是栈的 S1/S0, "栈深度标志"是 DEPTH(0..3)。

3. 分阶段计划(每步都能单点验证)

每个驱动都放在 drv/,用 r8forge_derive drv/<名字>.r8asm 0 -i "..." 跑,; out 逐项核对。

  1. drv/calc_lex.r8asm:只做分派。喂 "0 5 9 + - . , *",输出"这是数字(d) / 这是命令(k)"。 验证点:bit4 判断 + t 的取值范围。
  2. drv/calc_num.r8asm:"12"+终止符 → 整数 12(4 位缓冲右移 + clb_undigits)。 验证点:"0" "9" "10" "2047" 四个输入。
  3. drv/calc_disp.r8asm:整数 → > 提示符 + 4 位 ASCII + 换行。
  4. drv/calc_op.r8asm:12 34 + → 46(+ - * / 各一次)。
  5. examples/calc.r8asm:主循环 + EOF 退出 + ; in/; out 头部,进 examples_test。
  6. 有符号数(做完,见 §7):显示换 clb_digits_signed、除法换 clb_divmod_signed、 加一元负号。3 5 - . → -0002、-5 2 * . → -0010、-7 -2 / . → 0003。
  7. RPN 栈(做完,见 §4):3 格栈 + 运算符立刻算 + '.' 真 peek。1 2 + 3 4 * + . → 0015。

4. 栈:3 格,不用指针(做完)

.tp 是汇编期常量、没有间接寻址,所以不要做动态栈指针。实际落地的是 3 个固定格 S0..S2(S0 = 栈顶):

push(新数)  : S2 <- S1 ; S1 <- S0 ; 新数直接 clb_undigits 进 S0
op(a=S1,b=S0): 算进 RES ; 然后 S1 <- S2 ; S2 清掉 ; RES -> S0
'.'         : 只显示 S0(真 peek,"1 2 3 . . ." 连打三次 3)
','         : S0、S1、S2 和 DEPTH 一起清零

挪动的次序不能反(从高往低搬,否则还没搬的源被新值盖掉)。代价:push 2 次 copy (~1k 字符)、一次运算 2 次 copy —— 这也是为什么是 3 格而不是计划里的 16:簿记下来 一格一次 copy(~500 字符),16 格光 push 就要 8k,这条纸带直接冲到 7 万以上。

3 格够算 1 2 + 3 4 * +(最深用到 3);超过了就把最底下那个挤掉,跟老式计算器一样。 深度是要数的(DEPTH:push +1、算一次 -1),一元负号的判据就是 DEPTH == 0。 数深度的减法要挡住下溢(空栈再算一次会绕成全 1,之后的 '-' 就判错了)。

和旧的两寄存器版本(A 累加器 + P 待结算操作数)比,栈买到的是嵌套: 旧版 1 2 + 3 4 * + . 打 0007(第二个运算符把第一个覆盖了),现在打 0015。

5. 步数预算(按 11 位实测的每例代价)

动作 步数
攒一个数(clb_undigits) ≤ 36,481
+/-(clb_add_nc/clb_sub_nc) ~2.5k
*(clb_mul) ≤ 20,300
/(clb_divmod_signed) ≤ 35,202(byte_op_test 全扫的最坏值;无符号版是 31,579)
打印(clb_digits_signed) ≤ 117,606(byte_op_test 2048 个值的最坏值;无符号版 119,431)

一行 12 34 + . 实测 246,142 步(换栈之前是 280,645 —— 少了"结算旧 OP"那一段; examples/calc.r8asm 的头部写着这一轮的全部实测值)。examples_test 的上限是 2000 万步,所以会话控制在十几行以内(或把打印换成"里程表"版本,见下)。

6. 已知的坑(都在库里踩过)

  • 条件体的身体必须回到自己的条件格(净位移 0),否则 .tp 全错位;
  • copy 的缓冲格必须干净(脏了结果是 0);
  • 用 loop/endloop 计数器时,erase 计数器就能提前退出(EOF 就这么退);
  • 库宏每轮都重建 TEN 和轮数计数器 —— 这个终端的常量区(cell 32..43)就是为了把这些 搬到循环外,v2 再让 clb_undigits/clb_digits 支持"外部常量"版本。

7. 有符号数(第 6 步,做完)

约定在 SPEC §5.4、宏在 SPEC §7.10。计算器这边只动三处:

  1. 显示:clb_digits → clb_digits_signed(负数自己打 '-',然后打 |栈顶| 的定宽四位)。

  2. 除法:clb_divmod → clb_divmod_signed(截断、余数随被除数)。加、减、乘不用动, 二补码的模 2^W 运算天然对。

  3. 一元负号:判据是 cell DEPTH(栈深):

    DEPTH == 0(空栈)时字符 45 是一元负号:置 NEG、清 ISCMD(第 3 步据此这一轮 不算);下一个压栈的数在 step 2 里被 clb_neg_ip 取负。DEPTH != 0 时它就是 二元减号。注意 a 弹空了就是 0,0 - 栈顶 正好等于取负 —— 所以栈深只有 1 时 '-' 的两义性没有实际后果。

为什么不用"HAVE == 0 就当作一元负号"(最初的计划就是那样):HAVE 只表示"正在攒 数字",打完运算符之后它也是 0,于是 2 * -5 里的负号会被判成二元减号,结果错。

为什么也不用"上一个字符是运算符"(两寄存器版本就是这么写的):栈机器里 1 2 + - 的 '-' 是二元减法(拿栈顶去减那个"弹空了的 0"),按"上一个是运算符"判会把它 当一元负号、那个负号就被吞掉了。所以判据必须是栈的状态(深度),不是输入的历史。

作废的旧例子:2047 3 / . → 0682 是无符号时代的。有符号之后 2047 的位型是 -1, -1/3 截断成 0,现在打 > 0000;要 341 就写 1023 3 / .。能打的整数范围从 0..2047 变成 -1024..1023。

实测(r8forge_tape_run):3 5 - . → > -0002、-5 2 * . → > -0010、 -7 -2 / . → > 0003、-1024 2 / . → > -0512。纸带 59519 → 62624(两套包装宏

  • 一元负号)→ 64983(再换成 3 格栈,+2.4k)。