Trait Cpu

pub trait Cpu {
    type Reg: Register;

    // Required methods
    fn emu(&self) -> &Unicorn;
    fn mut_emu(&mut self) -> &mut Unicorn;

    // Provided methods
    fn reg_read(&self, reg: Self::Reg) -> Result<u64, Error> { ... }
    fn reg_read_i32(&self, reg: Self::Reg) -> Result<i32, Error> { ... }
    unsafe fn reg_write_generic<T: Sized>(
        &self,
        reg: Self::Reg,
        value: T,
    ) -> Result<(), Error> { ... }
    fn reg_write(&self, reg: Self::Reg, value: u64) -> Result<(), Error> { ... }
    fn reg_write_i32(&self, reg: Self::Reg, value: i32) -> Result<(), Error> { ... }
    fn mem_map(
        &self,
        address: u64,
        size: size_t,
        perms: Protection,
    ) -> Result<(), Error> { ... }
    unsafe fn mem_map_ptr<T>(
        &self,
        address: u64,
        size: size_t,
        perms: Protection,
        ptr: *mut T,
    ) -> Result<(), Error> { ... }
    fn mem_unmap(&self, address: u64, size: size_t) -> Result<(), Error> { ... }
    fn mem_write(&self, address: u64, bytes: &[u8]) -> Result<(), Error> { ... }
    fn mem_read(&self, address: u64, bytes: &mut [u8]) -> Result<(), Error> { ... }
    fn mem_read_as_vec(
        &self,
        address: u64,
        size: usize,
    ) -> Result<Vec<u8>, Error> { ... }
    fn mem_protect(
        &self,
        address: u64,
        size: usize,
        perms: Protection,
    ) -> Result<(), Error> { ... }
    fn mem_regions(&self) -> Result<Vec<MemRegion>, Error> { ... }
    fn emu_start(
        &self,
        begin: u64,
        until: u64,
        timeout: u64,
        count: usize,
    ) -> Result<(), Error> { ... }
    fn emu_stop(&self) -> Result<(), Error> { ... }
    fn add_code_hook<F>(
        &mut self,
        hook_type: CodeHookType,
        begin: u64,
        end: u64,
        callback: F,
    ) -> Result<uc_hook, Error>
       where F: Fn(&Unicorn, u64, u32) + 'static { ... }
    fn add_intr_hook<F>(&mut self, callback: F) -> Result<uc_hook, Error>
       where F: Fn(&Unicorn, u32) + 'static { ... }
    fn add_mem_hook<F>(
        &mut self,
        hook_type: MemHookType,
        begin: u64,
        end: u64,
        callback: F,
    ) -> Result<uc_hook, Error>
       where F: Fn(&Unicorn, MemType, u64, usize, i64) -> bool + 'static { ... }
    fn add_insn_in_hook<F>(&mut self, callback: F) -> Result<uc_hook, Error>
       where F: Fn(&Unicorn, u32, usize) -> u32 + 'static { ... }
    fn add_insn_out_hook<F>(&mut self, callback: F) -> Result<uc_hook, Error>
       where F: Fn(&Unicorn, u32, usize, u32) + 'static { ... }
    fn add_insn_sys_hook<F>(
        &mut self,
        insn_type: InsnSysX86,
        begin: u64,
        end: u64,
        callback: F,
    ) -> Result<uc_hook, Error>
       where F: Fn(&Unicorn) + 'static { ... }
    fn remove_hook(&mut self, hook: uc_hook) -> Result<(), Error> { ... }
    fn errno(&self) -> Error { ... }
    fn query(&self, query: Query) -> Result<usize, Error> { ... }
    fn context_save(&self) -> Result<Context, Error> { ... }
    fn context_restore(&self, context: &Context) -> Result<(), Error> { ... }
}

Required Associated Types

type Reg: Register

Required Methods

fn emu(&self) -> &Unicorn

fn mut_emu(&mut self) -> &mut Unicorn

Provided Methods

fn reg_read(&self, reg: Self::Reg) -> Result<u64, Error>

Read an unsigned value from a register.

fn reg_read_i32(&self, reg: Self::Reg) -> Result<i32, Error>

Read a signed 32-bit value from a register.

unsafe fn reg_write_generic<T: Sized>( &self, reg: Self::Reg, value: T, ) -> Result<(), Error>

Write a generic type to a register.

fn reg_write(&self, reg: Self::Reg, value: u64) -> Result<(), Error>

Write an unsigned value register.

fn reg_write_i32(&self, reg: Self::Reg, value: i32) -> Result<(), Error>

Write a signed 32-bit value to a register.

fn mem_map( &self, address: u64, size: size_t, perms: Protection, ) -> Result<(), Error>

Map a memory region in the emulator at the specified address.

address must be aligned to 4kb or this will return Error::ARG. size must be a multiple of 4kb or this will return Error::ARG.

Examples found in repository

examples/test.rs (line 28)

fn main() {
    let (major, minor) = unicorn::unicorn_version();
    println!("version : {}.{}", major, minor);
    println!(
        "Support for:\n\t x86: {}\n\t arm: {}\n\t mips: {}",
        unicorn::arch_supported(unicorn::Arch::X86),
        unicorn::arch_supported(unicorn::Arch::ARM),
        unicorn::arch_supported(unicorn::Arch::MIPS)
    );

    let emu = CpuARM::new(unicorn::Mode::THUMB).expect("failed to create emulator");

    let page_size = emu
        .query(unicorn::Query::PAGE_SIZE)
        .expect("failed to query page size");
    println!("page size : {}", page_size);
    let hardware_mode = emu
        .query(unicorn::Query::MODE)
        .expect("failed to query hardware mode");
    println!("hardware mode : {}", hardware_mode);

    println!("Sample error message : {}", unicorn::Error::HOOK.msg());

    emu.mem_map(0x10000, 0x4000, unicorn::Protection::ALL)
        .expect("failed to map first memory region");
    emu.mem_map(0x20000, 0x4000, unicorn::Protection::ALL)
        .expect("failed to map second memory region");
    let regions = emu
        .mem_regions()
        .expect("failed to retrieve memory mappings");
    println!("Regions : {}", regions.len());

    for region in &regions {
        println!("{:?}", region);
    }
}

unsafe fn mem_map_ptr<T>( &self, address: u64, size: size_t, perms: Protection, ptr: *mut T, ) -> Result<(), Error>

Map an existing memory region in the emulator at the specified address.

This function is marked unsafe because it is the responsibility of the caller to ensure that size matches the size of the passed buffer, an invalid size value will likely cause a crash in unicorn.

address must be aligned to 4kb or this will return Error::ARG.

size must be a multiple of 4kb or this will return Error::ARG.

ptr is a pointer to the provided memory region that will be used by the emulator.

fn mem_unmap(&self, address: u64, size: size_t) -> Result<(), Error>

Unmap a memory region.

address must be aligned to 4kb or this will return Error::ARG. size must be a multiple of 4kb or this will return Error::ARG.

fn mem_write(&self, address: u64, bytes: &[u8]) -> Result<(), Error>

Write a range of bytes to memory at the specified address.

fn mem_read(&self, address: u64, bytes: &mut [u8]) -> Result<(), Error>

Read a range of bytes from memory at the specified address.

fn mem_read_as_vec(&self, address: u64, size: usize) -> Result<Vec<u8>, Error>

Read a range of bytes from memory at the specified address; return the bytes read as a Vec.

fn mem_protect( &self, address: u64, size: usize, perms: Protection, ) -> Result<(), Error>

Set the memory permissions for an existing memory region.

address must be aligned to 4kb or this will return Error::ARG. size must be a multiple of 4kb or this will return Error::ARG.

fn mem_regions(&self) -> Result<Vec<MemRegion>, Error>

Returns a vector with the memory regions that are mapped in the emulator.

Examples found in repository

examples/test.rs (line 33)

fn main() {
    let (major, minor) = unicorn::unicorn_version();
    println!("version : {}.{}", major, minor);
    println!(
        "Support for:\n\t x86: {}\n\t arm: {}\n\t mips: {}",
        unicorn::arch_supported(unicorn::Arch::X86),
        unicorn::arch_supported(unicorn::Arch::ARM),
        unicorn::arch_supported(unicorn::Arch::MIPS)
    );

    let emu = CpuARM::new(unicorn::Mode::THUMB).expect("failed to create emulator");

    let page_size = emu
        .query(unicorn::Query::PAGE_SIZE)
        .expect("failed to query page size");
    println!("page size : {}", page_size);
    let hardware_mode = emu
        .query(unicorn::Query::MODE)
        .expect("failed to query hardware mode");
    println!("hardware mode : {}", hardware_mode);

    println!("Sample error message : {}", unicorn::Error::HOOK.msg());

    emu.mem_map(0x10000, 0x4000, unicorn::Protection::ALL)
        .expect("failed to map first memory region");
    emu.mem_map(0x20000, 0x4000, unicorn::Protection::ALL)
        .expect("failed to map second memory region");
    let regions = emu
        .mem_regions()
        .expect("failed to retrieve memory mappings");
    println!("Regions : {}", regions.len());

    for region in &regions {
        println!("{:?}", region);
    }
}

fn emu_start( &self, begin: u64, until: u64, timeout: u64, count: usize, ) -> Result<(), Error>

Emulate machine code for a specified duration.

begin is the address where to start the emulation. The emulation stops if until is hit. timeout specifies a duration in microseconds after which the emulation is stopped (infinite execution if set to 0). count is the maximum number of instructions to emulate (emulate all the available instructions if set to 0).

fn emu_stop(&self) -> Result<(), Error>

Stop the emulation.

This is usually called from callback function in hooks. NOTE: For now, this will stop the execution only after the current block.

fn add_code_hook<F>( &mut self, hook_type: CodeHookType, begin: u64, end: u64, callback: F, ) -> Result<uc_hook, Error>

where F: Fn(&Unicorn, u64, u32) + 'static,

Add a code hook.

fn add_intr_hook<F>(&mut self, callback: F) -> Result<uc_hook, Error>

where F: Fn(&Unicorn, u32) + 'static,

Add an interrupt hook.

fn add_mem_hook<F>( &mut self, hook_type: MemHookType, begin: u64, end: u64, callback: F, ) -> Result<uc_hook, Error>

where F: Fn(&Unicorn, MemType, u64, usize, i64) -> bool + 'static,

Add a memory hook.

fn add_insn_in_hook<F>(&mut self, callback: F) -> Result<uc_hook, Error>

where F: Fn(&Unicorn, u32, usize) -> u32 + 'static,

Add an “in” instruction hook.

fn add_insn_out_hook<F>(&mut self, callback: F) -> Result<uc_hook, Error>

where F: Fn(&Unicorn, u32, usize, u32) + 'static,

Add an “out” instruction hook.

fn add_insn_sys_hook<F>( &mut self, insn_type: InsnSysX86, begin: u64, end: u64, callback: F, ) -> Result<uc_hook, Error>

where F: Fn(&Unicorn) + 'static,

Add a “syscall” or “sysenter” instruction hook.

fn remove_hook(&mut self, hook: uc_hook) -> Result<(), Error>

Remove a hook.

hook is the value returned by either add_code_hook or add_mem_hook.

fn errno(&self) -> Error

Return the last error code when an API function failed.

Like glibc errno(), this function might not retain its old value once accessed.

fn query(&self, query: Query) -> Result<usize, Error>

Query the internal status of the engine.

Supported queries :

• Query::PAGE_SIZE : the page size used by the emulator.
• Query::MODE : the current hardware mode.

Examples found in repository

examples/test.rs (line 18)

fn main() {
    let (major, minor) = unicorn::unicorn_version();
    println!("version : {}.{}", major, minor);
    println!(
        "Support for:\n\t x86: {}\n\t arm: {}\n\t mips: {}",
        unicorn::arch_supported(unicorn::Arch::X86),
        unicorn::arch_supported(unicorn::Arch::ARM),
        unicorn::arch_supported(unicorn::Arch::MIPS)
    );

    let emu = CpuARM::new(unicorn::Mode::THUMB).expect("failed to create emulator");

    let page_size = emu
        .query(unicorn::Query::PAGE_SIZE)
        .expect("failed to query page size");
    println!("page size : {}", page_size);
    let hardware_mode = emu
        .query(unicorn::Query::MODE)
        .expect("failed to query hardware mode");
    println!("hardware mode : {}", hardware_mode);

    println!("Sample error message : {}", unicorn::Error::HOOK.msg());

    emu.mem_map(0x10000, 0x4000, unicorn::Protection::ALL)
        .expect("failed to map first memory region");
    emu.mem_map(0x20000, 0x4000, unicorn::Protection::ALL)
        .expect("failed to map second memory region");
    let regions = emu
        .mem_regions()
        .expect("failed to retrieve memory mappings");
    println!("Regions : {}", regions.len());

    for region in &regions {
        println!("{:?}", region);
    }
}

fn context_save(&self) -> Result<Context, Error>

Save the CPU context into an opaque struct.

fn context_restore(&self, context: &Context) -> Result<(), Error>

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Cpu for CpuARM64

type Reg = RegisterARM64

impl Cpu for CpuARM

type Reg = RegisterARM

impl Cpu for CpuM68K

type Reg = RegisterM68K

impl Cpu for CpuMIPS

type Reg = RegisterMIPS

impl Cpu for CpuSPARC

type Reg = RegisterSPARC

impl Cpu for CpuX86

type Reg = RegisterX86