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.
4.4 KiB
4.4 KiB
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 + .'
两个坑(都踩过)
+HEX=/+INFILE=的路径必须是纯 ASCII。Icarus 把 plusarg 原样传下去,路径里有 中文(这个仓库就在…/文档/…下)时$readmemh收到的是乱码,内存静默留空,机器 就把一整条"全是 0 号操作码"的纸带跑完、什么都不打。要么cd进 hex 所在目录用相对 路径(tests/rtl_sim.cmake就是这么做的),要么把文件拷到 ASCII 路径。in_ready不能加!in_valid的限定。第一版写成in_ready = … && !in_valid, 于是生产者永远看不到"接受"的边沿、握手死锁 —— 只有hello这种不读输入的纸带能跑。
RTL 里几个"故意这么写"的地方
- 程序存储器读 16 位窗口(
prog_addr0/prog_addr1两次字节读):3 bit 指令会跨字节, 取指必须看到相邻两个字节。真实板子上这对应"16 位宽 ROM"、"两片 ROM"或一个移位寄存器。 - 循环栈的进出账跟跳法绑定:跳回
['本身(retest)时]必须弹栈(['重跑会 再压一次);跳回['之后一格时要留栈到循环退出。RTL 只实现前者(契约口径), 软件侧--loop-stack --retest与它对应;r8forge_tape_pack_test盯着四种组合输出一致。 biz的前向跳过是独立状态(S_SCAN):每拍读一条、不算步数,跳到配对的]之后 再多走一格。,阻塞:in_ready拉高、所有寄存器保持到in_valid;读到 0 必须显式给 (in_valid+in_data=0)。- 停机:
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。