vm 模块注释完善：Doxygen 风格。

- Image.h/.cpp：头 104 布局逐字段、SHA-256 增量状态机（update/process/final）、
  校验项清单（from）、型号标识契约、func_row/const_entry/data_len 等访问器语义
- Machine.h/.cpp：Fault 枚举逐项、create 校验顺序（解析→SHA→型号）、
  调用约定（r0 结果/r1..r7 实参）、exec_one 取指/计数/分发流程、
  do_call/do_ret 帧语义、do_cal 八 FB 字段布局、slot_get/set 边界契约

vm/src/Image.cpp

@@ -1,6 +1,6 @@
 /**
  * @file Image.cpp
- * @brief vm 自带的 .stb 只读视图（执行器侧）
+ * @brief vm 自带的 .stb 只读视图实现（执行器侧；compiler 各有实现）
  * @author 
  * @date 2026-08-21
  */
@@ -14,14 +14,22 @@ namespace vm {
 
 namespace {
 
-    const uint32_t kMagic = 0x43545353u;   // "STSC" 小端
+    /// 映像魔数："STSC" 小端。
+    const uint32_t kMagic = 0x43545353u;
+    /// 映像格式版本。
     const uint32_t kVersion = 1;
+    /// 映像头字节数（72 原字段 + 型号标识[32] @72，12.13 修订）。
     const size_t kHeaderSize = 104;
+    /// 常量表一行字节数（tag:4 + value:8）。
     const size_t kConstEntrySize = 12;
+    /// 函数表一行字节数（nregs/code_offset/code_len 各 4）。
     const size_t kFuncRowSize = 12;
+    /// SHA-256 摘要长度（文件尾）。
     const size_t kSha256Size = 32;
+    /// 型号标识长度（头内 @72，不足补 '\0'）。
     const size_t kModelIdSize = 32;
 
+    /// 小端读 32 位。
     uint32_t get_le32(const uint8_t* p) {
         return static_cast<uint32_t>(p[0])
             | (static_cast<uint32_t>(p[1]) << 8)
@@ -29,6 +37,7 @@ namespace {
             | (static_cast<uint32_t>(p[3]) << 24);
     }
 
+    /// 小端读 64 位。
     uint64_t get_le64(const uint8_t* p) {
         uint64_t v = 0;
         for (int i = 0; i < 8; ++i) {
@@ -39,6 +48,7 @@ namespace {
 
     // ---- SHA-256（执行器侧实现，与 compiler 各一份）----
 
+    /// SHA-256 轮常量 K[0..63]。
     const uint32_t kShaK[64] = {
         0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
         0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
@@ -53,15 +63,26 @@ namespace {
         0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
     };
 
+    /// 循环右移。
     inline uint32_t rotr(uint32_t x, uint32_t n) { return (x >> n) | (x << (32 - n)); }
 
+    /**
+     * @brief SHA-256 增量状态机。
+     * @details 标准 FIPS 180-4 实现：update() 吸收任意长度字节流，final() 输出
+     *          32 字节大端摘要。按 64 字节块 process()。
+     */
     struct Sha256 {
         uint32_t h[8] = {0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
-                         0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19};
-        uint64_t total = 0;
-        uint8_t block[64];
-        size_t block_len = 0;
+                         0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19};  ///< 初始哈希值
+        uint64_t total = 0;   ///< 已吸收字节数（final 时编码进长度域）
+        uint8_t block[64];    ///< 当前块缓冲
+        size_t block_len = 0; ///< 块缓冲已用字节数
 
+        /**
+         * @brief 吸收数据。
+         * @param data 输入字节
+         * @param len 字节数
+         */
         void update(const uint8_t* data, size_t len) {
             total += len;
             while (len > 0) {
@@ -83,6 +104,7 @@ namespace {
             }
         }
 
+        /// 压缩一个满块（64 字节，w[0..63] 展开 + 64 轮）。
         void process() {
             uint32_t w[64];
             for (int i = 0; i < 16; ++i) {
@@ -115,6 +137,10 @@ namespace {
             h[4] += e; h[5] += f; h[6] += g; h[7] += hh;
         }
 
+        /**
+         * @brief 结束并输出摘要。
+         * @param out 32 字节输出缓冲（大端）
+         */
         void final(uint8_t out[32]) {
             const uint64_t bitlen = total * 8;
             const uint8_t pad = 0x80;
@@ -136,18 +162,31 @@ namespace {
             }
         }
 
+        /// 大端读 32 位。
         static uint32_t get_be32(const uint8_t* p) {
             return (static_cast<uint32_t>(p[0]) << 24) | (static_cast<uint32_t>(p[1]) << 16) |
                    (static_cast<uint32_t>(p[2]) << 8) | static_cast<uint32_t>(p[3]);
         }
     };
 
+    /**
+     * @brief 一次性 SHA-256。
+     * @param data 输入字节
+     * @param len 字节数
+     * @param out 32 字节摘要输出
+     */
     void sha256(const uint8_t* data, size_t len, uint8_t out[32]) {
         Sha256 s;
         s.update(data, len);
         s.final(out);
     }
 
+    /**
+     * @brief 按型号标识约定填充 32 字节：name + version（如 "STATOR1"），余下补 '\0'。
+     * @param name 型号名
+     * @param version 版本号
+     * @param out 32 字节输出缓冲
+     */
     void fill_model_id(const std::string& name, uint32_t version, char out[32]) {
         const std::string id = name + std::to_string(version);
         for (size_t i = 0; i < 32; ++i) {
@@ -157,6 +196,12 @@ namespace {
 
 }  // namespace
 
+/**
+ * @brief 从原始字节构造只读视图（不拷贝，调用方保证生命周期）。
+ * @param buf 映像缓冲；可为 nullptr
+ * @param len 缓冲字节数
+ * @return 校验结果；ok() 判成功，error() 取失败原因
+ */
 Image Image::from(const uint8_t* buf, size_t len) {
     Image v;
     v.buf_ = buf;
@@ -194,7 +239,7 @@ Image Image::from(const uint8_t* buf, size_t len) {
     h.offset_fb = get_le32(buf + 64);
     h.offset_data = get_le32(buf + 68);
 
-    // 段校验（数据段之后是 SHA-256 文件尾；步骤 8 做校验，这里仅保证有尾）
+    // 段校验（数据段之后是 SHA-256 文件尾；这里仅保证有尾，sha_ok() 做完整性校验）
     if (len < static_cast<size_t>(h.offset_data) + kSha256Size) {
         v.err_ = "missing sha256 tail";
         return v;
@@ -232,10 +277,20 @@ Image Image::from(const uint8_t* buf, size_t len) {
     return v;
 }
 
+/**
+ * @brief 从 vector 构造只读视图。
+ * @param buf 映像缓冲（引用 data()，调用方保证生命周期）
+ * @return 同 from(const uint8_t*, size_t)
+ */
 Image Image::from(const std::vector<uint8_t>& buf) {
     return from(buf.data(), buf.size());
 }
 
+/**
+ * @brief 读函数表一行。
+ * @param i 函数下标
+ * @return 该行字段；越界（或校验失败）时全 0
+ */
 FuncRow Image::func_row(size_t i) const {
     FuncRow r;
     if (ok_ && i < hdr_.n_funcs) {
@@ -247,6 +302,11 @@ FuncRow Image::func_row(size_t i) const {
     return r;
 }
 
+/**
+ * @brief 读常量表一项。
+ * @param i 常量下标
+ * @return 该条目；越界（或校验失败）时全 0
+ */
 ConstEntry Image::const_entry(size_t i) const {
     ConstEntry e;
     if (ok_ && i < hdr_.n_consts) {
@@ -257,18 +317,34 @@ ConstEntry Image::const_entry(size_t i) const {
     return e;
 }
 
+/**
+ * @brief 字节码段起点。
+ * @return 段指针；校验失败返回 nullptr
+ */
 const uint8_t* Image::code_bytes() const {
     return ok_ ? buf_ + hdr_.offset_code : nullptr;
 }
 
+/**
+ * @brief 数据段起点。
+ * @return 段指针；校验失败返回 nullptr
+ */
 const uint8_t* Image::data_bytes() const {
     return ok_ ? buf_ + hdr_.offset_data : nullptr;
 }
 
+/**
+ * @brief 数据段字节数。
+ * @return 段长度（不含 SHA-256 尾）；校验失败返回 0
+ */
 size_t Image::data_len() const {
     return ok_ ? (len_ - kSha256Size) - hdr_.offset_data : 0;
 }
 
+/**
+ * @brief 型号标识字符串。
+ * @return 头 @72 起 32 字节，去 '\0' 截断；校验失败返回空串
+ */
 std::string Image::model_id() const {
     if (!ok_) {
         return "";
@@ -281,12 +357,22 @@ std::string Image::model_id() const {
     return s;
 }
 
+/**
+ * @brief 型号标识是否匹配。
+ * @param name 期望型号名（如 "STATOR"）
+ * @param version 期望版本（如 1）
+ * @return 头内 32 字节与 "name + version" 补零后逐字节相等
+ */
 bool Image::model_matches(const std::string& name, uint32_t version) const {
     char want[kModelIdSize];
     fill_model_id(name, version, want);
     return std::memcmp(buf_ + 72, want, kModelIdSize) == 0;
 }
 
+/**
+ * @brief 文件尾 SHA-256 完整性校验。
+ * @return 对 len-32 字节内容算摘要，与文件尾 32 字节相等
+ */
 bool Image::sha_ok() const {
     if (!ok_) {
         return false;

vm/src/Machine.cpp

@@ -1,15 +1,13 @@
 /**
  * @file Machine.cpp
- * @brief 寄存器虚拟机（12.9，步骤 2：译码 switch）
+ * @brief 寄存器虚拟机实现（12.9：译码 switch + CALL/RET 帧栈 + CAL_* 定时器）
  * @author 
  * @date 2026-08-21
  *
  * @details 设计说明（详见 Doc/vm/指令执行.md）：
- * - 步骤 2 范围：create / run_cycle / step + 标量指令（MOVE/LOADK/NOT/AND/OR/算术/CMP）、
- *   跳转（JMP/JT/JF）、LOAD/STORE（slot × 8）；RET 仅处理 MAIN（周期结束）
- * - 步骤 3 补 CALL/RET 帧栈与栈深/坏操作码故障；步骤 4 补 CAL_* 定时器
  * - 取指：函数表 → code_offset（字节）→ u32；执行后 pc 先 +1，跳转再 pc += off
  * - 数据区 8 字节定宽槽：偏移 = slot × 8
+ * - 寄存器越界检查仅对把字段当寄存器的指令；a|b 作偏移/槽号/常量 id 时跳过
  */
 
 #include "vm/Machine.h"
@@ -23,6 +21,16 @@
 
 namespace vm {
 
+/**
+ * @brief 从映像字节构建机器（校验 + 拷贝数据段 + 建 MAIN 帧）。
+ * @param image .stb 映像字节
+ * @param out 输出 Machine（未初始化）
+ * @param err 错误输出；可为 nullptr（静默）
+ * @return true 成功；false（映像非法，err 已写）
+ * @details 校验顺序：解析 .stb（Image::from）→ SHA-256 → 型号标识匹配；
+ *          通过后拷贝数据段为工作副本，初始化边沿检测缓冲（每槽 2 字节），
+ *          建 MAIN 帧（跨周期保留）并把执行状态复位。
+ */
 bool Machine::create(const std::vector<uint8_t>& image, Machine* out,
                      std::string* err) {
     out->image_ = vm::Image::from(image);
@@ -67,6 +75,12 @@ bool Machine::create(const std::vector<uint8_t>& image, Machine* out,
     return true;
 }
 
+/**
+ * @brief 跑一个扫描周期：MAIN pc=0 执行到 RET。
+ * @return 故障（None = 正常完成）
+ * @details 循环执行 exec_one() 直到周期结束或故障；结束/故障后清空调用栈
+ *          （保留 MAIN 帧，PROGRAM 变量状态跨周期持久）。
+ */
 Fault Machine::run_cycle() {
     cycle_count_ = 0;
     ended_ = false;
@@ -84,6 +98,10 @@ Fault Machine::run_cycle() {
     return fault_;
 }
 
+/**
+ * @brief 执行一条指令，停在指令边界。
+ * @return true 继续；false 周期结束（MAIN 的 RET）或发生故障
+ */
 bool Machine::step() {
     if (ended_ || fault_ != Fault::None) {
         return false;
@@ -103,10 +121,19 @@ const uint8_t* Machine::data() const { return data_.data(); }
 size_t Machine::data_len() const { return data_.size(); }
 int64_t Machine::reg(uint8_t i) const { return cur_frame().regs[i]; }
 
+/**
+ * @brief 当前帧寄存器数。
+ * @return 栈顶帧 regs 大小（函数头 nregs）
+ */
 uint32_t Machine::nregs() const {
     return static_cast<uint32_t>(cur_frame().regs.size());
 }
 
+/**
+ * @brief 当前指令（pc_ 处）。
+ * @return 指令字；pc_ 越出本函数字节码段时返回 RET 哨兵
+ * @details 供单步/观察用；不修改任何执行状态。
+ */
 isa::Instr Machine::cur_instr() const {
     const vm::FuncRow row = image_.func_row(cur_frame().fn_id);
     const uint8_t* base = image_.code_bytes() + row.code_offset;
@@ -116,9 +143,20 @@ isa::Instr Machine::cur_instr() const {
     return reinterpret_cast<const uint32_t*>(base)[pc_];
 }
 
+/// @brief 当前（栈顶）帧引用。
 Machine::Frame& Machine::cur_frame() { return frames_.back(); }
+
+/// @brief 当前（栈顶）帧常量引用。
 const Machine::Frame& Machine::cur_frame() const { return frames_.back(); }
 
+/**
+ * @brief 译码执行一条指令。
+ * @return true 继续；false 故障（fault_ 已置）或周期结束
+ * @details 流程：取指（越界 → BadOp）→ 周期计数（超 cycle_limit → CycleLimit）→
+ *          pc 先 +1（跳转按"相对下一条"叠加）→ 寄存器越界检查 → 按操作码分发。
+ *          标量指令用 isa::types 饱和算术；LOAD/STORE 走 slot_get/slot_set；
+ *          CALL/RET 走 do_call/do_ret；CAL_* 走 do_cal。
+ */
 bool Machine::exec_one() {
     // ---- 取指 ----
     const vm::FuncRow row = image_.func_row(cur_frame().fn_id);
@@ -180,10 +218,11 @@ bool Machine::exec_one() {
                 return false;
             }
             const vm::ConstEntry c = image_.const_entry(cid);
+            // 按类型标记解释常量值：BOOL 归一化 0/1，INT 符号扩展，TIME 全 64 位
             if (c.tag == isa::types::Bool) {
                 regs[rd] = c.value ? 1 : 0;
             } else if (c.tag == isa::types::Int) {
-                regs[rd] = static_cast<int16_t>(c.value);  // 符号扩展
+                regs[rd] = static_cast<int16_t>(c.value);
             } else {
                 regs[rd] = static_cast<int64_t>(c.value);
             }
@@ -293,6 +332,12 @@ bool Machine::exec_one() {
     }
 }
 
+/**
+ * @brief 读数据区槽（8 字节定宽，小端）。
+ * @param slot 槽号
+ * @param out 输出值
+ * @return false = slot × 8 + 8 越出数据区
+ */
 bool Machine::slot_get(uint16_t slot, int64_t* out) const {
     const size_t off = static_cast<size_t>(slot) * 8;
     if (off + 8 > data_.size()) {
@@ -306,6 +351,12 @@ bool Machine::slot_get(uint16_t slot, int64_t* out) const {
     return true;
 }
 
+/**
+ * @brief 写数据区槽（8 字节定宽，小端）。
+ * @param slot 槽号
+ * @param v 要写入的值
+ * @return false = slot × 8 + 8 越出数据区
+ */
 bool Machine::slot_set(uint16_t slot, int64_t v) {
     const size_t off = static_cast<size_t>(slot) * 8;
     if (off + 8 > data_.size()) {
@@ -317,6 +368,14 @@ bool Machine::slot_set(uint16_t slot, int64_t v) {
     return true;
 }
 
+/**
+ * @brief 调用：压新帧。
+ * @param fn_id 目标函数（函数表下标）
+ * @return Fault（fn_id 越界 → BadOp；栈深 ≥ 64 → StackOverflow；成功 → None）
+ * @details 新帧寄存器清零，ret_pc = 当前 pc（已指向 CALL 下一条）；
+ *          按调用约定把调用方 r0..r7 复制进新帧（实参已由调用点 MOVE 进 r1..r7）；
+ *          pc 复位到新函数起点。
+ */
 Fault Machine::do_call(uint32_t fn_id) {
     if (fn_id >= image_.header().n_funcs) {
         return Fault::BadOp;
@@ -340,6 +399,13 @@ Fault Machine::do_call(uint32_t fn_id) {
     return Fault::None;
 }
 
+/**
+ * @brief 返回：弹帧 / 周期结束。
+ * @return Fault（成功 → None）
+ * @details MAIN 帧的 RET：ended_ = true（周期结束，不弹帧）。
+ *          非 MAIN 帧：按调用约定把 r0..r7 复制回调用方（r0 = 结果，r1..r7 原样），
+ *          pc 恢复为 ret_pc，弹帧。
+ */
 Fault Machine::do_ret() {
     if (frames_.size() <= 1) {
         ended_ = true;  // MAIN 的 RET：周期结束
@@ -357,6 +423,18 @@ Fault Machine::do_ret() {
     return Fault::None;
 }
 
+/**
+ * @brief 执行内置 FB（CAL_*）。
+ * @param op 操作码（CAL_TON..CAL_F_TRIG，8 个）
+ * @param slot 实例起始槽号
+ * @return Fault（槽越界 → BadSlot；非 CAL_* → BadOp；成功 → None）
+ * @details 内建 FB 布局冻结（Doc/compiler/符号表与链接.md）：
+ * - TON/TOF/TP：in/pt/q/et（字段 0/1/2/3）
+ * - CTU：cu/r/pv/q/cv（0/1/2/3/4）；CTD：cd/ld/pv/q/cv（同）
+ * - CTUD：cu/cd/r/lu/pv/qu/qd/cv（0..7）
+ * - R_TRIG / F_TRIG：clk/q（0/1）
+ * 字段偏移 = 字段序号 × 8（8 字节定宽槽）；边沿存 edge_prev_（每槽 2 字节）。
+ */
 Fault Machine::do_cal(uint8_t op, uint16_t slot) {
     // 内建 FB 布局冻结（Doc/compiler/符号表与链接.md）：
     //   TON/TOF/TP：in/pt/q/et（字段 0/1/2/3）