Crate x86_64_assembler

Crate x86_64_assembler 

Source
Expand description

§x86_64-assembler

支持 x64 和 x86 指令集的现代汇编器 - 强类型、面向对象、零依赖核心

§功能特性

  • 强类型设计: 使用 Rust 的类型系统确保汇编代码的正确性
  • 双架构支持: 同时支持 x86 和 x86_64 架构
  • 零依赖核心: 核心功能不依赖外部库，保证轻量和可靠性
  • 完整的指令集: 支持常用的 x86/x86_64 指令，包括数据传输、算术运算、控制流等
  • 灵活的 API: 提供高级构建器 API 和底层编码/解码 API
  • 错误处理: 完善的错误处理机制，提供清晰的错误信息

§核心组件

§1. X86_64Assembler - 主汇编器

主入口点，提供编码和解码功能：

use x86_64_assembler::X86_64Assembler;
use gaia_types::helpers::Architecture;

let assembler = X86_64Assembler::new(Architecture::X86_64)?;

§2. ProgramBuilder - 程序构建器

高级 API，用于构建汇编程序：

use x86_64_assembler::builder::ProgramBuilder;
use x86_64_assembler::instruction::Register;

let mut builder = ProgramBuilder::new(Architecture::X86_64);
builder
    .mov_reg_imm(Register::RAX, 42)?
    .push_reg(Register::RAX)?
    .call("my_function")?
    .ret()?;

§3. Instruction - 指令定义

完整的指令枚举，支持：

  • 数据传输: MOV, PUSH, POP
  • 算术运算: ADD, SUB
  • 控制流: CALL, RET
  • 其他: LEA, NOP

§4. 寄存器支持

完整的寄存器枚举，包括：

  • 8位寄存器: AL, CL, DL, BL, AH, CH, DH, BH
  • 16位寄存器: AX, CX, DX, BX, SP, BP, SI, DI
  • 32位寄存器: EAX, ECX, EDX, EBX, ESP, EBP, ESI, EDI
  • 64位寄存器: RAX, RCX, RDX, RBX, RSP, RBP, RSI, RDI
  • 扩展寄存器: R8-R15 及其子寄存器

§5. 操作数类型

支持多种操作数类型：

  • 寄存器操作数: Operand::Reg(Register::RAX)
  • 立即数操作数: Operand::imm(42, 64)
  • 内存操作数: Operand::mem(Some(Register::RAX), None, 1, 0)
  • 标签操作数: Operand::label("my_label")

§使用示例

§基本用法

use x86_64_assembler::{X86_64Assembler, instruction::{Instruction, Operand, Register}};
use gaia_types::helpers::Architecture;

// 创建汇编器
let assembler = X86_64Assembler::new(Architecture::X86_64)?;

// 构建指令
let instruction = Instruction::Mov {
    dst: Operand::Reg(Register::RAX),
    src: Operand::imm(42, 64),
};

// 编码指令
let bytes = assembler.encode(&instruction)?;
println!("编码结果: {:?}", bytes);

// 解码字节码
let decoded = assembler.decode(&bytes)?;
println!("解码结果: {:?}", decoded);

§使用构建器

use x86_64_assembler::builder::ProgramBuilder;
use x86_64_assembler::instruction::Register;
use gaia_types::helpers::Architecture;

let mut builder = ProgramBuilder::new(Architecture::X86_64);

// 构建一个简单的函数
builder
    .mov_reg_imm(Register::RAX, 10)?      // mov rax, 10
    .mov_reg_imm(Register::RDX, 20)?      // mov rdx, 20
    .add_reg_imm(Register::RAX, 5)?      // add rax, 5
    .push_reg(Register::RAX)?             // push rax
    .call("print_number")?                 // call print_number
    .add_reg_imm(Register::RSP, 8)?        // add rsp, 8 (清理栈)
    .ret()?;                               // ret

// 编译为字节码
let code = builder.compile_instructions()?;
println!("生成的机器码: {:?}", code);

§内存操作

use x86_64_assembler::instruction::{Operand, Register};

// 创建内存操作数
let mem_op = Operand::mem(
    Some(Register::RAX),    // 基址寄存器
    Some(Register::RBX),    // 索引寄存器
    4,                      // 比例因子
    16                      // 位移
);
// 等价于: [rax + rbx*4 + 16]

§架构支持

项目支持两种架构：

  • Architecture::X86: 32位 x86 架构
  • Architecture::X86_64: 64位 x86_64 架构

可以通过以下方式设置架构：

let mut assembler = X86_64Assembler::new(Architecture::X86)?;
assembler.set_architecture(Architecture::X86_64)?;

§错误处理

所有操作都返回 Result<T, GaiaError>，提供详细的错误信息：

match X86_64Assembler::new(Architecture::ARM) {
    Ok(assembler) => { /* 成功创建 */ }
    Err(error) => {
        println!("不支持的架构: {}", error);
    }
}

§模块结构

  • builder: 程序构建器模块，提供便捷的 API 来构建汇编程序
  • decoder: 指令解码器模块，用于将字节码解码为指令
  • encoder: 指令编码器模块，用于将指令编码为字节码
  • instruction: 指令定义模块，包含寄存器、操作数和指令的定义

§许可证

本项目采用 MPL-2.0 许可证开源。

§贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

§相关链接

Modules§

builder
ProgramBuilder 模块
decoder
InstructionDecoder 模块
encoder
InstructionEncoder 模块
instruction
Instruction 模块

Structs§

X86_64Assembler
x86_64汇编器主结构体