333 lines
14 KiB
Rust
333 lines
14 KiB
Rust
//! 编译器与 VM 共享的指令协议:编译器构造逻辑指令,编码器产生双字节代码单元,
|
|
//! EndorCode 构造时解码并验证,eval 消费已解码指令;这里不执行指令或维护运行栈。
|
|
|
|
use crate::{CompareOp, VmError};
|
|
|
|
/// Endor 自有操作码;每个物理代码单元含 opcode/oparg 两字节。
|
|
/// 采用类似 CPython 的单元设计,但编号与其字节码 ABI 不兼容。
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
#[repr(u8)]
|
|
pub enum Opcode {
|
|
/// 无操作,无操作数。
|
|
Nop = 0,
|
|
/// 以操作数索引代码常量表,将借用常量保留为栈根。
|
|
LoadConst = 1,
|
|
/// 读取 localsplus 局部槽,操作数为槽索引。
|
|
LoadFast = 2,
|
|
/// 弹出栈顶写局部槽,执行器先处理对象赋值协议。
|
|
StoreFast = 3,
|
|
/// 清除局部槽并归还其根,未绑定时报错。
|
|
DeleteFast = 4,
|
|
/// 以 names 索引查全局空间,缺失再查函数捕获的内置空间。
|
|
LoadGlobal = 5,
|
|
/// 以 names 索引将栈顶写入全局字典并弹出。
|
|
StoreGlobal = 6,
|
|
/// 以 names 索引删除全局键,缺失时报错。
|
|
DeleteGlobal = 7,
|
|
/// 丢弃栈顶并释放对应根。
|
|
PopTop = 8,
|
|
/// 复制距栈顶第 argument 项(从 1 起),对象值新增栈根。
|
|
Copy = 9,
|
|
/// 交换栈顶与第 argument 项,合法深度至少为 2。
|
|
Swap = 10,
|
|
/// 压入调用协议专用 Null 标记,不是语言 Nil。
|
|
PushNull = 11,
|
|
/// 消费函数、接收者或 Null 及 argument 个显式参数,调用后留下结果。
|
|
Call = 12,
|
|
/// 移出帧结果并清理执行帧,无操作数。
|
|
ReturnValue = 13,
|
|
/// 从当前逻辑指令末尾向前跳 argument 个代码单元。
|
|
JumpForward = 14,
|
|
/// 从当前逻辑指令末尾向后跳 argument 个代码单元。
|
|
JumpBackward = 15,
|
|
/// 弹出条件,假时向前跳 argument 个代码单元。
|
|
PopJumpIfFalse = 16,
|
|
/// 弹出条件,真时向前跳 argument 个代码单元。
|
|
PopJumpIfTrue = 17,
|
|
/// 把栈顶经真值协议变为布尔值,无操作数。
|
|
ToBool = 18,
|
|
/// 对栈顶求真后逻辑取反,无操作数。
|
|
UnaryNot = 19,
|
|
/// 比较栈顶两个值;操作数采用 compare/compare_operation 的映射。
|
|
CompareOp = 20,
|
|
/// 读取 localsplus 对应 Cell 内值,空 Cell 报未绑定。
|
|
LoadDeref = 21,
|
|
/// 把栈顶写入对应 Cell,保持闭包共享槽身份。
|
|
StoreDeref = 22,
|
|
/// 清空对应 Cell,后续读取视为未绑定。
|
|
DeleteDeref = 23,
|
|
/// 压入对应 Cell 自身句柄,供创建嵌套闭包使用。
|
|
LoadClosure = 24,
|
|
/// 以 names 索引绑定栈顶对象属性,以所得值替换 owner 栈项。
|
|
LoadAttr = 25,
|
|
/// 以 names 索引把栈中的值写入对象属性。
|
|
StoreAttr = 26,
|
|
/// 消费 argument 对键值,构造插入顺序字典。
|
|
BuildMap = 27,
|
|
/// 操作数低/高 16 位分别计默认值与捕获槽数量。
|
|
MakeFunction = 28,
|
|
/// 消费四个构类输入并压入类型结果,无操作数。
|
|
BuildClass = 29,
|
|
/// 观察栈顶等待对象,Pending 保存暂停位置,Ready 替换为结果。
|
|
Await = 30,
|
|
/// 操作数指定算术种类,对两个栈值求值并压入结果。
|
|
BinaryArithmetic = 31,
|
|
/// 对栈顶数值取负,无操作数。
|
|
UnaryNegate = 32,
|
|
/// 编码器专用高位前缀;逻辑指令构造方不得直接提交。
|
|
ExtendedArg = 255,
|
|
}
|
|
|
|
impl Opcode {
|
|
/// 物理解码器验证一个操作码字节;未知编号返回 None,不做不安全 enum 转换。
|
|
fn decode(byte: u8) -> Option<Self> {
|
|
// 显式白名单保证保留编号不会误解为已实现指令。
|
|
Some(match byte {
|
|
0 => Self::Nop,
|
|
1 => Self::LoadConst,
|
|
2 => Self::LoadFast,
|
|
3 => Self::StoreFast,
|
|
4 => Self::DeleteFast,
|
|
5 => Self::LoadGlobal,
|
|
6 => Self::StoreGlobal,
|
|
7 => Self::DeleteGlobal,
|
|
8 => Self::PopTop,
|
|
9 => Self::Copy,
|
|
10 => Self::Swap,
|
|
11 => Self::PushNull,
|
|
12 => Self::Call,
|
|
13 => Self::ReturnValue,
|
|
14 => Self::JumpForward,
|
|
15 => Self::JumpBackward,
|
|
16 => Self::PopJumpIfFalse,
|
|
17 => Self::PopJumpIfTrue,
|
|
18 => Self::ToBool,
|
|
19 => Self::UnaryNot,
|
|
20 => Self::CompareOp,
|
|
21 => Self::LoadDeref,
|
|
22 => Self::StoreDeref,
|
|
23 => Self::DeleteDeref,
|
|
24 => Self::LoadClosure,
|
|
25 => Self::LoadAttr,
|
|
26 => Self::StoreAttr,
|
|
27 => Self::BuildMap,
|
|
28 => Self::MakeFunction,
|
|
29 => Self::BuildClass,
|
|
30 => Self::Await,
|
|
31 => Self::BinaryArithmetic,
|
|
32 => Self::UnaryNegate,
|
|
255 => Self::ExtendedArg,
|
|
_ => return None,
|
|
})
|
|
}
|
|
|
|
/// 编解码共用的操作数分类;无操作数指令只能携带零且不得有扩展前缀。
|
|
pub(crate) fn takes_argument(self) -> bool {
|
|
!matches!(
|
|
self,
|
|
Self::Nop
|
|
| Self::PopTop
|
|
| Self::PushNull
|
|
| Self::ReturnValue
|
|
| Self::ToBool
|
|
| Self::UnaryNot
|
|
| Self::Await
|
|
| Self::UnaryNegate
|
|
| Self::BuildClass
|
|
)
|
|
}
|
|
}
|
|
|
|
/// 编译器构造的逻辑指令;完整操作数为 u32,扩展前缀由编解码器处理。
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub struct Instruction {
|
|
/// 逻辑操作,不应手工指定 ExtendedArg。
|
|
pub opcode: Opcode,
|
|
/// 完整操作数;具体含义由 opcode 决定,构造时尚未做代码布局校验。
|
|
pub argument: u32,
|
|
}
|
|
|
|
impl Instruction {
|
|
/// 编译器/宿主组装指令;这里只赋值,合法索引和栈效果由 EndorCode 校验。
|
|
pub const fn new(opcode: Opcode, argument: u32) -> Self {
|
|
Self { opcode, argument }
|
|
}
|
|
/// 编译器发出无参数指令的便捷入口,把 argument 明确置零;此处不检查 opcode 是否真的无参数。
|
|
pub const fn simple(opcode: Opcode) -> Self {
|
|
Self::new(opcode, 0)
|
|
}
|
|
|
|
/// 编译器为栈布局 [默认值..., 捕获 Cell..., code] 生成函数创建指令。
|
|
/// 低 16 位计末尾位置参数默认值,高 16 位计按自由变量顺序排列的捕获槽。
|
|
/// VM 一次构造函数,不需要额外元组或事后修改函数字段。
|
|
pub const fn make_function(defaults: u16, closure: u16) -> Self {
|
|
Self::new(
|
|
Opcode::MakeFunction,
|
|
(defaults as u32) | ((closure as u32) << 16),
|
|
)
|
|
}
|
|
|
|
/// 编译器将比较运算转成固定操作数,与下方反向解码表配对。
|
|
pub const fn compare(operation: CompareOp) -> Self {
|
|
Self::new(
|
|
Opcode::CompareOp,
|
|
// 将六种比较映射为稳定字节码编号,必须与 eval 的 CompareOp 解码一致。
|
|
match operation {
|
|
CompareOp::Lt => 0,
|
|
CompareOp::Le => 1,
|
|
CompareOp::Eq => 2,
|
|
CompareOp::Ne => 3,
|
|
CompareOp::Gt => 4,
|
|
CompareOp::Ge => 5,
|
|
},
|
|
)
|
|
}
|
|
|
|
/// VM/校验器解析比较种类;超出六个固定值时返回 None。
|
|
pub fn compare_operation(argument: u32) -> Option<CompareOp> {
|
|
compare_operation(argument)
|
|
}
|
|
|
|
/// VM 创建函数及栈校验器拆出默认值数、闭包槽数,不访问运行栈。
|
|
pub fn function_counts(argument: u32) -> (usize, usize) {
|
|
function_counts(argument)
|
|
}
|
|
|
|
/// EndorCode::from_instructions 调用:小操作数直接编码,大操作数最多用三个前缀。
|
|
/// 每单元两字节,前缀携带高位;不在这里重算跳转距离或校验常量/槽索引。
|
|
/// 空输入可编码为空字节串,EndorCode 的后续解码才拒绝空代码,编码成功不等于可执行。
|
|
pub fn encode_all(instructions: &[Self]) -> Result<Vec<u8>, VmError> {
|
|
// 逐条追加;报错时局部缓冲丢弃,不向调用者返回部分编码。
|
|
let mut bytes = Vec::new();
|
|
// 逻辑列表中每项最终对应一个非前缀单元及零到三个前缀单元。
|
|
for instruction in instructions {
|
|
// 前缀由完整 u32 操作数推导,拒绝手工插入导致分组歧义。
|
|
if instruction.opcode == Opcode::ExtendedArg {
|
|
return Err(invalid(0, "EXTENDED_ARG is emitted by the encoder"));
|
|
}
|
|
// 无参数操作携带非零数据是协议错误,报告当前输出的代码单元位置。
|
|
if !instruction.opcode.takes_argument() && instruction.argument != 0 {
|
|
return Err(invalid(bytes.len() / 2, "unexpected instruction operand"));
|
|
}
|
|
// 大端拆分方便先发高位前缀,最低字节始终放在最终 opcode 单元。
|
|
let parts = instruction.argument.to_be_bytes();
|
|
// 跳过前导零;全零时选最后字节,保证仍发出一个有效单元。
|
|
let first = parts.iter().position(|part| *part != 0).unwrap_or(3);
|
|
// 只输出所需高位,最长三项,不把最低字节重复编码。
|
|
for part in &parts[first..3] {
|
|
bytes.extend([Opcode::ExtendedArg as u8, *part]);
|
|
}
|
|
bytes.extend([instruction.opcode as u8, parts[3]]);
|
|
}
|
|
Ok(bytes)
|
|
}
|
|
}
|
|
|
|
/// 解码器产出、代码校验器和 eval 消费的逻辑位置;公开字段本身不保证由验证过的代码产生。
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub struct DecodedInstruction {
|
|
/// 逻辑指令起点(包括首个前缀),单位是双字节代码单元。
|
|
pub offset: usize,
|
|
/// 最后一个实际 opcode 单元之后的位置,作为相对跳转的基点。
|
|
pub next_offset: usize,
|
|
/// 已合并前缀的完整逻辑指令。
|
|
pub instruction: Instruction,
|
|
}
|
|
|
|
impl DecodedInstruction {
|
|
/// VM/校验器相对逻辑指令末尾解析跳转;此处不检查目标是否为有效指令边界。
|
|
pub fn jump_target(self) -> Result<usize, VmError> {
|
|
// 非跳转操作不能借用跳转计算;条件跳转按前向距离解释。
|
|
if !matches!(
|
|
self.instruction.opcode,
|
|
Opcode::JumpForward
|
|
| Opcode::JumpBackward
|
|
| Opcode::PopJumpIfFalse
|
|
| Opcode::PopJumpIfTrue
|
|
) {
|
|
return Err(invalid(self.offset, "instruction is not a jump"));
|
|
}
|
|
crate::code::jump_target(self)
|
|
}
|
|
}
|
|
|
|
/// EndorCode::with_layout 调用,将物理单元分组成逻辑指令;后续 verify 检查控制流与栈。
|
|
pub(crate) fn decode(bytes: &[u8]) -> Result<Vec<DecodedInstruction>, VmError> {
|
|
// 拒绝空代码与半个单元,保证下方 cursor+1 总能访问操作数字节。
|
|
if bytes.is_empty() || !bytes.len().is_multiple_of(2) {
|
|
return Err(invalid(
|
|
0,
|
|
"wordcode must contain complete two-byte code units",
|
|
));
|
|
}
|
|
// 输出逻辑指令列表与物理字节游标分开,前缀不会独立进入输出。
|
|
let mut instructions = Vec::new();
|
|
// cursor 以字节计,保存到 offset/next_offset 时再除以二。
|
|
let mut cursor = 0;
|
|
// 外层每次完整读一条逻辑指令,内层吸收连续高位前缀。
|
|
while cursor < bytes.len() {
|
|
// 记住首前缀/实际指令的起点,错误定位与跳转边界均用它。
|
|
let start = cursor / 2;
|
|
// 从高到低合并最多四个操作数字节。
|
|
let mut argument = 0_u32;
|
|
// 前缀最多三个,第四个将溢出 u32 编码容量。
|
|
let mut prefixes = 0;
|
|
// 遇到实际 opcode 才完成本条;流末尾仍只有前缀时报告悬空前缀。
|
|
loop {
|
|
// 前缀之后必须还有完整单元,不能将截断流视作正常结束。
|
|
if cursor >= bytes.len() {
|
|
return Err(invalid(start, "dangling EXTENDED_ARG"));
|
|
}
|
|
// 验证编号后再组合操作数,未知编号的错误位置指向该物理单元。
|
|
let opcode = Opcode::decode(bytes[cursor])
|
|
.ok_or_else(|| invalid(cursor / 2, "unknown opcode"))?;
|
|
argument = (argument << 8) | u32::from(bytes[cursor + 1]);
|
|
cursor += 2;
|
|
// 前缀只累积数据,不压入逻辑指令列表。
|
|
if opcode == Opcode::ExtendedArg {
|
|
prefixes += 1;
|
|
// 在读取第五个数据字节之前拒绝,防截断高位。
|
|
if prefixes > 3 {
|
|
return Err(invalid(start, "too many EXTENDED_ARG prefixes"));
|
|
}
|
|
continue;
|
|
}
|
|
// 即使扩展数据全零,无参数指令也不允许前缀。
|
|
if !opcode.takes_argument() && (argument != 0 || prefixes != 0) {
|
|
return Err(invalid(start, "unexpected instruction operand"));
|
|
}
|
|
// 起点保留首前缀位置,末尾记录已消费单元之后的位置。
|
|
instructions.push(DecodedInstruction {
|
|
offset: start,
|
|
next_offset: cursor / 2,
|
|
instruction: Instruction::new(opcode, argument),
|
|
});
|
|
break;
|
|
}
|
|
}
|
|
Ok(instructions)
|
|
}
|
|
|
|
/// Instruction 公共查询和代码校验共用的比较编号反向映射。
|
|
pub(crate) fn compare_operation(argument: u32) -> Option<CompareOp> {
|
|
Some(match argument {
|
|
0 => CompareOp::Lt,
|
|
1 => CompareOp::Le,
|
|
2 => CompareOp::Eq,
|
|
3 => CompareOp::Ne,
|
|
4 => CompareOp::Gt,
|
|
5 => CompareOp::Ge,
|
|
_ => return None,
|
|
})
|
|
}
|
|
|
|
/// 解出 MAKE_FUNCTION 的两个无符号计数;合法槽布局由 EndorCode/执行器另行检查。
|
|
pub(crate) fn function_counts(argument: u32) -> (usize, usize) {
|
|
((argument & 0xffff) as usize, (argument >> 16) as usize)
|
|
}
|
|
|
|
/// 编解码与代码校验统一构造带代码单元偏移的错误,不把偏移转成源文件行号。
|
|
pub(crate) fn invalid(offset: usize, reason: &'static str) -> VmError {
|
|
VmError::InvalidBytecode { offset, reason }
|
|
}
|