Struct Instance 

pub struct Instance<UserData = (), UserError = Infallible> { /* private fields */ }

Implementations

impl<UserData, UserError> Instance<UserData, UserError>

pub fn call_typed<FnArgs>( &mut self, user_data: &mut UserData, entry_point: impl EntryPoint, args: FnArgs, ) -> Result<(), CallError<UserError>>

where FnArgs: FuncArgs,

Calls a given exported function with the given arguments.

pub fn continue_execution( &mut self, user_data: &mut UserData, ) -> Result<(), CallError<UserError>>

Continues execution.

pub fn call_typed_and_get_result<FnResult, FnArgs>( &mut self, user_data: &mut UserData, entry_point: impl EntryPoint, args: FnArgs, ) -> Result<FnResult, CallError<UserError>>

where FnArgs: FuncArgs, FnResult: FuncResult,

A conveniance function to call Instance::call_typed and RawInstance::get_result_typed in a single function call.

Methods from Deref<Target = RawInstance>

pub fn module(&self) -> &Module

Returns the module from which this instance was created.

pub fn is_64_bit(&self) -> bool

Returns whether we’re running a 64-bit program.

pub fn run(&mut self) -> Result<InterruptKind, Error>

Starts or resumes the execution.

pub fn reg(&self, reg: Reg) -> RegValue

Gets the value of a given register.

pub fn set_reg(&mut self, reg: Reg, value: RegValue)

Sets the value of a given register.

pub fn gas(&self) -> Gas

Gets the amount of gas remaining.

Note that this being zero doesn’t necessarily mean that the execution ran out of gas, if the program ended up consuming exactly the amount of gas that it was provided with!

pub fn set_gas(&mut self, gas: Gas)

Sets the amount of gas remaining.

pub fn program_counter(&self) -> Option<ProgramCounter>

Gets the current program counter.

pub fn next_program_counter(&self) -> Option<ProgramCounter>

Gets the next program counter.

This is where the program will resume execution when RawInstance::run is called.

pub fn set_next_program_counter(&mut self, pc: ProgramCounter)

Sets the next program counter.

pub fn clear_regs(&mut self)

A convenience function which sets all of the registers to zero.

pub fn set_accessible_aux_size(&mut self, size: u32) -> Result<(), Error>

Sets the accessible region of the aux data, rounded up to the nearest page size.

pub fn set_host_side_aux_write_protect( &mut self, is_write_protected: bool, ) -> Result<(), Error>

Sets whether the aux data region is write-protected on the host-side.

This affects write_memory, zero_memory and is_memory_accessible.

Will return an error if called on an instance with dynamic paging enabled. Infallible otherwise.

pub fn reset_memory(&mut self) -> Result<(), Error>

Resets the VM’s memory to its initial state.

pub fn is_memory_accessible( &self, address: u32, size: u32, minimum_protection: MemoryProtection, ) -> bool

Returns whether a given chunk of memory is accessible.

If size is zero then this will always return true.

pub fn read_memory_into<'slice, B>( &self, address: u32, buffer: &'slice mut B, ) -> Result<&'slice mut [u8], MemoryAccessError>

where B: ?Sized + AsUninitSliceMut,

Reads the VM’s memory.

The whole memory region must be readable.

pub fn write_memory( &mut self, address: u32, data: &[u8], ) -> Result<(), MemoryAccessError>

Writes into the VM’s memory.

The whole memory region must be writable.

pub fn read_memory( &self, address: u32, length: u32, ) -> Result<Vec<u8>, MemoryAccessError>

Reads the VM’s memory.

The whole memory region must be readable.

pub fn read_u64(&self, address: u32) -> Result<u64, MemoryAccessError>

A convenience function to read an u64 from the VM’s memory.

This is equivalent to calling RawInstance::read_memory_into.

pub fn write_u64( &mut self, address: u32, value: u64, ) -> Result<(), MemoryAccessError>

A convenience function to write an u64 into the VM’s memory.

This is equivalent to calling RawInstance::write_memory.

pub fn read_u32(&self, address: u32) -> Result<u32, MemoryAccessError>

A convenience function to read an u32 from the VM’s memory.

This is equivalent to calling RawInstance::read_memory_into.

pub fn write_u32( &mut self, address: u32, value: u32, ) -> Result<(), MemoryAccessError>

A convenience function to write an u32 into the VM’s memory.

This is equivalent to calling RawInstance::write_memory.

pub fn read_u16(&self, address: u32) -> Result<u16, MemoryAccessError>

A convenience function to read an u16 from the VM’s memory.

This is equivalent to calling RawInstance::read_memory_into.

pub fn write_u16( &mut self, address: u32, value: u16, ) -> Result<(), MemoryAccessError>

A convenience function to write an u16 into the VM’s memory.

This is equivalent to calling RawInstance::write_memory.

pub fn read_u8(&self, address: u32) -> Result<u8, MemoryAccessError>

A convenience function to read an u8 from the VM’s memory.

This is equivalent to calling RawInstance::read_memory_into.

pub fn write_u8( &mut self, address: u32, value: u8, ) -> Result<(), MemoryAccessError>

A convenience function to write an u8 into the VM’s memory.

This is equivalent to calling RawInstance::write_memory.

pub fn zero_memory_with_memory_protection( &mut self, address: u32, length: u32, memory_protection: MemoryProtection, ) -> Result<(), MemoryAccessError>

Fills the given memory region with zeros and changes memory protection flags. Similar to RawInstance::zero_memory, but can only be called when dynamic paging is enabled.

address must be a multiple of the page size. The value of length will be rounded up to the nearest multiple of the page size. If length is zero then this call has no effect.

Can be used to resolve a segfault. It can also be used to preemptively initialize pages for which no segfault is currently triggered.

pub fn zero_memory( &mut self, address: u32, length: u32, ) -> Result<(), MemoryAccessError>

Fills the given memory region with zeros.

The whole memory region must be writable.

address must be greater or equal to 0x10000 and address + length cannot be greater than 0x100000000. If length is zero then this call has no effect and will always succeed.

pub fn protect_memory( &mut self, address: u32, length: u32, ) -> Result<(), MemoryAccessError>

Read-only protects a given memory region.

Is only supported when dynamic paging is enabled.

pub fn unprotect_memory( &mut self, address: u32, length: u32, ) -> Result<(), MemoryAccessError>

Removes read-only protection from a given memory region.

Is only supported when dynamic paging is enabled.

pub fn free_pages(&mut self, address: u32, length: u32) -> Result<(), Error>

Frees the given page(s).

address must be a multiple of the page size. The value of length will be rounded up to the nearest multiple of the page size. If length is zero then this call has no effect and will always succeed.

pub fn heap_size(&self) -> u32

Returns the current size of the program’s heap.

pub fn sbrk(&mut self, size: u32) -> Result<Option<u32>, Error>

pub fn prepare_call_untyped(&mut self, pc: ProgramCounter, args: &[RegValue])

A convenience function which sets up a fuction call according to the default ABI.

This function will:

1. clear all registers to zero,
2. initialize RA to 0xffff0000,
3. initialize SP to its default value,
4. set the program counter.

Will panic if args has more than 9 elements.

pub fn prepare_call_typed<FnArgs>(&mut self, pc: ProgramCounter, args: FnArgs)

where FnArgs: FuncArgs,

A convenience function which sets up a fuction call according to the default ABI.

This is equivalent to calling RawInstance::prepare_call_untyped.

Will panic if marshalling args through the FFI boundary requires too many registers.

pub fn get_result_typed<FnResult>(&self) -> FnResult

where FnResult: FuncResult,

Extracts a return value from the argument registers according to the default ABI.

This is equivalent to manually calling RawInstance::reg.

pub fn pid(&self) -> Option<u32>

Returns the PID of the sandbox corresponding to this instance.

Will be None if the instance doesn’t run in a separate process. Mostly only useful for debugging.

pub fn next_native_program_counter(&self) -> Option<usize>

Gets the next native program counter.

Will return None when running under an interpreter. Mostly only useful for debugging.

pub fn reset_interpreter_cache(&mut self)

Reset cache and therefore reclaim cache backed memory.

pub fn set_interpreter_cache_size_limit( &mut self, cache_info: Option<SetCacheSizeLimitArgs>, ) -> Result<(), Error>

Set a tight upper limit on the interpreter cache size (in bytes).

Trait Implementations

impl<UserData, UserError> Deref for Instance<UserData, UserError>

type Target = RawInstance

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<UserData, UserError> DerefMut for Instance<UserData, UserError>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.