zydis_rs/
lib.rs

1//! # zydis-rs
2//!
3//! 一个纯 Rust 实现的 x86/x64 反汇编和编码库，灵感来源于 Zydis。
4//!
5//! A pure Rust x86/x64 disassembler and encoder library inspired by Zydis.
6//!
7//! ## 功能特性 / Features
8//!
9//! - **零内存分配解码** - 高效的指令解码，适合性能敏感场景
10//! - **Intel 和 AT&T 语法格式化** - 灵活的输出格式选择
11//! - **指令编码** - 从结构化表示生成 x86/x64 指令机器码
12//! - **无外部依赖** - 纯 Rust 实现，无需 FFI 调用
13//! - **`no_std` 兼容** - 可在嵌入式环境中使用
14//! - **AVX/AVX2/AVX-512 支持** - 完整的现代 SIMD 指令集支持
15//!
16//! ## 功能开关 / Feature Flags
17//!
18//! - `decoder` (默认) - 指令解码支持
19//! - `formatter` (默认) - 指令格式化（Intel/AT&T 语法）
20//! - `encoder` - 指令编码支持
21//! - `std` - 标准库支持（默认禁用，no_std 环境）
22//!
23//! ## 快速开始 / Quick Start
24//!
25//! ### 一站式反汇编 / One-stop Disassembly
26//!
27//! 最简单的使用方式是使用一站式函数：
28//!
29//! ```rust,ignore
30//! use zydis_rs::{disassemble_intel, disassemble_all_intel, MachineMode, StackWidth};
31//!
32//! let code = &[0x48, 0x89, 0xE5]; // mov rbp, rsp
33//! let result = disassemble_intel(code, 0x1000, MachineMode::Long64, StackWidth::Width64)?;
34//!
35//! println!("{}", result.text); // "mov rbp, rsp"
36//! println!("0x{:X}", result.address); // 0x1000
37//! println!("{}", result.length); // 3
38//! # Ok::<(), zydis_rs::Error>(())
39//! ```
40//!
41//! ### 底层解码 / Low-level Decoding
42//!
43//! 如需更多控制，可直接使用 `Decoder` 和 `Formatter`：
44//!
45//! ```rust,ignore
46//! use zydis_rs::{Decoder, Formatter, Syntax, MachineMode, StackWidth};
47//!
48//! let code = &[0x48, 0x89, 0xE5]; // mov rbp, rsp
49//! let decoder = Decoder::new(MachineMode::Long64, StackWidth::Width64)?;
50//!
51//! let instruction = decoder.decode(code)?;
52//!
53//! let formatter = Formatter::new(Syntax::Intel);
54//! println!("{}", formatter.format_instruction(&instruction)); // "mov rbp, rsp"
55//! # Ok::<(), zydis_rs::Error>(())
56//! ```
57//!
58//! ### 指令编码 / Instruction Encoding
59//!
60//! 使用编码器生成 x86/x64 机器码：
61//!
62//! ```rust,ignore
63//! use zydis_rs::{Encoder, EncoderRequest, MachineMode, Mnemonic, Register};
64//!
65//! let encoder = Encoder::new(MachineMode::Long64, 64)?;
66//!
67//! // 编码 MOV RAX, 0x12345678
68//! // Encode MOV RAX, 0x12345678
69//! let request = EncoderRequest::new(Mnemonic::MOV)
70//!     .with_reg(Register::RAX)
71//!     .with_imm(0x12345678);
72//! let bytes = encoder.encode(&request)?;
73//!
74//! println!("{:?}", bytes); // [0x48, 0xB8, 0x78, 0x56, 0x34, 0x12, 0x00, 0x00, 0x00, 0x00]
75//! # Ok::<(), zydis_rs::Error>(())
76//! ```
77//!
78//! ## 支持的指令集 / Supported Instruction Sets
79//!
80//! - 通用整数指令（ADD, SUB, MOV, JMP, 等）
81//! - SSE/SSE2/SSE3/SSSE3/SSE4 指令集
82//! - AVX/AVX2 指令集
83//! - AVX-512 指令集（F, CD, BW, DQ, VL）
84//! - AMD XOP 指令集
85//!
86//! ## 示例 / Examples
87//!
88//! 查看 `examples/` 目录获取更多使用示例：
89//!
90//! - `basic_disasm.rs` - 基础反汇编
91//! - `encoder_demo.rs` - 编码器使用
92//! - `roundtrip.rs` - 编码后验证解码
93//!
94//! ## 架构说明 / Architecture Notes
95//!
96//! ### 解码器架构 / Decoder Architecture
97//!
98//! 解码器采用流水线式处理：
99//! 1. 前缀解析（Legacy, REX, VEX, EVEX, XOP）
100//! 2. 操作码查找
101//! 3. ModR/M 和 SIB 解析
102//! 4. 偏移量和立即数提取
103//! 5. 操作数构建
104//!
105//! ### 格式化器架构 / Formatter Architecture
106//!
107//! 格式化器支持多种语法风格：
108//! - **Intel**: `mov rax, rbx` - 标准 Intel 语法
109//! - **AT&T**: `mov %rbx, %rax` - GNU 工具使用的 AT&T 语法
110//! - **MASM**: `mov dword ptr [rax], 0x12345678` - Microsoft MASM 语法
111
112#![cfg_attr(not(feature = "std"), no_std)]
113
114extern crate alloc;
115
116// 核心模块
117pub mod error;
118pub mod isa;
119
120#[cfg(feature = "decoder")]
121pub mod decoder;
122
123#[cfg(feature = "formatter")]
124pub mod formatter;
125
126#[cfg(all(feature = "decoder", feature = "formatter"))]
127mod disassembler;
128
129#[cfg(feature = "encoder")]
130pub mod encoder;
131
132// 内部数据模块
133pub mod data;
134
135// FFI 模块 (用于对比测试)
136#[cfg(feature = "ffi")]
137pub mod ffi;
138
139// 重导出常用类型
140pub use error::{Error, Result};
141pub use isa::{MachineMode, Mnemonic, Register, RegisterClass, StackWidth};
142
143#[cfg(feature = "decoder")]
144pub use decoder::{
145    BranchType, ConditionCode, DecodedInstruction, Decoder, ExceptionClass, OpcodeMap, Operand,
146};
147
148#[cfg(feature = "formatter")]
149pub use formatter::{Formatter, OutputBuffer, Syntax};
150
151// 编码器重导出
152#[cfg(feature = "encoder")]
153pub use encoder::{Encoder, EncoderOperand, EncoderRequest, EvexZeroingMode, MemoryOperand};
154
155// 一站式 API 重导出
156#[cfg(all(feature = "decoder", feature = "formatter"))]
157pub use disassembler::{
158    DisassembledInstruction, DisassemblyIterator, disassemble_all_intel, disassemble_att,
159    disassemble_intel,
160};
161
162/// 库版本信息
163///
164/// # 示例 / Example
165///
166/// ```rust,ignore
167/// use zydis_rs::VERSION;
168/// println!("zydis-rs version: {}", VERSION);
169/// ```
170pub const VERSION: &str = env!("CARGO_PKG_VERSION");
zydis_rs/lib.rs

zydis_rs/
lib.rs
