chore: improve documentation, tests

Signed-off-by: Henry Gressmann <[email protected]>

Author: explodingcamera

.cargo/config.toml

@@ -2,6 +2,6 @@
 version-dev="workspaces version --no-git-commit --force tinywasm*"
 dev="run -- -l debug run"
 
-test-mvp="test --package tinywasm --test test-mvp"
-test-wast="test --package tinywasm --test test-wast --"
-generate-charts="test --package tinywasm --test generate-charts"
+test-mvp="test --package tinywasm --test test-mvp --release -- --enable "
+test-wast="test --package tinywasm --test test-wast -- --enable "
+generate-charts="test --package tinywasm --test generate-charts -- --enable "

.github/workflows/test.yaml

@@ -20,10 +20,10 @@ jobs:
           rustup default stable
 
       - name: Build (stable)
-        run: cargo +stable build --verbose
+        run: cargo +stable build --all
 
       - name: Run tests (stable)
-        run: cargo +stable test --verbose
+        run: cargo +stable test --all
 
   test-no-std:
     name: Test without default features on nightly Rust
@@ -37,7 +37,7 @@ jobs:
           rustup default nightly
 
       - name: Build (nightly, no default features)
-        run: cargo +nightly build --verbose --no-default-features
+        run: cargo +nightly build --all --no-default-features
 
       - name: Run tests (nightly, no default features)
-        run: cargo +nightly test --verbose --no-default-features
+        run: cargo +nightly test --all --no-default-features

Cargo.lock

@@ -19,7 +19,7 @@ argh="0.1"
 color-eyre={version="0.6", default-features=false}
 log="0.4"
 pretty_env_logger="0.5"
-wast={version="69.0", optional=true}
+wast={version="70.0", optional=true}
 
 [features]
 default=["wat"]

crates/cli/Cargo.toml

@@ -9,7 +9,6 @@ repository.workspace=true
 
 [dependencies]
 # fork of wasmparser with no_std support, see https://github.com/bytecodealliance/wasmtime/issues/3495
-# TODO: create dependency free parser
 wasmparser={version="0.100", package="wasmparser-nostd", default-features=false}
 log={version="0.4", optional=true}
 tinywasm-types={version="0.2.0-alpha.0", path="../types"}

crates/parser/Cargo.toml

@@ -10,6 +10,7 @@ extern crate alloc;
 #[allow(clippy::single_component_path_imports)]
 use log;
 
+// noop fallback if logging is disabled.
 #[cfg(not(feature = "logging"))]
 mod log {
     macro_rules! debug    ( ($($tt:tt)*) => {{}} );

crates/parser/src/lib.rs

@@ -19,7 +19,7 @@ tinywasm-types={version="0.2.0-alpha.0", path="../types", default-features=false
 
 [dev-dependencies]
 wasm-testsuite={path="../wasm-testsuite"}
-wast={version="69.0"}
+wast={version="70.0"}
 owo-colors={version="4.0"}
 eyre={version="0.6"}
 serde_json={version="1.0"}

crates/tinywasm/Cargo.toml

@@ -19,7 +19,7 @@ pub struct FuncHandle {
 }
 
 impl FuncHandle {
-    /// Call a function
+    /// Call a function (Invocation)
     ///
     /// See <https://webassembly.github.io/spec/core/exec/modules.html#invocation>
     pub fn call(&self, store: &mut Store, params: &[WasmValue]) -> Result<Vec<WasmValue>> {
@@ -66,8 +66,14 @@ impl FuncHandle {
 
         // Once the function returns:
         let result_m = func_ty.results.len();
+
+        // 1. Assert: m values are on the top of the stack (Ensured by validation)
+        debug_assert!(stack.values.len() >= result_m);
+
+        // 2. Pop m values from the stack
         let res = stack.values.last_n(result_m)?;
 
+        // The values are returned as the results of the invocation.
         Ok(res
             .iter()
             .zip(func_ty.results.iter())

crates/tinywasm/src/func.rs

@@ -42,16 +42,30 @@ impl ModuleInstance {
     }
 
     /// Instantiate the module in the given store
+    ///
+    /// See <https://webassembly.github.io/spec/core/exec/modules.html#exec-instantiation>
     pub fn instantiate(store: &mut Store, module: Module, imports: Option<Imports>) -> Result<Self> {
+        // This doesn't completely follow the steps in the spec, but the end result is the same
+        // Constant expressions are evaluated directly where they are used, so we
+        // don't need to create a auxiliary frame etc.
+
         let idx = store.next_module_instance_idx();
         let imports = imports.unwrap_or_default();
+
+        // TODO: doesn't link other modules yet
         let linked_imports = imports.link(store, &module)?;
+        let global_addrs = store.add_globals(module.data.globals.into(), &module.data.imports, &linked_imports, idx)?;
 
+        // TODO: imported functions missing
         let func_addrs = store.add_funcs(module.data.funcs.into(), idx);
+
         let table_addrs = store.add_tables(module.data.table_types.into(), idx);
         let mem_addrs = store.add_mems(module.data.memory_types.into(), idx)?;
-        let global_addrs = store.add_globals(module.data.globals.into(), &module.data.imports, &linked_imports, idx)?;
+
+        // TODO: active/declared elems need to be initialized
         let elem_addrs = store.add_elems(module.data.elements.into(), idx)?;
+
+        // TODO: active data segments need to be initialized
         let data_addrs = store.add_datas(module.data.data.into(), idx);
 
         let instance = ModuleInstanceInner {
@@ -70,8 +84,10 @@ impl ModuleInstance {
             imports: module.data.imports,
             exports: crate::ExportInstance(module.data.exports),
         };
+
         let instance = ModuleInstance::new(instance);
         store.add_instance(instance.clone())?;
+
         Ok(instance)
     }
 
@@ -176,13 +192,18 @@ impl ModuleInstance {
             }
         };
 
-        let func_addr = self.0.func_addrs[func_index as usize];
-        let func = store.get_func(func_addr as usize)?;
+        let func_addr = self
+            .0
+            .func_addrs
+            .get(func_index as usize)
+            .expect("No func addr for start func, this is a bug");
+
+        let func = store.get_func(*func_addr as usize)?;
         let ty = self.0.types[func.ty_addr() as usize].clone();
 
         Ok(Some(FuncHandle {
             module: self.clone(),
-            addr: func_addr,
+            addr: *func_addr,
             ty,
             name: None,
         }))

crates/tinywasm/src/instance.rs

@@ -43,7 +43,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 types
-//! let func = instance.get_typed_func::<(i32, i32), (i32,)>(&mut store, "add")?;
+//! let func = instance.typed_func::<(i32, i32), (i32,)>(&mut store, "add")?;
 //! let res = func.call(&mut store, (1, 2))?;
 //!
 //! assert_eq!(res, (3,));
@@ -60,7 +60,7 @@
 //! a custom allocator. This removes support for parsing from files and streams,
 //! but otherwise the API is the same.
 //!
-//! Additionally, if you want proper error types, you must use a `nightly` compiler.
+//! Additionally, if you want proper error types, you must use a `nightly` compiler to have the error trait in core.
 
 mod std;
 extern crate alloc;
@@ -70,6 +70,7 @@ extern crate alloc;
 #[allow(clippy::single_component_path_imports)]
 use log;
 
+// noop fallback if logging is disabled.
 #[cfg(not(feature = "logging"))]
 pub(crate) mod log {
     macro_rules! debug    ( ($($tt:tt)*) => {{}} );