diff --git a/AGENTS.md b/AGENTS.md index b9e4284..aa1b01f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,7 +98,13 @@ powershell -File tests\widths.ps1 -Widths 32 # 32 位:整套 10 个 target **除了 `INP`/`OUT` 的语义(那是宿主接口,允许按需定义),机器语义在没有明确要求的情况下一个字都 不许改**:8 条指令的行为、`biz`/`rnz` 判 `LSB`、`+` 是右旋、`-` 翻最低位、步数怎么算、 -内存是 259 格环、纸带从第一条指令跑到尾 —— 全部冻结。 +内存是环、纸带从第一条指令跑到尾 —— 全部冻结。 + +**几何(位宽 / 环大小)不是语义**,它是 `geometry.hh` 的构建选项:`-DR8FORGE_CELL_SIZE` +(1..32)、`-DR8FORGE_MEMORY_CELLS`(1..65536,默认 259)。换它们不算改语义,但**必须**按 +SPEC §13 走:先看目标纸带的最高格号(SPEC §1.2 有实测表:程序峰值 calc 51 / hello 49 / +term 27,全家桶自检 155),再跑整轮自检确认。物理机取 **8 位 + 64 格**(见 +`docs/hardware.md`);64 格在硬件上白送一个简化 —— `dp` 是 6 位计数器,回绕免费。 这条规矩是有来由的:三份实现(`derive` / `tape_run` / ROT-8-viz)互为对拍,任何一边"顺手修一下" 都会让另外两边看起来是错的,而我们没有第二份规格可以裁决。要改语义,先在 SPEC 里写清楚、 diff --git a/CMakeLists.txt b/CMakeLists.txt index 44b0538..a739edb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -20,6 +20,23 @@ if(R8FORGE_CELL_SIZE LESS 1 OR R8FORGE_CELL_SIZE GREATER 32) endif() add_compile_definitions(R8FORGE_CELL_SIZE=${R8FORGE_CELL_SIZE}) +# How many cells the tape holds. 259 is the historical default (a prime ring, so +# a walked-off-end bug cannot alias onto a power of two); it is a *hardware* +# knob as much as a software one. Every program we ship peaks well below 64 +# cells (calc 51, hello 49, signed_demo 34, term 27 -- geometry.hh lists the +# measurements), so `-DR8FORGE_MEMORY_CELLS=64` runs all of them; only the +# asm/test.r8asm self test, which lays every macro's cell block out side by side, +# needs the default. The ring is a modulo counter either way, so any size is +# legal; 1..65536 keeps the VMs' bookkeeping sane. +set(R8FORGE_MEMORY_CELLS 259 CACHE STRING "cells on the tape (1..65536)") +if(R8FORGE_MEMORY_CELLS LESS 1 OR R8FORGE_MEMORY_CELLS GREATER 65536) + message(FATAL_ERROR + "R8FORGE_MEMORY_CELLS=${R8FORGE_MEMORY_CELLS} is out of range: the ring is " + "addressed by a 16 bit counter in the physical machine, so the supported " + "range is 1..65536") +endif() +add_compile_definitions(R8FORGE_MEMORY_CELLS=${R8FORGE_MEMORY_CELLS}) + find_package(Threads REQUIRED) add_library(r8forge_core src/r8asm.cc src/synth.cc src/tape_opt.cc) diff --git a/SPEC.md b/SPEC.md index 7d0073a..740ebab 100644 --- a/SPEC.md +++ b/SPEC.md @@ -13,6 +13,8 @@ R8Forge = R8ASM 汇编器 + `%synth` 搜索器 + 标准库。这份文件规定 | 踩过的坑、失败过的方案、交接话 | `AGENTS.md`;设计长文在 `docs/` | 本文的每个数字都是在 **11 位 cell / 259 格**、MSVC Release 构建上**实测**的;口径见 §1.3。 +(两者都是构建选项:`-DR8FORGE_CELL_SIZE`、`-DR8FORGE_MEMORY_CELLS`。物理机取 8 位 / 64 格, +见 `docs/hardware.md`;几何变小之后哪些数字会变、哪些不会,§1.2 有实测表。) --- @@ -32,13 +34,31 @@ R8Forge = R8ASM 汇编器 + `%synth` 搜索器 + 标准库。这份文件规定 ```cpp // include/r8forge/geometry.hh -inline constexpr size_t kDefaultCellSize = 11; // 一个 cell 多少 bit -inline constexpr size_t kDefaultMemoryCells = 259; +inline constexpr size_t kDefaultCellSize = 11; // 构建选项 R8FORGE_CELL_SIZE +inline constexpr size_t kDefaultMemoryCells = 259; // 构建选项 R8FORGE_MEMORY_CELLS inline constexpr uint32_t kDefaultCellMask = (1u << kDefaultCellSize) - 1u; ``` 位宽可以用构建选项换:`cmake -S . -B build16 -DR8FORGE_CELL_SIZE=16` 会造出一整套 16 位的工具链(汇编器、库、五份 VM 都跟着走)。**上限是 32**(每份 VM 的 cell 都存在 `uint32_t` 里,CMake 里越界直接 `FATAL_ERROR`,见 §13)。实测:11 / 16 位下 `r8forge_synth_test` 8/8 通过;`byte_op_test` 在 8 / 11 / 16 位下全过(16 位那轮约 7.5 分钟,穷举 65536 个值 × 十余项),**17 位以上打印 `skipped` 并返回 0**(每轮 2^W 行,跑不动,但文件得在 1..32 位都编得过);32 位下整套工具链 10 个 target 全部可建、可跑。 +**环的大小也是构建选项**(`-DR8FORGE_MEMORY_CELLS=1..65536`,默认 259)。259 只是历史默认值(质数环,走飞了不会落回 2 的幂上),不是语义的一部分:`>`/`<` 都是模环回绕,任何尺寸都成立。实测每条纸带真正碰到的**最高格号**(脚本遍历纸带的 `>`/`<` 记峰值,`'<'@0` 全为 0,说明没有靠回绕的写法): + +| 纸带 | 峰值 | 64 格装得下? | +|---|---|---| +| `examples/term.r8asm` | 27 | ✓ | +| `examples/signed_demo.r8asm` | 34 | ✓ | +| `examples/hello.r8asm` | 49 | ✓ | +| `examples/calc.r8asm` | **51** | ✓ | +| `asm/test.r8asm`(全家桶自检) | **155** | ✗(它把每个宏的格子块并排铺开,是自检不是程序) | + +所以 **64 格能跑所有程序**,128 格留余量;全家桶自检只有 259(或 ≥156)装得下。整轮自检在 +`-DR8FORGE_MEMORY_CELLS=128` 和 `=64` 下都是 **8/8 通过**(11 位);物理机那套 **8 位 + 64 格** +组合下 `ctest -L widthfree` 5/5 通过,计算器/hello 的纸带与 259 格的版本**逐字节相同**、 +会话步数也完全相同(166 348 步)。64 格在硬件上是白送的简化:`dp` 变成 6 位计数器、 +回绕免费,不用做"模 259"的比较器逻辑。**代价**:程序若碰到 ≥ 环大小的格号,地址会被折 +回去(全家桶在 64 格下输出不变,但步数从 404 324 变成 404 540)—— 所以选环大小的规则是 +"≥ 程序碰到的最高格号 + 1"。 + 汇编器把三个名字注入 `.r8asm` 程序的作用域,宏库靠它们与位宽解耦: | 名字 | 值(11 位) | 用途 | @@ -928,9 +948,13 @@ r8forge_tape_run t.rot8 # 打印 out 和步数 ## 13. 维护 -- **改位宽/纸带长度**:`include/r8forge/geometry.hh` 两个常量 + 五份虚拟机 - (`tests/synth_test.cc`、`tests/byte_op_test.cc`、`tests/examples_test.cc`、`src/derive.cc`、 - `tests/tape_run.cc`)一起改;`asm/` 里的宏靠 `_CELL_SIZE` 自动跟随,不用动。 +- **改几何(位宽 / 环大小)**:**用构建选项,别改常量** —— + `-DR8FORGE_CELL_SIZE=<1..32>`、`-DR8FORGE_MEMORY_CELLS=<1..65536>`,CMake 里越界直接 + `FATAL_ERROR`;五份虚拟机(`tests/synth_test.cc`、`tests/byte_op_test.cc`、 + `tests/examples_test.cc`、`src/derive.cc`、`tests/tape_run.cc`)都从 `geometry.hh` 读, + 不用动。`asm/` 里的宏靠 `_CELL_SIZE` 自动跟随。换环大小之前先确认目标纸带的**最高格号** + (SPEC §1.2 有实测表和理由:程序碰到 ≥ 环大小的地址会被折回去,输出可能不变但步数会变)。 + `ROT-8-viz` 侧用 `-m/--mem` 和 `-b/--cell` 对齐同一套几何。 - **位宽上限是 32**:每份 VM 的 cell 都存在 `uint32_t` 里,`geometry.hh` 的 mask 特判了 32, CMake 里加守卫(`-DR8FORGE_CELL_SIZE` 越界直接 `FATAL_ERROR`)。想上 64 位得同时改五份 VM 的 cell、`geometry.hh`、汇编器的立即数类型(`r8asm.hh` 的 `data` 现在还是 `int16_t`)以及 diff --git a/docs/hardware.md b/docs/hardware.md index ce07967..cd242d1 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -5,7 +5,7 @@ 不是承诺;先把"机器要满足什么"和"预算多少"钉死,再挑载体。 **已定的两件事**:物理机做 **8 位 cell**(11 位格子的一半是"数位语义"、一半是邪门,物理上 -一个字节最好摆:`,`/`.` 天生就是一个字符、259 格正好 259 字节、一片 6116 装完); +一个字节最好摆:`,`/`.` 天生就是一个字符); 载体的挑选见 §5,还没定。 ## 1. 硬件的判据只有一条:状态序列 @@ -13,7 +13,7 @@ ISA 里**没有任何东西能看见时间**:没有计数器、没有中断、没有 `,`/`.` 的时序语义(`,` 阻塞、 `.` 立刻)。所以硬件只要满足 -> 第 n 条指令执行后,`ip`、`dp`、259 个 cell、输出流 与软件模型完全一致 +> 第 n 条指令执行后,`ip`、`dp`、环里的每个 cell、输出流 与软件模型完全一致 就等于"同一台机器",几拍一条指令、内存多慢、能不能流水,全都不影响语义(只影响快慢)。 这条自由是造机器的关键:**微码状态机、慢速内存、甚至转鼓,都是合法实现**。 @@ -24,8 +24,8 @@ ISA 里**没有任何东西能看见时间**:没有计数器、没有中断、 |---|---|---| | 指令 | 8 条:`>` `<` `+` `-` `[` `]` `,` `.` | **3 bit 操作码**,纸带就是 ROM/EEPROM,只读、无自修改 | | 程序 | 线性执行,`ip` 从 0 加到尾 | 程序计数器 = 纸带地址;没有别的跳转,只有 `[`/`]` 改 `ip` | -| 数据 | **259 格 × 8 bit**,复位全 0,`dp` 初始 0 | 就是 **259 字节**,一片 6116 装完;`dp` 是模 259 计数器(259 是质数,故意没有 2 的幂别名) | -| `>` / `<` | `dp = (dp ± 1) mod 259` | 9 bit 计数器 + 模 259 回绕 | +| 数据 | **64 格 × 8 bit**,复位全 0,`dp` 初始 0 | 就是 **64 字节**;`dp` 是 6 位计数器,回绕免费(见 §3 的实测:程序峰值 51 格) | +| `>` / `<` | `dp = (dp ± 1) mod N` | 6 位计数器,加/减 1 自然回绕,不需要比较器 | | `+` | 整格右旋(bit0 补到最高位) | 没有 ALU:8 bit 移位 + 回填(74HC299 一片,FPGA 里是接线) | | `-` | 翻最低位 | 一个 XOR 门 | | `[` (biz) | 最低位 = 0 → 跳到**配对 `]` 之后** | 前向扫描,深度计数 | @@ -55,7 +55,7 @@ rnz, 最低位 == 1: ip-- ; 深度=0 ## 3. 预算:现在的纸带要多大 -一条指令 3 bit,8 条挤 3 字节;数据 259 格。**物理机按 8 位算**,11/16/32 位那几行留着对照。 +一条指令 3 bit,8 条挤 3 字节;数据 **64 格**(`-DR8FORGE_MEMORY_CELLS=64`)。11/16/32 位那几行留着对照。 | 程序 | 8 位指令数 | ROM (3 bit/条) | 11 位指令数 | 16 位 | 32 位 | |---|---|---|---|---|---| @@ -70,10 +70,18 @@ rnz, 最低位 == 1: ip-- ; 深度=0 1. **选 8 位顺手把 `ip` 预算的问题解决了**:8 位计算器是 51 378 条,重新回到 65536 以内 (11 位那版 73 624 已经越过了历史 `INS_SIZE`)。16 位 `ip` 就够装,做成 20 位只是留余量。 -2. **数据 RAM 就是 259 字节**:一片 6116(2K×8)装下全部内存,地址 9 位(`dp` 模 259)。 +2. **数据 RAM 就是 64 字节**:一片 6116(2K×8)里塞 32 台都没问题;`dp` 6 位,回绕免费。 3. **32 位那版(126 KB)不进硬件**:它超过常见小 FPGA 的片上 BRAM(Tang Nano 9K ≈ 58 KB、 iCE40 UP5K ≈ 15 KB)。8 位物理机要跑的就是上表那五条。 +**环取 64 格**(`-DR8FORGE_MEMORY_CELLS=64`)。脚本遍历每条纸带的 `>`/`<` 记峰值 +(`'<'@0` 全为 0,说明没有靠回绕的写法):`calc` **51**、`hello` 49、`signed_demo` 34、 +`term` 27 —— 64 格装得下所有程序;只有 `asm/test.r8asm` 自检铺到 155(它把每个宏的格子块 +并排铺开,是自检不是程序)。实测:64 / 128 格下整轮自检 8/8 通过(11 位);物理机那套 +**8 位 + 64 格**下 `ctest -L widthfree` 5/5 通过,计算器纸带与 259 格版**逐字节相同**、 +会话步数也相同(166 348)。选环的规则见 SPEC §1.2:**≥ 程序碰到的最高格号 + 1** +(碰到 ≥ 环大小的地址会被折回去,输出可能不变、步数会变)。 + ## 4. 微架构 ``` @@ -83,12 +91,12 @@ rnz, 最低位 == 1: ip-- ; 深度=0 └──────▲───────┘ └───────▲───────┘ ▼ │ ip │ 状态 ┌──────────┐ ┌──────┴───────┐ ┌────────┴────────┐ │ 数据 RAM │ - │ ip 计数器 │◀──扫描单元──│ 括号扫描 (深度) │ │ 259 × 8 │ + │ ip 计数器 │◀──扫描单元──│ 括号扫描 (深度) │ │ 64 × 8 │ │ 16~20 bit │ ±1/扫描 └─────────────────┘ └────┬─────┘ - └──────────────┘ │ dp (9 bit, mod 259) │ + └──────────────┘ │ dp (6 bit, 自然回绕) │ ┌────────┴────────┐ │ │ dp 计数器 │──────── 地址 ────────┘ - │ (模 259 回绕) │ + │ (6 位, 回绕免费) │ └─────────────────┘ ``` @@ -113,7 +121,7 @@ rnz, 最低位 == 1: ip-- ; 深度=0 | 板子 | Tang Nano 9K(GW1NR-9):≈58 KB BSRAM、HDMI、板载 USB 串口,¥100 上下 | | 能跑 | 8 位全家桶(16.4 KB)✓、8 位计算器(19.3 KB)✓;11/16/32 位纸带只当对照(37 KB / — / ✗) | | 工具 | Gowin IDE 或开源的 yosys + nextpnr-gowin(后者更符合这个项目的脾气) | -| I/O | UART 115200 进/出,HDMI 画 259 格环 + `dp`/`ip`/当前格 | +| I/O | UART 115200 进/出,HDMI 画 64 格环 + `dp`/`ip`/当前格 | | 工作量 | 300~500 行 Verilog + testbench,一个周末 | | 速度 | 50 MHz / 4 拍 ≈ 12 M 指令/秒(比软件快一个量级,面板上能看到"瞬间算完") | @@ -125,9 +133,9 @@ rnz, 最低位 == 1: ip-- ; 深度=0 |---|---|---| | 程序 ROM | 29C010 / 39SF010(128 KB flash,用低 3 bit;8 位全家桶只要 16.4 KB) | 1 | | `ip` 计数器 | 74HC161 ×4(16 位够装 51 378 条;做 20 位就 ×5) | 4~5 | -| 数据 RAM | 6116(2K×8)—— 259 字节,一片就够 | 1 | +| 数据 RAM | 6116(2K×8)—— 只用 64 字节,一片能用 32 台 | 1 | | 数据寄存器/右旋 | 74HC299(8 位通用移位寄存器,右旋 + 保持一片搞定) | 1 | -| `dp` 计数器 + 模 259 | 74HC161 ×3 + 74HC85 + 回绕门 | 4~5 | +| `dp` 计数器 | 74HC161 ×2(6 位,回绕免费,不用比较器) | 2 | | 括号扫描 | 74HC191 ×2(上下计数)+ 比较器,或塞进 CPLD | 3~4 | | 控制/微码 | GAL22V10 ×2 或 ATF1502 CPLD(一片搞定解码 + 微序列) | 1~3 | | UART | 6850 ACIA 或 ATmega/CH340 桥 | 1~2 | @@ -139,9 +147,9 @@ rnz, 最低位 == 1: ip-- ; 深度=0 ### C. 机电(艺术品档) -* **数据环做转鼓**:**8 条磁道 × 259 格**、一个读头 + 一个写头(写头在下游**一格**处)。 +* **数据环做转鼓**:**8 条磁道 × 64 格**、一个读头 + 一个写头(写头在下游**一格**处)。 `>`/`<` 的"访问"就是等下一个格脉冲;`+`/`-` 在读到写头之间的那一格时间里改好写回, - 所以每条指令 ≈ 一格时间。3000 rpm、259 格/圈 → 77 µs/格 → 288 k 步 ≈ **22 s** ✓ 比想象中快。 + 所以每条指令 ≈ 一格时间。3000 rpm、64 格/圈 → 312 µs/格 → 166 k 步 ≈ **52 s**(环小了每圈格子少,鼓要转快点才追得上:10000 rpm → 16 s)。 代价是机加工(或找一个旧磁鼓/软盘改)。 * **程序做纸带**:3 bit 数据 + 1 孔同步,2.54 mm 孔距。`hello`(727 条)≈ 1.8 m ✓; 计算器(73 624 条)≈ **187 m** ✗ —— 所以纸带只适合演示级小程序,大纸带还是进 EEPROM。 @@ -162,9 +170,9 @@ rnz, 最低位 == 1: ip-- ; 深度=0 ## 6. 前面板 -* `ip`(16~20 bit)、`dp`(9 bit)、当前格(8 bit)各一排 LED;一条"纸带定位"进度条。 +* `ip`(16 bit)、`dp`(6 bit)、当前格(8 bit)各一排 LED;一条"纸带定位"进度条。 * 8 个指令灯:当前指令亮一个。 -* 259 格用 16×16 LED 矩阵或 128×64 OLED 画成**圆环**,`dp` 指的那格高亮(和 viz 一个样子)。 +* 64 格用 8×8 LED 矩阵或 128×64 OLED 画成**圆环**,`dp` 指的那格高亮(和 viz 一个样子)。 * 三个按键:单步 / 运行·暂停 / 复位;一个"输入"按键(按一下给 `,` 喂一个字符)。 * UART:一个终端窗口就是"键盘 + 打字机",计算器直接在上面用(8 位下打出来就是 `046` 这种)。 @@ -173,7 +181,7 @@ rnz, 最低位 == 1: ip-- ; 深度=0 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 逐**步**比。 + `(ip, dp, 环里的 cell, OUT 流, steps)` 与 `tape_run` 的终态;再抽几条 tape 逐**步**比。 3. **单步对拍(上板之后)**:`tape_run --trace` 导出每步状态,面板单步一遍对照 (M1 阶段就靠这个把接线错误抓出来)。 4. **里程碑**(数字都按 8 位实测): @@ -202,7 +210,7 @@ rnz, 最低位 == 1: ip-- ; 深度=0 ## 9. 待定 / 下一步 -* **已定**:位宽 = **8**;因此数据 RAM 259 字节、`.`/`,` 就是字节 I/O、8 位计算器 51 378 条 +* **已定**:位宽 = **8**、环 = **64 格**;因此数据 RAM 64 字节、`.`/`,` 就是字节 I/O、8 位计算器 51 378 条 (回到 65536 以内)、全家桶 99 824 步。 * **选哪一档**(A / B / C)—— 还没定,影响后面所有细节。 * **程序存储器**:内部 RAM、片外 flash/EEPROM、还是卡带装载。 diff --git a/include/r8forge/geometry.hh b/include/r8forge/geometry.hh index 8bec3ef..219e89f 100644 --- a/include/r8forge/geometry.hh +++ b/include/r8forge/geometry.hh @@ -7,8 +7,15 @@ // cell is in bits, and how many cells the tape holds. The instruction set does // not fix either (ROR just rotates inside a cell and the tape is a ring), so // these are the only places the old 8 bit / 256 cell assumptions live. -inline constexpr size_t kDefaultCellSize = R8FORGE_CELL_SIZE; // build option: -DR8FORGE_CELL_SIZE=<1..32> -inline constexpr size_t kDefaultMemoryCells = 259; +inline constexpr size_t kDefaultCellSize = R8FORGE_CELL_SIZE; // build option: -DR8FORGE_CELL_SIZE=<1..32> +inline constexpr size_t kDefaultMemoryCells = R8FORGE_MEMORY_CELLS; // build option: -DR8FORGE_MEMORY_CELLS=<1..65536> +// The ring size is a *hardware* decision as much as a software one: the physical +// machine only has to hold the highest cell a program ever touches. Measured on +// every program we ship (a script walks the tape's > and < and records the peak): +// calc 51, hello 49, signed_demo 34, term 27 -- so a 64 cell ring runs all of +// them, and 259 was only ever the historical default. The one exception is +// asm/test.r8asm, the "every macro once" self test, which lays every macro's +// cell block out side by side and peaks at 155; it needs the default. // The VMs store a cell in uint32_t, so 32 bits is the ceiling -- and `1u << 32` // would be undefined, hence the special case instead of a plain shift. CMake // refuses anything outside 1..32 at configure time, and the exhaustive byte