Files
dsh 9b31a51fec hardware: M0 -- the packer, the RTL, and a simulator that agrees byte for byte
The two things software cannot check by reading its own source are the 3 bit
packing and the bracket strategy, so both got a tool and a test.

New in the library (r8forge/tape.hh, src/tape.cc): the opcode numbering (taken
from ROT-8-viz enum, so the packed image and the hardware decoder cannot drift),
text <-> opcodes, opcodes <-> 3 bit bytes, the .r8t image with its trailer and
crc32, and a machine model that runs a packed tape the way a board would.  The
model takes the bracket strategy as an option: backward scan with loop stack or
not, and jump-back-onto-the-[ (the contract) or past it (what the interpreters
do).  All four combinations print the same thing, and the step count differs by
exactly the number of taken ] instructions -- which is what the test asserts.

Found and fixed while writing it: the loop stack discipline depends on the jump
convention.  Jumping onto the [ means the [ re-pushes, so ] must pop on the jump;
jumping past it means the entry must stay until the loop exits.  Mixing them up
emptied the stack on the second iteration of the calculator main loop -- caught
by the equivalence test on examples/calc.r8asm, not by reading the code.

Tools: r8forge_tape_pack (text tape -> image + --hex for $readmemh + --verify,
727 instructions become 273 bytes for hello, 62%, and the trailer sits past the
halt so address 0 of a ROM is instruction 0), and r8forge_tape_run now reads an
image directly and takes --loop-stack / --retest.

hardware/rot8.v: the 8 bit / 64 cell machine -- 3 bit opcodes from a byte
addressed memory read as a 16 bit window, a 6 bit dp with free wrap, the loop
stack bracket jump, blocking input, halt on ip == length, and a step counter that
counts instructions rather than cycles.  hardware/tb_rot8.v loads a --hex image
and prints the OUT stream in tape_run format.

Verified with Icarus Verilog 14 (the RTL against tape_run --loop-stack --retest):
  hello        577 instructions  417 steps  10 outs
  term         16414            17643      11 (fed "lhi")
  calc         51378           166741      19 (fed "12 34 + .": prints the prompt,
                                                046 and the next prompt)
  flagship     43676           100142      93
Every OUT stream identical.  ctest -R rtl_sim runs that comparison from an 8 bit
build (11 tests in the default build now, where the RTL test self-skips because
the RTL is the 8 bit machine).

Two traps worth remembering: Icarus passes plusargs through as raw bytes, so an
absolute +HEX path containing non-ASCII (this checkout is under a Chinese
directory name) arrives mangled, $readmemh silently leaves the memory empty and
the machine obediently runs LEN steps of opcode 0 printing nothing -- run vvp
from the directory holding the hex with a relative name.  And in_ready must not
be qualified with !in_valid or the input handshake deadlocks.
2026-11-20 16:25:54 +08:00

4.4 KiB
Raw Permalink Blame History

ROT-8 硬件:这个目录里有什么

docs/hardware.md 的落地部分。三样东西都跑通了(Icarus Verilog 14.0):

文件 是什么 状态
rot8.v 机器的 RTL:8 条指令、3 bit 操作码、6 位 dp 的 64 格环、循环栈式括号跳转 ✅ 与软件逐字节一致
tb_rot8.v testbench:$readmemh 一张镜像,跑到停机,按 tape_run 的格式打印 OUT 流和步数 ✅
(工具)r8forge_tape_pack 文本纸带 → 3 bit 打包镜像 + --hex($readmemh 用) ✅ 在 tests/ 里

实测:RTL 与软件完全一致

8 位 / 64 格,tape_run --loop-stack --retest(板子实际采用的口径)对标 vvp:

纸带 指令数 步数 OUT 个数 结果
-+. 微测试 3 3 1 ✅ 打出 128
hello 577 417 10 ✅
term(输入 lhi) 16 414 17 643 11 ✅
calc(输入 12 34 + .) 51 378 166 741 19 ✅ 打出 > 12 34 + . / 046 / >
全家桶 asm/test.r8asm 43 676 100 142 93 ✅

自动化:ctest -R rtl_sim(在 8 位 / 64 格的构建里真跑,其它几何打印 SKIP)。 tests/rtl_sim.cmake 就是那一轮:汇编 → 打包 → 软件跑 → iverilog 编 → vvp 跑 → 比对 OUT 流和步数。

自己跑一遍

# 8 位 / 64 格的构建(RTL 就是这台机器)
cmake -S . -B build8 -DR8FORGE_CELL_SIZE=8 -DR8FORGE_MEMORY_CELLS=64
cmake --build build8 --config Release

# 1) 汇编 + 打包 + 出 hex
build8/Release/r8forge examples/hello.r8asm > hello.rot8
build8/Release/r8forge_tape_pack hello.rot8 -o hello.r8t --hex hello.hex --verify

# 2) 软件侧金标准(注意两个开关)
build8/Release/r8forge_tape_run hello.r8t --loop-stack --retest

# 3) RTL
iverilog -g2012 -o rot8_tb.vvp hardware/rot8.v hardware/tb_rot8.v
vvp rot8_tb.vvp +HEX=hello.hex +LEN=577

带输入的程序(calc、term):把输入写成一个文件(不要换行),用 +INFILE= 喂; 文件读完之后机器读到 0(和解释器的 EOF 语义一致):

printf '12 34 + .' > calc_in.txt
vvp rot8_tb.vvp +HEX=calc8.hex +LEN=51378 +INFILE=calc_in.txt
build8/Release/r8forge_tape_run calc8.r8t --loop-stack --retest -i '12 34 + .'

两个坑(都踩过)

  1. +HEX= / +INFILE= 的路径必须是纯 ASCII。Icarus 把 plusarg 原样传下去,路径里有 中文(这个仓库就在 …/文档/… 下)时 $readmemh 收到的是乱码,内存静默留空,机器 就把一整条"全是 0 号操作码"的纸带跑完、什么都不打。要么 cd 进 hex 所在目录用相对 路径(tests/rtl_sim.cmake 就是这么做的),要么把文件拷到 ASCII 路径。
  2. in_ready 不能加 !in_valid 的限定。第一版写成 in_ready = … && !in_valid, 于是生产者永远看不到"接受"的边沿、握手死锁 —— 只有 hello 这种不读输入的纸带能跑。

RTL 里几个"故意这么写"的地方

  1. 程序存储器读 16 位窗口(prog_addr0 / prog_addr1 两次字节读):3 bit 指令会跨字节, 取指必须看到相邻两个字节。真实板子上这对应"16 位宽 ROM"、"两片 ROM"或一个移位寄存器。
  2. 循环栈的进出账跟跳法绑定:跳回 [' 本身(retest)时 ] 必须弹栈([' 重跑会 再压一次);跳回 [' 之后一格时要留栈到循环退出。RTL 只实现前者(契约口径), 软件侧 --loop-stack --retest 与它对应;r8forge_tape_pack_test 盯着四种组合输出一致。
  3. biz 的前向跳过是独立状态(S_SCAN):每拍读一条、不算步数,跳到配对的 ] 之后 再多走一格。
  4. , 阻塞:in_ready 拉高、所有寄存器保持到 in_valid;读到 0 必须显式给 (in_valid + in_data=0)。
  5. 停机:ip >= prog_len → halted,并且这一拍不再执行(第一版漏了判断,会从纸带外 多取一条、步数多 1)。

还没做的

  • 上板(M1):RTL 已经能跑,缺的是引脚约束、时钟、串口和面板。
  • ROM 烧写格式:28C256 / 39SF010 吃裸二进制 —— tape pack -o x.bin 去掉 16 字节 trailer 即可(--hex 那份是给仿真用的)。
  • UART / 前面板 / 单步:RTL 已经留了 run / step / ip / dp / steps / halted。