From fbe5720e585a9168099db72ff82c21da7de965b9 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Thu, 27 Mar 2025 11:56:44 +0100 Subject: [PATCH 1/8] remove unnecessary README infos --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index 7fc92ca8e8..1e5eadbb2c 100644 --- a/README.md +++ b/README.md @@ -40,8 +40,6 @@ Wasmi is suitable for safety critical use cases and has been audited several tim ## Distinct Features -The following list states some of the distinct features of Wasmi. - - Simple, correct and deterministic execution of WebAssembly. - Low-overhead and cross-platform WebAssembly runtime for embedded environments. - JIT bomb resisting translation. @@ -56,8 +54,6 @@ Refer to the [Wasmi usage guide](./docs/usage.md) to learn how properly to use [ ## WebAssembly Proposals -The new Wasmi engine supports a variety of WebAssembly proposals and will support even more of them in the future. - | | WebAssembly Proposal | | |:-:|:--|:--| | ✅ | [`mutable-global`] | ≥ `0.14.0` | From fa1100deffcb74aa23cc23542cd2bbdb4a4b08db Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Thu, 27 Mar 2025 12:04:43 +0100 Subject: [PATCH 2/8] readme: add section about Wasmi crate features --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 1e5eadbb2c..c40c6851bf 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,16 @@ Refer to the [Wasmi usage guide](./docs/usage.md) to learn how properly to use [ [(#1364)]: https://github.com/wasmi-labs/wasmi/issues/1364 [(#1369)]: https://github.com/wasmi-labs/wasmi/issues/1369 +## Crate Features + +| Proposal | Wasmi 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. | +| `wat` | `wasmi` | Enables support to parse Wat encoded Wasm modules. | +| `simd` | `wasmi`, `wasmi_core`, `wasmi_ir`, `wasmi_cli` | Enables support for the Wasm `simd` proposal. Note that this may introduce execution overhead and increased memory consumption for Wasm executions that do not need Wasm `simd` functionality. | +| `hash-collections` | `wasmi`, `wasmi_collections` | Enables use of hash-map based collections in Wasmi internals. This might yield performance improvements in some use cases. | +| `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. | + ## Development ### Build & Test From 3df4d0f4692fa05b8939f39e7c17e9747116a4fc Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Thu, 27 Mar 2025 12:05:30 +0100 Subject: [PATCH 3/8] readme: restructure Wasm proposals section --- README.md | 41 +++++++++++++++++------------------------ 1 file changed, 17 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index c40c6851bf..b2a669ecee 100644 --- a/README.md +++ b/README.md @@ -52,31 +52,24 @@ Wasmi is suitable for safety critical use cases and has been audited several tim Refer to the [Wasmi usage guide](./docs/usage.md) to learn how properly to use [Wasmi](https://crates.io/crates/wasmi). -## WebAssembly Proposals - -| | WebAssembly Proposal | | +## WebAssembly Features + +| | WebAssembly Proposal | | | | WebAssembly Proposal | | +|:-:|:--|:--|:-:|:--|:--|:--| +| ✅ | [`mutable-global`] | ≥ `0.14.0` | | ✅ | [`custom-page-sizes`] | [≥ `0.41.0`][(#1197)] | +| ✅ | [`saturating-float-to-int`] | ≥ `0.14.0` | | ✅ | [`memory64`] | [≥ `0.41.0`][(#1357)] | +| ✅ | [`sign-extension`] | ≥ `0.14.0` | | ✅ | [`wide-arithmetic`] | [≥ `0.42.0`][(#1369)] | +| ✅ | [`multi-value`] | ≥ `0.14.0` | | ✅ | [`simd`] | [≥ `0.43.0`][(#1364)] | +| ✅ | [`bulk-memory`] | [≥ `0.24.0`][(#628)] | | 📅 | [`relaxed-simd`] | Depends on `simd`. | +| ✅ | [`reference-types`] | [≥ `0.24.0`][(#635)] | | 📅 | [`function-references`] | [Tracking Issue][(#774)] | +| ✅ | [`tail-calls`] | [≥ `0.28.0`][(#683)] | | 📅 | [`gc`] | [Tracking Issue][(#775)] | +| ✅ | [`extended-const`] | [≥ `0.29.0`][(#707)] | | 📅 | [`threads`] | [Tracking Issue][(#777)] | +| ✅ | [`multi-memory`] | [≥ `0.37.0`][(#1191)] | | 📅 | [`exception-handling`] | [Tracking Issue][(#1037)] | + +| | Embeddings | | |:-:|:--|:--| -| ✅ | [`mutable-global`] | ≥ `0.14.0` | -| ✅ | [`saturating-float-to-int`] | ≥ `0.14.0` | -| ✅ | [`sign-extension`] | ≥ `0.14.0` | -| ✅ | [`multi-value`] | ≥ `0.14.0` | -| ✅ | [`bulk-memory`] | [≥ `0.24.0`][(#628)] | -| ✅ | [`reference-types`] | [≥ `0.24.0`][(#635)] | -| ✅ | [`tail-calls`] | [≥ `0.28.0`][(#683)] | -| ✅ | [`extended-const`] | [≥ `0.29.0`][(#707)] | -| ✅ | [`multi-memory`] | [≥ `0.37.0`][(#1191)] | -| ✅ | [`custom-page-sizes`] | [≥ `0.41.0`][(#1197)] | -| ✅ | [`memory64`] | [≥ `0.41.0`][(#1357)] | -| ✅ | [`wide-arithmetic`] | [≥ `0.42.0`][(#1369)] | -| 📅 | [`simd`] | [Tracking Issue][(#1364)] | -| 📅 | [`relaxed-simd`] | Depends on `simd`. | -| 📅 | [`function-references`] | [Tracking Issue][(#774)] | -| 📅 | [`gc`] | [Tracking Issue][(#775)] | -| 📅 | [`threads`] | [Tracking Issue][(#777)] | -| 📅 | [`exception-handling`] | [Tracking Issue][(#1037)] | -| | | -| 👨‍🔬 | [WASI] | WASI (`wasip1`) support via the [`wasmi_wasi` crate]. | -| 👨‍🔬 | [C-API] | Official Wasm C-API support via the [`wasmi_c_api_impl` crate]. | +| ✅ | [WASI] | WASI (`wasip1`) support via the [`wasmi_wasi` crate]. | +| ✅ | [C-API] | Official Wasm C-API support via the [`wasmi_c_api_impl` crate]. | [`mutable-global`]: https://github.com/WebAssembly/mutable-global [`saturating-float-to-int`]: https://github.com/WebAssembly/nontrapping-float-to-int-conversions From 4a793f9f8de868e53dfe4b2d28bbf40fea315a20 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Thu, 27 Mar 2025 12:05:48 +0100 Subject: [PATCH 4/8] add Wasmi crate feature sections to docs --- crates/wasmi/src/lib.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/crates/wasmi/src/lib.rs b/crates/wasmi/src/lib.rs index d200060851..9f0726ed85 100644 --- a/crates/wasmi/src/lib.rs +++ b/crates/wasmi/src/lib.rs @@ -58,6 +58,17 @@ //! Ok(()) //! } //! ``` +//! +//! # Crate Features +//! +//! | Proposal | Wasmi 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. | +//! | `wat` | `wasmi` | Enables support to parse Wat encoded Wasm modules. | +//! | `simd` | `wasmi`, `wasmi_core`, `wasmi_ir`, `wasmi_cli` | Enables support for the Wasm `simd` proposal. Note that this may introduce execution overhead and increased memory consumption for Wasm executions that do not need Wasm `simd` functionality. | +//! | `hash-collections` | `wasmi`, `wasmi_collections` | Enables use of hash-map based collections in Wasmi internals. This might yield performance improvements in some use cases. | +//! | `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. | + #![no_std] #![warn( From 9f73974e7b1de4979c365300b1dda710ac3c2cc5 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Thu, 27 Mar 2025 12:12:48 +0100 Subject: [PATCH 5/8] improve crate feature section in readme and docs --- README.md | 13 +++++++------ crates/wasmi/src/lib.rs | 14 +++++++------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index b2a669ecee..c2abaf84a9 100644 --- a/README.md +++ b/README.md @@ -116,13 +116,14 @@ Refer to the [Wasmi usage guide](./docs/usage.md) to learn how properly to use [ ## Crate Features -| Proposal | Wasmi Crates | Description | +| 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. | -| `wat` | `wasmi` | Enables support to parse Wat encoded Wasm modules. | -| `simd` | `wasmi`, `wasmi_core`, `wasmi_ir`, `wasmi_cli` | Enables support for the Wasm `simd` proposal. Note that this may introduce execution overhead and increased memory consumption for Wasm executions that do not need Wasm `simd` functionality. | -| `hash-collections` | `wasmi`, `wasmi_collections` | Enables use of hash-map based collections in Wasmi internals. This might yield performance improvements in some use cases. | -| `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. | +| `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` proposal. 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 diff --git a/crates/wasmi/src/lib.rs b/crates/wasmi/src/lib.rs index 9f0726ed85..cf18d8fa1d 100644 --- a/crates/wasmi/src/lib.rs +++ b/crates/wasmi/src/lib.rs @@ -61,14 +61,14 @@ //! //! # Crate Features //! -//! | Proposal | Wasmi Crates | Description | +//! | 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. | -//! | `wat` | `wasmi` | Enables support to parse Wat encoded Wasm modules. | -//! | `simd` | `wasmi`, `wasmi_core`, `wasmi_ir`, `wasmi_cli` | Enables support for the Wasm `simd` proposal. Note that this may introduce execution overhead and increased memory consumption for Wasm executions that do not need Wasm `simd` functionality. | -//! | `hash-collections` | `wasmi`, `wasmi_collections` | Enables use of hash-map based collections in Wasmi internals. This might yield performance improvements in some use cases. | -//! | `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. | - +//! | `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` proposal. 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. | #![no_std] #![warn( From 68922504f10b169839aee8a532e6831cb0533a23 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Thu, 27 Mar 2025 12:14:05 +0100 Subject: [PATCH 6/8] apply rustfmt --- crates/wasmi/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/wasmi/src/lib.rs b/crates/wasmi/src/lib.rs index cf18d8fa1d..4583653e16 100644 --- a/crates/wasmi/src/lib.rs +++ b/crates/wasmi/src/lib.rs @@ -58,9 +58,9 @@ //! Ok(()) //! } //! ``` -//! +//! //! # 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. | From 45c73ce5a49cfa3d87eda8889ad4d99e99b5a8a3 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Thu, 27 Mar 2025 12:22:27 +0100 Subject: [PATCH 7/8] add tracking issue for Wasm relaxed-simd proposal --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c2abaf84a9..c5987b2cca 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ Refer to the [Wasmi usage guide](./docs/usage.md) to learn how properly to use [ | ✅ | [`saturating-float-to-int`] | ≥ `0.14.0` | | ✅ | [`memory64`] | [≥ `0.41.0`][(#1357)] | | ✅ | [`sign-extension`] | ≥ `0.14.0` | | ✅ | [`wide-arithmetic`] | [≥ `0.42.0`][(#1369)] | | ✅ | [`multi-value`] | ≥ `0.14.0` | | ✅ | [`simd`] | [≥ `0.43.0`][(#1364)] | -| ✅ | [`bulk-memory`] | [≥ `0.24.0`][(#628)] | | 📅 | [`relaxed-simd`] | Depends on `simd`. | +| ✅ | [`bulk-memory`] | [≥ `0.24.0`][(#628)] | | 📅 | [`relaxed-simd`] | [Tracking Issue][(#1431)] | | ✅ | [`reference-types`] | [≥ `0.24.0`][(#635)] | | 📅 | [`function-references`] | [Tracking Issue][(#774)] | | ✅ | [`tail-calls`] | [≥ `0.28.0`][(#683)] | | 📅 | [`gc`] | [Tracking Issue][(#775)] | | ✅ | [`extended-const`] | [≥ `0.29.0`][(#707)] | | 📅 | [`threads`] | [Tracking Issue][(#777)] | @@ -113,6 +113,7 @@ Refer to the [Wasmi usage guide](./docs/usage.md) to learn how properly to use [ [(#1357)]: https://github.com/wasmi-labs/wasmi/issues/1357 [(#1364)]: https://github.com/wasmi-labs/wasmi/issues/1364 [(#1369)]: https://github.com/wasmi-labs/wasmi/issues/1369 +[(#1431)]: https://github.com/wasmi-labs/wasmi/issues/1431 ## Crate Features From 39bcdf3efca748d3ed005fb856fffe5f07c5d9f2 Mon Sep 17 00:00:00 2001 From: Robin Freyler Date: Thu, 27 Mar 2025 12:26:55 +0100 Subject: [PATCH 8/8] render docs of crates with `simd` feature enabled --- crates/ir/Cargo.toml | 3 +++ crates/wasmi/Cargo.toml | 3 +++ 2 files changed, 6 insertions(+) diff --git a/crates/ir/Cargo.toml b/crates/ir/Cargo.toml index 6e477c71c9..82cf659c88 100644 --- a/crates/ir/Cargo.toml +++ b/crates/ir/Cargo.toml @@ -27,3 +27,6 @@ std = [ "wasmi_core/std", ] simd = ["wasmi_core/simd"] + +[package.metadata.docs.rs] +features = ["std", "simd"] diff --git a/crates/wasmi/Cargo.toml b/crates/wasmi/Cargo.toml index 3fe900dad1..eab447b783 100644 --- a/crates/wasmi/Cargo.toml +++ b/crates/wasmi/Cargo.toml @@ -72,3 +72,6 @@ extra-checks = [] [[bench]] name = "benches" harness = false + +[package.metadata.docs.rs] +features = ["std", "wat", "simd"]