Interpreter/Doc/isa/指令配置.md

# 机器定义文件（machine.toml V2）

指令集与类型的**唯一事实来源**，**只给编译器**（STCompiler/compiler）使用。执行器（vm）不读本文件——它是下位机程序，内建全部指令。
V2 规格（STATOR2，阶段 1 定稿；N5 闭合）。schema 变更：opcode → 前缀分区 + op；class/format → fmt；CAL_* 8 op → 1 CAL + fb 表 14 条。

## 架构

```text
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 自实现）
                                  │         + 型号匹配校验（STATOR2）+ SHA-256 校验
                                  ▼
                              isa（归执行器侧，只管指令定义）
```

| 模块 | 职责 |
|---|---|
| `compiler` | 配置驱动编译；自带 `.stb` 写实现；`--disasm` 用配置参数名/形态自格式化 |
| `vm` | 内建全指令集（执行 switch 在 vm）；自带 `.stb` 读实现 + 型号/SHA-256 校验；不读配置 |
| `isa` | 归执行器侧（vm 依赖），只管指令定义：前缀分区/Op/Instr/Encode/形态/类型/饱和/disasm |
| `machine.toml` | 编译器唯一知识来源（V2 schema，本文） |

## 决策清单（V2 定案）

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_id16（V1 的 CAL_* 8 op 作废）
5. 新增指令/类型/FB：**只改配置 + 对应实现**，指令格式零变化（N2/N3 预留位已留）

## 配置文件格式（TOML V2）

**全属性必填，不可省略**：

```toml
[meta]
name = "STATOR"          # 型号名（参与 .stb 型号标识）
version = 2              # 格式版本（型号标识 = "STATOR2"；V1 = 1）

# ---- 类型：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"
kind = "bool"
func = 0

[[type]]
name = "BYTE"
base = "uint8"
kind = "bit"
func = 0

[[type]]
name = "USINT"
base = "uint8"
kind = "uint"
func = 0

# ...（其余 16 条见 §类型系统，格式同）

# ---- 指令（V2：prefix + 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"
prefix = "11"
op = 0
fmt = "RR"
func = "width"
params = ["rd", "rs"]
enabled = true

[[op]]
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"
prefix = "10"
op = 1
fmt = "NONE"
func = "none"
params = []
enabled = true

# ---- 内建 FB（14 条；fb_id 唯一 0..14；字段类型命中 type 表；布局偏移编译期按 1/2/4/8 对齐计算）
[[fb]]
name = "TON"
fb_id = 0
fields = [["in", "BOOL"], ["pt", "TIME"], ["q", "BOOL"], ["et", "TIME"]]

[[fb]]
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 互锁）

| 类型 | 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 无 |

- **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（浮点）、time（TIME 毫秒）、date（DATE/TOD/DT，v1 不运算）
- **语言层 19 类型名全量进关键字**；禁隐式变量转换；字面量按上下文适配；进制前缀 2#/8#/16#

## 强校验清单（加载时，任一不符 → 报错退出）

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 表非空

## 加东西的流程

| 加什么 | 改配置 | 改代码 |
|---|---|---|
| 新指令（RR/RRR 等已有形态） | op 表加一行（分区内空闲 op） | 编译器发射 + vm 执行 switch |
| 新形态（fmt 11..15） | — | 指令编码 + 两端实现（预留位） |
| 新类型（标量） | type 表加行 + func 空位 | 编译器类型层 + vm func 表 |
| 新内建 FB | fb 表加行 | vm do_cal 分派 + 编译器实例布局 |
| 字符串/数组/跳转表 | — | 32B 组（0001）实现（N2/N4，延后） |

## 与 V1 schema 的差异

| 项 | V1 | V2 |
|---|---|---|
| meta.version | 1 | **2** |
| op 标识 | `opcode`（0..33 全局） | **`prefix` + `op`**（分区内） |
| 分类 | class（plain/instance）+ format | **fmt**（与 prefix 互锁） |
| 数据语义 | tag（0/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） |