Struct Vmctx

Source

pub struct Vmctx { /* private fields */ }

Expand description

An opaque handle to a running instance’s context.

Implementations§

Source §

impl Vmctx

Source

pub unsafe fn from_raw(vmctx: *mut lucet_vmctx) -> Vmctx

Create a Vmctx from the compiler-inserted vmctx argument in a guest function.

This is almost certainly not what you want to use to get a Vmctx; instead use the first argument of a function with the #[lucet_hostcall] attribute, which must have the type &mut Vmctx.

Source

pub fn as_raw(&self) -> *mut lucet_vmctx

Return the underlying vmctx pointer.

Source

pub fn heap(&self) -> Ref<'_, [u8]>

Return the WebAssembly heap as a slice of bytes.

If the heap is already mutably borrowed by heap_mut(), the instance will terminate with TerminationDetails::BorrowError.

Source

pub fn heap_mut(&self) -> RefMut<'_, [u8]>

Return the WebAssembly heap as a mutable slice of bytes.

If the heap is already borrowed by heap() or heap_mut(), the instance will terminate with TerminationDetails::BorrowError.

Source

pub fn check_heap<T>(&self, ptr: *const T, len: usize) -> bool

Check whether a given range in the host address space overlaps with the memory that backs the instance heap.

Source

pub fn contains_embed_ctx<T: Any>(&self) -> bool

Check whether a context value of a particular type exists.

Source

pub fn get_embed_ctx<T: Any>(&self) -> Ref<'_, T>

Get a reference to a context value of a particular type.

If a context of that type does not exist, the instance will terminate with TerminationDetails::CtxNotFound.

If the context is already mutably borrowed by get_embed_ctx_mut, the instance will terminate with TerminationDetails::BorrowError.

Source

pub fn get_embed_ctx_mut<T: Any>(&self) -> RefMut<'_, T>

Get a mutable reference to a context value of a particular type.

If a context of that type does not exist, the instance will terminate with TerminationDetails::CtxNotFound.

If the context is already borrowed by some other use of get_embed_ctx or get_embed_ctx_mut, the instance will terminate with TerminationDetails::BorrowError.

Source

pub unsafe fn terminate_no_unwind(&mut self, details: TerminationDetails) -> !

Terminate this guest and return to the host context without unwinding.

This is almost certainly not what you want to use to terminate an instance from a hostcall, as any resources currently in scope will not be dropped. Instead, use lucet_hostcall_terminate! which unwinds to the enclosing hostcall body.

Source

pub fn grow_memory(&mut self, additional_pages: u32) -> Result<u32, Error>

Grow the guest memory by the given number of WebAssembly pages.

On success, returns the number of pages that existed before the call.

Source

pub fn globals(&self) -> Ref<'_, [GlobalValue]>

Return the WebAssembly globals as a slice of i64s.

If the globals are already mutably borrowed by globals_mut(), the instance will terminate with TerminationDetails::BorrowError.

Source

pub fn globals_mut(&self) -> RefMut<'_, [GlobalValue]>

Return the WebAssembly globals as a mutable slice of i64s.

If the globals are already borrowed by globals() or globals_mut(), the instance will terminate with TerminationDetails::BorrowError.

Source

pub fn get_func_from_idx( &self, table_idx: u32, func_idx: u32, ) -> Result<FunctionHandle, Error>

Get a function pointer by WebAssembly table and function index.

This is useful when a hostcall takes a function pointer as its argument, as WebAssembly uses table indices as its runtime representation of function pointers.

§Safety

We do not currently reflect function type information into the Rust type system, so callers of the returned function must take care to cast it to the correct type before calling. The correct type will include the vmctx argument, which the caller is responsible for passing from its own context.

There is currently no guarantee that guest functions will return before faulting, or terminating the instance in a subsequent hostcall. This means that any Rust resources that are held open when the guest function is called might be leaked if the guest function, for example, divides by zero. Work to make this safer is ongoing.

use lucet_runtime_macros::lucet_hostcall;
use lucet_runtime_internals::lucet_hostcall_terminate;
use lucet_runtime_internals::vmctx::{lucet_vmctx, Vmctx};

#[lucet_hostcall]
#[no_mangle]
pub unsafe extern "C" fn hostcall_call_binop(
    vmctx: &mut Vmctx,
    binop_table_idx: u32,
    binop_func_idx: u32,
    operand1: u32,
    operand2: u32,
) -> u32 {
    if let Ok(binop) = vmctx.get_func_from_idx(binop_table_idx, binop_func_idx) {
        let typed_binop = std::mem::transmute::<
            usize,
            extern "C" fn(*mut lucet_vmctx, u32, u32) -> u32,
        >(binop.ptr.as_usize());
        unsafe { (typed_binop)(vmctx.as_raw(), operand1, operand2) }
    } else {
        lucet_hostcall_terminate!("invalid function index")
    }
}