///|
/// DEX 解析与 Dalvik 反汇编基础库的类型与公开接口。
///
/// 本文件为数据结构定义与公开 API 入口;解析实现见 `parse.mbt`、
/// 指令解码见 `instr.mbt`、smali 文本输出见 `disasm.mbt`。
/// 规范依据:AOSP dalvik-bytecode 文档与 dex 格式(Apache-2.0 / CC-BY-4.0 文档)。
/// 边界:单 DEX 容器 + 表 + code_item + 指令解码;不做 CFG、不做 Java 反编译。
///|
/// DEX 版本 / magic 前缀。多 dex(classes2.dex…)由上层合并,本库只管单个 DEX。
pub(all) enum DexVersion {
Dex035
Dex037
Dex038
Dex039
Dex040
Dex041
Unknown(Int32)
}
///|
/// 六张索引表之一的类别标识,用于错误定位与诊断输出。
#derive(Debug)
pub(all) enum TableKind {
StringId
TypeId
ProtoId
FieldId
MethodId
ClassDef
CallSiteId
MethodHandle
MapList
}
///|
pub extend TableKind with Debug::{to_repr}
///|
/// 单条 Dalvik 指令解码结果。`opcode` 为 0x00–0xFF 原值,`operands` 为已解码的字面量。
pub(all) struct Instruction {
offset : Int32
opcode : Int32
mnemonic : String
operands : Array[String]
raw : Bytes
}
///|
/// try/catch 异常处理项;`handler_pc` 为 code_item 内以 code unit 计的偏移。
pub(all) struct TryItem {
start_addr : Int32
insn_count : Int32
handler_off : Int32
catch_type_index : Int32?
}
///|
/// code_item 的结构化表示;`debug_info` 保留原始字节,暂不展开。
pub(all) struct CodeItem {
registers_size : Int32
ins_size : Int32
outs_size : Int32
tries_size : Int32
debug_info_off : Int32
insns : Array[Instruction]
tries : Array[TryItem]
debug_info : Bytes
}
///|
/// 方法定义。`code` 为 `None` 表示 abstract / native 方法。
pub(all) struct MethodDef {
class_index : Int32
name_index : Int32
proto_index : Int32
access_flags : UInt32
code_off : Int32
code : CodeItem?
}
///|
/// 字段定义。
pub(all) struct FieldDef {
class_index : Int32
type_index : Int32
name_index : Int32
access_flags : UInt32
}
///|
/// 原型(proto_id)的结构化表示。
pub(all) struct ProtoId {
shorty : String
return_type : String
parameters : Array[String]
}
///|
/// class_def 的结构化表示;`class_data_off = 0` 表示无 class_data。
pub(all) struct ClassDef {
class_index : Int32
type_descriptor : String
superclass_index : Int32?
interfaces : Array[Int32]
source_file : String?
access_flags : UInt32
class_data_off : Int32
static_fields : Array[FieldDef]
instance_fields : Array[FieldDef]
direct_methods : Array[MethodDef]
virtual_methods : Array[MethodDef]
}
///|
/// 单 DEX 文件的解析结果(纯值,无句柄)。
pub(all) struct DexFile {
version : DexVersion
checksum : UInt32
signature : Bytes
file_size : Int32
header_size : Int32
endian_tag : UInt32
strings : Array[String]
type_descriptors : Array[String]
protos : Array[ProtoId]
fields : Array[FieldDef]
methods : Array[MethodDef]
classes : Array[ClassDef]
/// DEX 038+:method_handles_item 表(无该表时为空)。
handles : Array[MethodHandleItem]
/// DEX 038+:call_site_id_item 表(无该表时为空)。
call_sites : Array[CallSiteItem]
map_list : Bytes
}
///|
/// DEX 错误模型:全部带偏移或索引,便于黄金样本差分定位。
#derive(Debug)
pub suberror DexError {
UnexpectedEof(Int32)
BadMagic(String)
UnsupportedVersion(String)
BadTableOffset(TableKind, Int32)
InvalidIndex(TableKind, Int32)
InvalidInstruction(Int32, Int32)
BadCodeItem(Int32, String)
BadDebugInfo(Int32, String)
MultiDexNotMerged(String)
}
///|
pub extend DexError with Debug::{to_repr}
///|
/// 方法句柄:在 `DexFile` 内定位一个方法,作为 `code` / `disasm` 的输入。
pub type MethodHandle = Int32
///|
/// 只读反汇编输出契约,便于后续替换为不同文本后端。
pub trait Disassembler {
fn disasm(Self, MethodHandle) -> String raise DexError
}
///|
/// 解析单个 DEX 字节流。
///
/// - 参数:`data` 为完整 DEX 文件字节;调用方保留所有权,本函数不缓存。
/// - 返回:`DexFile` 纯值,包含六张表、class_def 与已解码的 code_item/指令流。
/// - 错误:magic、版本、表偏移、索引越界、非法指令均以 `DexError` 传播。
/// - 线程:无全局可变状态,可并发解析不同 DEX;返回值为只读。
/// - 非目标:不做控制流图、不做 Java 反编译、不合并多 dex、不做符号解析。
pub fn parse(data : Bytes) -> DexFile raise DexError {
parse_dex(data)
}
///|
/// 返回全部 class_def(保持文件内顺序)。
pub fn DexFile::classes(self : DexFile) -> Array[ClassDef] {
self.classes
}
///|
/// 返回指定类(class_defs 表索引)下的全部方法(direct + virtual)。
/// `class_index` 越界抛 `InvalidIndex(ClassDef, class_index)`。
pub fn DexFile::methods(
self : DexFile,
class_index : Int32,
) -> Array[MethodDef] raise DexError {
if class_index < 0 || class_index >= self.classes.length() {
raise DexError::InvalidIndex(TableKind::ClassDef, class_index)
}
let c = self.classes[class_index]
let out : Array[MethodDef] = []
for m in c.direct_methods {
out.push(m)
}
for m in c.virtual_methods {
out.push(m)
}
out
}
///|
/// 返回指定方法(method_ids 表索引)的 code_item;abstract / native 方法返回 `None`。
/// `method_ref` 越界抛 `InvalidIndex(MethodId, method_ref)`。
pub fn DexFile::code(
self : DexFile,
method_ref : MethodHandle,
) -> CodeItem? raise DexError {
if method_ref < 0 || method_ref >= self.methods.length() {
raise DexError::InvalidIndex(TableKind::MethodId, method_ref)
}
self.methods[method_ref].code
}
///|
/// 返回字符串表(string_id 顺序)。
pub fn DexFile::strings(self : DexFile) -> Array[String] {
self.strings
}
///|
/// 输出 smali 风格反汇编文本;不做 CFG、不做类型推断。
/// `method_ref` 为 method_ids 表索引;越界抛 `InvalidIndex(MethodId, ...)`。
pub fn disasm(
dex : DexFile,
method_ref : MethodHandle,
) -> String raise DexError {
disasm_impl(dex, method_ref)
}