diff --git a/AGENTS.md b/AGENTS.md index ba11853..b9e4284 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -181,6 +181,12 @@ powershell -File tests\widths.ps1 -Widths 32 # 32 位:整套 10 个 target 迷你 `printf`(终端纸带和计算器外壳都做完之后用处要重新评估)、以及栈要不要再深一格 (3 → 4 格现在没有预算障碍了)。 +**硬件那条线**单独放在 [`docs/hardware.md`](docs/hardware.md):ISA 已经全部实现,机器语义 +里没有任何东西能看见时间,所以"状态序列一致"就是同一台机器;文档里钉了硬件需求(含 +`biz`/`rnz` 扫描的确切边界)、ROM/RAM 预算(`ip` 至少要 17 位 —— 计算器 73624 已经越过 +历史 `INS_SIZE`)、FPGA / 分立 TTL / 机电三档载体,以及"先写 `r8forge tape pack` + RTL +testbench 对拍"的 M0~M4 路线。没开工,等选档。 + ## 索引 | 想查 | 去哪儿 | @@ -188,5 +194,7 @@ powershell -File tests\widths.ps1 -Widths 32 # 32 位:整套 10 个 target | `%synth` 语法语义、几何、宏契约、验证矩阵、边界、维护清单 | [`SPEC.md`](SPEC.md) | | 除法为什么这么写、实测步数、没做的优化 | [`docs/divmod.md`](docs/divmod.md) | | 字节级库的取舍、原地补码的突破、乘法器那一课 | [`docs/byte-ops.md`](docs/byte-ops.md) | +| 计算器的协议 / RPN 栈 / 终端外壳与三个坑 | [`docs/calc.md`](docs/calc.md) | +| 造一台真机器:硬件需求、预算、三档载体、对拍路线 | [`docs/hardware.md`](docs/hardware.md) | | 上游语言规格(`%synth` 不在里面) | `r8asm_rev/SPEC.md`(本机路径见 `AGENTS.local.md`) | | ROT-8 指令集(`BIZ`/`RNZ` 判 LSB) | `../ROT-8-viz/README.md` 与 `src/rot8.c` | diff --git a/README.md b/README.md index 8e57bea..7b8dbc5 100644 --- a/README.md +++ b/README.md @@ -149,3 +149,5 @@ ctest --test-dir build -C Release -j 4 --output-on-failure # 上面这些一次 `--profile`、缓存体检、CI。 * [`docs/calc.md`](docs/calc.md) —— 桌上计算器:命令协议、3 格 RPN 栈、终端外壳(回显/ 退格/提示符)、分阶段计划。 +* [`docs/hardware.md`](docs/hardware.md) —— 造一台真的 ROT-8:硬件需求、ROM/RAM 预算、 + FPGA / 分立 TTL / 机电三档载体、打包器与 RTL 对拍路线。 diff --git a/SPEC.md b/SPEC.md index 7c852b8..7d0073a 100644 --- a/SPEC.md +++ b/SPEC.md @@ -957,5 +957,7 @@ r8forge_tape_run t.rot8 # 打印 out 和步数 * [`docs/divmod.md`](docs/divmod.md) —— `clb_divmod` 的移位-恢复除法:每轮状态、W+1 位比较怎么拆、7 个草稿格、5 个坑、实测步数、没做的优化。 * [`docs/byte-ops.md`](docs/byte-ops.md) —— 字节级库为什么是现在这样:`raw_*` 与 `clb_*_nc` 的取舍、原地 `_ip` 的突破、乘法器从重复加法换成移位-加法的那一课。 +* [`docs/calc.md`](docs/calc.md) —— 计算器:命令协议、3 格 RPN 栈、终端外壳(回显/退格/提示符)与它的三个坑、实测步数。 +* [`docs/hardware.md`](docs/hardware.md) —— 把这台机器做出来:ISA 翻成硬件需求(含括号扫描的确切边界)、ROM/RAM 预算、FPGA / 分立 TTL / 机电三档载体、打包器与 RTL 对拍路线。 (原来 §14 的内容整段搬进了 `docs/divmod.md`,小节号从 `14.x` 改成 `1..6`。) diff --git a/docs/hardware.md b/docs/hardware.md new file mode 100644 index 0000000..af497df --- /dev/null +++ b/docs/hardware.md @@ -0,0 +1,206 @@ +# ROT-8 硬件:从规格到一台机器 + +软件这边已经到"四份虚拟机互为对拍 + 穷举测试全绿"的程度,造硬件最大的好处是**有黄金模型**: +每一条纸带、每一步的 `ip`/`dp`/cell 值都能先算出来,硬件只要逐步对上就行。这份文档是设计稿, +不是承诺;先把"机器要满足什么"和"预算多少"钉死,再挑载体。 + +## 1. 硬件的判据只有一条:状态序列 + +ISA 里**没有任何东西能看见时间**:没有计数器、没有中断、没有 `,`/`.` 的时序语义(`,` 阻塞、 +`.` 立刻)。所以硬件只要满足 + +> 第 n 条指令执行后,`ip`、`dp`、259 个 cell、输出流 与软件模型完全一致 + +就等于"同一台机器",几拍一条指令、内存多慢、能不能流水,全都不影响语义(只影响快慢)。 +这条自由是造机器的关键:**微码状态机、慢速内存、甚至转鼓,都是合法实现**。 + +## 2. 机器规格(从 `SPEC.md` §1 翻成硬件需求) + +| 项 | 值 | 硬件含义 | +|---|---|---| +| 指令 | 8 条:`>` `<` `+` `-` `[` `]` `,` `.` | **3 bit 操作码**,纸带就是 ROM/EEPROM,只读、无自修改 | +| 程序 | 线性执行,`ip` 从 0 加到尾 | 程序计数器 = 纸带地址;没有别的跳转,只有 `[`/`]` 改 `ip` | +| 数据 | **259 格**,复位全 0,`dp` 初始 0 | 数据 RAM 259 × W;`dp` 是模 259 计数器(259 是质数,故意没有 2 的幂别名) | +| `>` / `<` | `dp = (dp ± 1) mod 259` | 9 bit 计数器 + 模 259 回绕 | +| `+` | 整格右旋(bit0 补到最高位) | 没有 ALU:移位 + 回填,一格一根线 | +| `-` | 翻最低位 | 一个 XOR 门 | +| `[` (biz) | 最低位 = 0 → 跳到**配对 `]` 之后** | 前向扫描,深度计数 | +| `]` (rnz) | 最低位 = 1 → 跳**回配对 `[`(它要重跑)** | 后向扫描,深度计数 | +| `,` | 整格写入输入字符 | 阻塞到有字符;**EOF 读成 0**(见 §8) | +| `.` | 输出整格 | W ≥ 8 走串行 ASCII(低 7 位);W < 8 打十进制 | +| 停机 | `ip` 走完纸带 | 一个 `halt` 触发器 | + +括号扫描的**确切**边界(照 `ROT-8-viz/src/rot8.c` 的 `rot8_biz`/`rot8_rnz`,别按常识猜): + +``` +biz, 最低位 == 0: ip++ ; 深度=0 + while 深度 != 0 or 当前 != rnz: + 当前 == biz ? 深度++ : (当前 == rnz ? 深度-- : 跳过) + ip++ + ; 出循环时 ip 停在那个 rnz 上,主循环的 ip++ 越过它 +rnz, 最低位 == 1: ip-- ; 深度=0 + while 深度 != 0 or 当前 != biz: + 当前 == rnz ? 深度++ : (当前 == biz ? 深度-- : 跳过) + ip-- + ip-- ; 让主循环的 ip++ 把它指回那个 biz +``` + +两条容易写错的:`[` 是"跳到 `]` 后面"(差一就变成死循环);`]` 是"跳回 `[` 本身",让 `[` +重新测试(**不是** `[` 的后面)。硬件里就是两个方向的扫描状态机 + 一个 5 bit 深度计数器 +(库里最深的嵌套不到 16 层)。 + +## 3. 预算:现在的纸带要多大 + +一条指令 3 bit,8 条挤 3 字节;数据 259 格。 + +| 程序 | 指令数 | 程序 ROM (3 bit/条) | 数据 RAM (W=11 / 16) | +|---|---|---|---| +| `examples/full_add.r8asm` | 95 | 36 B | 356 B / 518 B | +| `examples/hello.r8asm` | 727 | 273 B | 同上(数据总是 259 格) | +| `examples/term.r8asm` | 21 721 | 8.1 KB | | +| `asm/test.r8asm`(全家桶) | 62 351 | 23.4 KB | | +| `examples/calc.r8asm`(11 位) | **73 624** | 27.6 KB | | +| `examples/calc.r8asm`(16 位) | 112 802 | 42.3 KB | | +| `examples/calc.r8asm`(32 位) | 336 304 | 126 KB | | + +两个直接结论: + +1. **`ip` 至少要 17 位**。历史上的 `INS_SIZE` 是 65536,但计算器接了终端之后是 73624 —— + 硬件要是按 16 位做,现在的计算器装不进去(这正是当初那条预算被花掉的代价)。 + 20 位(1 M 条)留够余量,反正 ROM 便宜。 +2. **32 位那版(126 KB)不建议做进内部 RAM**:它已经超过常见小 FPGA 的片上 BRAM + (Tang Nano 9K ≈ 58 KB、iCE40 UP5K ≈ 15 KB)。物理机默认 11 位,16 位当可选项, + 32 位留给软件。 + +## 4. 微架构 + +``` + ┌──────────────┐ 3 bit ┌───────────────┐ + │ tape ROM │──opcode──▶│ 解码/微序列 │── we, we_dp, dp±, scan ──┐ + │ (ip → 指令) │ │ (2~4 拍/指令) │ │ + └──────▲───────┘ └───────▲───────┘ ▼ + │ ip │ 状态 ┌──────────┐ + ┌──────┴───────┐ ┌────────┴────────┐ │ 数据 RAM │ + │ ip 计数器 │◀──扫描单元──│ 括号扫描 (深度) │ │ 259 × W │ + │ 17~20 bit │ ±1/扫描 └─────────────────┘ └────┬─────┘ + └──────────────┘ │ dp (9 bit, mod 259) │ + ┌────────┴────────┐ │ + │ dp 计数器 │──────── 地址 ────────┘ + │ (模 259 回绕) │ + └─────────────────┘ +``` + +* **数据通路只有三件**:右旋(`{cell[0], cell[W-1:1]}`)、翻 bit0、取 bit0。没有加法器、 + 没有比较器、没有立即数。 +* **一条指令 2~4 拍**:`FETCH → DECODE → EXEC(→ 扫描) → ip++`。1 MHz 时钟、4 拍/指令 = + 250 k 指令/秒 → 计算器一次会话(约 288 k 步)≈ 1.2 s;10 MHz 就是 0.1 s。 +* **`+`/`-` 的读改写**:单口 RAM 也能做(一拍读、一拍写),要求"同一格内完成",因为 + 语义里没有别的指令能插进来。 +* **`ip` 与 `dp` 都从 0 起**,数据 RAM 复位清零(用 FPGA 的初始化或 TTL 的复位清零脚)。 +* **停机**:`ip == 长度` → `halt`,时钟门控;前面板一个"运行/单步/复位"三档开关。 +* **步数计数器**:软件口径的"步"就是指令数,硬件加一个只读的 32 位计数器即可(面板显示, + 或 UART 报 `steps=N`),方便和 `tape_run` 的步数逐位对上。 + +## 5. 载体三档 + +### A. FPGA(建议先做这一档) + +| 项 | 选择 | +|---|---| +| 板子 | Tang Nano 9K(GW1NR-9):≈58 KB BSRAM、HDMI、板载 USB 串口,¥100 上下 | +| 能跑 | 11 位全家桶(23.4 KB)✓、16 位计算器(42.3 KB)✓、32 位 ✗ | +| 工具 | Gowin IDE 或开源的 yosys + nextpnr-gowin(后者更符合这个项目的脾气) | +| I/O | UART 115200 进/出,HDMI 画 259 格环 + `dp`/`ip`/当前格 | +| 工作量 | 300~500 行 Verilog + testbench,一个周末 | +| 速度 | 50 MHz / 4 拍 ≈ 12 M 指令/秒(比软件快一个量级,面板上能看到"瞬间算完") | + +### B. 分立 TTL("真机器",博物馆档) + +| 部件 | 选型 | 片数 | +|---|---|---| +| 程序 ROM | 29C010 / 39SF010(128 KB flash,用低 3 bit) | 1 | +| `ip` 计数器 | 74HC161 ×5(20 位) | 5 | +| 数据 RAM | 6116 ×2(2K×8,11 位用 8+3)或 1 片做 W=8 | 1~2 | +| 数据寄存器/右旋 | 74HC299 ×2(8 位通用移位寄存器)或 74HC273+多路开关 | 2~3 | +| `dp` 计数器 + 模 259 | 74HC161 ×3 + 74HC85 + 回绕门 | 4~5 | +| 括号扫描 | 74HC191 ×2(上下计数)+ 比较器,或塞进 CPLD | 3~4 | +| 控制/微码 | GAL22V10 ×2 或 ATF1502 CPLD(一片搞定解码 + 微序列) | 1~3 | +| UART | 6850 ACIA 或 ATmega/CH340 桥 | 1~2 | +| 时钟/复位/面板 | 555 或晶振、74HC14、LED/数码管 | 5~8 | +| **合计** | | **~25~35 片**,¥300~600 | + +速度:1~2 MHz、4 拍/指令 → 0.25~0.5 M 指令/秒,计算器一次会话 1~2 s ✓ 够快。 +工作量:几周(面包板先通,再画 PCB)。 + +### C. 机电(艺术品档) + +* **数据环做转鼓**:11 条磁道 × 259 格、一个读头 + 一个写头(写头在下游**一格**处)。 + `>`/`<` 的"访问"就是等下一个格脉冲;`+`/`-` 在读到写头之间的那一格时间里改好写回, + 所以每条指令 ≈ 一格时间。3000 rpm、259 格/圈 → 77 µs/格 → 288 k 步 ≈ **22 s** ✓ 比想象中快。 + 代价是机加工(或找一个旧磁鼓/软盘改)。 +* **程序做纸带**:3 bit 数据 + 1 孔同步,2.54 mm 孔距。`hello`(727 条)≈ 1.8 m ✓; + 计算器(73 624 条)≈ **187 m** ✗ —— 所以纸带只适合演示级小程序,大纸带还是进 EEPROM。 + 折中:**卡带**(FSK 1200~9600 baud)当"装载介质",23 KB 在 20~160 s 内装进 RAM。 +* 也可以只做"面板 + 真 I/O"的半机电:MCU 跑 ISA,面板是真按键/LED/数码管。 + +| | A FPGA | B TTL | C 机电 | +|---|---|---|---| +| 上手时间 | 一个周末 | 几周 | 几个月起 | +| 成本 | ¥100~300 | ¥300~600 | ¥1000+ + 机加工 | +| 速度 | 12 M 指令/秒 | 0.25~0.5 M | 40~45 k | +| 能跑全家桶/计算器 | ✓ | ✓ | ✓(慢,但够) | +| 教学/观赏性 | 中 | **高** | **最高** | +| 可改 ISA/调试 | 改一行重烧 | 换 ROM | 换凸轮/继电器 | + +建议:**A 先做**(一周内能跑真纸带),B 作为"正式机器"的目标(A 的 RTL 状态机原样翻成 +微码表,接口和时序都不变),C 当展示件。 + +## 6. 前面板 + +* `ip`(17+ bit)、`dp`(9 bit)、当前格(W bit)各一排 LED;一条"纸带定位"进度条。 +* 8 个指令灯:当前指令亮一个。 +* 259 格用 16×16 LED 矩阵或 128×64 OLED 画成**圆环**,`dp` 指的那格高亮(和 viz 一个样子)。 +* 三个按键:单步 / 运行·暂停 / 复位;一个"输入"按键(按一下给 `,` 喂一个字符)。 +* UART:一个终端窗口就是"键盘 + 打字机",计算器直接在上面用。 + +## 7. 验证方案(这是软件层白送的大礼) + +1. **打包器**:新工具 `r8forge tape pack -o x.bin`,按 3 bit 小端打包(8 条指令 3 字节)。 + 同时给 `r8forge_tape_run` 加一个 `.bin` 载入路径 —— 打包器对不对,用现有四份 VM 一比就知道。 +2. **RTL 仿真对拍**:同一份 `.bin` 在 Verilog testbench 里跑完,比较 + `(ip, dp, 259 格, OUT 流, steps)` 与 `tape_run` 的终态;再抽几条 tape 逐**步**比。 +3. **单步对拍(上板之后)**:`tape_run --trace` 导出每步状态,面板单步一遍对照 + (M1 阶段就靠这个把接线错误抓出来)。 +4. **里程碑**: + + | | 内容 | 验收 | + |---|---|---| + | M0 | 打包器 + RTL 仿真 | `hello`、`term`、`asm/test.r8asm` 三条纸带的终态与 `tape_run` 一致 | + | M1 | 上板,面板 + 单步 | 单步跑 `hello`,OUT 与仿真逐字符一致 | + | M2 | UART + 连续运行 | `asm/test.r8asm` 跑完,步数 = 202 159 | + | M3 | 交互 | 终端里把计算器会话打出来(`12 34 + .` → `0046`) | + | M4 | 位宽开关 | 8 / 11 / 16 位各跑一遍字节级测试纸带 | + +## 8. 动手前必须先定下来的语义(软件里已经定了,硬件要照抄) + +1. **`,` 是阻塞的**。`derive`/`tape_run` 用 `-i` 预装输入、读空后给 0;viz 的串行模式 + 是真的 `getchar()` 阻塞,EOF 给 0。硬件取后者:`UART RX` 等到一个字节再继续; + **EOF 是一个显式事件**(终端发 `0x04`,或面板上的"EOF"键),此时读入 0 —— + 否则交互时每个空读都会把程序送去退出。 +2. **`.` 的两种输出**:W ≥ 8 时把低 7 位当字符发给串口;W < 8 时打十进制数(viz 的行为)。 + 建议整机只做 W ≥ 8,省掉十进制那套。 +3. **`,` 写整格**:不是只写低 7 位(2026-11 改过的语义),高位置 0(或按 7E1 帧那套约定 + 填校验/停止位,默认关)。硬件就是"把收到的字节写进整格,再按 W 截断"。 +4. **`[`/`]` 的扫描边界**照 §2 那两段伪码,尤其 `]` 要跳回 `[` 本身。 +5. **宽度是构建参数**,不是运行时状态:同一份纸带只对一个宽度成立(库宏按 `_CELL_SIZE` 展开)。 + 面板上的"位宽"开关只能切"换一份 ROM",不能切"同一份纸带换语义"。 + +## 9. 待定 / 下一步 + +* **选哪一档**(A / B / C)—— 影响后面所有细节。 +* **位宽**:8(TTL 最省:一格一个字节)、11(项目默认,全家桶/计算器都是它)、16(能跑 + 16 位那套,RAM 要 16 位)。 +* **程序存储器**:内部 RAM、片外 flash/EEPROM、还是卡带装载。 +* **要不要"纸带"这个物理形态**:演示级纸带(≤ ~2000 条)可以做,大程序进 ROM。 +* **第一步做什么**:我建议先写 M0 —— `r8forge tape pack` + 一份 `hardware/rot8.v` 的 + testbench 对拍。它不依赖任何硬件采购,而且做完之后 A/B/C 三档共用同一份"黄金模型"。