Interpreter/Doc/executor/执行器入口.md

执行器入口

BytecodeExecutor 模块：可执行入口。CMake 目标：BytecodeExecutor（EXECUTABLE），链接 vm 和 isa，不链 compiler。源码目录 executor/。

第一版两个可执行：STCompiler 编译出 <name>.stb 与 <name>.runtime.toml；BytecodeExecutor 加载映像按扫描周期跑。总顺序见 初步计划.md 第 12.10 节。

用法

BytecodeExecutor <name>.stb [--cycles N] [--replay <file>] [--step] [--sidecar <path>]

• --cycles N：跑 N 个周期（缺省 10）
• --replay <file>：读录制的 I 序列（每行空格分隔的 0/1，按 sidecar io.input 绑定顺序），逐周期喂入；读尽后保持最后一行
• --step：单步——采样 I 后逐指令打印（pc/fn/反汇编 + 执行后非零寄存器），跑 1 个周期，最后打印 I/Q
• 每周期打印 cycle N: I=[...] Q=[...]（按 sidecar 绑定顺序）；故障打印 FAULT(n) 并退出码 1

sidecar 定位（当前 + 计划）

• 当前（已实现）：sidecar 路径按「同名替换扩展名」推导——<name>.stb → <name>.runtime.toml。依据：sidecar 是编译产物的配对文件，同名约束由 STCompiler 写侧强制，约定即可。
• 已实现：--sidecar <path> 显式指定 I/O 绑定文件。适用场景：同一程序多套接线配置并存（厂内/现场不同 sidecar）、接线文件与 .stb 不同目录。缺省行为不变（未指定时回退到同名推导），向后兼容。

职责

• 加载 .stb 映像与 <name>.runtime.toml sidecar（I/O 绑定 var → 槽号 → channel/bit；V2 槽号为槽表条目下标）
• 读取时校验型号标识与 SHA-256：型号不匹配 / 文件被篡改 → 直接报错拒绝（执行器只接受与自身内建型号一致的映像）
• 按 sidecar 采样 I、写回 Q（不创造变量；V2 槽表两级：绑定 var → 槽号 → slot_addr → 值区）
• dt_ms / cycle_limit 从映像头取，推进内置 FB（15 条：TON/TOF/TP/CTU/DCTU/CTD/DCTD/CTUD/DCTUD/R_TRIG/F_TRIG/SR/RS/PWM/RTC）
• 单步、看寄存器和映像、按录制的 I 回放

边界

• 指令与映像编码见 指令与映像.md
• ST 解析与链接见 编译管线.md，本模块不碰 .st
• 寄存器执行循环见 扫描周期.md

---

TUI 观察界面（最后做，v1 只预留）

TUI 属于本模块（BytecodeExecutor 的界面），用途是观察 VM 运行状态（寄存器、I/Q/M、全局、FB 字段、pc、cycle 计数）。v1 不做 TUI，只预留两点：

1. 可替换输出层：所有人类可读输出走可注入 sink（默认文本模式）。将来 TUI 独占终端时，文本输出换成 TUI 渲染器，互不污染。
2. 展示层与 vm 观察 API 分离：TUI 只轮询 vm 的只读快照（见 扫描周期.md 可观察性接口），不写 VM 状态。

候选库：third_party/FTXUI/（占位，vendor 在 TUI 阶段进行，见 third_party/README.md）。