diff --git a/Doc/compiler/编译管线.md b/Doc/compiler/编译管线.md index 1bcf34c..4deeda8 100644 --- a/Doc/compiler/编译管线.md +++ b/Doc/compiler/编译管线.md @@ -1,27 +1,28 @@ # 编译管线 -compiler 模块：ST / toml 编译器。CMake 目标：`compiler`（`STATIC`），依赖 [`指令与映像.md`](../isa/指令与映像.md)。可执行入口 `STCompiler`（本模块 `src/main.cpp`，链 `compiler` + `isa`）。 +compiler 模块：ST / toml 编译器。CMake 目标：`compiler`（`STATIC`），**不依赖 isa**（指令 opcode / 类型元数据 / FB 布局来自 `compiler/machine.toml`，见 [`指令配置.md`](../isa/指令配置.md)）。可执行入口 `STCompiler`（本模块 `src/main.cpp`，链 `compiler`）。 读齐工程后走直通 pass，产出单一映像文件，不上 LLVM。词法、语法、符号表、检查、codegen、链接都留在本库，不再拆 CMake 子库。 -语言规则、toml 字段、链接与第 12 节阶段见 [`初步计划.md`](../初步计划.md)。指令和映像只认 [`指令与映像.md`](../isa/指令与映像.md)。 +语言规则、toml 字段、链接与第 12 节阶段见 [`初步计划.md`](../初步计划.md)。`.stb` 格式契约见 [`指令与映像.md`](../isa/指令与映像.md)（compiler 自带写实现 + 型号标识/SHA-256）。 ## 管线 ```text -读 toml、收齐 .st +加载 machine.toml（--machine，强校验） + → 读 toml、收齐 .st → 词法 / 递归下降语法 → 收集导出符号 → 解析 VAR_EXTERNAL、链接、定地址 → 类型检查 - → 按 PROGRAM / FUNCTION / FB 编寄存器码 + → 按 PROGRAM / FUNCTION / FB 编寄存器码（opcode/类型/FB 布局查配置） → 回填跳转、写映像头与工程哈希 - → 写 .stb（映像）与 .runtime.toml（sidecar：io 绑定） + → 写 .stb（头 104 含型号标识 + 段 + SHA-256 文件尾）与 .runtime.toml（sidecar：io 绑定） ``` ## 边界 - toml **不声明变量**；`VAR_GLOBAL` 第一版只允许出现在 `gvl.file` - `[[io.*]]` 的 `var` 必须已在 GVL 中；同名全局链接失败 -- 第三方 toml 解析放 `third_party/`，本库私有链接 -- 不写扫描周期，不链 `vm` +- 第三方 toml 解析（toml++）放 `third_party/`，本库私有链接 +- 不写扫描周期，不链 `vm`、不链 `isa` diff --git a/Doc/isa/指令与映像.md b/Doc/isa/指令与映像.md index 1805a6a..354fee2 100644 --- a/Doc/isa/指令与映像.md +++ b/Doc/isa/指令与映像.md @@ -2,16 +2,16 @@ isa 模块规范：指令集 + 映像 + 定宽类型。不是编译器，不把 `.st` 编成映像。 -`compiler` 按本文件写出字节，`vm` 只认这些字节。两边不互链。 +`compiler` 写 `.stb`、`vm` 读 `.stb`，两边**各自实现**读写；`isa` 归执行器侧只管指令定义。指令 opcode / 类型 / FB 布局的登记见 [`指令配置.md`](指令配置.md)（`compiler/machine.toml`，与代码强校验）。 全工程定案见 [`初步计划.md`](../初步计划.md)。**类型、指令编码、映像布局以本文为准**，不要另写一份互相打架的表。头文件实现本文，不另当规范。 ```text -STCompiler → compiler → isa -BytecodeExecutor → vm → isa +STCompiler → compiler （编码查 machine.toml；自带 .stb 写） +BytecodeExecutor → vm → isa （isa 只管指令；vm 自带 .stb 读） ``` -CMake 目标：`isa`（`STATIC`），无依赖。公开头：`isa/include/isa/`。 +CMake 目标：`isa`（`STATIC`），无依赖；`vm` PUBLIC 链 `isa`。公开头：`isa/include/isa/`。 --- @@ -240,11 +240,11 @@ isa/ ``` ```cmake -add_library(isa STATIC src/Encode.cpp src/Image.cpp) +add_library(isa STATIC src/Encode.cpp) target_include_directories(isa PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include) ``` -`compiler` / `vm`：`target_link_libraries(... PUBLIC isa)`。 +`vm`：`target_link_libraries(vm PUBLIC isa)`；`compiler` 不链 `isa`。 --- diff --git a/Doc/vm/扫描周期.md b/Doc/vm/扫描周期.md index c40ce26..33c0bd1 100644 --- a/Doc/vm/扫描周期.md +++ b/Doc/vm/扫描周期.md @@ -15,7 +15,8 @@ vm 模块：寄存器虚拟机。CMake 目标：`vm`（`STATIC`），只依赖 [ ## 边界 -- 只认 `isa` 映像；类型与溢出按 [`指令与映像.md`](../isa/指令与映像.md)（`INT` 饱和） +- 只认 `.stb` 映像（`vm` 自带读实现）；读取时**型号标识匹配 + SHA-256 校验**，不符/篡改 → 拒绝 +- 类型与溢出按 [`指令与映像.md`](../isa/指令与映像.md)（`INT` 饱和）；指令定义归 `isa` - 局部 / `VAR` = 固定寄存器；`nregs` 在函数头 - `CALL` 目标是立即数 `fn_id`，有界调用栈 - 无 GC、无堆、无线程；每周期受 `cycle_limit` 限制 @@ -63,7 +64,7 @@ VM 需要无歧义地访问数据区，当前变宽布局（BOOL 1B / INT 2B / T - `Codegen.cpp` 简化：`width_of`/`align_up` 删除、`layout_data`/`layout_fb_instances` 按槽号布局、指令 slot = 符号表槽号 - `codegen_test` 断言更新（slot 从字节偏移变槽号、数据区字节数变化） -### 步骤 1：`Machine.h`（新建 `vm/include/vm/Machine.h`） +### 步骤 1：`Machine.h`（已落地 `vm/include/vm/Machine.h`） ```cpp namespace vm { @@ -83,32 +84,32 @@ namespace vm { ``` - `Fault` 枚举 + 帧结构 `{ fn_id, regs[nregs], ret_pc, ret_fn_id }`；调用栈深度上限 64 -- 只依赖 `isa`（`ImageView` + 类型/饱和函数） +- 只依赖 `isa`（指令定义）+ 自带 `vm::Image`（.stb 读） -### 步骤 2：`Machine.cpp` 译码 switch +### 步骤 2：`Machine.cpp` 译码 switch（已落地） - 取指：函数表 → `code_offset`（字节）→ 读 u32 → 拆 `op/rd/a/b` - 标量：`MOVE` / `LOADK`（常量表 tag 定值表示）/ `NOT` / `AND` / `OR`（布尔）/ `ADD/SUB/MUL/DIV`（`sat_*`）/ `CMP_xx`（全宽比较） - 跳转：`JMP` / `JT` / `JF`（`pc += off`，相对下一条语义） - 数据区：`LOAD_I/LOAD_M/LOAD_GLOBAL`、`STORE_Q/STORE_M/STORE_GLOBAL`（同一实现，slot × 8） -### 步骤 3：CALL / RET 帧栈 + 故障 +### 步骤 3：CALL / RET 帧栈 + 故障（已落地） - `CALL fn_id`：压新帧（复制 r0..r7）→ pc=0；`RET`：复制 r0..r7 回调用方 → 弹栈（MAIN 的 RET = 周期结束） - `cycle_limit` 超限（用例 6）、栈深 > 64、`BadOp` / `BadSlot` / `BadConst` → 周期中止返回故障 -### 步骤 4：定时器与边沿（8 个 CAL_*） +### 步骤 4：定时器与边沿（已落地） - 执行时用映像 `dt_ms` 推进（每周期一次调用 = 推进一次），不读系统时钟 - TON：in 真 → et += dt（到 pt 停）、q = et ≥ pt；in 假 → et = 0 - TOF：in 真 → q=1、et=0；掉电 → et += dt、et ≥ pt → q=0 - CTU：cu 上升沿（**上次 cu 存 VM 侧 vector**，按实例基槽索引）→ cv+1；r → 复位；q = cv ≥ pv -### 步骤 5：可观察性基础 +### 步骤 5：可观察性基础（已落地） - `step()` / `pc` / `fn_id` / `cycle_count` / `call_depth` / `reg` 落基础实现；`snapshot()` 留 12.11 补全 -### 步骤 6：`vm_test`（`tests/src/vm_test.cpp` + CMake，链 `vm` 库） +### 步骤 6：`vm_test`（已落地） - 手工拼小映像（`isa` 编码函数）：赋值、跳转、CALL/RET 帧复制、cycle_limit - 编译器产物全链路：用例 01/02/04/05/07/09/13/15/17/18/20 跑周期断言寄存器与数据区 @@ -116,6 +117,6 @@ namespace vm { - TON：dt=10、pt=30 → 第 3 周期 q=1；CTU：上升沿计数 - **确定性**：同一 I 序列跑两遍，数据区完全一致 -### 步骤 7：验证 + 提交 +### 步骤 7：验证 + 提交（已落地，ctest 14/14） - `cmake --build` + `ctest`（新增 `vm_cycles` 后 10/10 全绿）；20 用例扫描：14 正例执行通过 diff --git a/Doc/vm/指令执行.md b/Doc/vm/指令执行.md index 00f810d..f6ade00 100644 --- a/Doc/vm/指令执行.md +++ b/Doc/vm/指令执行.md @@ -5,6 +5,9 @@ ## 执行模型 ```text +加载（Machine::create）：解析 .stb（vm 自读实现）→ 型号匹配（内建 STATOR1）→ SHA-256 校验 + 任一不符 → 直接拒绝（不创建机器） + 每个扫描周期（run_cycle）： 1. pc = 0，从入口函数（MAIN）开始逐条执行 2. 执行到 MAIN 的 RET → 周期结束 diff --git a/Doc/初步计划.md b/Doc/初步计划.md index 9771ebe..4e9e5ae 100644 --- a/Doc/初步计划.md +++ b/Doc/初步计划.md @@ -530,17 +530,21 @@ CMake 三个库能空编译：`isa`、`compiler`、`vm`；两个可执行 `STCom 编译与执行拆成两个可执行，映像 `.stb` 是中间产物： ```text -STCompiler -o .stb # 编译：读 toml + .st → 映像 + sidecar -BytecodeExecutor .stb [--cycles N] # 执行：加载 .stb + sidecar，跑 N 周期 +STCompiler -o .stb --machine +BytecodeExecutor .stb [--cycles N] ``` -- `STCompiler` 链 `compiler` + `isa`；`BytecodeExecutor` 链 `vm` + `isa`，**不链 `compiler`**。 -- 产物两个文件：`.stb`（映像，魔数 `STSC`）+ `.runtime.toml`（sidecar：I/O 绑定 var → 槽号 → channel/bit）。`[[io.*]]` 不进映像，sidecar 由 STCompiler 生成，不创造变量。 +- `STCompiler` 链 `compiler`（**不链 `isa`**，编码查 `machine.toml`）；`BytecodeExecutor` 链 `vm` + `isa`，**不链 `compiler`**。 +- 产物两个文件：`.stb`（头 104 含型号标识 + 段 + SHA-256 文件尾）+ `.runtime.toml`（sidecar：I/O 绑定 var → 槽号 → channel/bit）。`[[io.*]]` 不进映像，sidecar 由 STCompiler 生成，不创造变量。 - `dt_ms` / `cycle_limit` 从映像头取，sidecar 不重复配置。 +- 执行器读取时**型号匹配 + SHA-256 校验**，不匹配/篡改 → 拒绝。 - 最小可观测：BytecodeExecutor 打印本周期 I/Q，或把寄存器/映像 dump 出来。 - 回放：读预先录制的 I 序列（文本即可），不接真实硬件。 -完成：`STCompiler examples/line1/project.toml -o line1.stb` 产出两个文件；`BytecodeExecutor line1.stb` 能跑若干周期。 +完成：`STCompiler examples/line1/project.toml -o line1.stb --machine compiler/machine.toml` 产出两个文件；`BytecodeExecutor line1.stb` 能跑若干周期。 + +> 12.13 修订：指令 opcode / 类型 / FB 布局的登记移入 `compiler/machine.toml`（见 [`指令配置.md`](isa/指令配置.md)）， +> `STCompiler` 编译路径必填 `--machine`。 --- @@ -575,8 +579,8 @@ BytecodeExecutor .stb [--cycles N] # 执行：加载 .stb + sidecar ### 12.13 依赖方向（全程遵守） ```text -STCompiler → compiler → isa -BytecodeExecutor → vm → isa +STCompiler → compiler （编码查 machine.toml；自带 .stb 写） +BytecodeExecutor → vm → isa （isa 只管指令；vm 自带 .stb 读） ``` - 指令或映像布局有变：先改 `isa` 和编解码测试，再改两端。 diff --git a/README.md b/README.md index 2728cc2..4f7c4d5 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,14 @@ 方案见 [`Doc/初步计划.md`](Doc/初步计划.md)，模块文档见 [`Doc/索引.md`](Doc/索引.md)。 ```text -多个 .st - ↑ project.toml 列出 +多个 .st + machine.toml（指令/类型/FB 布局） + ↑ project.toml 列出源文件；machine.toml 唯一事实来源 ↓ -STCompiler（compiler 库：词法 / 语法 → 符号表 → 类型检查 → 寄存器码 → 链接） +STCompiler（compiler 库：词法 / 语法 → 符号表 → 类型检查 → 寄存器码 → 链接；编码查 machine.toml） ↓ -.stb 映像 + .runtime.toml sidecar +.stb 映像（头 104 含型号标识 + 段 + SHA-256 文件尾）+ .runtime.toml sidecar ↓ -BytecodeExecutor（vm 库按扫描周期执行；喂 I、收 Q、给 Δt、回放） +BytecodeExecutor（vm 库按扫描周期执行；型号/SHA 校验；喂 I、收 Q、给 Δt、回放） ``` ## 目录 @@ -40,33 +40,33 @@ BytecodeExecutor（vm 库按扫描周期执行；喂 I、收 Q、给 Δt、回 ## 模块与 CMake 目标 -三个静态库与两个可执行，与目录一一对应。`compiler` 与 `vm` 不互相链接，合同放在 `isa`。依赖方向：`STCompiler → compiler → isa`、`BytecodeExecutor → vm → isa`。 +三个静态库与两个可执行，与目录一一对应。`compiler` 与 `vm` 不互相链接。指令/类型/FB 布局的**唯一事实来源是 `compiler/machine.toml`**（编译器运行时加载）；`isa` 归执行器侧（`vm` 依赖），只管指令定义。依赖方向：`STCompiler → compiler`、`BytecodeExecutor → vm → isa`。 | 目录 | 目标 | 类型 | 依赖 | 职责 | |---|---|---|---|---| -| `isa/` | `isa` | `STATIC` | 无 | 约 20 条指令编码、映像头、工程哈希、`BOOL` / `INT` / `TIME` 宽度 | -| `compiler/` | `compiler` | `STATIC` | `isa` | 读 toml、收齐 `.st`、解析、链接、定址、类型检查、编寄存器码、写映像 | -| `vm/` | `vm` | `STATIC` | `isa` | 一台 VM、一个入口、一份映像；扫描周期、寄存器、FB、有界 `CALL` / `RET` | -| `compiler/` | `STCompiler` | `EXECUTABLE` | `compiler`、`isa` | `STCompiler -o .stb`：编译并写映像 + sidecar；`--disasm` 可反汇编 | +| `isa/` | `isa` | `STATIC` | 无 | 指令定义（Op/Instr/Encode/Types/饱和/disasm），**归执行器侧** | +| `compiler/` | `compiler` | `STATIC` | toml++（私有） | 读 toml、收齐 `.st`、解析、链接、定址、类型检查、编寄存器码、写 `.stb`（指令 opcode/类型/FB 布局全部来自 `machine.toml`） | +| `vm/` | `vm` | `STATIC` | `isa` | 一台 VM、一个入口、一份映像；扫描周期、寄存器、FB、有界 `CALL` / `RET`；自带 `.stb` 读实现 + 型号/SHA-256 校验 | +| `compiler/` | `STCompiler` | `EXECUTABLE` | `compiler` | `STCompiler -o .stb --machine `：编译并写映像 + sidecar；`--disasm` 可反汇编 | | `executor/` | `BytecodeExecutor` | `EXECUTABLE` | `vm`、`isa` | `BytecodeExecutor .stb`：加载映像 + sidecar，采样 I、执行 `PROGRAM MAIN`、写回 Q、用 Δt 推进定时器 / 计数器、回放 | 词法、语法、符号表、检查、codegen、链接都留在 `compiler` 一个库里，不再拆 CMake 子库。 ### `isa` -编译器写映像、虚拟机读映像，两边共用同一套编码。放这里避免循环依赖。 +归执行器侧（`vm` 依赖），**只管指令定义**：Op 枚举 / Instr 打包 / Encode（编解码·disasm）/ Types（饱和）。执行器执行 switch 在 `vm`。 ### `compiler` -toml **不声明变量**，只列出源文件、指定唯一 GVL、可选地把已有全局接到硬件。`VAR_GLOBAL` 第一版只允许出现在 `gvl.file`（如 `globals.st`）。 +toml **不声明变量**，只列出源文件、指定唯一 GVL、可选地把已有全局接到硬件。`VAR_GLOBAL` 第一版只允许出现在 `gvl.file`（如 `globals.st`）。指令 opcode / 类型元数据 / FB 布局**全部来自 `compiler/machine.toml`**（`STCompiler --machine` 加载，强校验后编译）。 ### `vm` -每个扫描周期：采样 I → 从 `PROGRAM MAIN` 的 `pc=0` 执行到 `RET` → 写回 Q → 用本周期 Δt 推进 `TON` / `TOF` / `CTU`。无 GC、无堆、无线程；变量编译期分配。 +每个扫描周期：采样 I → 从 `PROGRAM MAIN` 的 `pc=0` 执行到 `RET` → 写回 Q → 用本周期 Δt 推进内置 FB。无 GC、无堆、无线程；变量编译期分配。读取 `.stb` 时**校验型号标识与 SHA-256**（不匹配/篡改 → 拒绝）。 ### `executor`（BytecodeExecutor） -第一版两个可执行：`STCompiler` 编译出 `.stb`（映像）+ `.runtime.toml`（sidecar：I/O 绑定）；`BytecodeExecutor` 加载后按扫描周期跑。不再有"一条命令编译 + 跑"。`dt_ms` / `cycle_limit` 从映像头取。 +`STCompiler` 编译出 `.stb`（含型号标识 + SHA-256）+ `.runtime.toml`（sidecar：I/O 绑定）；`BytecodeExecutor` 加载后按扫描周期跑。`dt_ms` / `cycle_limit` 从映像头取。 ### `examples/` 与 `tests/` diff --git a/compiler/README.md b/compiler/README.md index e1fafc1..0b567c3 100644 --- a/compiler/README.md +++ b/compiler/README.md @@ -1,6 +1,6 @@ # compiler -ST / toml 编译器。CMake 目标：`compiler`（`STATIC`），依赖 `isa`；可执行 `STCompiler`。 +ST / toml 编译器。CMake 目标：`compiler`（`STATIC`），**不依赖 `isa`**——指令 opcode / 类型元数据 / FB 布局来自 `compiler/machine.toml`（见 [`指令配置.md`](../doc/isa/指令配置.md)）；自带 `.stb` 写实现。可执行入口 `STCompiler`。 - **使用说明**（构建 / 用法 / 工程文件 / ST 子集 / 错误类别）：[`doc/compiler/STCompiler使用说明.md`](../doc/compiler/STCompiler使用说明.md) - 边界与管线：[`doc/compiler/编译管线.md`](../doc/compiler/编译管线.md) diff --git a/executor/README.md b/executor/README.md index ca9eb17..eceb121 100644 --- a/executor/README.md +++ b/executor/README.md @@ -1,5 +1,5 @@ # executor -BytecodeExecutor 模块：可执行入口。CMake 目标：`BytecodeExecutor`（`EXECUTABLE`），链接 `vm` 和 `isa`，**不链 `compiler`**。 +BytecodeExecutor 模块：可执行入口。CMake 目标：`BytecodeExecutor`（`EXECUTABLE`），链接 `vm` 和 `isa`，**不链 `compiler`**。读取 `.stb` 时校验型号标识与 SHA-256。 职责与边界见 [`doc/executor/执行器入口.md`](../doc/executor/执行器入口.md)。 diff --git a/isa/README.md b/isa/README.md index 608797c..137d01b 100644 --- a/isa/README.md +++ b/isa/README.md @@ -1,15 +1,15 @@ # isa -指令集 + 映像 + 定宽类型。CMake 目标：`isa`（`STATIC`），无依赖。 +**归执行器侧**，只管指令定义。CMake 目标：`isa`（`STATIC`），无依赖；被 `vm` 依赖。 -`compiler` 写映像、`vm` 读映像，两边只依赖本目录，不互链。 +`compiler` **不依赖 isa**——指令 opcode / 类型元数据 / FB 布局全部来自 `compiler/machine.toml`（见 [`指令配置.md`](../doc/isa/指令配置.md)）。`.stb` 映像读写由 `compiler`（写侧）与 `vm`（读侧）**各自实现**。 ```text -STCompiler → compiler → isa -BytecodeExecutor → vm → isa +STCompiler → compiler （编码查 machine.toml，自带 .stb 写） +BytecodeExecutor → vm → isa （isa 只管指令；vm 自带 .stb 读） ``` -**类型、操作码、指令字、映像布局以** [`doc/isa/指令与映像.md`](../doc/isa/指令与映像.md) **为准。** 头文件实现该文，本 README 不另当规范。`.stb` 结构面向使用者的拆解见 [`doc/isa/stb文件格式.md`](../doc/isa/stb文件格式.md)。全工程阶段见 [`doc/初步计划.md`](../doc/初步计划.md) 12.0～12.1。 +**操作码、指令字以** [`doc/isa/指令与映像.md`](../doc/isa/指令与映像.md) **为准。** 头文件实现该文，本 README 不另当规范。`.stb` 结构拆解见 [`doc/isa/stb文件格式.md`](../doc/isa/stb文件格式.md)。指令/类型/FB 登记见 [`doc/isa/指令配置.md`](../doc/isa/指令配置.md)。 公开头：`isa/include/isa/`。 @@ -17,139 +17,48 @@ BytecodeExecutor → vm → isa ## 做 / 不做 -**做：** 操作码与 32-bit 指令、映像头与段、`BOOL`/`INT`/`TIME` 宽度与饱和、编解码、工程哈希、一条指令的文本转储。 +**做：** 操作码与 32-bit 指令字、`BOOL`/`INT`/`TIME` 定宽与饱和、编解码、一条指令的文本转储。 -**不做：** toml、关键字、符号表、AST、VM `switch`、扫描周期、I/O 采样。`AND`/`OR` 只组合已算好的值；短路由 `compiler` 编成跳转。 +**不做：** 映像读写（compiler/vm 各自实现）、toml/关键字/符号表/AST、VM 执行 switch（在 `vm`）、扫描周期、I/O 采样。 --- -## 实现步骤 - -原则：先冻合同，再头文件，再 `.cpp`，再最小测试。每步能编过再进下一步。改编码或映像字段时，先改规范文和本模块，再动 `compiler` / `vm`。 - -目标目录（与规范一致）： +## 目录与 CMake ```text isa/ CMakeLists.txt README.md include/isa/ - Types.h # 宽度、饱和、槽值 - Op.h # 操作码枚举 + 助记符 + Types.h # 宽度、饱和 + Op.h # 操作码枚举 + OpFormat/OpClass + kOpDefs 表 + 助记符 Instr.h # 32-bit 打包/拆字段（inline） Encode.h # encode / decode / disasm - Image.h # 头、段、FNV、读写缓冲 src/ Encode.cpp - Image.cpp ``` ```cmake -add_library(isa STATIC src/Encode.cpp src/Image.cpp) +add_library(isa STATIC src/Encode.cpp) target_include_directories(isa PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include) ``` -`compiler` / `vm`：`target_link_libraries(... PUBLIC isa)`。 +`vm`：`target_link_libraries(vm PUBLIC isa)`；`compiler` 不链 `isa`。 --- -### 0. CMake 骨架 +## 实现说明 -根 `CMakeLists.txt` 已 `add_subdirectory` 了 `compiler` / `vm` / `executor`。这三个目录若没有 `CMakeLists.txt`，顶层 configure 失败，`isa` 也编不过。 +- **`Types.h`**：`Bool` = `uint8_t`、`Int` = `int16_t`、`Time` = `int64_t`（毫秒，理由见规范文）；`sat_add/sub/mul/div`（饱和规则见规范文）；`TypeTag`（0/1/2，`.stb` 常量表契约） +- **`Op.h`**：`enum Op : uint8_t`（数值即编码，与 `machine.toml` 强校验一致）；`OpFormat`（RR/RRR/IMM/SLOT/JMP/JC/CALL/CAL/NONE）与 `OpClass`（Plain/Instance）；34 条 `kOpDefs{ name, format, cls }`；`mnemonic/format/op_class` 查表 +- **`Encode.cpp`**：`encode/decode` 往返 + `disasm`（按 format 表驱动，文本与规范文一致） -本步只让工程能配置、能链，不写业务。 +## 测试 -- 写本目录 `CMakeLists.txt`（上面那段即可） -- `compiler` / `vm`：空 `.cpp` + `PUBLIC` 链 `isa` -- `executor`：`BytecodeExecutor`，`main` 打印版本，链 `vm`、`isa`；`STCompiler` 入口在 `compiler/src/main.cpp`，链 `compiler`、`isa` -- 根 CMake：`enable_testing()`（测试文件下一步再加） - -完成：`cmake --build` 过。 - ---- - -### 1. 冻合同（先改规范文） - -[`指令与映像.md`](../doc/isa/指令与映像.md) 已有助记符和 `[ op:8 | rd:8 | a:8 | b:8 ]`，还缺**数值和映像字节**。头文件不得自己发明一份表。 - -把下面这些写进规范文，再写代码（细则以该文最终落笔为准）： - -- 指令字：小端 `uint32_t`；`op`/`rd`/`a`/`b` 各 8 bit；`imm16 = a | (b << 8)`；`off16` 为有符号、单位是指令条数 -- 操作码 0..28 连续赋值，以后只追加不插队 -- 各指令操作数字面（`LOADK`/`JMP`/`CALL`/`LOAD_*`/`STORE_*`/`CAL_*`/`RET`） -- `INT` 饱和、`INT_MIN / -1`、除零、`BOOL` 只允许 0/1 -- FNV-1a 64 的 basis/prime；路径只当排序键，对文件内容 update；空集合 = basis -- 映像魔数 `STSC`、版本 1、头字段偏移与长度、常量表/函数表/FB 表一行的字节 -- 第一版可写映像：空槽、空常量表/FB、`MAIN`（`fn_id=0`）、一条 `RET` - -完成：规范文能当唯一合同；本 README 仍只指向它。 - ---- - -### 2. `Types.h` - -`include/isa/Types.h`，inline，无对应 `.cpp`。命名空间 `isa`。C++20；本模块保持简单结构体，不依赖花哨特性。 - -- `Bool` = `uint8_t`，`Int` = `int16_t`，`Time` = `int64_t`（毫秒；理由见规范文） -- `TypeTag`：`Bool` / `Int` / `Time` -- `sat_add` / `sat_sub` / `sat_mul` / `sat_div`（规则见规范文） -- `pack_bool` / `pack_int` / `pack_time` → 4 字节 cell；对应 unpack - -完成：单独包含该头能编译。 - ---- - -### 3. `Op.h` + `Instr.h` - -- `Op.h`：`enum Op : uint8_t`，取值与规范文一致；`mnemonic(Op)` 助记符（已在头内落地） -- `Instr.h`：`typedef uint32_t Instr`；`pack`、取 `op`/`rd`/`a`/`b`、`imm16`/`off16`；按形态 `enc_rr` / `enc_rrr` / `enc_imm` / `enc_jmp` / `enc_jc` - -完成：能打包/拆开一条 32-bit 指令，不依赖 `.cpp`。 - ---- - -### 4. `Encode.h` + `Encode.cpp` - -给 `STCompiler --disasm` 和测试往返打印： - -- `Decoded { Op op; uint8_t rd, a, b; }` -- `Instr encode(Decoded)` / `Decoded decode(Instr)` -- `disasm(Instr, char* out, size_t cap)` - -`disasm` 格式冻在规范文，例如：`RET`、`MOVE r1, r2`、`LOADK r0, 3`、`ADD r1, r2, r3`、`JMP +4`、`JT r0, -1`、`CALL 1`、`LOAD_I r0, 2`、`CAL_TON 0`。 - -完成：一条指令能编、能解、能打出一行文本。 - ---- - -### 5. `Image.h` + `Image.cpp` - -- `fnv1a64` / `fnv1a64_update` -- `ImageView`：只读视图，指向外部缓冲 -- `read_image`：校验魔数、版本、头大小、各段不越界、`entry_fn_id` 落在函数表内 -- `write_ret_main(cycle_limit, dt_ms, hash)` → `std::vector`：空槽 + `MAIN` + 一条 `RET` -- `.stb` 文件读写与 `.runtime.toml` sidecar（I/O 绑定 var → 槽号 → channel/bit） - -小端 `put_*` / `get_*` 只放 `.cpp`，不把 packed struct 当 ABI。本阶段不写完整 `ImageBuilder`（等 codegen）。 - -完成：能写出并读回「空映像 + 一条 `RET`」。 - ---- - -### 6. 最小测试 - -在 `tests/` 加一个只链 `isa` 的 CTest 可执行文件（不是第 12.2 节那 20 个用例）： - -- `RET` / `ADD` / `LOADK` / `JMP -1`：encode 后再 decode，字段一致；`disasm` 非空 -- `write_ret_main` 再 `read_image`：魔数、version=1、`n_funcs=1`、入口是 `RET` -- `fnv1a64` 空输入等于 basis - -完成：`ctest` 过上述用例。 - ---- +`tests/isa_test`（链 `isa`）：饱和、操作码冻结值、指令打包、encode/decode 往返、disasm 文本、OpClass 分类。 ## 验收 -- `cmake --build` 过；`ctest` 过 isa 往返 -- `compiler` / `vm` 只 `#include `，不互相包含 -- 操作码或映像有变：先改 [`指令与映像.md`](../doc/isa/指令与映像.md) + 本目录 + 本测试，再改两端 +- `cmake --build` 过；`ctest` 过（`isa_roundtrip` 等 14 个用例全绿） +- `vm` 只 `#include `；`compiler` 不引用 `isa` +- 操作码有变：先改 `compiler/machine.toml` + 本目录 + 测试，再改两端 diff --git a/vm/README.md b/vm/README.md index ec97cc3..1136036 100644 --- a/vm/README.md +++ b/vm/README.md @@ -1,5 +1,5 @@ # vm -寄存器虚拟机。CMake 目标：`vm`（`STATIC`），只依赖 `isa`。 +寄存器虚拟机。CMake 目标：`vm`（`STATIC`），只依赖 `isa`（只管指令定义）；自带 `.stb` 读实现 + 型号/SHA-256 校验。 扫描周期与边界见 [`doc/vm/扫描周期.md`](../doc/vm/扫描周期.md)。