zydis-rs

A pure Rust x86/x64 disassembler and encoder library inspired by Zydis.

一个纯 Rust 实现的 x86/x64 反汇编和编码库，灵感来源于 Zydis。

Features / 特性

Core / 核心

• Decoder / 解码器: Decode x86/x64 instruction bytes into structured representation / 将字节序列解码为结构化表示
• Encoder / 编码器: Encode instructions back to bytes / 将指令编码为字节序列
• Formatter / 格式化器: Format instructions as readable text (Intel, AT&T, MASM syntax) / 格式化为可读文本（多种语法）

Technical / 技术特性

• Zero-allocation decoding: Minimal heap allocations for performance-sensitive scenarios / 零分配解码
• no_std support: Works in embedded environments / 支持 no_std 环境
• No FFI: Pure Rust implementation, no C dependencies / 纯 Rust 实现，无外部依赖
• Thread-safe: Decoder and Encoder are stateless and can be shared across threads / 线程安全

ISA Support / 指令集支持

• General-purpose integer instructions / 通用整数指令
• SSE/SSE2/SSE3/SSSE3/SSE4.1/SSE4.2
• AVX/AVX2
• AVX-512 (F, CD, BW, DQ, VL, VNNI, BF16)
• AMX (Advanced Matrix Extensions)
• BMI1/BMI2/POPCNT/LZCNT/TZCNT
• FMA/FMA4
• AES-NI/VAES/VPCLMULQDQ
• XOP/FMA4 (AMD)
• 3DNow! (AMD)
• FPU (x87)
• And more... / 更多...

Installation / 安装

Add to your Cargo.toml:

[dependencies]
zydis-rs = "0.1.0"

Feature Flags / 功能开关

Development Features / 开发特性

The zydis-sys feature is for development and testing only. It enables:

zydis-sys 功能仅用于开发和测试。它用于：

• Comparison testing against the original Zydis C library / 与原始 Zydis C 库的对比测试
• Compatibility verification between zydis-rs and Zydis C / zydis-rs 与 Zydis C 之间的兼容性验证

Warning / 警告: End users should NOT enable this feature. It requires the Zydis C library to be installed on your system and is intended for contributors who want to verify compatibility.

普通用户不应该启用此功能。它需要系统安装 Zydis C 库，仅适用于想要验证兼容性的贡献者。

To enable (requires Zydis C library installed) / 启用方法（需要安装 Zydis C 库）:

cargo test --features zydis-sys

Disable default features for no_std:

[dependencies]
zydis-rs = { version = "0.1.0", default-features = false, features = ["decoder"] }

Quick Start / 快速开始

Decoding / 解码

use zydis_rs::{Decoder, MachineMode};

// Create a 64-bit decoder
let decoder = Decoder::new(MachineMode::Long64, 64)?;

// Decode instruction
let bytes = &[0x48, 0x89, 0xD8]; // mov rax, rbx
let instruction = decoder.decode(bytes)?;

println!("Mnemonic: {}", instruction.mnemonic.name());
println!("Length: {} bytes", instruction.length);
println!("Operands: {}", instruction.operand_count);
# Ok::<(), zydis_rs::Error>(())

One-stop Disassembly / 一站式反汇编

use zydis_rs::{disassemble_intel, disassemble_all_intel, MachineMode, StackWidth};

let code = &[0x48, 0x89, 0xE5]; // mov rbp, rsp
let result = disassemble_intel(code, 0x1000, MachineMode::Long64, StackWidth::Width64)?;

println!("{}: {}", result.address, result.text); // 0x1000: mov rbp, rsp
# Ok::<(), zydis_rs::Error>(())

Encoding / 编码

use zydis_rs::{Encoder, EncoderRequest, MachineMode, Register};
use zydis_rs::isa::Mnemonic;

let encoder = Encoder::new(MachineMode::Long64, 64)?;

// Encode MOV RAX, RBX
let request = EncoderRequest::new(Mnemonic::MOV)
    .with_reg(Register::RAX)
    .with_reg(Register::RBX);

let bytes = encoder.encode(&request)?;
println!("Encoded: {:02X?}", bytes); // [0x48, 0x89, 0xD8]
# Ok::<(), zydis_rs::Error>(())

Formatting / 格式化

use zydis_rs::{Decoder, Formatter, Syntax};

let decoder = Decoder::new(MachineMode::Long64, 64)?;
let instruction = decoder.decode(&[0x48, 0x89, 0xD8])?;

// Intel syntax
let intel = Formatter::new(Syntax::Intel);
println!("{}", intel.format_instruction(&instruction)); // mov rax, rbx

// AT&T syntax
let att = Formatter::new(Syntax::Att);
println!("{}", att.format_instruction(&instruction)); // mov %rbx, %rax

// MASM syntax
let masm = Formatter::new(Syntax::Masm);
println!("{}", masm.format_instruction(&instruction)); // mov rax, rbx
# Ok::<(), zydis_rs::Error>(())

Memory Operands / 内存操作数

use zydis_rs::{Encoder, EncoderRequest, MachineOperand, MachineMode, Register};
use zydis_rs::isa::Mnemonic;

let encoder = Encoder::new(MachineMode::Long64, 64)?;

// MOV RAX, [RBP - 8]
let mem = MemoryOperand::base_disp(Register::RBP, -8);
let request = EncoderRequest::new(Mnemonic::MOV)
    .with_reg(Register::RAX)
    .with_mem(mem);

let bytes = encoder.encode(&request)?;
# Ok::<(), zydis_rs::Error>(())

AVX Instructions / AVX 指令

use zydis_rs::{Decoder, Encoder, EncoderRequest, MachineMode, Register};
use zydis_rs::isa::Mnemonic;

let decoder = Decoder::new(MachineMode::Long64, 64)?;
let encoder = Encoder::new(MachineMode::Long64, 64)?;

// Decode AVX instruction
let avx_bytes = &[0xC5, 0xF0, 0x58, 0xC2]; // VADDPS XMM0, XMM1, XMM2
let instruction = decoder.decode(avx_bytes)?;
println!("{}", instruction.mnemonic.name()); // VADDPS

// Encode AVX instruction
let request = EncoderRequest::new(Mnemonic::VADDPS)
    .with_reg(Register::XMM0)
    .with_reg(Register::XMM1)
    .with_reg(Register::XMM2);
let encoded = encoder.encode(&request)?;
# Ok::<(), zydis_rs::Error>(())

Examples / 示例

The examples/ directory contains comprehensive examples:

Run an example:

cargo run --example basic_decode
cargo run --example avx512_decode

Benchmarks / 性能测试

Run the benchmark suite:

# All benchmarks
cargo bench

# Specific benchmark
cargo bench --bench decode_benchmark
cargo bench --bench encode_benchmark
cargo bench --bench format_benchmark

Documentation / 文档

Generate and view the API documentation:

cargo doc --open

Key Documentation / 关键文档

• CHANGELOG - Version history and changes / 版本历史和变更
• Migration Guide - Migrating from Zydis C API / 从 Zydis C API 迁移
• Development Roadmap - Development progress / 开发进度

Testing / 测试

# Run all tests
cargo test

# Run specific test
cargo test --test integration_test

# Run compatibility tests
cargo test --test compat_test

# Run doc tests
cargo test --doc

Current Status / 当前状态

Comparison with Zydis / 与 Zydis 对比

Architecture / 架构

zydis-rs
├── src/
│   ├── lib.rs           # Library entry point
│   ├── error.rs         # Error types
│   ├── decoder/         # Decoding module
│   │   ├── mod.rs       # Decoder implementation
│   │   ├── instruction.rs
│   │   ├── operand.rs
│   │   └── prefix.rs
│   ├── encoder/         # Encoding module
│   │   ├── mod.rs       # Encoder implementation
│   │   ├── request.rs
│   │   └── vex.rs, evex.rs
│   ├── formatter/       # Formatting module
│   │   ├── mod.rs       # Formatter implementation
│   │   ├── intel.rs
│   │   ├── att.rs
│   │   └── masm.rs
│   ├── isa/             # ISA definitions
│   │   ├── mnemonic.rs
│   │   ├── register.rs
│   │   └── attributes.rs
│   └── data/            # Instruction tables
├── examples/            # Usage examples
├── benches/             # Performance benchmarks
└── tests/               # Integration tests

Contributing / 贡献

Contributions are welcome! Please feel free to submit a Pull Request.

欢迎贡献代码！请随时提交 Pull Request。

License / 许可证

MIT License

Acknowledgments / 致谢

This project is inspired by Zydis, an excellent C x86/x64 disassembler library.

本项目灵感来源于 Zydis，一个优秀的 C 语言 x86/x64 反汇编库。