Files
R8Forge/TODO.md
T
dsh 723b8285dd docs: record the signed number plan in AGENTS, SPEC and TODO
The four decisions are settled and the work is not done, so each fact goes where it
belongs:

  SPEC 5.4   two complement, the sign bit is _CELL_SIZE-1 (-1024..1023 at 11 bits,
             -128..127 at 8 bits, symmetric, so no |MIN| trap), display -0042,
             truncating division (the remainder takes the sign of the dividend),
             silent wraparound.  Addition, subtraction and multiplication need no
             change: the arithmetic is already modulo 2^W.
  TODO       three independently verifiable steps -- clb_digits_signed (sign test
             via clb_sub_nc against HALF = 2^(_CELL_SIZE-1), negate a copy, then the
             existing digits), clb_divmod_signed (magnitudes, unsigned divide, signs
             reapplied), and the calculator unary minus when HAVE is clear.  Each
             step lists its acceptance sweep.
  AGENTS     a short pointer so the next session sees the big queued thing.

The width trap is called out in all three: HALF must be %rep _CELL_SIZE; a literal
11 would misread the sign bit on an 8 bit machine.
2026-11-18 20:20:55 +08:00

5.1 KiB
Raw Blame History

TODO

"还没做"的事都收在这一个文件里,别散在 README/AGENTS/docs 中。每条写清楚为什么值得做和 从哪开始;做完就删掉(历史在 git log 里)。SPEC.md §12 那张"已经确认走不通"的表是 结论,不是待办,别混进来。

已经做完、从这份清单里移出去的:桌上计算器(examples/calc.r8asm,11 位 62585 字符、三方 一致、位宽矩阵见 tests/widths.ps1)、INP 整格写入的语义修正、参考虚拟机支持 >64k 纸带。

有符号数(三步走,约定见 SPEC §5.4)

表示法、显示格式、除法语义、溢出行为都已经定死,剩下三个可独立验收的步骤:

  1. clb_digits_signed N REG S T F:T = |N| 的副本,F = 符号位。判负用 clb_sub_nc T HALF(HALF = 2^(_CELL_SIZE-1),必须 %rep _CELL_SIZE,写死 11 会 在 8 位机器上把符号位判错),负数先 output 45 再对副本 clb_neg_ip,最后走现有 clb_digits。验收:2048 个值全扫,期望串在 C++ 里按 x >= 2^(W-1) ? x - 2^W : x 算, 2047 -> -0001、1024 -> -1024、0 -> 0000。
  2. clb_divmod_signed N D Q R S T1 T2 F:取符号 → 各自绝对值 → 调 clb_divmod → 商的符号按异或、余数取被除数的符号(截断语义自动成立)。验收:|a|,|b| <= 32 全组合
    • 边界(0、正负 1、正负 1023、正负 1024),与 C 的除法和取余逐项比。
  3. 计算器的一元负号:字符 45 在 HAVE == 0 时置 NEG 标志,flush 时对 clb_undigits 的结果取反;HAVE == 1 时仍是减号。验收:3 5 - . -> -0002、 -5 2 * . -> -0010、-7 -2 / . -> 0003。

每步做完都能停在可用状态(第 1 步之后 clb_digits_signed 就能单独用)。

交互计算(下一步)

  • RPN 栈:现在的计算器是两寄存器(A 累加器 + P 待结算操作数),没有栈。 .tp 是汇编期常量,所以只能做"固定 N 格 + 整体挪位"的假栈:每次 push ≈ N 个 copy (约 500 字符/格)。65536 的纸带预算下 16 深可行(~12k 字符),4 深最划算;理论上 259 格内存能到 200 层,但一次 push 要 10 万字符,不现实。起点:把 calc.r8asm 的 A/P 换成 4 格窗口先跑通,再看要不要 16。
  • 终端纸带:提示符 + 逐字符回显 + 行编辑(退格打印 \b \b)+ 命令分派。零件都在 drv/calc_*(分派、数字攒取、显示、四则)——缺的是"长驻循环 + 落行 + 会话结束"。 验收用头部 ; in 喂一整段会话,examples_test 会自动跑。
  • 迷你 printf:clb_puts 和 load 已经有了(examples/hello.r8asm 能打一整句),还缺 %d / %c / %s 的格式化 —— 那需要"格式串 + 参数表"的约定,比 puts 复杂一档。

工具

重复清位…… 要能重算跳转偏移。配套 r8forge_tape_diff(比较两条纸带的 OUT 流和步数) 证明等价 —— 一次改动全库受益。

  • %synth --verify:把 .r8forge_cache/ 里每条结果按对应表的所有输入重跑一遍, 给"缓存已入库"兜底 —— 一条坏条目会让每次构建静默用错块。
  • CI:暂时不做。本地 ctest --test-dir build -j 4(8 条,9 秒)和 tests/widths.ps1 (位宽矩阵,约 20 分钟)都能手动跑;act_runner 的镜像装不出 cmake,先放着。 ROT-8-viz 仍然零测试:串行默认 / -n / 几何 / 7E1 全靠手测 —— 哪天真要接 CI,先补它。
  • src/r8asm.cc:154 有个上游留下的 // TODO: FILL THE BLANK(ROT8_NODE 宏的 children 是空的)。那是继承来的实现,先记着,别顺手改。

画面

  • 把 259 格当帧缓冲:串行下 \r(0x0D)能原地重绘,1 bit/cell 的 16×16 位图或 8×8 生命游戏都能塞进纸带,rot8_test --live 里直接看它动。

要重新量的一条

  • copy 的脏缓冲:SPEC §7.7 写着"缓冲格必须干净,脏了拷贝结果是 0",但 stage 2 的探针 (缓冲 2040、源 4)里 copy 结果是对的、缓冲也自己归零了。要么那条结论当初量的是别的路径 (比如 clb_digits 里连着用的写法),要么它已经不成立 —— 写清楚之前别把两种说法都留着。 顺便:clb_bit_mov 的「吃源」契约也值得一起复验。

想清楚但没做的优化

  • clb_divmod 预计算 ~D:单轮 2019 → 973 步,估计 28.6k → 17.6k 步,纸带净 −76; 没换是因为当时指名用 raw_sub。细节和注意事项见 docs/divmod.md 第 6 节。
  • clb_divmod 里那个 495 字符的提交 copy:还是全展开的,可以想压缩的办法。

顺手清掉的小尾巴

  • viz 的 read_tape(固定缓冲那版)在 vm_test.c 改用 read_tape_alloc 之后应该没人用了: 要么删掉,要么在头注释里标 deprecated。
  • viz 的 INS_SIZE 现在只是历史常量(真正的上限是 ROT8_MAX_TAPE = 16 M 条指令), README 里可以说明一句。