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

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

Browse Source 
- Types.h：定宽类型、TypeTag、饱和四则的 @brief/@param/@return
- Op.h：Op 枚举冻结约束、OpFormat/OpClass、OpDef/kOpDefs 表、三个查询函数
- Instr.h：指令字布局、pack/拆字段、按形态 enc_* 系列
- Encode.h/.cpp：Decoded 字段语义、encode/decode/disasm 契约
This commit is contained in:
Admin
2026-08-21 23:19:08 +08:00
parent 6873b5ee0b
commit 96607cfe75
5 changed files with 237 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
isa/include/isa/Encode.h
+30 -7
View File
@@ -1,6 +1,7 @@
/**
* @file Encode.h
* @brief 指令编解码与反汇编
* @details 给 STCompiler --disasm 与测试往返使用；文本格式见 Doc/isa/指令与映像.md。
* @author
* @date 2026-08-19
*/
@@ -14,18 +15,40 @@
#include "isa/Op.h"
namespace isa {
// 解码后的字段视图
/**
* @brief 解码后的字段视图。
* @details 各字段是 8 位原始值，含义按操作数形态（OpFormat）解释，
* a|b 可用 imm16 / off16 组合成 16 位视图。
*/
struct Decoded {
Op op;
uint8_t rd;
uint8_t a;
uint8_t b;
Op op; ///< 操作码
uint8_t rd; ///< 目标寄存器 / 条件寄存器
uint8_t a; ///< 源寄存器 / 立即数低 8 位 / 偏移低 8 位
uint8_t b; ///< 源寄存器 / 立即数高 8 位 / 偏移高 8 位
};
// 编解码往返：encode(decode(w)) == w
/**
* @brief 编码：字段视图打包成一条 32 位指令字。
* @param d 解码后的字段视图
* @return 打包后的指令字；满足 encode(decode(w)) == w
*/
Instr encode(Decoded d);
/**
* @brief 解码：指令字拆成字段视图。
* @param w 32 位指令字
* @return 各字段视图
*/
Decoded decode(Instr w);
// 反汇编一行文本，写入 out，至多 cap 字节（含 '\0'）。格式见 Doc/isa/指令与映像.md。
/**
* @brief 反汇编一条指令为一行文本。
* @param w 指令字
* @param out 输出缓冲
* @param cap 缓冲容量（含 '\0'）；cap==0 时直接返回、不写 out
* @details 按操作数形态表驱动输出（如 `RET`、`MOVE r1, r2`、`LOADK r0, 3`、
* `ADD r1, r2, r3`、`JMP +4`、`JT r0, -1`、`CALL 1`、`CAL_TON 0`）；
* 未知操作码输出 `??? 0x<w>`。
*/
void disasm(Instr w, char* out, size_t cap);
}
isa/include/isa/Instr.h
+95 -13
View File
@@ -1,6 +1,8 @@
/**
* @file Instr.h
* @brief 32-bit 指令打包 / 拆字段
* @brief 32-bit 指令字打包 / 拆字段
* @details 指令字布局：`[ op:8 | rd:8 | a:8 | b:8 ]`，整体是一个小端 uint32_t。
* 字段含义按操作码形态解释，见 Doc/isa/指令与映像.md。
* @author
* @date 2026-08-19
*/
@@ -12,11 +14,17 @@
#include "isa/Op.h"
namespace isa {
// 指令字：[ op:8 | rd:8 | a:8 | b:8 ]，整体是一个小端 uint32_t。
// 字段含义按操作码形态解释，见 Doc/isa/指令与映像.md。
/// 指令字：`[ op:8 | rd:8 | a:8 | b:8 ]`，小端 uint32_t。
typedef uint32_t Instr;
// 打包 / 拆字段
/**
* @brief 打包：四个字段拼成一条指令字。
* @param op 操作码（低 8 位）
* @param rd 目标寄存器 / 条件寄存器（第 8..15 位）
* @param a 源寄存器 / 立即数低 8 位 / 偏移低 8 位（第 16..23 位）
* @param b 源寄存器 / 立即数高 8 位 / 偏移高 8 位（第 24..31 位）
* @return 打包后的指令字
*/
inline Instr pack(Op op, uint8_t rd, uint8_t a, uint8_t b) {
return static_cast<uint32_t>(static_cast<uint8_t>(op))
| (static_cast<uint32_t>(rd) << 8)
@@ -24,69 +32,143 @@ namespace isa {
| (static_cast<uint32_t>(b) << 24);
}
/**
* @brief 取操作码。
* @param w 指令字
* @return 低 8 位解释为 Op
*/
inline Op op(Instr w) {
return static_cast<Op>(w & 0xFFu);
}
/**
* @brief 取目标寄存器字段。
* @param w 指令字
* @return rd（第 8..15 位）
*/
inline uint8_t rd(Instr w) {
return static_cast<uint8_t>((w >> 8) & 0xFFu);
}
/**
* @brief 取 a 字段。
* @param w 指令字
* @return a（第 16..23 位）
*/
inline uint8_t a(Instr w) {
return static_cast<uint8_t>((w >> 16) & 0xFFu);
}
/**
* @brief 取 b 字段。
* @param w 指令字
* @return b（第 24..31 位）
*/
inline uint8_t b(Instr w) {
return static_cast<uint8_t>((w >> 24) & 0xFFu);
}
// 组合视图：a|b 拼成 16 位（const_id / fn_id / slot）
/**
* @brief 组合视图：a|b 拼成 16 位无符号数。
* @param w 指令字
* @return 小端拼出的 16 位值，用作 const_id / fn_id / slot 号
*/
inline uint16_t imm16(Instr w) {
return static_cast<uint16_t>(a(w) | (static_cast<uint16_t>(b(w)) << 8));
}
// 组合视图：a|b 为有符号相对偏移，单位是指令条数
/**
* @brief 组合视图：a|b 为有符号相对偏移。
* @param w 指令字
* @return 偏移量，单位是指令条数（跳转目标 = 下一条指令 + off）
*/
inline int16_t off16(Instr w) {
return static_cast<int16_t>(imm16(w));
}
// 按形态的便捷编码
/**
* @brief 按 RR 形态编码。
* @param op 操作码（MOVE / NOT）
* @param rd 目标寄存器
* @param rs 源寄存器（放进 a）
* @return 指令字
*/
inline Instr enc_rr(Op op, uint8_t rd, uint8_t rs) {
return pack(op, rd, rs, 0); // MOVE / NOT：a = rs
return pack(op, rd, rs, 0);
}
/**
* @brief 按 RRR 形态编码。
* @param op 操作码（AND/OR/ADD/.../CMP_xx）
* @param rd 目标寄存器
* @param ra 第一源寄存器
* @param rb 第二源寄存器
* @return 指令字
*/
inline Instr enc_rrr(Op op, uint8_t rd, uint8_t ra, uint8_t rb) {
return pack(op, rd, ra, rb); // AND/OR/ADD/.../CMP_xx
return pack(op, rd, ra, rb);
}
/**
* @brief 按 IMM 形态编码。
* @param op 操作码（LOADK）
* @param rd 目标寄存器
* @param imm 16 位立即数（const_id），拆成 a|b 存放
* @return 指令字
*/
inline Instr enc_imm(Op op, uint8_t rd, uint16_t imm) {
return pack(op, rd, static_cast<uint8_t>(imm & 0xFFu),
static_cast<uint8_t>((imm >> 8) & 0xFFu)); // LOADK
static_cast<uint8_t>((imm >> 8) & 0xFFu));
}
/**
* @brief 按 JMP 形态编码。
* @param off 有符号相对偏移（条数），拆成 a|b 存放
* @return 指令字
*/
inline Instr enc_jmp(int16_t off) {
return pack(Op::JMP, 0,
static_cast<uint8_t>(static_cast<uint16_t>(off) & 0xFFu),
static_cast<uint8_t>((static_cast<uint16_t>(off) >> 8) & 0xFFu));
}
/**
* @brief 按 JC 形态编码（条件跳转）。
* @param op 操作码（JT / JF）
* @param r 条件寄存器（放进 rd）
* @param off 有符号相对偏移（条数），放进 a|b
* @return 指令字
*/
inline Instr enc_jc(Op op, uint8_t r, int16_t off) {
// JT / JF：条件寄存器在 rd，偏移在 a|b
return pack(op, r,
static_cast<uint8_t>(static_cast<uint16_t>(off) & 0xFFu),
static_cast<uint8_t>((static_cast<uint16_t>(off) >> 8) & 0xFFu));
}
/**
* @brief 按 SLOT 形态编码。
* @param op 操作码（LOAD_I / STORE_Q / LOAD_M / STORE_M / LOAD_GLOBAL / STORE_GLOBAL / CAL_*）
* @param rd 目标寄存器（CAL_* 时置 0）
* @param slot 槽号 / 实例号，放进 a|b
* @return 指令字
*/
inline Instr enc_slot(Op op, uint8_t rd, uint16_t slot) {
// LOAD_I / STORE_Q / LOAD_M / STORE_M / LOAD_GLOBAL / STORE_GLOBAL / CAL_*
// 槽号 / 实例号在 a|b
return enc_imm(op, rd, slot);
}
/**
* @brief 按 CALL 形态编码。
* @param fn_id 函数表下标，放进 a|b
* @return 指令字
*/
inline Instr enc_call(uint16_t fn_id) {
return enc_imm(Op::CALL, 0, fn_id);
}
/**
* @brief 按 NONE 形态编码（RET）。
* @return 指令字
*/
inline Instr enc_ret() {
return pack(Op::RET, 0, 0, 0);
}
isa/include/isa/Op.h
+42 -11
View File
@@ -1,6 +1,8 @@
/**
* @file Op.h
* @brief 操作码枚举 + 助记符
* @brief 操作码枚举、操作数形态与编译期指令表
* @details 操作码数值即 .stb 指令编码。执行器（vm）只依赖本表；
* 编译器侧的登记见 Doc/isa/指令配置.md（compiler/machine.toml，与之强校验）。
* @author
* @date 2026-08-19
*/
@@ -10,8 +12,11 @@
#include <cstdint>
namespace isa {
// 操作码一次列全。数值即编码：冻结后不得改顺序、不得插值，
// 增加指令只能追加到末尾，并同步 Doc/isa/指令与映像.md 与测试。
/**
* @brief 操作码枚举。
* @details 数值即编码：冻结后不得改顺序、不得插值，增加指令只能追加到末尾，
* 并同步 Doc/isa/指令与映像.md、compiler/machine.toml 与测试。
*/
enum class Op : uint8_t {
MOVE = 0, // MOVE rd, rs
LOADK = 1, // LOADK rd, const_id
@@ -50,10 +55,13 @@ namespace isa {
RET = 33, // RET
};
// 操作码总数
/// 操作码总数（= 最大 opcode + 1，kOpDefs 的下标上界）。
static const int kOpCount = 34;
// 操作数形态（三层分类第二层，见 Doc/isa/指令配置.md）
/**
* @brief 操作数形态（三层分类第二层，见 Doc/isa/指令配置.md）。
* @details 决定操作数 a|b 的解释方式与反汇编文本格式。
*/
enum class OpFormat : uint8_t {
RR, // 两寄存器：rd rs（MOVE / NOT）
RRR, // 三寄存器：rd ra rb（逻辑 / 算术 / 比较）
@@ -66,19 +74,28 @@ namespace isa {
NONE, // 无操作数（RET）
};
// 操作对象大类（三层分类第一层）
/**
* @brief 操作对象大类（三层分类第一层）。
*/
enum class OpClass : uint8_t {
Plain, // 无实例：寄存器 / 立即数 / 槽 / 分支 / 调用
Instance, // 有实例：操作数据区实例块（内建 FB）
};
// 编译期指令表：下标与 Op 数值一一对应（ops.txt 强校验的基准）
/**
* @brief 编译期指令表条目。
* @details 一条指令的名称、操作数形态与大类；下标与 Op 数值一一对应。
*/
struct OpDef {
const char* name;
OpFormat format;
OpClass cls;
const char* name; ///< 助记符（与 .stb / machine.toml 一致）
OpFormat format; ///< 操作数形态
OpClass cls; ///< 操作对象大类
};
/**
* @brief 编译期指令表：下标与 Op 数值一一对应（machine.toml 强校验的基准）。
* @details 表与 Op 枚举同步维护；查询入口见 mnemonic / format / op_class。
*/
static const OpDef kOpDefs[kOpCount] = {
{"MOVE", OpFormat::RR, OpClass::Plain}, // 0
{"LOADK", OpFormat::IMM, OpClass::Plain}, // 1
@@ -116,17 +133,31 @@ namespace isa {
{"RET", OpFormat::NONE, OpClass::Plain}, // 33
};
// 助记符 / 格式 / 大类：查表（越界返回哨兵）
/**
* @brief 查助记符。
* @param op 操作码
* @return 对应助记符；越界返回哨兵 "???"
*/
inline const char* mnemonic(Op op) {
const int idx = static_cast<int>(op);
return (idx >= 0 && idx < kOpCount) ? kOpDefs[idx].name : "???";
}
/**
* @brief 查操作数形态。
* @param op 操作码
* @return 对应 OpFormat；越界返回 OpFormat::NONE
*/
inline OpFormat format(Op op) {
const int idx = static_cast<int>(op);
return (idx >= 0 && idx < kOpCount) ? kOpDefs[idx].format : OpFormat::NONE;
}
/**
* @brief 查操作对象大类。
* @param op 操作码
* @return 对应 OpClass；越界返回 OpClass::Plain
*/
inline OpClass op_class(Op op) {
const int idx = static_cast<int>(op);
return (idx >= 0 && idx < kOpCount) ? kOpDefs[idx].cls : OpClass::Plain;
isa/include/isa/Types.h
+51 -10
View File
@@ -1,6 +1,8 @@
/**
* @file Types.h
* @brief 类型定义
* @brief 定宽类型与饱和算术
* @details 虚拟机字长与类型契约的唯一来源。compiler 与 vm 共用同一套规则，
* 详见 Doc/isa/指令与映像.md。
* @author
* @date 2026-08-18
*/
@@ -12,15 +14,28 @@
namespace isa {
namespace types {
// 定宽类型。整数溢出规则：饱和（夹到 INT 最小/最大），
// 由 compiler 与 vm 按同一规则实现，见 Doc/isa/指令与映像.md。
using BOOL = uint8_t; // 只允许 0/1
using INT = int16_t; // IEC INT
// 毫秒，有符号。64 位理由见 Doc/isa/指令与映像.md：
// 差值可负、为 DATE_AND_TIME 与 64 位定时器预留。槽位按 8 字节对齐。
/**
* @brief 布尔值：8 位，只允许 0/1（0=FALSE，1=TRUE）。
*/
using BOOL = uint8_t;
/**
* @brief IEC INT：16 位有符号整数，溢出按饱和规则处理。
*/
using INT = int16_t;
/**
* @brief 时间：64 位有符号整数，单位毫秒。
* @details 取 64 位的理由见 Doc/isa/指令与映像.md：差值可负、
* 为 DATE_AND_TIME 与 64 位定时器预留。槽位按 8 字节对齐。
*/
using TIME = int64_t;
// 槽 / 常量表类型标记，数值冻结：0=BOOL、1=INT、2=TIME（见映像规范）
/**
* @brief 槽 / 常量表类型标记。
* @details 数值冻结并写入 .stb 常量表：0=BOOL、1=INT、2=TIME（见映像规范），
* 不得改顺序、不得插值。
*/
enum TypeTag : uint8_t {
Bool = 0,
Int = 1,
@@ -29,6 +44,13 @@ namespace isa {
// 饱和算术：夹到 INT 最小/最大，编译期与 VM 共用同一规则。
/**
* @brief 饱和加法。
* @param a 加数
* @param b 加数
* @return a+b，超出 INT 范围时夹到最小/最大值
* @details 中间量用 int32 计算，避免 int16 溢出未定义行为。
*/
inline INT sat_add(INT a, INT b) {
const int32_t sum = static_cast<int32_t>(a) + static_cast<int32_t>(b);
return static_cast<INT>(sum < std::numeric_limits<INT>::min() ? std::numeric_limits<INT>::min()
@@ -36,6 +58,13 @@ namespace isa {
: sum);
}
/**
* @brief 饱和减法。
* @param a 被减数
* @param b 减数
* @return a-b，超出 INT 范围时夹到最小/最大值
* @details 中间量用 int32 计算，避免 int16 溢出未定义行为。
*/
inline INT sat_sub(INT a, INT b) {
const int32_t diff = static_cast<int32_t>(a) - static_cast<int32_t>(b);
return static_cast<INT>(diff < std::numeric_limits<INT>::min() ? std::numeric_limits<INT>::min()
@@ -43,6 +72,13 @@ namespace isa {
: diff);
}
/**
* @brief 饱和乘法。
* @param a 乘数
* @param b 乘数
* @return a*b，超出 INT 范围时夹到最小/最大值
* @details 中间量用 int32 计算，避免 int16 溢出未定义行为。
*/
inline INT sat_mul(INT a, INT b) {
const int32_t prod = static_cast<int32_t>(a) * static_cast<int32_t>(b);
return static_cast<INT>(prod < std::numeric_limits<INT>::min() ? std::numeric_limits<INT>::min()
@@ -50,12 +86,17 @@ namespace isa {
: prod);
}
/**
* @brief 饱和除法。
* @param a 被除数
* @param b 除数
* @return a/b；b==0 视为除以 1 返回 a；INT_MIN / -1 溢出饱和到 INT_MAX
* @details b==0 返回 a 是为避免未定义行为；除零的语义由 compiler/VM 层报错。
*/
inline INT sat_div(INT a, INT b) {
// b == 0 视为除以 1，避免未定义行为；除零的语义由 compiler/VM 层报错
if (b == 0) {
return a;
}
// INT_MIN / -1 溢出：饱和到 INT_MAX
if (a == std::numeric_limits<INT>::min() && b == -1) {
return std::numeric_limits<INT>::max();
}
isa/src/Encode.cpp
+19 -1
View File
@@ -1,6 +1,6 @@
/**
* @file Encode.cpp
* @brief 指令编解码与反汇编
* @brief 指令编解码与反汇编实现
* @author
* @date 2026-08-19
*/
@@ -11,10 +11,20 @@
namespace isa {
/**
* @brief 编码：字段视图打包成一条 32 位指令字。
* @param d 解码后的字段视图
* @return 打包后的指令字；满足 encode(decode(w)) == w
*/
Instr encode(Decoded d) {
return pack(d.op, d.rd, d.a, d.b);
}
/**
* @brief 解码：指令字拆成字段视图。
* @param w 32 位指令字
* @return 各字段视图
*/
Decoded decode(Instr w) {
Decoded d;
d.op = op(w);
@@ -24,6 +34,14 @@ Decoded decode(Instr w) {
return d;
}
/**
* @brief 反汇编一条指令为一行文本。
* @param w 指令字
* @param out 输出缓冲
* @param cap 缓冲容量（含 '\0'）；cap==0 时直接返回、不写 out
* @details 按操作数形态表驱动输出，文本与 Doc/isa/指令与映像.md 一致；
* 未知操作码输出 `??? 0x<w>`。
*/
void disasm(Instr w, char* out, size_t cap) {
if (cap == 0) {
return;