Struct unicorn_engine::Unicorn

pub struct Unicorn<'a, D: 'a> { /* private fields */ }

A Unicorn emulator instance.

Implementations

impl<'a> Unicorn<'a, ()>

pub fn new(arch: Arch, mode: Mode) -> Result<Unicorn<'a, ()>, uc_error>

Create a new instance of the unicorn engine for the specified architecture and hardware mode.

pub unsafe fn from_handle( handle: uc_handle, ) -> Result<Unicorn<'a, ()>, uc_error>

Safety

The function has to be called with a valid uc_handle pointer that was previously allocated by a call to uc_open. Calling the function with a non null pointer value that does not point to a unicorn instance will cause undefined behavior.

impl<'a, D> Unicorn<'a, D>

where D: 'a,

pub fn new_with_data( arch: Arch, mode: Mode, data: D, ) -> Result<Unicorn<'a, D>, uc_error>

Create a new instance of the unicorn engine for the specified architecture and hardware mode.

impl<'a, D> Unicorn<'a, D>

pub fn get_data(&self) -> &D

Return whatever data was passed during initialization.

For an example, have a look at utils::init_emu_with_heap where a struct is passed which is used for a custom allocator.

pub fn get_data_mut(&mut self) -> &mut D

Return a mutable reference to whatever data was passed during initialization.

pub fn get_arch(&self) -> Arch

Return the architecture of the current emulator.

pub fn get_handle(&self) -> uc_handle

Return the handle of the current emulator.

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

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

pub fn mem_read(&self, address: u64, buf: &mut [u8]) -> Result<(), uc_error>

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

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

Return a range of bytes from memory at the specified emulated physical address as vector.

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

Write the data in bytes to the emulated physical address address

pub unsafe fn mem_map_ptr( &mut self, address: u64, size: usize, perms: Permission, ptr: *mut c_void, ) -> Result<(), uc_error>

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

Safety

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.

pub fn mem_map( &mut self, address: u64, size: size_t, perms: Permission, ) -> Result<(), uc_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.

pub fn mmio_map<R, W>( &mut self, address: u64, size: size_t, read_callback: Option<R>, write_callback: Option<W>, ) -> Result<(), uc_error>

where R: FnMut(&mut Unicorn<'_, D>, u64, usize) -> u64 + 'a, W: FnMut(&mut Unicorn<'_, D>, u64, usize, u64) + 'a,

Map in am MMIO region backed by callbacks.

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.

pub fn mmio_map_ro<F>( &mut self, address: u64, size: size_t, callback: F, ) -> Result<(), uc_error>

where F: FnMut(&mut Unicorn<'_, D>, u64, usize) -> u64 + 'a,

Map in a read-only MMIO region backed by a callback.

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.

pub fn mmio_map_wo<F>( &mut self, address: u64, size: size_t, callback: F, ) -> Result<(), uc_error>

where F: FnMut(&mut Unicorn<'_, D>, u64, usize, u64) + 'a,

Map in a write-only MMIO region backed by a callback.

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.

pub fn mem_unmap(&mut self, address: u64, size: size_t) -> Result<(), uc_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.

pub fn mem_protect( &mut self, address: u64, size: size_t, perms: Permission, ) -> Result<(), uc_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.

pub fn reg_write<T: Into<i32>>( &mut self, regid: T, value: u64, ) -> Result<(), uc_error>

Write an unsigned value from a register.

pub fn reg_write_long<T: Into<i32>>( &self, regid: T, value: &[u8], ) -> Result<(), uc_error>

Write variable sized values into registers.

The user has to make sure that the buffer length matches the register size. This adds support for registers >64 bit (GDTR/IDTR, XMM, YMM, ZMM (x86); Q, V (arm64)).

pub fn reg_read<T: Into<i32>>(&self, regid: T) -> Result<u64, uc_error>

Read an unsigned value from a register.

Not to be used with registers larger than 64 bit.

pub fn reg_read_long<T: Into<i32>>( &self, regid: T, ) -> Result<Box<[u8]>, uc_error>

Read 128, 256 or 512 bit register value into heap allocated byte array.

This adds safe support for registers >64 bit (GDTR/IDTR, XMM, YMM, ZMM, ST (x86); Q, V (arm64)).

pub fn reg_read_i32<T: Into<i32>>(&self, regid: T) -> Result<i32, uc_error>

Read a signed 32-bit value from a register.

pub fn add_code_hook<F>( &mut self, begin: u64, end: u64, callback: F, ) -> Result<UcHookId, uc_error>

where F: FnMut(&mut Unicorn<'_, D>, u64, u32) + 'a,

Add a code hook.

pub fn add_block_hook<F>( &mut self, begin: u64, end: u64, callback: F, ) -> Result<UcHookId, uc_error>

where F: FnMut(&mut Unicorn<'_, D>, u64, u32) + 'a,

Add a block hook.

pub fn add_mem_hook<F>( &mut self, hook_type: HookType, begin: u64, end: u64, callback: F, ) -> Result<UcHookId, uc_error>

where F: FnMut(&mut Unicorn<'_, D>, MemType, u64, usize, i64) -> bool + 'a,

Add a memory hook.

pub fn add_intr_hook<F>(&mut self, callback: F) -> Result<UcHookId, uc_error>

where F: FnMut(&mut Unicorn<'_, D>, u32) + 'a,

Add an interrupt hook.

pub fn add_insn_invalid_hook<F>( &mut self, callback: F, ) -> Result<UcHookId, uc_error>

where F: FnMut(&mut Unicorn<'_, D>) -> bool + 'a,

Add hook for invalid instructions

pub fn add_insn_in_hook<F>(&mut self, callback: F) -> Result<UcHookId, uc_error>

where F: FnMut(&mut Unicorn<'_, D>, u32, usize) -> u32 + 'a,

Add hook for x86 IN instruction.

pub fn add_insn_out_hook<F>( &mut self, callback: F, ) -> Result<UcHookId, uc_error>

where F: FnMut(&mut Unicorn<'_, D>, u32, usize, u32) + 'a,

Add hook for x86 OUT instruction.

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

where F: FnMut(&mut Unicorn<'_, D>) + 'a,

Add hook for x86 SYSCALL or SYSENTER.

pub fn add_tlb_hook<F>( &mut self, begin: u64, end: u64, callback: F, ) -> Result<UcHookId, uc_error>

where F: FnMut(&mut Unicorn<'_, D>, u64, MemType) -> Option<TlbEntry> + 'a,

pub fn remove_hook(&mut self, hook_id: UcHookId) -> Result<(), uc_error>

Remove a hook.

hook_id is the value returned by add_*_hook functions.

pub fn context_alloc(&self) -> Result<Context, uc_error>

Allocate and return an empty Unicorn context.

To be populated via context_save.

pub fn context_save(&self, context: &mut Context) -> Result<(), uc_error>

Save current Unicorn context to previously allocated Context struct.

pub fn context_init(&self) -> Result<Context, uc_error>

Allocate and return a Context struct initialized with the current CPU context.

This can be used for fast rollbacks with context_restore. In case of many non-concurrent context saves, use context_alloc and *_save individually to avoid unnecessary allocations.

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

Restore a previously saved Unicorn context.

Perform a quick rollback of the CPU context, including registers and some internal metadata. Contexts may not be shared across engine instances with differing arches or modes. Memory has to be restored manually, if needed.

pub fn emu_start( &mut self, begin: u64, until: u64, timeout: u64, count: usize, ) -> Result<(), uc_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).

pub fn emu_stop(&mut self) -> Result<(), uc_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.

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

Query the internal status of the engine.

supported: MODE, PAGE_SIZE, ARCH

pub fn pc_read(&self) -> Result<u64, uc_error>

Gets the current program counter for this unicorn instance.

pub fn set_pc(&mut self, value: u64) -> Result<(), uc_error>

Sets the program counter for this unicorn instance.

pub fn ctl_get_mode(&self) -> Result<Mode, uc_error>

pub fn ctl_get_page_size(&self) -> Result<u32, uc_error>

pub fn ctl_set_page_size(&self, page_size: u32) -> Result<(), uc_error>

pub fn ctl_get_arch(&self) -> Result<Arch, uc_error>

pub fn ctl_get_timeout(&self) -> Result<u64, uc_error>

pub fn ctl_exits_enable(&self) -> Result<(), uc_error>

pub fn ctl_exits_disable(&self) -> Result<(), uc_error>

pub fn ctl_get_exits_count(&self) -> Result<usize, uc_error>

pub fn ctl_get_exits(&self) -> Result<Vec<u64>, uc_error>

pub fn ctl_set_exits(&self, exits: &[u64]) -> Result<(), uc_error>

pub fn ctl_get_cpu_model(&self) -> Result<i32, uc_error>

pub fn ctl_set_cpu_model(&self, cpu_model: i32) -> Result<(), uc_error>

pub fn ctl_remove_cache(&self, address: u64, end: u64) -> Result<(), uc_error>

pub fn ctl_request_cache( &self, address: u64, tb: &mut TranslationBlock, ) -> Result<(), uc_error>

pub fn ctl_flush_tb(&self) -> Result<(), uc_error>

pub fn ctl_flush_tlb(&self) -> Result<(), uc_error>

pub fn ctl_context_mode(&self, mode: ContextMode) -> Result<(), uc_error>

pub fn ctl_tlb_type(&self, t: TlbType) -> Result<(), uc_error>

Trait Implementations

impl<'a, D> Debug for Unicorn<'a, D>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.