阶段1-2:指令配置.md 重写为 machine.toml V2 schema(N5 定稿)

- op 表:prefix+op(分区内编号)替代 opcode;fmt 与前缀互锁;func 类别
  (none/width/full/float/dst)
- type 表:19 条(base 基元别名 + kind 语义 + func 显式映射,互锁强校验)
- fb 表:14 条(fb_id 0..14 + 字段类型,布局偏移编译期按 1/2/4/8 对齐算)
- 强校验清单 5 项 + 加东西流程 + 与 V1 schema 差异表
This commit is contained in:
2026-08-25 11:55:05 +08:00
parent ec1df225e2
commit 7caa407485
+127 -114
View File
@@ -1,176 +1,189 @@
# 机器定义文件(machine.toml
# 机器定义文件(machine.toml V2
指令集与类型的**唯一事实来源**,**只给编译器**STCompiler/compiler)使用。执行器(vm)不读本文件——它是下位机程序,内建全部指令。
V2 规格(STATOR2,阶段 1 定稿;N5 闭合)。schema 变更:opcode → 前缀分区 + opclass/format → fmtCAL_* 8 op → 1 CAL + fb 表 14 条。
## 架构(最终定案)
## 架构
```text
machine.toml(只给编译器:meta + type 别名表 + op 表 + fb 表)
│ 运行时加载(toml++)+ 强校验
machine.toml(只给编译器:meta + type 表 + op 表 + fb 表)
│ 运行时加载(toml++)+ 强校验(前缀/op/func/fmt 互锁)
STCompiler → compiler(编码 opcode / 类型元数据 / FB 布局 全部来自配置)
│ 写 .stb(compiler 自带写实现:型号标识[32] + SHA-256 文件尾)
.stb ──→ BytecodeExecutor → vm(执行 switch 在 vm;读 .stb 自实现)
│ + 型号匹配校验 + SHA-256 校验
│ + 型号匹配校验STATOR2+ SHA-256 校验
isa(归执行器侧,只管指令定义)
```
| 模块 | 职责 |
|---|---|
| `compiler` | 配置驱动编译;自带 `.stb` 写实现;`--disasm` 用配置参数名/format 自格式化 |
| `vm` | 内建全指令集(执行 switch 在 vm);自带 `.stb` 读实现 + 型号/SHA-256 校验;无屏蔽、不读配置 |
| `isa` | **归执行器侧**vm 依赖),**只管指令定义**Op 枚举/Instr/Encode/OpFormat/OpClass/类型/饱和/disasm。指令的具体执行实现在 vm |
| `machine.toml` | 编译器唯一知识来源 |
| `compiler` | 配置驱动编译;自带 `.stb` 写实现;`--disasm` 用配置参数名/形态自格式化 |
| `vm` | 内建全指令集(执行 switch 在 vm);自带 `.stb` 读实现 + 型号/SHA-256 校验;不读配置 |
| `isa` | 归执行器侧(vm 依赖),只管指令定义:前缀分区/Op/Instr/Encode/形态/类型/饱和/disasm |
| `machine.toml` | 编译器唯一知识来源V2 schema,本文) |
## 决策清单(定案)
## 决策清单(V2 定案)
1. 指令两大分类:**PLAIN**(无实例,26 条)/ **INSTANCE**(有实例,8 条 `CAL_*`
2. 三层分类:`class`(操作对象)→ `format`(操作数形态)→ `参数名`语义
3. isa 归执行器侧、只管指令定义;执行 switch 留在 vm
4. 配置改 TOML、改名 machine.toml,只给编译器;vm 不需要配置
5. 一致性靠 `.stb`:**型号标识[32]**(定长字符串含版本)+ **SHA-256 文件尾**compiler/vm 各实现一份)+ 强校验
6. 类型:**基元内置**(编译器内建 bit/int8..uint64/float32/float64,元数据在代码);配置类型行 = `name + base + range? + tag`(别名);**值域约束进配置**(如 BOOL range=[0,1]
7. 字符串:**方案 A**v1 不做;"组合类型"(含定长字符串 STRING(n))为未来扩展,需时再扩 .stb 格式)
8. `.stb` 读写:compiler 写、vm 读,**各自实现**(无共享 image 模块)
9. 冻结哈希测试更新(接受)
1. **指令编码**:变长 4/8/16/32B;**前缀分区**表达长度与形态(`11`/`10`/`011`/`010 xxx`/`0010`/`0011`/`0001`
2. **op 表**`prefix + op`(分区内编号)替代 V1 的单一 opcode;`fmt` 与前缀互锁;`func` 类别表达数据语义
3. **类型**:19 种 IEC 类型(编译器内建基元别名 + kind 语义 + func 显式映射)
4. **FB**14 条内建(fb_id 0..14),`[[fb]]` 表承载字段类型;CAL 指令 + fb_id16V1 的 CAL_* 8 op 作废)
5. 新增指令/类型/FB:**只改配置 + 对应实现**,指令格式零变化(N2/N3 预留位已留)
## 指令三层分类
```text
class(操作对象) → format(操作数形态) → 参数名(操作数语义)
PLAIN/INSTANCE RR/RRR/IMM/SLOT/ rd/rs/const_id/
JMP/JC/CALL/CAL/NONE slot/off/fn_id/instance
```
| 大类 | 操作对象 | 现有指令 |
|---|---|---|
| **PLAIN**(无实例) | 寄存器 / 立即数 / 槽号 / 分支 / 调用 | MOVE/LOADK/NOT/AND/OR/算术/CMP_* / JMP/JT/JF / LOAD_*/STORE_* / CALL/RET26 条) |
| **INSTANCE**(有实例) | 数据区实例块(内建 FB | CAL_TON/TOF/TP/CTU/CTD/CTUD/R_TRIG/F_TRIG8 条) |
format 不可省:同是"第二个操作数是数字",`LOADK`/`LOAD_I`/`CALL` 渲染相同但语义不同(常量 id / 槽号 / fn_id,由参数名表达);"数字 vs 寄存器 vs 偏移"的渲染差异(`r%d` / `%u` / `%+d`)只有 format 能表达。
## 配置文件格式(TOML
## 配置文件格式(TOML V2
**全属性必填,不可省略**
```toml
[meta]
name = "STATOR" # 型号名(参与 .stb 型号标识)
version = 1 # 指令集版本(参与 .stb 型号标识
version = 2 # 格式版本(型号标识 = "STATOR2"V1 = 1
# ---- 类型:编译器内建基元(bit/int8/int16/int32/int64/uint8/uint16/uint32/uint64/float32/float64
# 配置类型 = 基元别名(+ 值域约束 + .stb 契约 tag
# ---- 类型:19 种 IEC 类型(V2
# base = 编译器内建基元(bit/int8/int16/int32/int64/uint8/uint16/uint32/uint64/float32/float64
# kind = 语言语义(bool/bit/int/uint/float/time/date)——同 func 不同 kind 区分(BOOL/BYTE/USINT
# func = type 位段值(0..9),与 base 宽度/符号互锁强校验
[[type]]
name = "BOOL"
base = "uint8"
range = [0, 1] # 值域约束(语言语义数据化;缺省 = 基元全范围)
tag = 0 # 常量表契约(强校验)
kind = "bool"
func = 0
[[type]]
name = "INT"
base = "int16"
tag = 1
name = "BYTE"
base = "uint8"
kind = "bit"
func = 0
[[type]]
name = "TIME"
base = "int64"
tag = 2
name = "USINT"
base = "uint8"
kind = "uint"
func = 0
# ---- 指令(全属性必填
# ...(其余 16 条见 §类型系统,格式同
# ---- 指令(V2prefix + op + fmt + func 类别)
# prefix:形态前缀(11/10/011/010000..010101/0010/0011/0001
# op:分区内编号(0 起)
# fmt:操作数形态(RR/NONE/RRR/IMM/SLOT/JMP/JC/CALL/CAL/SLOT+off/IMM64/预留)
# func:数据语义类别(none=无类型 / width=宽度 0..3 / full=全矩阵 0..9 /
# float=浮点 8/9 / dst=目标类型 0..9
# params:参数名(与 fmt 互锁,见强校验)
[[op]]
name = "MOVE"
opcode = 0
class = "plain" # plain / instance
format = "RR"
prefix = "11"
op = 0
fmt = "RR"
func = "width"
params = ["rd", "rs"]
enabled = true
[[op]]
name = "CAL_TON"
opcode = 24
class = "instance"
format = "CAL"
params = ["instance"]
name = "LOAD"
prefix = "010001"
op = 0
fmt = "SLOT"
func = "full"
params = ["rd", "slot"]
enabled = true
[[op]]
name = "CAL"
prefix = "010101"
op = 0
fmt = "CAL"
func = "none"
params = ["fb_id", "slot"]
enabled = true
[[op]]
name = "RET"
opcode = 33
class = "plain"
format = "NONE"
prefix = "10"
op = 1
fmt = "NONE"
func = "none"
params = []
enabled = true
# ---- 内建 FB布局登记;cal_opcode 与 op 行强校验一致
# ---- 内建 FB14 条;fb_id 唯一 0..14;字段类型命中 type 表;布局偏移编译期按 1/2/4/8 对齐计算
[[fb]]
name = "ton"
opcode = 24
name = "TON"
fb_id = 0
fields = [["in", "BOOL"], ["pt", "TIME"], ["q", "BOOL"], ["et", "TIME"]]
[[fb]]
name = "ctud"
opcode = 29
fields = [["cu", "BOOL"], ["cd", "BOOL"], ["r", "BOOL"], ["lu", "BOOL"],
["pv", "INT"], ["qu", "BOOL"], ["qd", "BOOL"], ["cv", "INT"]]
name = "CTU"
fb_id = 3
fields = [["cu", "BOOL"], ["r", "BOOL"], ["pv", "INT"], ["q", "BOOL"], ["cv", "INT"]]
[[fb]]
name = "DCTU"
fb_id = 4
fields = [["cu", "BOOL"], ["r", "BOOL"], ["pv", "DINT"], ["q", "BOOL"], ["cv", "DINT"]]
[[fb]]
name = "RTC"
fb_id = 14
fields = [["enable", "BOOL"], ["date", "DATE"], ["tod", "TOD"]]
```
## 类型系统
## 类型系统19 条,func 互锁)
- **基元内置**:编译器内建 `bit/int8/int16/int32/int64/uint8/uint16/uint32/uint64/float32/float64`(宽度/有无符号/是否浮点元数据在代码,C 语义)
- **别名**:配置类型行只写 `name + base + range? + tag`——宽度/符号/浮点从 base 继承
- **值域约束**`range`(如 BOOL [0,1])供编译器做常量/赋值检查;缺省 = 基元全范围
- **tag 契约**`tag`0/1/2)与 `.stb` 常量表格式强校验(防 type 表改序破坏旧 .stb)
- **字符串**:v1 不做(方案 A);组合类型(含 `STRING(n)`)为未来扩展,文档预留,需时再扩 `.stb` 格式
- 半数据化边界:**类型定义数据化**(配置),**运算/类型检查语义代码化**(如 AND 只吃 BOOL 是语言规则,在 compiler 代码;饱和算术在 vm/isa
| 类型 | base 基元 | kind | func | 宽度/符号 |
|---|---|---|---|---|
| BOOL | uint8 | bool | 0 | 1B — |
| BYTE | uint8 | bit | 0 | 1B 无 |
| WORD | uint16 | bit | 2 | 2B 无 |
| DWORD | uint32 | bit | 4 | 4B 无 |
| LWORD | uint64 | bit | 6 | 8B 无 |
| SINT | int8 | int | 1 | 1B 有 |
| INT | int16 | int | 3 | 2B 有 |
| DINT | int32 | int | 5 | 4B 有 |
| LINT | int64 | int | 7 | 8B 有 |
| USINT | uint8 | uint | 0 | 1B 无 |
| UINT | uint16 | uint | 2 | 2B 无 |
| UDINT | uint32 | uint | 4 | 4B 无 |
| ULINT | uint64 | uint | 6 | 8B 无 |
| TIME | int64 | time | 7 | 8B 有(ms) |
| REAL | float32 | float | 8 | 4B IEEE754 |
| LREAL | float64 | float | 9 | 8B IEEE754 |
| DATE | uint32 | date | 4 | 4B 无(天) |
| TOD | uint32 | date | 4 | 4B 无(当日 ms) |
| DT | uint64 | date | 6 | 8B 无 |
## .stb 加固(格式冻结更新
- **func 互锁规则**`(width, signed)` 组合必须与 func 匹配(1B无=0、1B有=1、2B无=2、2B有=3、4B无=4、4B有=5、8B无=6、8B有=7、F32=8、F64=9
- **kind 语义**bool(编译器强制 0/1)、bit(位串,逻辑/移位运算)、uint(无符号整数算术)、int(有符号整数算术)、float(浮点)、timeTIME 毫秒)、dateDATE/TOD/DTv1 不运算)
- **语言层 19 类型名全量进关键字**;禁隐式变量转换;字面量按上下文适配;进制前缀 2#/8#/16#
见 [`指令与映像.md`](指令与映像.md):头新增 **型号标识[32]**(定长 ASCII 字符串,含版本,不足补 `'\0'`);文件尾新增 **SHA-256[32]**(对前面全部内容计算,compiler 写侧 / vm 读侧各自实现)。执行器读取时:
## 强校验清单(加载时,任一不符 → 报错退出)
```text
型号标识与自身支持型号不匹配 → 直接报错
SHA-256 不匹配 → 报错(文件损坏/篡改)
```
## 强校验清单(加载/读取时,任一不符 → 报错退出)
1. TOML 语法与字段完整性(全属性必填)
2. `type.base` 命中内建基元;`range` 合法(min ≤ max、类型相符)
3. `tag``.stb` 常量表契约一致(0/1/2
4. `op.opcode` 唯一、0..255`class` 合法;`format` 合法;**类别-格式互锁**INSTANCE ↔ CAL
5. `fb.opcode` 与 op 行的 CAL_* 一致;fb 字段类型命中配置类型表
6. 型号标识(.stb 侧)
1. **meta**`name` 非空、`version` = 2
2. **type**19 条必填全集(BOOL..DT);`base` 命中内建基元;`kind` 合法;`func` ∈ 0..9 且与 base 的 (width, signed) 互锁
3. **op**`prefix` 合法(11/10/011/010000..010101/0010/0011/0001);`prefix``fmt` 互锁(11↔RR、10↔NONE、011↔RRR、010000↔IMM、010001↔SLOT、010010↔JMP、010011↔JC、010100↔CALL、010101↔CAL、0010↔SLOT+off、0011↔IMM64);`op` 分区内唯一;`func` 类别合法(none/width/full/float/dst);`params` 数量与 fmt 互锁(RR=2、NONE=0、RRR=3、IMM=2、SLOT=2、JMP=1、JC=2、CALL=1、CAL=2、SLOT+off=3、IMM64=2);`enabled` 布尔
4. **fb**14 条必填全集(fb_id 0..14);`fb_id` 唯一;字段名唯一;字段类型命中 `[[type]]`
5. **op-fb 互锁**`CAL`010101)的 fb_id 由 `[[fb]]` 表提供——CAL 指令存在当且仅当 fb 表非空
## 加东西的流程
```text
加普通指令:machine.toml 加 [[op]] 一行 + vm 一个语义 case → 重建 vm
加内建 FB machine.toml 加 [[fb]] 一行 + vm 一个语义 case → 重建 vmcompiler 免重建)
加语言类型:machine.toml 加 [[type]] 一行(别名+tag)+ 类型检查/VM 语义代码 → 重建
改型号版本:machine.toml [meta] version +1 → 旧 .stb 被旧/新执行器按型号校验决定是否接受
```
| 加什么 | 改配置 | 改代码 |
|---|---|---|
| 新指令(RR/RRR 等已有形态) | op 表加一行(分区内空闲 op) | 编译器发射 + vm 执行 switch |
| 新形态(fmt 11..15) | — | 指令编码 + 两端实现(预留位) |
| 新类型(标量) | type 表加行 + func 空位 | 编译器类型层 + vm func 表 |
| 新内建 FB | fb 表加行 | vm do_cal 分派 + 编译器实例布局 |
| 字符串/数组/跳转表 | — | 32B 组(0001)实现(N2/N4,延后) |
## 执行计划(分支 dev_ops_config
## 与 V1 schema 的差异
```
0. 文档定案(本文 + 指令与映像.md 格式冻结更新 + stb文件格式.md 修订注记) ← 当前
1. ✅ OpFormat/OpClass 显式化 + disasm 表驱动(已完成,35dabf4
2. machine.toml 落地:meta + type 表 + op 34 条 + fb 8 条
3. compiler 配置驱动改造:toml++ 加载 + 强校验;编码 opcode / 类型元数据 /
FB 布局来自配置(compiler 不再依赖 isa
4. .stb 写侧:compiler 实现 型号标识[32] + SHA-256 文件尾
5. .stb 读侧:vm 自实现读 + 型号匹配 + SHA-256 校验(isa 的 Image 拆出)
6. CLISTCompiler --machine <path>(编译路径必填)
7. 测试:machine 解析/校验负例、型号不匹配报错、SHA-256 篡改检测、
冻结哈希更新、全量回归
8. 文档 + 提交
```
## 实现前确认项(4 项,未定案)
1. 配置文件名与位置:建议 `compiler/machine.toml`(只归编译器用)
2. 型号标识生成规则:建议 `[meta] name + version` 拼成 32 字节(如 `"STATOR" + "1"` → 补 `'\0'`);vm 内建"支持型号列表"比对
3. compiler 内部 `TypeKind`Bool/Int/Time):保留为语言语义枚举(类型检查规则),元数据从配置 base 查
4. 依赖方向确认:`compiler` 不再依赖 `isa``compiler → toml++` 自有;`STCompiler → compiler``vm → isa`
| 项 | V1 | V2 |
|---|---|---|
| meta.version | 1 | **2** |
| op 标识 | `opcode`0..33 全局) | **`prefix` + `op`**(分区内) |
| 分类 | classplain/instance+ format | **fmt**(与 prefix 互锁) |
| 数据语义 | tag0/1/2 | **func** 类别(none/width/full/float/dst |
| 类型 | 3 条(BOOL/INT/TIME | **19 条**base/kind/func |
| FB | 8 条(opcode 对应 CAL_* | **14 条**fb_id 0..14 |