Memory in wasmtime - Rust (original) (raw)


#[repr(C)]

pub struct Memory { /* private fields */ }

Available on crate feature runtime only.

Expand description

A WebAssembly linear memory.

WebAssembly memories represent a contiguous array of bytes that have a size that is always a multiple of the WebAssembly page size, currently 64 kilobytes.

WebAssembly memory is used for global data (not to be confused with wasmglobal items), statics in C/C++/Rust, shadow stack memory, etc. Accessing wasm memory is generally quite fast.

Memories, like other wasm items, are owned by a Store.

§`Memory` and Safety

Linear memory is a lynchpin of safety for WebAssembly. In Wasmtime there are safe methods of interacting with a Memory:

Note that all of these consider the entire store context as borrowed for the duration of the call or the duration of the returned slice. This largely means that while the function is running you’ll be unable to borrow anything else from the store. This includes getting access to the T onStore, but it also means that you can’t recursively call into WebAssembly for instance.

If you’d like to dip your toes into handling Memory in a more raw fashion (e.g. by using raw pointers or raw slices), then there’s a few important points to consider when doing so:

Any recursive calls into WebAssembly can possibly modify any byte of the entire memory. This means that whenever wasm is called Rust can’t have any long-lived borrows live across the wasm function call. Slices like &mut [u8] will be violated because they’re not actually exclusive at that point, and slices like &[u8] are also violated because their contents may be mutated.
WebAssembly memories can grow, and growth may change the base pointer. This means that even holding a raw pointer to memory over a wasm function call is also incorrect. Anywhere in the function call the base address of memory may change. Note that growth can also be requested from the embedding API as well.

As a general rule of thumb it’s recommended to stick to the safe methods ofMemory if you can. It’s not advised to use raw pointers or unsafeoperations because of how easy it is to accidentally get things wrong.

Some examples of safely interacting with memory are:

use wasmtime::{Memory, Store, MemoryAccessError};

// Memory can be read and written safely with the `Memory::read` and
// `Memory::write` methods.
// An error is returned if the copy did not succeed.
fn safe_examples(mem: Memory, store: &mut Store<()>) -> Result<(), MemoryAccessError> {
    let offset = 5;
    mem.write(&mut *store, offset, b"hello")?;
    let mut buffer = [0u8; 5];
    mem.read(&store, offset, &mut buffer)?;
    assert_eq!(b"hello", &buffer);

    // Note that while this is safe care must be taken because the indexing
    // here may panic if the memory isn't large enough.
    assert_eq!(&mem.data(&store)[offset..offset + 5], b"hello");
    mem.data_mut(&mut *store)[offset..offset + 5].copy_from_slice(b"bye!!");

    Ok(())
}

It’s worth also, however, covering some examples of incorrect,unsafe usages of Memory. Do not do these things!

use wasmtime::{Memory, Store};

// NOTE: All code in this function is not safe to execute and may cause
// segfaults/undefined behavior at runtime. Do not copy/paste these examples
// into production code!
unsafe fn unsafe_examples(mem: Memory, store: &mut Store<()>) -> Result<()> {
    // First and foremost, any borrow can be invalidated at any time via the
    // `Memory::grow` function. This can relocate memory which causes any
    // previous pointer to be possibly invalid now.
    unsafe {
        let pointer: &u8 = &*mem.data_ptr(&store);
        mem.grow(&mut *store, 1)?; // invalidates `pointer`!
        // println!("{}", *pointer); // FATAL: use-after-free
    }

    // Note that the use-after-free also applies to slices, whether they're
    // slices of bytes or strings.
    unsafe {
        let mem_slice = std::slice::from_raw_parts(
            mem.data_ptr(&store),
            mem.data_size(&store),
        );
        let slice: &[u8] = &mem_slice[0x100..0x102];
        mem.grow(&mut *store, 1)?; // invalidates `slice`!
        // println!("{:?}", slice); // FATAL: use-after-free
    }

    // The `Memory` type may be stored in other locations, so if you hand
    // off access to the `Store` then those locations may also call
    // `Memory::grow` or similar, so it's not enough to just audit code for
    // calls to `Memory::grow`.
    unsafe {
        let pointer: &u8 = &*mem.data_ptr(&store);
        some_other_function(store); // may invalidate `pointer` through use of `store`
        // println!("{:?}", pointer); // FATAL: maybe a use-after-free
    }

    // An especially subtle aspect of accessing a wasm instance's memory is
    // that you need to be extremely careful about aliasing. Anyone at any
    // time can call `data_unchecked()` or `data_unchecked_mut()`, which
    // means you can easily have aliasing mutable references:
    unsafe {
        let ref1: &u8 = &*mem.data_ptr(&store).add(0x100);
        let ref2: &mut u8 = &mut *mem.data_ptr(&store).add(0x100);
        // *ref2 = *ref1; // FATAL: violates Rust's aliasing rules
    }

    Ok(())
}

Overall there’s some general rules of thumb when unsafely working withMemory and getting raw pointers inside of it:

If you never have a “long lived” pointer into memory, you’re likely in the clear. Care still needs to be taken in threaded scenarios or when/where data is read, but you’ll be shielded from many classes of issues.
Long-lived pointers must always respect Rust’a aliasing rules. It’s ok for shared borrows to overlap with each other, but mutable borrows must overlap with nothing.
Long-lived pointers are only valid if they’re not invalidated for their lifetime. This means that Store isn’t used to reenter wasm or the memory itself is never grown or otherwise modified/aliased.

At this point it’s worth reiterating again that unsafely working withMemory is pretty tricky and not recommended! It’s highly recommended to use the safe methods to interact with Memory whenever possible.

§`Memory` Safety and Threads

Currently the wasmtime crate does not implement the wasm threads proposal, but it is planned to do so. It may be interesting to readers to see how this affects memory safety and what was previously just discussed as well.

Once threads are added into the mix, all of the above rules still apply. There’s an additional consideration that all reads and writes can happen concurrently, though. This effectively means that any borrow into wasm memory are virtually never safe to have.

Mutable pointers are fundamentally unsafe to have in a concurrent scenario in the face of arbitrary wasm code. Only if you dynamically know for sure that wasm won’t access a region would it be safe to construct a mutable pointer. Additionally even shared pointers are largely unsafe because their underlying contents may change, so unless UnsafeCell in one form or another is used everywhere there’s no safety.

One important point about concurrency is that while Memory::grow can happen concurrently it will never relocate the base pointer. Shared memories must always have a maximum size and they will be preallocated such that growth will never relocate the base pointer. The current size of the memory may still change over time though.

Overall the general rule of thumb for shared memories is that you must atomically read and write everything. Nothing can be borrowed and everything must be eagerly copied out. This means that Memory::data andMemory::data_mut won’t work in the future (they’ll probably return an error) for shared memories when they’re implemented. When possible it’s recommended to use Memory::read and Memory::write which will still be provided.

Memory in wasmtime - Rust (original) (raw)

§Memory and Safety

§Memory Safety and Threads

§Panics

§Examples

§Panics

§Examples

§Panics

§Panics

§Panics

§Panics

§Panics

§Panics

§Panics

§Panics

§Errors

§Panics

§Examples

§`Memory` and Safety

§`Memory` Safety and Threads