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.
84 lines
4.4 KiB
Markdown
84 lines
4.4 KiB
Markdown
# 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 流和步数。
|
||
|
||
## 自己跑一遍
|
||
|
||
```sh
|
||
# 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 语义一致):
|
||
|
||
```sh
|
||
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`。
|