feat: memory backend api

Signed-off-by: Henry <mail@henrygressmann.de>

Author: explodingcamera

crates/tinywasm/Cargo.toml

@@ -55,7 +55,7 @@ canonicalize_nans=[]
 # derive Debug for runtime/types structs
 debug=["tinywasm-types/debug"]
 
-# expose module-internal by-index inspection APIs
+# expose module-internal by-index inspection APIs for non-exported entities (for testing and debugging)
 guest_debug=[]
 
 # enable x86-specific SIMD intrinsics in Value128 (uses unsafe code)
@@ -139,6 +139,10 @@ harness=false
 name="tinywasm_modes"
 harness=false
 
+[[bench]]
+name="memory_backends"
+harness=false
+
 [[test]]
 name="test-wasm-3"
 harness=false

crates/tinywasm/benches/memory_backends.rs

@@ -0,0 +1,122 @@
+use criterion::measurement::WallTime;
+use criterion::{BatchSize, BenchmarkGroup, BenchmarkId, Criterion, criterion_group, criterion_main};
+use std::hint::black_box;
+use tinywasm::{LinearMemory, PagedMemory, VecMemory};
+
+const PAGE_SIZE: usize = 64 * 1024;
+const CHUNK_SIZE: usize = 4 * 1024;
+const GROW_STEPS: usize = 32;
+const BENCH_MEASUREMENT_TIME: std::time::Duration = std::time::Duration::from_secs(10);
+
+const MEMORY_LEN: usize = PAGE_SIZE * 4;
+const CONTIGUOUS_OFFSET: usize = 1024;
+const CONTIGUOUS_LEN: usize = 2048;
+const CROSS_CHUNK_OFFSET: usize = CHUNK_SIZE - 512;
+const CROSS_CHUNK_LEN: usize = CHUNK_SIZE * 2;
+
+fn bench_grow<M, F>(group: &mut BenchmarkGroup<'_, WallTime>, backend: &str, make_memory: F)
+where
+    M: LinearMemory,
+    F: Fn() -> M + Copy,
+{
+    group.bench_function(BenchmarkId::new("grow", backend), |b| {
+        b.iter_batched(
+            make_memory,
+            |mut memory| {
+                for page_count in 2..=GROW_STEPS + 1 {
+                    memory.grow_to(page_count * PAGE_SIZE).unwrap();
+                }
+                black_box(memory.len())
+            },
+            BatchSize::SmallInput,
+        )
+    });
+}
+
+fn bench_write_all<M: LinearMemory>(
+    group: &mut BenchmarkGroup<'_, WallTime>,
+    backend: &str,
+    workload: &str,
+    mut memory: M,
+    offset: usize,
+    len: usize,
+) {
+    let src = vec![0xA5; len];
+    group.bench_function(BenchmarkId::new(format!("write_all/{workload}"), backend), |b| {
+        b.iter(|| {
+            memory.write_all(offset, black_box(&src)).unwrap();
+            black_box(memory.len())
+        })
+    });
+}
+
+fn bench_read_exact<M: LinearMemory>(
+    group: &mut BenchmarkGroup<'_, WallTime>,
+    backend: &str,
+    workload: &str,
+    mut memory: M,
+    offset: usize,
+    len: usize,
+) {
+    let src = vec![0x5A; len];
+    memory.write_all(offset, &src).unwrap();
+
+    let mut dst = vec![0; len];
+    group.bench_function(BenchmarkId::new(format!("read_exact/{workload}"), backend), |b| {
+        b.iter(|| {
+            memory.read_exact(offset, black_box(&mut dst)).unwrap();
+            black_box(&dst);
+        })
+    });
+}
+
+fn criterion_benchmark(c: &mut Criterion) {
+    let mut group = c.benchmark_group("memory_backends");
+    group.measurement_time(BENCH_MEASUREMENT_TIME);
+
+    bench_grow(&mut group, "vec", || VecMemory::new(PAGE_SIZE));
+    bench_grow(&mut group, "paged", || PagedMemory::new(PAGE_SIZE, CHUNK_SIZE));
+
+    bench_write_all(&mut group, "vec", "contiguous", VecMemory::new(MEMORY_LEN), CONTIGUOUS_OFFSET, CONTIGUOUS_LEN);
+    bench_write_all(
+        &mut group,
+        "paged",
+        "contiguous",
+        PagedMemory::new(MEMORY_LEN, CHUNK_SIZE),
+        CONTIGUOUS_OFFSET,
+        CONTIGUOUS_LEN,
+    );
+    bench_read_exact(&mut group, "vec", "contiguous", VecMemory::new(MEMORY_LEN), CONTIGUOUS_OFFSET, CONTIGUOUS_LEN);
+    bench_read_exact(
+        &mut group,
+        "paged",
+        "contiguous",
+        PagedMemory::new(MEMORY_LEN, CHUNK_SIZE),
+        CONTIGUOUS_OFFSET,
+        CONTIGUOUS_LEN,
+    );
+
+    bench_write_all(&mut group, "vec", "cross_chunk", VecMemory::new(MEMORY_LEN), CROSS_CHUNK_OFFSET, CROSS_CHUNK_LEN);
+    bench_write_all(
+        &mut group,
+        "paged",
+        "cross_chunk",
+        PagedMemory::new(MEMORY_LEN, CHUNK_SIZE),
+        CROSS_CHUNK_OFFSET,
+        CROSS_CHUNK_LEN,
+    );
+    bench_read_exact(&mut group, "vec", "cross_chunk", VecMemory::new(MEMORY_LEN), CROSS_CHUNK_OFFSET, CROSS_CHUNK_LEN);
+    bench_read_exact(
+        &mut group,
+        "paged",
+        "cross_chunk",
+        PagedMemory::new(MEMORY_LEN, CHUNK_SIZE),
+        CROSS_CHUNK_OFFSET,
+        CROSS_CHUNK_LEN,
+    );
+
+    group.finish();
+}
+
+criterion_group!(benches, criterion_benchmark);
+criterion_main!(benches);

crates/tinywasm/benches/tinywasm.rs

@@ -1,6 +1,8 @@
 use criterion::{Criterion, criterion_group, criterion_main};
 use eyre::Result;
-use tinywasm::{FuncContext, HostFunction, Imports, ModuleInstance, Store, types};
+use tinywasm::{
+    Engine, FuncContext, HostFunction, Imports, MemoryBackend, ModuleInstance, Store, engine::Config, types,
+};
 use types::TinyWasmModule;
 
 const WASM: &[u8] = include_bytes!("../../../examples/rust/out/tinywasm.wasm");
@@ -22,7 +24,8 @@ fn tinywasm_from_twasm(twasm: &[u8]) -> Result<TinyWasmModule> {
 }
 
 fn tinywasm_run(module: TinyWasmModule) -> Result<()> {
-    let mut store = Store::default();
+    let engine = Engine::new(Config::default().with_memory_backend(MemoryBackend::paged(64 * 1024)));
+    let mut store = Store::new(engine);
     let mut imports = Imports::default();
     imports.define("env", "printi32", HostFunction::from(&mut store, |_: FuncContext<'_>, _: i32| Ok(())));
     let instance = ModuleInstance::instantiate(&mut store, module.into(), Some(imports)).expect("instantiate");

crates/tinywasm/benches/tinywasm_modes.rs

@@ -58,7 +58,7 @@ fn criterion_benchmark(c: &mut Criterion) {
     let mut group = c.benchmark_group("tinywasm_modes");
     group.measurement_time(BENCH_MEASUREMENT_TIME);
 
-    let per_instruction_engine = Engine::new(Config::new().fuel_policy(FuelPolicy::PerInstruction));
+    let per_instruction_engine = Engine::new(Config::new().with_fuel_policy(FuelPolicy::PerInstruction));
     group.bench_function("resume_fuel_per_instruction", |b| {
         b.iter_batched_ref(
             || {
@@ -70,7 +70,7 @@ fn criterion_benchmark(c: &mut Criterion) {
         )
     });
 
-    let weighted_engine = Engine::new(Config::new().fuel_policy(FuelPolicy::Weighted));
+    let weighted_engine = Engine::new(Config::new().with_fuel_policy(FuelPolicy::Weighted));
     group.bench_function("resume_fuel_weighted", |b| {
         b.iter_batched_ref(
             || setup_typed_func(module.clone(), Some(weighted_engine.clone())).expect("setup fuel weighted"),

crates/tinywasm/src/engine.rs

@@ -1,5 +1,8 @@
 use alloc::sync::Arc;
 
+/// Memory backend types and traits.
+pub use crate::store::{LinearMemory, MemoryBackend, PagedMemory, VecMemory};
+
 /// Global configuration for the WebAssembly interpreter
 ///
 /// Can be cheaply cloned and shared across multiple executions and threads.
@@ -66,6 +69,8 @@ pub struct Config {
     pub max_call_stack_size: usize,
     /// Fuel accounting policy used by budgeted execution.
     pub fuel_policy: FuelPolicy,
+    /// Backend used for runtime memories.
+    pub memory_backend: MemoryBackend,
 }
 
 impl Config {
@@ -75,10 +80,26 @@ impl Config {
     }
 
     /// Set the fuel accounting policy for budgeted execution.
-    pub fn fuel_policy(mut self, fuel_policy: FuelPolicy) -> Self {
+    pub fn with_fuel_policy(mut self, fuel_policy: FuelPolicy) -> Self {
         self.fuel_policy = fuel_policy;
         self
     }
+
+    /// Set the backend used for runtime memories.
+    pub fn with_memory_backend(mut self, memory_backend: MemoryBackend) -> Self {
+        self.memory_backend = memory_backend;
+        self
+    }
+
+    /// Get the current fuel policy
+    pub fn fuel_policy(&self) -> FuelPolicy {
+        self.fuel_policy
+    }
+
+    /// Get the current memory backend
+    pub fn memory_backend(&self) -> &MemoryBackend {
+        &self.memory_backend
+    }
 }
 
 impl Default for Config {
@@ -89,6 +110,7 @@ impl Default for Config {
             stack_128_size: DEFAULT_VALUE_STACK_128_SIZE,
             max_call_stack_size: DEFAULT_MAX_CALL_STACK_SIZE,
             fuel_policy: FuelPolicy::default(),
+            memory_backend: MemoryBackend::default(),
         }
     }
 }

crates/tinywasm/src/error.rs

@@ -1,3 +1,4 @@
+use alloc::boxed::Box;
 use alloc::string::{String, ToString};
 use alloc::vec::Vec;
 use core::fmt::Debug;
@@ -18,7 +19,7 @@ pub enum Error {
     Linker(LinkingError),
 
     /// A WebAssembly feature is not supported
-    UnsupportedFeature(String),
+    UnsupportedFeature(&'static str),
 
     /// An unknown error occurred
     Other(String),
@@ -89,6 +90,9 @@ pub enum Trap {
     /// An unreachable instruction was executed
     Unreachable,
 
+    /// A host function returned an error
+    HostFunction(Box<dyn core::error::Error + Send + Sync>),
+
     /// An out-of-bounds memory access occurred
     MemoryOutOfBounds {
         /// The offset of the access
@@ -143,6 +147,9 @@ pub enum Trap {
         /// The actual type
         actual: FuncType,
     },
+
+    /// Catch-all for other messages
+    Other(&'static str),
 }
 
 impl Trap {
@@ -160,6 +167,8 @@ impl Trap {
             Self::UndefinedElement { .. } => "undefined element",
             Self::UninitializedElement { .. } => "uninitialized element",
             Self::IndirectCallTypeMismatch { .. } => "indirect call type mismatch",
+            Self::HostFunction(_) => "host function trap",
+            Self::Other(message) => message,
         }
     }
 }
@@ -231,6 +240,8 @@ impl Display for LinkingError {
 impl Display for Trap {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
+            Self::Other(message) => write!(f, "{message}"),
+            Self::HostFunction(message) => write!(f, "host function trap: {message}"),
             Self::Unreachable => write!(f, "unreachable"),
             Self::MemoryOutOfBounds { offset, len, max } => {
                 write!(f, "out of bounds memory access: offset={offset}, len={len}, max={max}")
@@ -265,6 +276,16 @@ impl Debug for Error {
 
 impl core::error::Error for Error {}
 
+#[cfg(feature = "std")]
+impl From<Error> for crate::std::io::Error {
+    fn from(value: Error) -> Self {
+        match value {
+            Error::Io(err) => err,
+            other => Self::other(other.to_string()),
+        }
+    }
+}
+
 #[cfg(feature = "parser")]
 impl From<tinywasm_parser::ParseError> for Error {
     fn from(value: tinywasm_parser::ParseError) -> Self {

crates/tinywasm/src/imports.rs

@@ -276,8 +276,7 @@ impl Imports {
                             return Err(LinkingError::incompatible_import_type(import).into());
                         };
                         let mem = store.state.get_mem(memory.0.addr);
-                        let (size, kind) = { (mem.page_count, mem.kind) };
-                        Self::compare_memory_types(import, &kind, import_ty, size)?;
+                        Self::compare_memory_types(import, &mem.kind, import_ty, mem.page_count)?;
                         imports.memories.push(memory.0.addr);
                     }
                     Extern::Function(func_handle) => {
@@ -327,8 +326,7 @@ impl Imports {
                     }
                     (ExternVal::Memory(memory_addr), ImportKind::Memory(ty)) => {
                         let mem = store.state.get_mem(memory_addr);
-                        let (size, kind) = { (mem.page_count, mem.kind) };
-                        Self::compare_memory_types(import, &kind, ty, size)?;
+                        Self::compare_memory_types(import, &mem.kind, ty, mem.page_count)?;
                         imports.memories.push(memory_addr);
                     }
                     (ExternVal::Func(func_addr), ImportKind::Function(ty)) => {

crates/tinywasm/src/instance.rs

@@ -133,7 +133,7 @@ impl ModuleInstance {
 
         addrs.funcs.extend(store.init_funcs(&module.0.funcs, idx));
         addrs.tables.extend(store.init_tables(&module.0.table_types, idx));
-        addrs.memories.extend(store.init_memories(&module.0.memory_types, idx));
+        addrs.memories.extend(store.init_memories(&module.0.memory_types, idx)?);
         let global_addrs = store.init_globals(addrs.globals, &module.0.globals, &addrs.funcs, idx)?;
         let (elem_addrs, elem_trapped) =
             store.init_elements(&addrs.tables, &addrs.funcs, &global_addrs, &module.0.elements, idx)?;