From fff7aef96877c2eb8d28f43657005cfd64f8a0ea Mon Sep 17 00:00:00 2001 From: chentianya Date: Fri, 21 Aug 2026 23:21:51 +0800 Subject: [PATCH] =?UTF-8?q?vm=20=E6=A8=A1=E5=9D=97=E6=B3=A8=E9=87=8A?= =?UTF-8?q?=E5=AE=8C=E5=96=84=EF=BC=9ADoxygen=20=E9=A3=8E=E6=A0=BC?= =?UTF-8?q?=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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/include/vm/Image.h | 130 +++++++++++++++++++++++++++++----------- vm/include/vm/Machine.h | 111 +++++++++++++++++++++------------- vm/src/Image.cpp | 100 ++++++++++++++++++++++++++++--- vm/src/Machine.cpp | 88 +++++++++++++++++++++++++-- 4 files changed, 341 insertions(+), 88 deletions(-) diff --git a/vm/include/vm/Image.h b/vm/include/vm/Image.h index e3dac36..33bb5bd 100644 --- a/vm/include/vm/Image.h +++ b/vm/include/vm/Image.h @@ -5,7 +5,7 @@ * @date 2026-08-21 * * @details 格式契约见 Doc/isa/指令与映像.md（12.13 修订：头 104 = 72 + 型号标识[32]， - * 文件尾 SHA-256[32]）。步骤 7：解析头与段；步骤 8：补型号匹配与 SHA-256 校验。 + * 文件尾 SHA-256[32]）。解析头与段、补型号匹配与 SHA-256 校验都在本模块完成。 */ #pragma once @@ -17,71 +17,131 @@ namespace vm { - // 执行器内建支持型号（与 machine.toml [meta] 对齐；.stb 型号不匹配直接拒绝） + /// 执行器内建支持型号（与 machine.toml [meta] 对齐；.stb 型号不匹配直接拒绝）。 static const char* const kModelName = "STATOR"; + /// 执行器内建支持型号版本（与 machine.toml [meta] 对齐）。 static const uint32_t kModelVersion = 1; - // 映像头（字段与 Doc/isa/指令与映像.md 一致） + /** + * @brief 映像头字段（104 字节；字段顺序与 Doc/isa/指令与映像.md 一致）。 + * @details 全部为小端值；型号标识 32 字节 @72 不在此结构内（见 model_id()）。 + */ struct ImageHeader { - uint32_t cycle_limit = 0; - uint32_t dt_ms = 0; - uint64_t project_hash = 0; - uint32_t entry_fn_id = 0; - uint32_t n_globals = 0; - uint32_t n_i = 0; - uint32_t n_q = 0; - uint32_t n_m = 0; - uint32_t n_consts = 0; - uint32_t n_funcs = 0; - uint32_t offset_const = 0; - uint32_t offset_funcs = 0; - uint32_t offset_code = 0; - uint32_t offset_fb = 0; - uint32_t offset_data = 0; + uint32_t cycle_limit = 0; ///< 每周期指令数上限（超出 → Fault::CycleLimit） + uint32_t dt_ms = 0; ///< 周期时长（毫秒，定时器/计数器推进步长） + uint64_t project_hash = 0; ///< 工程哈希（FNV-1a 64，只读展示） + uint32_t entry_fn_id = 0; ///< 入口函数（PROGRAM MAIN）在函数表的下标 + uint32_t n_globals = 0; ///< 全局变量槽数（数据段最前段） + uint32_t n_i = 0; ///< 输入变量（I）槽数 + uint32_t n_q = 0; ///< 输出变量（Q）槽数 + uint32_t n_m = 0; ///< 中间变量（M）槽数 + uint32_t n_consts = 0; ///< 常量表条目数 + uint32_t n_funcs = 0; ///< 函数表行数 + uint32_t offset_const = 0; ///< 常量表段起点（相对文件头） + uint32_t offset_funcs = 0; ///< 函数表段起点 + uint32_t offset_code = 0; ///< 字节码段起点 + uint32_t offset_fb = 0; ///< FB 表段起点 + uint32_t offset_data = 0; ///< 数据段起点（之后为 SHA-256 文件尾） }; + /** + * @brief 函数表一行（12 字节）。 + */ struct FuncRow { - uint32_t nregs = 0; - uint32_t code_offset = 0; // 相对字节码段起点（字节） - uint32_t code_len = 0; // 指令条数 + uint32_t nregs = 0; ///< 本函数寄存器数（函数头 nregs） + uint32_t code_offset = 0; ///< 相对字节码段起点（字节） + uint32_t code_len = 0; ///< 指令条数 }; + /** + * @brief 常量表一项（12 字节）。 + */ struct ConstEntry { - uint32_t tag = 0; - uint64_t value = 0; + uint32_t tag = 0; ///< 类型标记（isa::types::TypeTag：0=BOOL、1=INT、2=TIME） + uint64_t value = 0; ///< 值（LOADK 时按 tag 解释） }; - // 只读视图：校验过的映像（指向外部缓冲） + /** + * @brief 只读视图：指向外部缓冲的校验过的 .stb 映像。 + * @details from() 完成魔数/版本/头/各段/尺寸一致性校验；型号匹配与 SHA-256 + * 由 model_matches() / sha_ok() 另行查询（Machine::create 里一起做）。 + * 所有方法在校验失败（ok() == false）时返回安全默认值。 + */ class Image { public: + /** + * @brief 从原始字节构造只读视图（不拷贝，调用方保证生命周期）。 + * @param buf 映像缓冲；可为 nullptr + * @param len 缓冲字节数 + * @return 校验结果；ok() 判成功，error() 取失败原因 + * @details 校验项：非空、长度 ≥ 头、魔数 STSC、版本 1、五个段偏移单调且在 + * SHA-256 尾之前、常量表/函数表尺寸一致、代码段 4 字节对齐、 + * 入口 fn_id 在函数表内。 + */ static Image from(const uint8_t* buf, size_t len); + + /** + * @brief 从 vector 构造只读视图。 + * @param buf 映像缓冲（引用 data()，调用方保证生命周期） + * @return 同 from(const uint8_t*, size_t) + */ static Image from(const std::vector& buf); + /// @return 校验是否通过。 bool ok() const { return ok_; } + + /// @return 校验失败原因；成功时为空串。 const std::string& error() const { return err_; } + + /// @return 映像头字段。 const ImageHeader& header() const { return hdr_; } + /** + * @brief 读函数表一行。 + * @param i 函数下标 + * @return 该行字段；越界（或校验失败）时全 0 + */ FuncRow func_row(size_t i) const; + + /** + * @brief 读常量表一项。 + * @param i 常量下标 + * @return 该条目；越界（或校验失败）时全 0 + */ ConstEntry const_entry(size_t i) const; - const uint8_t* code_bytes() const; // 字节码段起点 - const uint8_t* data_bytes() const; // 数据段起点 - size_t data_len() const; // 字节数（不含 SHA 尾） + /// @return 字节码段起点；校验失败返回 nullptr。 + const uint8_t* code_bytes() const; - // 12.13：型号标识与 SHA-256 校验 + /// @return 数据段起点；校验失败返回 nullptr。 + const uint8_t* data_bytes() const; + + /// @return 数据段字节数（不含 SHA-256 尾）；校验失败返回 0。 + size_t data_len() const; + + /// @return 型号标识字符串（头 @72 的 32 字节，去 '\0' 截断）。 std::string model_id() const; + + /** + * @brief 型号标识是否匹配。 + * @param name 期望型号名（如 "STATOR"） + * @param version 期望版本（如 1） + * @return 头内 32 字节与 "name + version" 补零后逐字节相等 + */ bool model_matches(const std::string& name, uint32_t version) const; - bool sha_ok() const; // 文件尾 32 字节 SHA-256 校验 + + /// @return 文件尾 32 字节是否为内容（去尾后）的 SHA-256。 + bool sha_ok() const; public: - // 默认构造为无效态（ok() == false） + /// 默认构造为无效态（ok() == false）。 Image() : buf_(nullptr), len_(0) {} private: - const uint8_t* buf_; - size_t len_; - bool ok_ = false; - std::string err_; - ImageHeader hdr_; + const uint8_t* buf_; ///< 外部缓冲指针（不持有） + size_t len_; ///< 缓冲长度 + bool ok_ = false; ///< 校验是否通过 + std::string err_; ///< 失败原因 + ImageHeader hdr_; ///< 解析出的头字段 }; } diff --git a/vm/include/vm/Machine.h b/vm/include/vm/Machine.h index a3f4ba5..289b90d 100644 --- a/vm/include/vm/Machine.h +++ b/vm/include/vm/Machine.h @@ -5,7 +5,8 @@ * @date 2026-08-21 * * @details 设计说明（详见 Doc/vm/扫描周期.md 与 Doc/vm/指令执行.md）： - * - 只认 isa 映像（ImageView）；无 GC、无堆、无线程 + * - 只认 .stb 映像（vm 自带读实现；Machine::create 做型号/SHA-256 校验）； + * 无 GC、无堆、无线程 * - 扫描周期：MAIN pc=0 → RET；MAIN 帧跨周期保留，调用栈深度上限 64 * - 帧：{ fn_id, regs[nregs], ret_pc, ret_fn_id }；CALL 压帧复制 r0..r7， * RET 复制回调用方（r0=结果） @@ -24,30 +25,41 @@ namespace vm { - // 周期/指令故障 + /** + * @brief 周期/指令故障码。 + */ enum class Fault { - None, // 正常 - CycleLimit, // 本周期指令数超过映像头 cycle_limit（用例 6） - StackOverflow, // 调用栈深度超过 64 - BadOp, // 非法操作码（op ≥ 29） - BadSlot, // slot × 8 + 8 越出数据区 - BadConst, // const_id 越出常量表 + None, ///< 正常 + CycleLimit, ///< 本周期指令数超过映像头 cycle_limit（用例 6） + StackOverflow, ///< 调用栈深度超过 64 + BadOp, ///< 非法操作码 / 寄存器越界 / CALL 目标越出函数表 + BadSlot, ///< slot × 8 + 8 越出数据区 + BadConst, ///< const_id 越出常量表 }; + /** + * @brief 寄存器虚拟机：按扫描周期执行 .stb 映像。 + * @details 一个实例 = 一台机器：持有映像只读视图 + 数据区工作副本 + 调用栈。 + * MAIN 帧跨周期保留（PROGRAM 变量状态持久）；每周期从 pc=0 执行到 + * MAIN 的 RET，期间调用栈可进可出（上限 64 帧）。 + * I 采样写入 / Q 读回由外部（executor）经 data() 完成，VM 只管数据区。 + */ class Machine { public: /** - * @brief 从映像字节构建机器（校验 + 拷贝数据段 + 建 MAIN 帧） + * @brief 从映像字节构建机器（校验 + 拷贝数据段 + 建 MAIN 帧）。 * @param image .stb 映像字节 * @param out 输出 Machine（未初始化） * @param err 错误输出；可为 nullptr（静默） * @return true 成功；false（映像非法，err 已写） + * @details 校验顺序：解析 .stb（Image::from）→ SHA-256 → 型号标识匹配 + * （内建 kModelName + kModelVersion），任一不符直接拒绝。 */ static bool create(const std::vector& image, Machine* out, std::string* err); /** - * @brief 跑一个扫描周期：MAIN pc=0 执行到 RET + * @brief 跑一个扫描周期：MAIN pc=0 执行到 RET。 * @return 故障（None = 正常完成）；调用栈清空但 MAIN 帧保留 */ Fault run_cycle(); @@ -55,76 +67,93 @@ namespace vm { // ---- 可观察性（v1 预留，12.11 供单步/回放/TUI）---- /** - * @brief 执行一条指令，停在指令边界 + * @brief 执行一条指令，停在指令边界。 * @return true 继续；false 周期结束（MAIN 的 RET）或发生故障 */ bool step(); - /** @brief 最近一次故障（step 返回 false 后查询） */ + /// @brief 最近一次故障（step 返回 false 后查询）。 Fault fault() const; - /** @brief 周期是否已结束（MAIN 的 RET 后为 true） */ + /// @brief 周期是否已结束（MAIN 的 RET 后为 true）。 bool ended() const; - /** @brief 映像头（dt_ms / cycle_limit 等） */ + /// @brief 映像头（dt_ms / cycle_limit 等）。 const vm::ImageHeader& header() const; - /** @brief 当前指令下标（相对当前函数字节码段） */ + /// @brief 当前指令下标（相对当前函数字节码段）。 uint32_t pc() const; - /** @brief 当前函数 fn_id */ + /// @brief 当前函数 fn_id。 uint32_t fn_id() const; - /** @brief 本周期已执行指令数 */ + /// @brief 本周期已执行指令数。 uint32_t cycle_count() const; - /** @brief 调用栈深度（MAIN 帧 = 1） */ + /// @brief 调用栈深度（MAIN 帧 = 1）。 uint32_t call_depth() const; - /** @brief 数据区（I 采样写入 / Q 读回由外部做；8 字节定宽槽） */ + /// @brief 数据区（I 采样写入 / Q 读回由外部做；8 字节定宽槽）。 uint8_t* data(); const uint8_t* data() const; - /** @brief 数据区字节数 */ + /// @brief 数据区字节数。 size_t data_len() const; - /** @brief 当前帧寄存器值（i < nregs） */ + /// @brief 当前帧寄存器值（i < nregs）。 int64_t reg(uint8_t i) const; - /** @brief 当前帧寄存器数（函数头 nregs） */ + /// @brief 当前帧寄存器数（函数头 nregs）。 uint32_t nregs() const; - /** @brief 当前指令（pc_ 处；单步/观察用） */ + /// @brief 当前指令（pc_ 处；单步/观察用；pc 越界时返回 RET 哨兵）。 isa::Instr cur_instr() const; private: + /** + * @brief 调用帧。 + */ struct Frame { - uint32_t fn_id = 0; // 本帧函数 - std::vector regs; // 寄存器文件（大小 = 函数头 nregs） - uint32_t ret_pc = 0; // CALL 的下一条（非 MAIN 帧有意义） - uint32_t ret_fn_id = 0; // 返回目标函数 + uint32_t fn_id = 0; ///< 本帧函数 + std::vector regs; ///< 寄存器文件（大小 = 函数头 nregs） + uint32_t ret_pc = 0; ///< CALL 的下一条（非 MAIN 帧有意义） + uint32_t ret_fn_id = 0; ///< 返回目标函数 }; - vm::Image image_; // 映像只读视图（vm 自实现） - std::vector data_; // 数据区工作副本（8 字节定宽槽） - std::vector frames_; // 调用栈（[0] = MAIN，跨周期保留） - // 边沿检测上次输入（每槽 2 字节：[slot*2] 第一边沿、[slot*2+1] 第二边沿； - // CTU/CTD/R_TRIG/F_TRIG 用第一、CTUD 用两个），跨周期保留 + vm::Image image_; ///< 映像只读视图（vm 自实现，指向外部缓冲） + std::vector data_; ///< 数据区工作副本（8 字节定宽槽） + std::vector frames_; ///< 调用栈（[0] = MAIN，跨周期保留） + /** + * @brief 边沿检测上次输入（每槽 2 字节：[slot*2] 第一边沿、[slot*2+1] 第二边沿； + * CTU/CTD/R_TRIG/F_TRIG 用第一、CTUD 用两个），跨周期保留。 + */ std::vector edge_prev_; - uint32_t pc_ = 0; // 当前 pc（相对本帧函数字节码段） - uint32_t cycle_count_ = 0; // 本周期指令数 - Fault fault_ = Fault::None; // 最近一次故障 - bool ended_ = false; // step 后周期是否已结束 + uint32_t pc_ = 0; ///< 当前 pc（相对本帧函数字节码段） + uint32_t cycle_count_ = 0; ///< 本周期指令数 + Fault fault_ = Fault::None;///< 最近一次故障 + bool ended_ = false; ///< step 后周期是否已结束 + /// @brief 当前（栈顶）帧引用。 Frame& cur_frame(); + /// @brief 当前（栈顶）帧常量引用。 const Frame& cur_frame() const; - bool exec_one(); // 译码执行一条（12.9 步骤 2/3/4 填充） - Fault do_call(uint32_t fn_id); // 压帧；BadFn 用 BadOp 表示 - Fault do_ret(); // 弹帧 / 周期结束 - Fault do_cal(uint8_t op, uint16_t slot); // TON/TOF/CTU（12.9 步骤 4） - // 数据区槽读写（8 字节定宽；越界返回 false） + /// @brief 译码执行一条；false = 故障或周期结束。 + bool exec_one(); + + /// @brief 压帧（复制 r0..r7）；fn_id 越界以 BadOp 表示。 + Fault do_call(uint32_t fn_id); + + /// @brief 弹帧 / 周期结束（复制 r0..r7 回调用方）。 + Fault do_ret(); + + /// @brief 执行内置 FB（TON/TOF/TP/CTU/CTD/CTUD/R_TRIG/F_TRIG）。 + Fault do_cal(uint8_t op, uint16_t slot); + + /// @brief 读数据区槽（8 字节定宽；越界返回 false）。 bool slot_get(uint16_t slot, int64_t* out) const; + + /// @brief 写数据区槽（8 字节定宽；越界返回 false）。 bool slot_set(uint16_t slot, int64_t v); }; } diff --git a/vm/src/Image.cpp b/vm/src/Image.cpp index d826c00..66bb53f 100644 --- a/vm/src/Image.cpp +++ b/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(p[0]) | (static_cast(p[1]) << 8) @@ -29,6 +37,7 @@ namespace { | (static_cast(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(p[0]) << 24) | (static_cast(p[1]) << 16) | (static_cast(p[2]) << 8) | static_cast(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(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& 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; diff --git a/vm/src/Machine.cpp b/vm/src/Machine.cpp index ab869cf..e247d31 100644 --- a/vm/src/Machine.cpp +++ b/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& image, Machine* out, std::string* err) { out->image_ = vm::Image::from(image); @@ -67,6 +75,12 @@ bool Machine::create(const std::vector& 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(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(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(c.value); // 符号扩展 + regs[rd] = static_cast(c.value); } else { regs[rd] = static_cast(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(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(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）