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

84 lines
4.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`。