feat: add more examples, work on new public api

explodingcamera · explodingcamera · commit d8d439e64016 · 2024-01-26T15:16:05.000+01:00
Signed-off-by: Henry Gressmann &lt;mail@henrygressmann.de&gt;
diff --git a/.cargo/config.toml b/.cargo/config.toml
@@ -1,7 +1,6 @@
 [alias]
 version-dev="workspaces version --no-git-commit --force tinywasm*"
 dev="run -- -l debug run"
-
 test-mvp="test --package tinywasm --test test-mvp --release -- --enable "
 test-2="test --package tinywasm --test test-two --release -- --enable "
 test-wast="test --package tinywasm --test test-wast -- --enable "
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -20,10 +20,10 @@ jobs:
         run: rustup update stable
 
       - name: Build (stable)
-        run: cargo +stable build --workspace --exclude wasm-testsuite
+        run: cargo +stable build --workspace
 
       - name: Run tests (stable)
-        run: cargo +stable test --workspace --exclude wasm-testsuite
+        run: cargo +stable test --workspace
 
       - name: Run MVP testsuite
         run: cargo +stable test-mvp
@@ -41,10 +41,10 @@ jobs:
         run: rustup update nightly
 
       - name: Build (nightly, no default features)
-        run: cargo +nightly build --workspace --exclude wasm-testsuite --exclude rust-wasm-examples --no-default-features
+        run: cargo +nightly build --workspace --no-default-features
 
       - name: Run tests (nightly, no default features)
-        run: cargo +nightly test --workspace --exclude wasm-testsuite --exclude rust-wasm-examples --no-default-features
+        run: cargo +nightly test --workspace --no-default-features
 
       - name: Run MVP testsuite (nightly)
         run: cargo +nightly test-mvp
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,6 @@
 /target
 notes.md
 examples/rust/out/*
+examples/rust/target
+examples/rust/Cargo.lock
 examples/wast/*
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,5 +1,9 @@
 {
     "search.exclude": {
         "**/wasm-testsuite/data": true
-    }
+    },
+    "rust-analyzer.linkedProjects": [
+        "./Cargo.toml",
+        "./examples/rust/Cargo.toml"
+    ]
 }
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,5 +1,5 @@
 [workspace]
-members=["crates/*", "examples/rust"]
+members=["crates/*"]
 resolver="2"
 
 [profile.wasm]
@@ -21,6 +21,10 @@ name="tinywasm-root"
 publish=false
 edition="2021"
 
+[[example]]
+name="wasm-rust"
+test=false
+
 [dev-dependencies]
 color-eyre="0.6"
 tinywasm={path="crates/tinywasm"}
diff --git a/crates/cli/src/bin.rs b/crates/cli/src/bin.rs
@@ -112,7 +112,7 @@ fn run(module: Module, func: Option<String>, args: Vec<WasmValue>) -> Result<()>
     let instance = module.instantiate(&mut store, None)?;
 
     if let Some(func) = func {
-        let func = instance.exported_func_by_name(&store, &func)?;
+        let func = instance.exported_func_untyped(&store, &func)?;
         let res = func.call(&mut store, &args)?;
         info!("{res:?}");
     }
diff --git a/crates/tinywasm/src/export.rs b/crates/tinywasm/src/export.rs
diff --git a/crates/tinywasm/src/imports.rs b/crates/tinywasm/src/imports.rs
@@ -77,6 +77,11 @@ impl FuncContext<'_> {
     pub fn module(&self) -> &crate::ModuleInstance {
         self.module
     }
+
+    /// Get a reference to an exported memory
+    pub fn memory(&mut self, name: &str) -> Result<crate::MemoryRef> {
+        self.module.exported_memory(self.store, name)
+    }
 }
 
 impl Debug for HostFunction {
@@ -276,7 +281,7 @@ impl Imports {
 
         if let Some(addr) = self.modules.get(&name.module) {
             let instance = store.get_module_instance(*addr)?;
-            return Some(ResolvedExtern::Store(instance.export(&import.name)?));
+            return Some(ResolvedExtern::Store(instance.export_addr(&import.name)?));
         }
 
         None
@@ -398,7 +403,7 @@ impl Imports {
                             Self::compare_table_types(import, &table.borrow().kind, ty)?;
                             imports.tables.push(table_addr);
                         }
-                        (ExternVal::Mem(memory_addr), ImportKind::Memory(ty)) => {
+                        (ExternVal::Memory(memory_addr), ImportKind::Memory(ty)) => {
                             let mem = store.get_mem(memory_addr as usize)?;
                             let (size, kind) = {
                                 let mem = mem.borrow();
diff --git a/crates/tinywasm/src/instance.rs b/crates/tinywasm/src/instance.rs
@@ -1,12 +1,9 @@
 use alloc::{boxed::Box, format, string::ToString, sync::Arc};
-use tinywasm_types::{
-    DataAddr, ElemAddr, Export, ExternVal, ExternalKind, FuncAddr, FuncType, GlobalAddr, Import, MemAddr,
-    ModuleInstanceAddr, TableAddr,
-};
+use tinywasm_types::*;
 
 use crate::{
     func::{FromWasmValueTuple, IntoWasmValueTuple},
-    log, Error, FuncHandle, FuncHandleTyped, Imports, Module, Result, Store,
+    log, Error, FuncHandle, FuncHandleTyped, Imports, MemoryRef, Module, Result, Store,
 };
 
 /// An instanciated WebAssembly module
@@ -106,7 +103,7 @@ impl ModuleInstance {
     }
 
     /// Get a export by name
-    pub fn export(&self, name: &str) -> Option<ExternVal> {
+    pub fn export_addr(&self, name: &str) -> Option<ExternVal> {
         let exports = self.0.exports.iter().find(|e| e.name == name.into())?;
         let kind = exports.kind.clone();
         let addr = match kind {
@@ -162,12 +159,12 @@ impl ModuleInstance {
     }
 
     /// Get an exported function by name
-    pub fn exported_func_by_name(&self, store: &Store, name: &str) -> Result<FuncHandle> {
+    pub fn exported_func_untyped(&self, store: &Store, name: &str) -> Result<FuncHandle> {
         if self.0.store_id != store.id() {
             return Err(Error::InvalidStore);
         }
 
-        let export = self.export(name).ok_or_else(|| Error::Other(format!("Export not found: {}", name)))?;
+        let export = self.export_addr(name).ok_or_else(|| Error::Other(format!("Export not found: {}", name)))?;
         let ExternVal::Func(func_addr) = export else {
             return Err(Error::Other(format!("Export is not a function: {}", name)));
         };
@@ -179,15 +176,32 @@ impl ModuleInstance {
     }
 
     /// Get a typed exported function by name
-    pub fn typed_func<P, R>(&self, store: &Store, name: &str) -> Result<FuncHandleTyped<P, R>>
+    pub fn exported_func<P, R>(&self, store: &Store, name: &str) -> Result<FuncHandleTyped<P, R>>
     where
         P: IntoWasmValueTuple,
         R: FromWasmValueTuple,
     {
-        let func = self.exported_func_by_name(store, name)?;
+        let func = self.exported_func_untyped(store, name)?;
         Ok(FuncHandleTyped { func, marker: core::marker::PhantomData })
     }
 
+    /// Get an exported memory by name
+    pub fn exported_memory(&self, store: &mut Store, name: &str) -> Result<MemoryRef> {
+        let export = self.export_addr(name).ok_or_else(|| Error::Other(format!("Export not found: {}", name)))?;
+        let ExternVal::Memory(mem_addr) = export else {
+            return Err(Error::Other(format!("Export is not a memory: {}", name)));
+        };
+        let mem = self.memory(store, mem_addr)?;
+        Ok(mem)
+    }
+
+    /// Get a memory by address
+    pub fn memory(&self, store: &Store, addr: MemAddr) -> Result<MemoryRef> {
+        let addr = self.resolve_mem_addr(addr);
+        let mem = store.get_mem(addr as usize)?;
+        Ok(MemoryRef { instance: mem.clone() })
+    }
+
     /// Get the start function of the module
     ///
     /// Returns None if the module has no start function
@@ -204,7 +218,7 @@ impl ModuleInstance {
             Some(func_index) => func_index,
             None => {
                 // alternatively, check for a _start function in the exports
-                let Some(ExternVal::Func(func_addr)) = self.export("_start") else {
+                let Some(ExternVal::Func(func_addr)) = self.export_addr("_start") else {
                     return Ok(None);
                 };
 
diff --git a/crates/tinywasm/src/lib.rs b/crates/tinywasm/src/lib.rs
@@ -51,7 +51,7 @@
 //! // Get a typed handle to the exported "add" function
 //! // Alternatively, you can use `instance.get_func` to get an untyped handle
 //! // that takes and returns [`WasmValue`]s
-//! let func = instance.typed_func::<(i32, i32), i32>(&mut store, "add")?;
+//! let func = instance.exported_func::<(i32, i32), i32>(&mut store, "add")?;
 //! let res = func.call(&mut store, (1, 2))?;
 //!
 //! assert_eq!(res, 3);
@@ -99,6 +99,9 @@ pub use module::Module;
 mod instance;
 pub use instance::ModuleInstance;
 
+mod reference;
+pub use reference::*;
+
 mod func;
 pub use func::{FuncHandle, FuncHandleTyped};
 
diff --git a/crates/tinywasm/src/reference.rs b/crates/tinywasm/src/reference.rs
@@ -0,0 +1,17 @@
+use core::cell::RefCell;
+
+use alloc::rc::Rc;
+
+use crate::{GlobalInstance, MemoryInstance};
+
+/// A reference to a memory instance
+#[derive(Debug, Clone)]
+pub struct MemoryRef {
+    pub(crate) instance: Rc<RefCell<MemoryInstance>>,
+}
+
+/// A reference to a global instance
+#[derive(Debug, Clone)]
+pub struct GlobalRef {
+    pub(crate) instance: Rc<RefCell<GlobalInstance>>,
+}
diff --git a/crates/tinywasm/tests/testsuite/run.rs b/crates/tinywasm/tests/testsuite/run.rs
@@ -428,7 +428,7 @@ impl TestSuite {
                                 continue;
                             };
 
-                            let module_global = match match module.export(global) {
+                            let module_global = match match module.export_addr(global) {
                                 Some(ExternVal::Global(addr)) => {
                                     store.get_global_val(addr as usize).map_err(|_| eyre!("failed to get global"))
                                 }
diff --git a/crates/tinywasm/tests/testsuite/util.rs b/crates/tinywasm/tests/testsuite/util.rs
@@ -25,7 +25,7 @@ pub fn exec_fn_instance(
         return Err(tinywasm::Error::Other("no instance found".to_string()));
     };
 
-    let func = instance.exported_func_by_name(store, name)?;
+    let func = instance.exported_func_untyped(store, name)?;
     func.call(store, args)
 }
 
@@ -42,7 +42,7 @@ pub fn exec_fn(
     let mut store = tinywasm::Store::new();
     let module = tinywasm::Module::from(module);
     let instance = module.instantiate(&mut store, imports)?;
-    instance.exported_func_by_name(&store, name)?.call(&mut store, args)
+    instance.exported_func_untyped(&store, name)?.call(&mut store, args)
 }
 
 pub fn catch_unwind_silent<F: FnOnce() -> R, R>(f: F) -> std::thread::Result<R> {
diff --git a/crates/types/src/lib.rs b/crates/types/src/lib.rs
@@ -316,7 +316,7 @@ pub type ModuleInstanceAddr = Addr;
 pub enum ExternVal {
     Func(FuncAddr),
     Table(TableAddr),
-    Mem(MemAddr),
+    Memory(MemAddr),
     Global(GlobalAddr),
 }
 
@@ -325,7 +325,7 @@ impl ExternVal {
         match self {
             Self::Func(_) => ExternalKind::Func,
             Self::Table(_) => ExternalKind::Table,
-            Self::Mem(_) => ExternalKind::Memory,
+            Self::Memory(_) => ExternalKind::Memory,
             Self::Global(_) => ExternalKind::Global,
         }
     }
@@ -334,7 +334,7 @@ impl ExternVal {
         match kind {
             ExternalKind::Func => Self::Func(addr),
             ExternalKind::Table => Self::Table(addr),
-            ExternalKind::Memory => Self::Mem(addr),
+            ExternalKind::Memory => Self::Memory(addr),
             ExternalKind::Global => Self::Global(addr),
         }
     }
diff --git a/examples/README.md b/examples/README.md
@@ -1,10 +1,10 @@
 # Examples
 
-## WasmRust
+## Wasm-Rust
 
 These are examples using WebAssembly generated from Rust code.
-To run these, you first need to build the Rust code into WebAssembly, since the wasm files are not included in the repository to keep it small.
-This requires the `wasm32-unknown-unknown` target and `wasm-opt` to be installed (available via Binaryen).
+To run these, you first need to build the Rust code, since the resulting wasm files are not included in the repository to keep it small.
+This requires the `wasm32-unknown-unknown` target and `wasm-opt` to be installed (available via [Binaryen](https://github.com/WebAssembly/binaryen)).
 
 ```bash
 $ ./examples/rust/build.sh
@@ -20,3 +20,4 @@ Where `<example>` is one of the following:
 
 - `hello`: A simple example that prints a number to the console.
 - `tinywasm`: Runs `hello` using TinyWasm - inside of TinyWasm itself!
+- `fibonacci`: Calculates the x-th Fibonacci number.
diff --git a/examples/rust/Cargo.toml b/examples/rust/Cargo.toml
@@ -1,5 +1,8 @@
 cargo-features=["per-package-target"]
 
+# treat this as an independent package
+[workspace]
+
 [package]
 publish=false
 name="rust-wasm-examples"
@@ -16,3 +19,14 @@ path="src/hello.rs"
 [[bin]]
 name="tinywasm"
 path="src/tinywasm.rs"
+
+[[bin]]
+name="fibonacci"
+path="src/fibonacci.rs"
+
+[profile.wasm]
+opt-level="s"
+lto="thin"
+codegen-units=1
+panic="abort"
+inherits="release"
diff --git a/examples/rust/README.md b/examples/rust/README.md
@@ -1 +1,4 @@
-# Examples using Rust compiled to WebAssembly
+# WebAssembly Rust Examples
+
+This is a seperate crate that generates WebAssembly from Rust code.
+It is used by the `wasm-rust` example.
diff --git a/examples/rust/build.sh b/examples/rust/build.sh
@@ -1,11 +1,14 @@
 #!/usr/bin/env bash
 cd "$(dirname "$0")"
 
-bins=("hello" "tinywasm")
+bins=("hello" "tinywasm" "fibonacci")
 exclude_wat=("tinywasm")
-out_dir="../../target/wasm32-unknown-unknown/wasm"
+out_dir="./target/wasm32-unknown-unknown/wasm"
 dest_dir="out"
 
+# ensure out dir exists
+mkdir -p "$dest_dir"
+
 for bin in "${bins[@]}"; do
     cargo build --target wasm32-unknown-unknown --package rust-wasm-examples --profile=wasm --bin "$bin"
 
diff --git a/examples/rust/src/fibonacci.rs b/examples/rust/src/fibonacci.rs
@@ -0,0 +1,17 @@
+#![no_std]
+#![no_main]
+
+#[cfg(not(test))]
+#[panic_handler]
+fn panic(_info: &core::panic::PanicInfo) -> ! {
+    core::arch::wasm32::unreachable()
+}
+
+#[no_mangle]
+// The rust compiler will convert this to an iterative algorithm.
+pub extern "C" fn fibonacci(n: i32) -> i32 {
+    if n <= 1 {
+        return n;
+    }
+    fibonacci(n - 1) + fibonacci(n - 2)
+}
diff --git a/examples/rust/src/tinywasm.rs b/examples/rust/src/tinywasm.rs
@@ -26,7 +26,7 @@ fn run() -> tinywasm::Result<()> {
     )?;
     let instance = module.instantiate(&mut store, Some(imports))?;
 
-    let add_and_print = instance.typed_func::<(i32, i32), ()>(&mut store, "add_and_print")?;
+    let add_and_print = instance.exported_func::<(i32, i32), ()>(&mut store, "add_and_print")?;
     add_and_print.call(&mut store, (1, 2))?;
     Ok(())
 }
diff --git a/examples/wasm-rust.rs b/examples/wasm-rust.rs
diff --git a/examples/wasm/add.wasm b/examples/wasm/add.wasm

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,9 @@`
`1`	`1`	`{`
`2`	`2`	`"search.exclude": {`
`3`	`3`	`"**/wasm-testsuite/data": true`
`4`		`- }`
	`4`	`+ },`
	`5`	`+ "rust-analyzer.linkedProjects": [`
	`6`	`+ "./Cargo.toml",`
	`7`	`+ "./examples/rust/Cargo.toml"`
	`8`	`+ ]`
`5`	`9`	`}`
Original file line number	Diff line number	Diff line change
`@@ -112,7 +112,7 @@ fn run(module: Module, func: Option<String>, args: Vec<WasmValue>) -> Result<()>`
`112`	`112`	`let instance = module.instantiate(&mut store, None)?;`
`113`	`113`
`114`	`114`	`if let Some(func) = func {`
`115`		`- let func = instance.exported_func_by_name(&store, &func)?;`
	`115`	`+ let func = instance.exported_func_untyped(&store, &func)?;`
`116`	`116`	`let res = func.call(&mut store, &args)?;`
`117`	`117`	`info!("{res:?}");`
`118`	`118`	`}`