💾Interacting with memory

This example illustrates the basics of the basics of interacting with Wasm module memory.

A Wasm module can export its memory. With Wasmer you'll be able to interact with this memory.

In this example we'll illustrate the basics of interacting with the module memory:

  • How to query information about the memory;

  • How to load read from the memory;

  • How to write to the memory.

There are mainly two ways of interacting with the memory, either through exported function or by calling the memory API directly. It really depends on how the memory is exported.

First we are going to want to initialize a new project. To do this we can navigate to our project folder, or create one. In this example, we will create a new project. Lets create it and navigate to it:

The final code for this example can be found on GitHub.

Please take a look at the setup steps for Rust.

cargo new memory
cd memory

We have to modify Cargo.toml to add the Wasmer dependencies as shown below:

[dependencies]
# The Wasmer API
wasmer = "1.0"

Now that we have everything set up, let's go ahead and try it out!

Querying memory information

The first interesting thing to do is to query information about the memory. To do that we must either have access to the memory (i.e it has to be exported) or we must have access to an exported function which is able to give us this information.

One important thing to note: the size of the memory can be expressed as a number of pages or a number of bytes.

Each page of memory is 64 KiB in size.

let mem_size: NativeFunc<(), i32> = instance
    .exports
    .get_native_function("mem_size")?;
let memory = instance.exports.get_memory("memory")?;

assert_eq!(memory.size(), Pages::from(1));
assert_eq!(memory.size().bytes(), Bytes::from(65536 as usize));
assert_eq!(memory.data_size(), 65536);

let result = mem_size.call()?;
assert_eq!(Pages::from(result as u32), memory.size());

Now that we know the size of our memory it's time to see how we can change this.

Growing the memory

A memory can be grown to allow storing more things into it. This is easily done through

memory.grow(2)?;
assert_eq!(memory.size(), Pages::from(3));
assert_eq!(memory.data_size(), 65536 * 3);

To grow a memory you have to call the dedicated method and provide the number of pages, called the delta, you want to add to the memory.

Reading from and writing to the memory

Now that we know how to query and adjust the size of the memory, let's see how we can write to it or read from it.

We'll only focus on how to do this using exported functions, the goal is to show how to work with memory addresses.

Let's start by using absolute memory addresses to write and read a value.

let get_at: NativeFunc<i32, i32> = instance
    .exports
    .get_native_function("get_at")?;
let set_at: NativeFunc<(i32, i32), ()> = instance
    .exports
    .get_native_function("set_at")?;

let mem_addr = 0x2220;
let val = 0xFEFEFFE;

set_at.call(mem_addr, val)?;

let result = get_at.call(mem_addr)?;
println!("Value at {:#x?}: {:?}", mem_addr, result);

Now assume we want to write a value at the end of the second memory page and the read it. Let's see how we can do that:

let page_size = 0x1_0000;
let mem_addr = (page_size * 2) - mem::size_of_val(&val) as i32;
let val = 0xFEA09;
set_at.call(mem_addr, val)?;

let result = get_at.call(mem_addr)?;
println!("Value at {:#x?}: {:?}", mem_addr, result);

As you can see here we can use the size of a page and the size of the value we want to write to compute an address and write to it.

Keep in mind that memory address can be any number you want as long as it is valid regarding the memory size.

In the previous examples, we used hexadecimal notation but you are free to use decimal notation if needed.

It enough for now: we only covered how to interact with the memory through exported functions. If you want to know more, see the following example:

► Using memory pointers

Running

We now have everything we need to run the Wasm module, let's do it!

You should be able to run it using the cargo run command. The output should look like this:

Compiling module...
Instantiating module...
Querying memory size...
Memory size: 1
Growing memory...
Value at 0x2220: 267382782
Value at 0x1fffc: 1042953

If you want to run the examples from the Wasmer repository codebase directly, you can also do:

git clone https://github.com/wasmerio/wasmer.git
cd wasmer
cargo run --example memory --release --features "cranelift"

Last updated