diff --git a/Doc/README.md b/Doc/README.md deleted file mode 100644 index d833710..0000000 --- a/Doc/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Doc - -设计文档，不是编译目标。 - -| 文件 | 内容 | -|---|---| -| [`初步计划.md`](初步计划.md) | 定案：子集 ST、toml 工程、寄存器 VM、执行模型、ST 子集；第 12 节为分阶段实现顺序 | - -仓库根目录 [`README.md`](../README.md) 只说明目录和模块边界；语言规则、映像与扫描周期的细节以本目录为准。 diff --git a/Doc/compiler/编译管线.md b/Doc/compiler/编译管线.md new file mode 100644 index 0000000..cd0c370 --- /dev/null +++ b/Doc/compiler/编译管线.md @@ -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` diff --git a/Doc/host/宿主入口.md b/Doc/host/宿主入口.md new file mode 100644 index 0000000..4dea1f9 --- /dev/null +++ b/Doc/host/宿主入口.md @@ -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) diff --git a/Doc/vm/扫描周期.md b/Doc/vm/扫描周期.md new file mode 100644 index 0000000..16d789b --- /dev/null +++ b/Doc/vm/扫描周期.md @@ -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` diff --git a/Doc/索引.md b/Doc/索引.md new file mode 100644 index 0000000..72ac6f6 --- /dev/null +++ b/Doc/索引.md @@ -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` 为准。 diff --git a/README.md b/README.md index 9debe64..ccdb042 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 子集 ST + 扫描周期虚拟机。IEC 风格的子集 ST：用 `project.toml` 组织多个 `.st`，编译成单一映像，由寄存器虚拟机按扫描周期执行。 -方案见 [`Doc/初步计划.md`](Doc/初步计划.md)。 +方案见 [`Doc/初步计划.md`](Doc/初步计划.md)，模块文档见 [`Doc/索引.md`](Doc/索引.md)。 ```text 多个 .st diff --git a/compiler/README.md b/compiler/README.md index 239d95a..eebf619 100644 --- a/compiler/README.md +++ b/compiler/README.md @@ -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)。 diff --git a/host/README.md b/host/README.md index 17e7c9c..8ffe590 100644 --- a/host/README.md +++ b/host/README.md @@ -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)。 diff --git a/vm/README.md b/vm/README.md index feba254..ec97cc3 100644 --- a/vm/README.md +++ b/vm/README.md @@ -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)。