From 1f8748d43164b79cc17e14273b0357ae87584db4 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:38:24 +0200 Subject: [PATCH 01/10] add docs/development.md --- docs/developement.md | 80 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/developement.md diff --git a/docs/developement.md b/docs/developement.md new file mode 100644 index 0000000000..b7b17c48ef --- /dev/null +++ b/docs/developement.md @@ -0,0 +1,80 @@ +# Wasmi Development + +## Checkout & Build + +Clone the Wasmi repository and build using `cargo`: + +```console +git clone https://github.com/wasmi-labs/wasmi.git --recursive +cd wasmi +cargo build +``` + +## Testing + +Wasmi has two major test suites that are accessed via the `wasmi` and `wasmi_wast` crates respectively. + +- `cargo test -p wasmi`: unit tests and tons of detailed translation unit tests +- `cargo test -p wasmi_wast`: integration tests including the official Wasm spec testsuite + +As usual both testsuites can be run at the same time via `cargo test`. + +## Benchmarks + +In order to benchmark Wasmi use the following command: + +```console +cargo bench --bench benches -p wasmi +``` + +Benchmarks in Wasmi are structured in the following way: + +- `translate`: test cases that primarily benchmark the translation performance + - `checked`: validate + translate eagerly + - `unchecked`: eagerly translate but not validate + - `fueled`: same as `checked` but with fuel metering enabled + - `lazy`: validate + translate lazily + - `lazy-translation`: validate eagerly but translate lazily +- `instantiate`: test cases that primarily benchmark the Wasm module instantiation performance +- `execute`: test cases that primarily benchmark Wasmi's execution performance + - `call`: call based testcases + - `tiny_keccak`, `regex_redux`, `reverse_complement`: compiled from optimized Rust sources + - `fibonacci`: variety of fibonacci tests (recusion, tail-recursion and iteration) + - `memory`: test cases benchmarking memory accesses (load, store, bulk-ops) + - many more .. +- `overhead`: test cases that benchmark Wasmi call performance overhead + +Example: to benchmark all fibonacci test cases use the following command: + +``` +`cargo bench --bench benches -p wasmi execute/fibonacci`. +``` + +## Fuzzing + +Wasmi has some built-in fuzzers that are even used in Google's OSSFuzz. + +- `translate`: optimized to find crashes and bugs during Wasmi translation +- `execute`: optimized to find crashes and bugs during Wasmi execution +- `differential`: finds mismatches between different Wasm runtimes + - Wasm runtimes compared against trunc Wasmi are Wasmtime and an old Wasmi v0.31 + +## Publishing a Release + +Publishing new Wasmi versions requires to publish new versions for all crates in the Wasmi workspace. + +In order to successfully publish one needs to publish the following Wasmi crates in the following order: + +- `wasmi_core` +- `wasmi_collections` +- `wasmi_ir` +- `wasmi` +- `wasmi_wast` +- `wasmi_wasi` +- `wasmi_c_api_macros` +- `wasmi_c_api_impl` +- `wasmi_cli` (*) + +(*) Before publishing `wasmi_cli` one needs to comment-out the `profile.release` information +in its `Cargo.toml`. This is required due to a bug in Cargo: https://github.com/rust-lang/cargo/issues/8264 +This step can and should be dropped once this Cargo bug has been fixed. From 8f651ffbcc5cc986f72ec3d4d5a3c7934e33f663 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:40:54 +0200 Subject: [PATCH 02/10] update usage -> docs README section --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bead680484..7d481a1d38 100644 --- a/README.md +++ b/README.md @@ -48,9 +48,10 @@ Wasmi is suitable for safety critical use cases and has been audited several tim - Built-in support for fuel metering. - Supports the official [Wasm C-API](https://github.com/WebAssembly/wasm-c-api). -## Usage +## Docs -Refer to the [Wasmi usage guide](./docs/usage.md) to learn how properly to use [Wasmi](https://crates.io/crates/wasmi). +- [Usage Guide](./docs/usage.md): learn how to use the [Wasmi API](https://crates.io/crates/wasmi) properly. +- [Development Guide](./docs/developement.md): learn how to develop for Wasmi. ## WebAssembly Features From c55ff6a17f517044979b40981055bae2f5552605 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:42:50 +0200 Subject: [PATCH 03/10] replace Crate Features section with link in Docs section --- README.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/README.md b/README.md index 7d481a1d38..f8b4cdfef5 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,7 @@ Wasmi is suitable for safety critical use cases and has been audited several tim - [Usage Guide](./docs/usage.md): learn how to use the [Wasmi API](https://crates.io/crates/wasmi) properly. - [Development Guide](./docs/developement.md): learn how to develop for Wasmi. +- [Crate Features](https://docs.rs/wasmi/latest/wasmi/#crate-features): learn about `wasmi` crate features. ## WebAssembly Features @@ -116,17 +117,6 @@ Wasmi is suitable for safety critical use cases and has been audited several tim [(#1369)]: https://github.com/wasmi-labs/wasmi/issues/1369 [(#1443)]: https://github.com/wasmi-labs/wasmi/pull/1443 -## Crate Features - -| Feature | Crates | Description | -|:-:|:--|:--| -| `std` | `wasmi`
`wasmi_core`
`wasmi_ir`
`wasmi_collections` | Enables usage of Rust's standard library. This may have some performance advantages when enabled. Disabling this feature makes Wasmi compile on platforms that do not provide Rust's standard library such as many embedded platforms.

Enabled by default. | -| `wat` | `wasmi` | Enables support to parse Wat encoded Wasm modules.

Enabled by default. | -| `simd` | `wasmi`
`wasmi_core`
`wasmi_ir`
`wasmi_cli` | Enables support for the Wasm `simd` and `relaxed-simd` proposals. Note that this may introduce execution overhead and increased memory consumption for Wasm executions that do not need Wasm `simd` functionality.

Disabled by default. | -| `hash-collections` | `wasmi`
`wasmi_collections` | Enables use of hash-map based collections in Wasmi internals. This might yield performance improvements in some use cases.

Disabled by default. | -| `prefer-btree-collections` | `wasmi`
`wasmi_collections` | Enforces use of btree-map based collections in Wasmi internals. This may yield performance improvements and memory consumption decreases in some use cases. Also it enables Wasmi to run on platforms that have no random source.

Disabled by default. | -| `extra-checks` | `wasmi` | Enables extra runtime checks in the Wasmi executor. Expected execution overhead is ~20%. Enable this if your focus is on safety. Disable this for maximum execution performance.

Disabled by default. | - ## Development ### Build & Test From f184e64fbc5807b2ff9cefac36c8263c507700c9 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:43:25 +0200 Subject: [PATCH 04/10] remove Development and Benchmarks section from README This info is now fully accessible via the new Docs README section. --- README.md | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/README.md b/README.md index f8b4cdfef5..de5ef33683 100644 --- a/README.md +++ b/README.md @@ -117,29 +117,6 @@ Wasmi is suitable for safety critical use cases and has been audited several tim [(#1369)]: https://github.com/wasmi-labs/wasmi/issues/1369 [(#1443)]: https://github.com/wasmi-labs/wasmi/pull/1443 -## Development - -### Build & Test - -Clone the Wasmi repository and build using `cargo`: - -```console -git clone https://github.com/wasmi-labs/wasmi.git --recursive -cd wasmi -cargo build -cargo test -``` - -### Benchmarks - -In order to benchmark Wasmi use the following command: - -```console -cargo bench -``` - -Use `translate`, `instantiate`, `execute` or `overhead` filters to only run benchmarks that test performance of Wasm translation, instantiation, execution or miscellaneous overhead respectively, e.g. `cargo bench execute`. - ## Supported Platforms Wasmi supports a wide variety of architectures and platforms. From 4eb20d47d9d5ed538beb8f0c7c94881c4c6d00f8 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:44:15 +0200 Subject: [PATCH 05/10] simplify Supported Platforms README section --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index de5ef33683..e83a2ac01d 100644 --- a/README.md +++ b/README.md @@ -122,8 +122,7 @@ Wasmi is suitable for safety critical use cases and has been audited several tim Wasmi supports a wide variety of architectures and platforms. - Fore more details see this [list of supported platforms for Rust](https://doc.rust-lang.org/stable/rustc/platform-support.html). -- **Note:** Wasmi can be used in `no_std` embedded environments, thus not requiring the standard library (`std`). -- Only some platforms are checked in CI and guaranteed to be fully working by the Wasmi maintainers. +- Wasmi supports `no_std` embedded environments, thus not requiring the standard library (`std`). ## License From 1fffb0c3ab7580a6de73d3d68249572f121ba9cc Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:50:29 +0200 Subject: [PATCH 06/10] add example to fuzzing section in development docs --- docs/developement.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/developement.md b/docs/developement.md index b7b17c48ef..9178907f31 100644 --- a/docs/developement.md +++ b/docs/developement.md @@ -58,6 +58,13 @@ Wasmi has some built-in fuzzers that are even used in Google's OSSFuzz. - `execute`: optimized to find crashes and bugs during Wasmi execution - `differential`: finds mismatches between different Wasm runtimes - Wasm runtimes compared against trunc Wasmi are Wasmtime and an old Wasmi v0.31 + - Requires the `differential` crate feature. + +Example usage: + +``` +cargo +nightly fuzz run differential --features differential +``` ## Publishing a Release From 4b40628f85305579ab53a8d169801d850391cfff Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:54:28 +0200 Subject: [PATCH 07/10] add emojies to doc section items --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e83a2ac01d..7d93500675 100644 --- a/README.md +++ b/README.md @@ -50,9 +50,9 @@ Wasmi is suitable for safety critical use cases and has been audited several tim ## Docs -- [Usage Guide](./docs/usage.md): learn how to use the [Wasmi API](https://crates.io/crates/wasmi) properly. -- [Development Guide](./docs/developement.md): learn how to develop for Wasmi. -- [Crate Features](https://docs.rs/wasmi/latest/wasmi/#crate-features): learn about `wasmi` crate features. +- [📖 Usage Guide](./docs/usage.md): learn how to use the [Wasmi API](https://crates.io/crates/wasmi) properly. +- [🛠️ Development Guide](./docs/developement.md): learn how to develop for Wasmi. +- [✨ Crate Features](https://docs.rs/wasmi/latest/wasmi/#crate-features): learn about `wasmi` crate features. ## WebAssembly Features From cd643d2028a371005ff18c657549c61f659f53f1 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:54:54 +0200 Subject: [PATCH 08/10] add Compiler word --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7d93500675..78518a4d91 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Wasmi is suitable for safety critical use cases and has been audited several tim - Simple, correct and deterministic execution of WebAssembly. - Low-overhead and cross-platform WebAssembly runtime for embedded environments. -- JIT bomb resisting translation. +- Compiler/JIT bomb resisting translation. - Loosely mirrors the [Wasmtime API](https://docs.rs/wasmtime/). - 100% WebAssembly spec testsuite compliance. - Built-in support for fuel metering. From 918b2e9d589e861b4e5b37ac4f3b4897faa3f9e9 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:56:24 +0200 Subject: [PATCH 09/10] exclude emojies from links --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 78518a4d91..a08d723ddb 100644 --- a/README.md +++ b/README.md @@ -50,9 +50,9 @@ Wasmi is suitable for safety critical use cases and has been audited several tim ## Docs -- [📖 Usage Guide](./docs/usage.md): learn how to use the [Wasmi API](https://crates.io/crates/wasmi) properly. -- [🛠️ Development Guide](./docs/developement.md): learn how to develop for Wasmi. -- [✨ Crate Features](https://docs.rs/wasmi/latest/wasmi/#crate-features): learn about `wasmi` crate features. +- 📖 [Usage Guide](./docs/usage.md): learn how to use the [Wasmi API](https://crates.io/crates/wasmi) properly. +- 🛠️ [Development Guide](./docs/developement.md): learn how to develop for Wasmi. +- ✨ [Crate Features](https://docs.rs/wasmi/latest/wasmi/#crate-features): learn about `wasmi` crate features. ## WebAssembly Features From c9ac2371f77feca4d629881ded937b2e2fef0978 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Mon, 21 Jul 2025 11:57:33 +0200 Subject: [PATCH 10/10] use https instead of http --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a08d723ddb..d0bee85053 100644 --- a/README.md +++ b/README.md @@ -128,8 +128,8 @@ Wasmi supports a wide variety of architectures and platforms. Licensed under either of - * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or ) - * MIT license ([LICENSE-MIT](LICENSE-MIT) or ) + * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or ) + * MIT license ([LICENSE-MIT](LICENSE-MIT) or ) at your option.