From 11b5984412b662c186ec626c99c8fadcab9594f9 Mon Sep 17 00:00:00 2001 From: YE-YU LIN Date: Wed, 11 Nov 2026 16:56:02 +0800 Subject: [PATCH] docs: document the Wide Arithmetic proposal List the --enable-wide-arithmetic flag on the wasmedge, parse, validate, instantiate and compile CLI pages, after --enable-threads to match the order in include/driver/options.h. Add the proposal to the WebAssembly proposals table and add a guide page with CLI, AOT and C API examples. Assisted-by: Claude (Anthropic) Assisted-by: OpenAI Codex Signed-off-by: YE-YU LIN --- docs/start/build-and-run/aot.md | 1 + docs/start/build-and-run/cli.md | 1 + docs/start/build-and-run/instantiate.md | 1 + docs/start/build-and-run/parse.md | 1 + docs/start/build-and-run/validate.md | 1 + docs/start/wasmedge/extensions/proposals.md | 2 + .../wasmedge/extensions/wide-arithmetic.md | 97 +++++++++++++++++++ 7 files changed, 104 insertions(+) create mode 100644 docs/start/wasmedge/extensions/wide-arithmetic.md diff --git a/docs/start/build-and-run/aot.md b/docs/start/build-and-run/aot.md index 2af9f0929..a8c8922a5 100644 --- a/docs/start/build-and-run/aot.md +++ b/docs/start/build-and-run/aot.md @@ -68,6 +68,7 @@ The options of the `wasmedge compile` command are as follows. - Use `--disable-exception-handling` to disable the [Exception Handling](https://github.com/WebAssembly/exception-handling) proposal (Default `ON`). - Use `--disable-memory64` to disable the [Memory64](https://github.com/WebAssembly/memory64) proposal (Default `ON`). - Use `--enable-threads` to enable the [Threads](https://github.com/webassembly/threads) proposal (Default `OFF`). + - Use `--enable-wide-arithmetic` to enable the [Wide Arithmetic](https://github.com/WebAssembly/wide-arithmetic) proposal (Default `OFF`). - Use `--enable-all` to enable ALL proposals above. 7. _(Optional)_ `--optimize`: Select the LLVM optimization level. - Use `--optimize LEVEL` to set the optimization level. The `LEVEL` should be one of `0`, `1`, `2`, `3`, `s`, or `z`. diff --git a/docs/start/build-and-run/cli.md b/docs/start/build-and-run/cli.md index 1a50c37a0..55580f056 100644 --- a/docs/start/build-and-run/cli.md +++ b/docs/start/build-and-run/cli.md @@ -121,6 +121,7 @@ The options of the `wasmedge` CLI tool are as follows: - Use `--disable-exception-handling` to disable the [Exception Handling](https://github.com/WebAssembly/exception-handling) proposal (Default `ON`). - Use `--disable-memory64` to disable the [Memory64](https://github.com/WebAssembly/memory64) proposal (Default `ON`). - Use `--enable-threads` to enable the [Threads](https://github.com/webassembly/threads) proposal (Default `OFF`). + - Use `--enable-wide-arithmetic` to enable the [Wide Arithmetic](https://github.com/WebAssembly/wide-arithmetic) proposal (Default `OFF`). - Use `--enable-component` to enable the [Component Model](https://github.com/WebAssembly/component-model) proposal (Default `OFF`, loader and validator phase only). - Use `--enable-all` to enable ALL proposals above. 11. _(Optional)_ Other options: diff --git a/docs/start/build-and-run/instantiate.md b/docs/start/build-and-run/instantiate.md index 3e77fca76..457f96a97 100644 --- a/docs/start/build-and-run/instantiate.md +++ b/docs/start/build-and-run/instantiate.md @@ -66,6 +66,7 @@ The options of the `wasmedge instantiate` command are as follows. - Use `--disable-exception-handling` to disable the [Exception Handling](https://github.com/WebAssembly/exception-handling) proposal (Default `ON`). - Use `--disable-memory64` to disable the [Memory64](https://github.com/WebAssembly/memory64) proposal (Default `ON`). - Use `--enable-threads` to enable the [Threads](https://github.com/webassembly/threads) proposal (Default `OFF`). + - Use `--enable-wide-arithmetic` to enable the [Wide Arithmetic](https://github.com/WebAssembly/wide-arithmetic) proposal (Default `OFF`). - Use `--enable-component` to enable the [Component Model](https://github.com/WebAssembly/component-model) proposal (Default `OFF`, loader phase only). - Use `--enable-all` to enable ALL proposals above. 9. Input WASM file (`/path/to/wasm/file`). diff --git a/docs/start/build-and-run/parse.md b/docs/start/build-and-run/parse.md index 51bddcfc7..84786f452 100644 --- a/docs/start/build-and-run/parse.md +++ b/docs/start/build-and-run/parse.md @@ -58,6 +58,7 @@ The options of the `wasmedge parse` command are as follows. - Use `--disable-exception-handling` to disable the [Exception Handling](https://github.com/WebAssembly/exception-handling) proposal (Default `ON`). - Use `--disable-memory64` to disable the [Memory64](https://github.com/WebAssembly/memory64) proposal (Default `ON`). - Use `--enable-threads` to enable the [Threads](https://github.com/webassembly/threads) proposal (Default `OFF`). + - Use `--enable-wide-arithmetic` to enable the [Wide Arithmetic](https://github.com/WebAssembly/wide-arithmetic) proposal (Default `OFF`). - Use `--enable-component` to enable the [Component Model](https://github.com/WebAssembly/component-model) proposal (Default `OFF`, loader phase only). - Use `--enable-all` to enable ALL proposals above. 5. Input WASM file (`/path/to/wasm/file`). diff --git a/docs/start/build-and-run/validate.md b/docs/start/build-and-run/validate.md index 457a2fa68..cf5769b4b 100644 --- a/docs/start/build-and-run/validate.md +++ b/docs/start/build-and-run/validate.md @@ -58,6 +58,7 @@ The options of the `wasmedge validate` command are as follows. - Use `--disable-exception-handling` to disable the [Exception Handling](https://github.com/WebAssembly/exception-handling) proposal (Default `ON`). - Use `--disable-memory64` to disable the [Memory64](https://github.com/WebAssembly/memory64) proposal (Default `ON`). - Use `--enable-threads` to enable the [Threads](https://github.com/webassembly/threads) proposal (Default `OFF`). + - Use `--enable-wide-arithmetic` to enable the [Wide Arithmetic](https://github.com/WebAssembly/wide-arithmetic) proposal (Default `OFF`). - Use `--enable-component` to enable the [Component Model](https://github.com/WebAssembly/component-model) proposal (Default `OFF`, loader phase only). - Use `--enable-all` to enable ALL proposals above. 5. Input WASM file (`/path/to/wasm/file`). diff --git a/docs/start/wasmedge/extensions/proposals.md b/docs/start/wasmedge/extensions/proposals.md index 96fd73ede..bc0e3b323 100644 --- a/docs/start/wasmedge/extensions/proposals.md +++ b/docs/start/wasmedge/extensions/proposals.md @@ -26,6 +26,7 @@ WasmEdge supports the following [WebAssembly proposals](https://github.com/WebAs | [Exception handling][] | `--disable-exception-handling` | `WasmEdge_Proposal_ExceptionHandling` | ✓ (since `0.16.0`) | ✓ (since `0.14.0`) | ✓ (since `0.18.0`) | | [Memory64][] | `--disable-memory64` | `WasmEdge_Proposal_Memory64` | ✓ (since `0.17.0`) | ✓ (since `0.17.0`) | ✓ (since `0.17.0`) | | [Threads][] | `--enable-threads` | `WasmEdge_Proposal_Threads` | | ✓ (since `0.10.1`) | ✓ (since `0.10.1`) | +| [Wide Arithmetic][] | `--enable-wide-arithmetic` | `WasmEdge_Proposal_WideArithmetic` | | ✓ (since `0.19.0`) | ✓ (since `0.19.0`) | | [Component Model][] | `--enable-component` | `WasmEdge_Proposal_Component` | | Loader and validator (since `0.17.0`) | | Besides the proposals above, WasmEdge implements the [WebAssembly C and C++ API][] (`wasm.h` and `wasm.hh`) in the WasmEdge shared library since `0.18.0`, in parallel with the [WasmEdge C API](../../../embed/c/intro.md). @@ -47,6 +48,7 @@ Besides the proposals above, WasmEdge implements the [WebAssembly C and C++ API] [Garbage collection]: https://github.com/WebAssembly/gc [Relaxed SIMD]: https://github.com/WebAssembly/relaxed-simd [Memory64]: https://github.com/WebAssembly/memory64 +[Wide Arithmetic]: https://github.com/WebAssembly/wide-arithmetic [WebAssembly C and C++ API]: https://github.com/WebAssembly/wasm-c-api ## WASI proposals diff --git a/docs/start/wasmedge/extensions/wide-arithmetic.md b/docs/start/wasmedge/extensions/wide-arithmetic.md new file mode 100644 index 000000000..cb53cad32 --- /dev/null +++ b/docs/start/wasmedge/extensions/wide-arithmetic.md @@ -0,0 +1,97 @@ +--- +sidebar_position: 5 +--- + +# Wide Arithmetic + +WasmEdge supports the [WebAssembly Wide Arithmetic proposal](https://github.com/WebAssembly/wide-arithmetic) starting from version `0.19.0`. The proposal adds instructions that produce 128-bit results from 64-bit values, which helps big-integer and cryptography code avoid emulating carries and wide products with several instructions. + +## What is Wide Arithmetic? + +The proposal does not add an `i128` type. A 128-bit value is passed as two `i64` values: the low half followed by the high half. + +| Instruction | Inputs | Results | +| --- | --- | --- | +| `i64.add128` | `lhs_lo lhs_hi rhs_lo rhs_hi` | `lo hi` | +| `i64.sub128` | `lhs_lo lhs_hi rhs_lo rhs_hi` | `lo hi` | +| `i64.mul_wide_s` | `lhs rhs` | `lo hi` | +| `i64.mul_wide_u` | `lhs rhs` | `lo hi` | + +`i64.add128` and `i64.sub128` wrap around modulo 2^128. `i64.mul_wide_s` and `i64.mul_wide_u` return the full 128-bit product of two signed or unsigned 64-bit values. + +The proposal is disabled by default. Enable it with the `--enable-wide-arithmetic` flag. The `--enable-all` flag also enables it. + +## Prerequisites + +- WasmEdge `0.19.0` or later. See the [installation guide](https://github.com/WasmEdge/docs/blob/main/docs/start/install.md). +- [`wasm-tools`](https://github.com/bytecodealliance/wasm-tools), to compile `.wat` source files to `.wasm`. See the [Garbage Collection guide](gc.md#prerequisites) for installation steps. + +## Example + +Create a file called `wide.wat`: + +```wasm +(module + (func (export "add128") (param i64 i64 i64 i64) (result i64 i64) + (i64.add128 (local.get 0) (local.get 1) (local.get 2) (local.get 3))) + (func (export "mul_wide_u") (param i64 i64) (result i64 i64) + (i64.mul_wide_u (local.get 0) (local.get 1)))) +``` + +Compile it to a `.wasm` binary: + +```bash +wasm-tools parse wide.wat -o wide.wasm +``` + +Add `0xFFFFFFFFFFFFFFFF` (passed as `-1`) and `1`. The low half overflows to `0` and the carry goes to the high half: + +```bash +wasmedge --enable-wide-arithmetic --reactor wide.wasm add128 -1 0 1 0 +``` + +Expected output: + +``` +0 +1 +``` + +Multiply `0xFFFFFFFFFFFFFFFF` by `2` as unsigned values: + +```bash +wasmedge --enable-wide-arithmetic --reactor wide.wasm mul_wide_u -1 2 +``` + +Expected output: + +``` +-2 +1 +``` + +The CLI prints each `i64` result as a signed decimal number, so the low half `0xFFFFFFFFFFFFFFFE` is shown as `-2`. + +Without the flag, WasmEdge rejects the module when loading it: + +```bash +wasmedge --reactor wide.wasm add128 -1 0 1 0 +``` + +## AOT Compilation + +Pass the flag when compiling the module: + +```bash +wasmedge compile --enable-wide-arithmetic wide.wasm wide_aot.wasm +wasmedge --enable-wide-arithmetic --run-mode=aot --reactor wide_aot.wasm add128 -1 0 1 0 +``` + +## C API + +To enable Wide Arithmetic programmatically via the WasmEdge C API, use the `WasmEdge_Proposal_WideArithmetic` enumeration value: + +```c +WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate(); +WasmEdge_ConfigureAddProposal(ConfCxt, WasmEdge_Proposal_WideArithmetic); +```