//! 编译器与 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 { // 显式白名单保证保留编号不会误解为已实现指令。 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 { 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, 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 { // 非跳转操作不能借用跳转计算;条件跳转按前向距离解释。 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, 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 { 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 } }