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

阶段 D 步骤 11：文档同步 + 提交（指令配置全流程收尾）。

Browse Source 
- stb文件格式.md：288 字节真实拆解（头 104 含型号标识 STATOR1@0x48、函数表 0x68、
  代码 0x80 fn0 RET=0x21、数据段 0xC8 7 槽、SHA-256 尾 0x100）；工具验证与执行器关系更新
- STCompiler使用说明.md：--machine 参数（编译/disasm 必填、打印模式不需要）、
  .stb 加固说明、288 字节示例、当前状态（可编译+可执行+配置驱动）
- 执行器入口.md：读取时型号/SHA 校验拒绝
- ctest 14/14 全绿
This commit is contained in:
Admin
2026-08-21 22:35:20 +08:00
parent 40bfd175c4
commit 0ebf193ff9
3 changed files with 66 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Doc/isa/stb文件格式.md
+36 -28
View File
@@ -1,8 +1,6 @@
# .stb 映像文件结构
编译产物 `.stb` 的**面向使用者**的结构说明。规范以 [`指令与映像.md`](指令与映像.md) 为准，本文用 `line1.stb`（224 字节）做真实拆解。
> **12.13 修订**（编译器写侧已落地，vm 读侧待步骤 8）：头新增型号标识[32]（头 72 → 104 字节，段偏移基准同步后移），文件尾新增 SHA-256[32]（对文件尾之前全部内容计算）。line1 产物现为 288 字节。本文拆解仍为旧格式数字，需在 vm 侧落地后统一重新生成。
编译产物 `.stb` 的**面向使用者**的结构说明。规范以 [`指令与映像.md`](指令与映像.md) 为准，本文用 `line1.stb`（288 字节，12.13 修订后）做真实拆解。
## 概览
@@ -12,7 +10,7 @@
```
┌──────────────────────────────────────────────────┐
│ 头（72 字节，偏移 0） │
│ 头（104 字节，偏移 0，含型号标识[32]） │
├──────────────────────────────────────────────────┤
│ 常量表段 offset_const .. offset_funcs │
├──────────────────────────────────────────────────┤
@@ -22,11 +20,13 @@
├──────────────────────────────────────────────────┤
│ FB 布局段 offset_fb .. offset_data（v1 为空）│
├──────────────────────────────────────────────────┤
│ 数据段 offset_data .. 文件末尾 │
│ 数据段 offset_data .. offset_data+len │
├──────────────────────────────────────────────────┤
│ SHA-256 文件尾（32 字节，对文件尾之前全部内容） │
└──────────────────────────────────────────────────┘
```
## 头（72 字节）
## 头（104 字节）
| 偏移 | 宽 | 字段 | line1 实际值 |
|---|---|---|---|
@@ -42,11 +42,15 @@
| 40 | 4 | M 槽数 `n_m` | 0 |
| 44 | 4 | 常量数 `n_consts` | 0 |
| 48 | 4 | 函数数 `n_funcs` | 2 |
| 52 | 4 | `offset_const` | 72 |
| 56 | 4 | `offset_funcs` | 72 |
| 60 | 4 | `offset_code` | 96 |
| 64 | 4 | `offset_fb` | 168 |
| 68 | 4 | `offset_data` | 168 |
| 52 | 4 | `offset_const` | 104（`0x68`） |
| 56 | 4 | `offset_funcs` | 104 |
| 60 | 4 | `offset_code` | 128（`0x80`） |
| 64 | 4 | `offset_fb` | 200（`0xC8`） |
| 68 | 4 | `offset_data` | 200 |
| 72 | 32 | **型号标识**（定长 ASCII 含版本，补 `'\0'`） | `"STATOR1"`（`0x48..0x67`） |
> 12.13 修订：型号标识由 `machine.toml [meta] name + version` 拼成（如 `STATOR + 1` → `"STATOR1"`）；
> 执行器读取时型号不匹配 → 直接报错。
## 常量表段（`offset_const` 起）
@@ -76,15 +80,15 @@ line1（2 行）：
- `CALL` 的 `fn_id` = 函数表行下标
- 调用约定：结果 r0、参数 r1..r7、变量与临时 r8 起
line1 `MAIN` 前 5 条（`0x60` 起，slot 为 8 字节定宽槽号）：
line1 `MAIN` 前 5 条（`0x84` 起；`0x80` 是 `fn 0` 的占位 `RET`，slot 为 8 字节定宽槽号）：
| 偏移 | 字节 | 反汇编 | 含义 |
|---|---|---|---|
| 0x64 | `12 08 01 00` | `LOAD_I r8, 1` | I0_0（io.input 绑定 → LOAD_I，槽 1） |
| 0x68 | `17 08 04 00` | `STORE_GLOBAL r8, 4` | starter.start（槽 4）← I0_0 |
| 0x6C | `16 09 02 00` | `LOAD_GLOBAL r9, 2` | I0_1（槽 2） |
| 0x70 | `17 09 05 00` | `STORE_GLOBAL r9, 5` | starter.stop（槽 5）← I0_1 |
| 0x74 | `16 08 04 00` | `LOAD_GLOBAL r8, 4` | 内联体：读 starter.start（槽 4） |
| 0x84 | `12 08 01 00` | `LOAD_I r8, 1` | I0_0（io.input 绑定 → LOAD_I，槽 1） |
| 0x88 | `17 08 04 00` | `STORE_GLOBAL r8, 4` | starter.start（槽 4）← I0_0 |
| 0x8C | `16 09 02 00` | `LOAD_GLOBAL r9, 2` | I0_1（槽 2） |
| 0x90 | `17 09 05 00` | `STORE_GLOBAL r9, 5` | starter.stop（槽 5）← I0_1 |
| 0x94 | `16 08 04 00` | `LOAD_GLOBAL r8, 4` | 内联体：读 starter.start（槽 4） |
## FB 布局段（`offset_fb` 起）
@@ -96,24 +100,28 @@ v1 为空（用户 FB 内联展开，字段偏移已算进数据段；内建 8
槽序：**全局块**（`n_globals` 个，声明序）→ **FB 实例块**（POU 收集序、实例声明序，每字段一槽）。
line1 数据段（56 字节 = 7 槽 × 8B，`0xA8` 起）：
line1 数据段（56 字节 = 7 槽 × 8B，`0xC8` 起）：
| 槽号 | 偏移 | 内容 |
|---|---|---|
| 0 | 0xA8 | EmergencyStop（BOOL，初值 0） |
| 1 | 0xB0 | I0_0（BOOL） |
| 2 | 0xB8 | I0_1（BOOL） |
| 3 | 0xC0 | Q0_0（BOOL） |
| 4 | 0xC8 | starter.start（BOOL） |
| 5 | 0xD0 | starter.stop（BOOL） |
| 6 | 0xD8 | starter.q（BOOL） |
| 0 | 0xC8 | EmergencyStop（BOOL，初值 0） |
| 1 | 0xD0 | I0_0（BOOL） |
| 2 | 0xD8 | I0_1（BOOL） |
| 3 | 0xE0 | Q0_0（BOOL） |
| 4 | 0xE8 | starter.start（BOOL） |
| 5 | 0xF0 | starter.stop（BOOL） |
| 6 | 0xF8 | starter.q（BOOL） |
## SHA-256 文件尾（32 字节）
数据段之后追加 32 字节 SHA-256：**对文件尾之前全部内容计算**（`0x100..0x11F`）。执行器必须校验通过才运行；任一字节被篡改 → 直接拒绝。compiler 写侧与 vm 读侧**各自实现**一份 SHA-256。
## 用工具验证
- `ctest` 的 `isa_roundtrip` / `codegen_slice1` 覆盖编解码往返与映像校验
- `isa::ImageView` 提供只读视图（校验魔数/版本/段边界/入口 fn_id）
- `ctest`：`codegen_slice1`（写侧 model/sha 自检）、`vm_cycles`（读侧型号/SHA 拒绝）、`machine_config`
- `STCompiler x.stb --disasm --machine machine.toml`：显示 `model=` 与 `sha=ok|BAD`
- 手工检查：`xxd line1.stb` 对照上表逐段核对
## 与执行器的关系
`BytecodeExecutor`（12.9/12.10 实现）只读本格式：头（`cycle_limit`/`dt_ms`）、函数表（帧 `nregs` + 代码定位）、数据段（全局 + FB 实例状态）。I/O 绑定**不在**映像里，在 sidecar `<name>.runtime.toml`（var → 槽号 → channel/bit）。
`BytecodeExecutor` 只读本格式：头（`cycle_limit`/`dt_ms`/型号标识）、函数表（帧 `nregs` + 代码定位）、数据段（全局 + FB 实例状态）。读取时**型号匹配 + SHA-256 校验**，任一不符 → 报错拒绝。I/O 绑定**不在**映像里，在 sidecar `<name>.runtime.toml`（var → 槽号 → channel/bit）。