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

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

Browse Source 
- 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 边界契约
This commit is contained in:
Admin
2026-08-21 23:21:51 +08:00
parent 96607cfe75
commit fff7aef968
4 changed files with 341 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
vm/include/vm/Image.h
+95 -35
View File
@@ -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<uint8_t>& 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_; ///< 解析出的头字段
};
}
vm/include/vm/Machine.h
+70 -41
View File
@@ -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<uint8_t>& 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<int64_t> regs; // 寄存器文件（大小 = 函数头 nregs）
uint32_t ret_pc = 0; // CALL 的下一条（非 MAIN 帧有意义）
uint32_t ret_fn_id = 0; // 返回目标函数
uint32_t fn_id = 0; ///< 本帧函数
std::vector<int64_t> regs; ///< 寄存器文件（大小 = 函数头 nregs）
uint32_t ret_pc = 0; ///< CALL 的下一条（非 MAIN 帧有意义）
uint32_t ret_fn_id = 0; ///< 返回目标函数
};
vm::Image image_; // 映像只读视图（vm 自实现）
std::vector<uint8_t> data_; // 数据区工作副本（8 字节定宽槽）
std::vector<Frame> frames_; // 调用栈（[0] = MAIN，跨周期保留）
// 边沿检测上次输入（每槽 2 字节：[slot*2] 第一边沿、[slot*2+1] 第二边沿；
// CTU/CTD/R_TRIG/F_TRIG 用第一、CTUD 用两个），跨周期保留
vm::Image image_; ///< 映像只读视图（vm 自实现，指向外部缓冲）
std::vector<uint8_t> data_; ///< 数据区工作副本（8 字节定宽槽）
std::vector<Frame> frames_; ///< 调用栈（[0] = MAIN，跨周期保留）
/**
* @brief 边沿检测上次输入（每槽 2 字节：[slot*2] 第一边沿、[slot*2+1] 第二边沿；
* CTU/CTD/R_TRIG/F_TRIG 用第一、CTUD 用两个），跨周期保留。
*/
std::vector<uint8_t> 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);
};
}