文档同步：machine.toml 配置驱动架构收尾。
- README.md：依赖方向（STCompiler→compiler 不链 isa）、模块表、isa 归执行器侧、 数据流图（machine.toml + 型号/SHA） - isa/README.md：重写——只管指令定义（Types/Op/Instr/Encode），删 Image 部分 - 指令与映像.md：依赖图与 CMake（compiler 不链 isa） - 编译管线.md：管线首步加载 machine.toml、产物含型号/SHA - 初步计划.md：12.10/12.13 修订（--machine、依赖方向） - 扫描周期.md / 指令执行.md：12.9 步骤标注已落地、vm 读校验说明 - compiler/vm/executor README：依赖与边界同步
This commit is contained in:
@@ -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 布局查配置）
|
||||
→ 回填跳转、写映像头与工程哈希
|
||||
→ 写 <name>.stb（映像）与 <name>.runtime.toml（sidecar：io 绑定）
|
||||
→ 写 <name>.stb（头 104 含型号标识 + 段 + SHA-256 文件尾）与 <name>.runtime.toml（sidecar：io 绑定）
|
||||
```
|
||||
|
||||
## 边界
|
||||
|
||||
- toml **不声明变量**；`VAR_GLOBAL` 第一版只允许出现在 `gvl.file`
|
||||
- `[[io.*]]` 的 `var` 必须已在 GVL 中；同名全局链接失败
|
||||
- 第三方 toml 解析放 `third_party/`，本库私有链接
|
||||
- 不写扫描周期，不链 `vm`
|
||||
- 第三方 toml 解析（toml++）放 `third_party/`，本库私有链接
|
||||
- 不写扫描周期，不链 `vm`、不链 `isa`
|
||||
|
||||
+6
-6
@@ -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`。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+10
-9
@@ -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 正例执行通过
|
||||
|
||||
@@ -5,6 +5,9 @@
|
||||
## 执行模型
|
||||
|
||||
```text
|
||||
加载（Machine::create）：解析 .stb（vm 自读实现）→ 型号匹配（内建 STATOR1）→ SHA-256 校验
|
||||
任一不符 → 直接拒绝（不创建机器）
|
||||
|
||||
每个扫描周期（run_cycle）：
|
||||
1. pc = 0，从入口函数（MAIN）开始逐条执行
|
||||
2. 执行到 MAIN 的 RET → 周期结束
|
||||
|
||||
+11
-7
@@ -530,17 +530,21 @@ CMake 三个库能空编译：`isa`、`compiler`、`vm`；两个可执行 `STCom
|
||||
编译与执行拆成两个可执行，映像 `.stb` 是中间产物：
|
||||
|
||||
```text
|
||||
STCompiler <project.toml> -o <name>.stb # 编译：读 toml + .st → 映像 + sidecar
|
||||
BytecodeExecutor <name>.stb [--cycles N] # 执行：加载 .stb + sidecar，跑 N 周期
|
||||
STCompiler <project.toml> -o <name>.stb --machine <machine.toml>
|
||||
BytecodeExecutor <name>.stb [--cycles N]
|
||||
```
|
||||
|
||||
- `STCompiler` 链 `compiler` + `isa`；`BytecodeExecutor` 链 `vm` + `isa`，**不链 `compiler`**。
|
||||
- 产物两个文件：`<name>.stb`（映像，魔数 `STSC`）+ `<name>.runtime.toml`（sidecar：I/O 绑定 var → 槽号 → channel/bit）。`[[io.*]]` 不进映像，sidecar 由 STCompiler 生成，不创造变量。
|
||||
- `STCompiler` 链 `compiler`（**不链 `isa`**，编码查 `machine.toml`）；`BytecodeExecutor` 链 `vm` + `isa`，**不链 `compiler`**。
|
||||
- 产物两个文件：`<name>.stb`（头 104 含型号标识 + 段 + SHA-256 文件尾）+ `<name>.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 <name>.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` 和编解码测试，再改两端。
|
||||
|
||||
Reference in New Issue
Block a user