chentianya/Interpreter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

把各模块说明从 README 拆到 Doc，并用索引替代 Doc/README。

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Admin
2026-08-18 17:18:40 +08:00
co-authored by Cursor
parent 583f14967a
commit e4cdaf4717
9 changed files with 93 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Doc/README.md
-9
View File
@@ -1,9 +0,0 @@
# Doc
设计文档，不是编译目标。
| 文件 | 内容 |
|---|---|
| [`初步计划.md`](初步计划.md) | 定案：子集 ST、toml 工程、寄存器 VM、执行模型、ST 子集；第 12 节为分阶段实现顺序 |
仓库根目录 [`README.md`](../README.md) 只说明目录和模块边界；语言规则、映像与扫描周期的细节以本目录为准。
Doc/compiler/编译管线.md
+26
View File
@@ -0,0 +1,26 @@
# 编译管线
compiler 模块：ST / toml 编译器。CMake 目标：`compiler`（`STATIC`），依赖 [`指令与映像.md`](../isa/指令与映像.md)。
读齐工程后走直通 pass，产出单一映像，不上 LLVM。词法、语法、符号表、检查、codegen、链接都留在本库，不再拆 CMake 子库。
语言规则、toml 字段、链接与第 12 节阶段见 [`初步计划.md`](../初步计划.md)。指令和映像只认 [`指令与映像.md`](../isa/指令与映像.md)。
## 管线
```text
读 toml、收齐 .st
→ 词法 / 递归下降语法
→ 收集导出符号
→ 解析 VAR_EXTERNAL、链接、定地址
→ 类型检查
→ 按 PROGRAM / FUNCTION / FB 编寄存器码
→ 回填跳转、写映像头与工程哈希
```
## 边界
- toml **不声明变量**；`VAR_GLOBAL` 第一版只允许出现在 `gvl.file`
- `[[io.*]]` 的 `var` 必须已在 GVL 中；同名全局链接失败
- 第三方 toml 解析放 `third_party/`，本库私有链接
- 不写扫描周期，不链 `vm`
Doc/host/宿主入口.md
+18
View File
@@ -0,0 +1,18 @@
# 宿主入口
host 模块：可执行入口。CMake 目标：`host`（`EXECUTABLE`），链接 `compiler` 和 `vm`。
第一版一条命令：读工程 → 编译映像 → 按扫描周期跑。不拆独立的编译器可执行文件。总顺序见 [`初步计划.md`](../初步计划.md) 第 12.10 节。
## 职责
- 读 `project.toml` 和其中的 `.st`，交给 `compiler`
- 按 `[[io.input]]` / `[[io.output]]` 采样 I、写回 Q（不创造变量）
- 把 `dt_ms` 交给 VM，推进 `TON` / `TOF` / `CTU`
- 单步、看寄存器和映像、按录制的 `I` 回放
## 边界
- 指令编码见 [`指令与映像.md`](../isa/指令与映像.md)
- ST 解析与链接见 [`编译管线.md`](../compiler/编译管线.md)
- 寄存器执行循环见 [`扫描周期.md`](../vm/扫描周期.md)
Doc/vm/扫描周期.md
+22
View File
@@ -0,0 +1,22 @@
# 扫描周期
vm 模块：寄存器虚拟机。CMake 目标：`vm`（`STATIC`），只依赖 [`指令与映像.md`](../isa/指令与映像.md)。
运行时是 **一台 VM、一个入口、一份映像**。不链接 `compiler`。扫描周期与确定性见 [`初步计划.md`](../初步计划.md) 第 2、8 节。
## 扫描周期
```text
1. 按 toml 的 io 绑定，采样 → I / 输入全局
2. 从 PROGRAM MAIN 的 pc=0 执行到 RET
3. 写回 Q / 输出全局
4. 用本周期 Δt 推进 TON / TOF / CTU（不用 wall clock）
```
## 边界
- 只认 `isa` 映像；类型与溢出按 [`指令与映像.md`](../isa/指令与映像.md)（`INT` 饱和）
- 局部 / `VAR` = 固定寄存器；`nregs` 在函数头
- `CALL` 目标是立即数 `fn_id`，有界调用栈
- 无 GC、无堆、无线程；每周期受 `cycle_limit` 限制
- I/O 从哪来、Δt 谁给、回放怎么喂，属于 `host`
Doc/索引.md
+23
View File
@@ -0,0 +1,23 @@
# 文档索引
设计文档，不是编译目标。全工程定案在根下；各 CMake 模块一个文件夹，文件名标明用途。
```text
doc/
索引.md
初步计划.md
isa/指令与映像.md
compiler/编译管线.md
vm/扫描周期.md
host/宿主入口.md
```
| 路径 | 内容 |
|---|---|
| [`初步计划.md`](初步计划.md) | 全工程定案：子集 ST、toml、执行模型、第 12 节阶段 |
| [`isa/指令与映像.md`](isa/指令与映像.md) | 指令、映像、定宽类型、饱和；**规范以此为准** |
| [`compiler/编译管线.md`](compiler/编译管线.md) | 编译器边界与管线 |
| [`vm/扫描周期.md`](vm/扫描周期.md) | 扫描周期与 VM 边界 |
| [`host/宿主入口.md`](host/宿主入口.md) | 可执行入口：编译 + 跑周期 |
代码目录里的 README 只作入口；类型、指令、映像以 `isa/指令与映像.md` 为准。
README.md
+1 -1
View File
@@ -2,7 +2,7 @@
子集 ST + 扫描周期虚拟机。IEC 风格的子集 ST：用 `project.toml` 组织多个 `.st`，编译成单一映像，由寄存器虚拟机按扫描周期执行。
方案见 [`Doc/初步计划.md`](Doc/初步计划.md)。
方案见 [`Doc/初步计划.md`](Doc/初步计划.md)，模块文档见 [`Doc/索引.md`](Doc/索引.md)。
```text
多个 .st
compiler/README.md
+1 -24
View File
@@ -2,27 +2,4 @@
ST / toml 编译器。CMake 目标：`compiler`（`STATIC`），依赖 `isa`。
读齐工程后走直通 pass，产出单一映像，不上 LLVM。词法、语法、符号表、检查、codegen、链接都留在本库，不再拆 CMake 子库。
## 管线
```text
读 toml、收齐 .st
→ 词法 / 递归下降语法
→ 收集导出符号
→ 解析 VAR_EXTERNAL、链接、定地址
→ 类型检查
→ 按 PROGRAM / FUNCTION / FB 编寄存器码
→ 回填跳转、写映像头与工程哈希
```
## 工程文件
toml **不声明变量**，只做三件事：列出源文件、指定唯一 GVL、（可选）把已声明的全局接到硬件。
- 字段：`files` / `entry` / `cycle_limit` / `dt_ms` / `gvl.file` / 可选 `io.*`
- 第一版只有 `gvl.file` 允许出现 `VAR_GLOBAL`
- `[[io.*]]` 的 `var` 必须已在 GVL 中声明，否则编译错误
- 同名 `VAR_GLOBAL` 链接失败，禁止覆盖
第三方 toml 解析放在 `third_party/`，本库私有链接。
边界与管线见 [`doc/compiler/编译管线.md`](../doc/compiler/编译管线.md)。语言规则见 [`doc/初步计划.md`](../doc/初步计划.md)。
host/README.md
+1 -12
View File
@@ -2,15 +2,4 @@
可执行入口。CMake 目标：`host`（`EXECUTABLE`），链接 `compiler` 和 `vm`。
第一版一条命令：读工程 → 编译映像 → 按扫描周期跑。不拆独立的编译器可执行文件。
## 职责
- 读 `project.toml` 和其中的 `.st`，交给 `compiler`
- 按 `[[io.input]]` / `[[io.output]]` 采样 I、写回 Q
- 把 `dt_ms` 交给 VM，推进 `TON` / `TOF` / `CTU`
- 单步、看寄存器和映像、按录制的 `I` 回放
## 不放什么
指令编码（`isa`）、ST 解析与链接（`compiler`）、寄存器执行循环（`vm`）。
职责与边界见 [`doc/host/宿主入口.md`](../doc/host/宿主入口.md)。
vm/README.md
+1 -20
View File
@@ -2,23 +2,4 @@
寄存器虚拟机。CMake 目标：`vm`（`STATIC`），只依赖 `isa`。
运行时是 **一台 VM、一个入口、一份映像**。不链接 `compiler`。
## 扫描周期
```text
1. 按 toml 的 io 绑定，采样 → I / 输入全局
2. 从 PROGRAM MAIN 的 pc=0 执行到 RET
3. 写回 Q / 输出全局
4. 用本周期 Δt 推进 TON / TOF / CTU（不用 wall clock）
```
## 约束
- 局部 / `VAR` = 固定寄存器；`nregs` 写在函数头
- `I` / `Q` / `M` 走映像指令，不是通用寄存器
- FB 实例固定布局，字段偏移编译期算死
- `CALL` 目标是立即数 `fn_id`，有界调用栈
- 无 GC、无堆、无线程；每周期受 `cycle_limit` 限制
I/O 从哪来、Δt 谁给、回放怎么喂，属于 `host`。
扫描周期与边界见 [`doc/vm/扫描周期.md`](../doc/vm/扫描周期.md)。