Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions docs/develop/c/exception_handling.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
sidebar_position: 6
---

# Exception Handling

WasmEdge implements the [latest exception-handling proposal](https://github.com/WebAssembly/exception-handling) (post Oct 2023). Legacy EH instructions such as `delegate` are rejected at load time.

Enable the proposal when running or compiling:

```bash
wasmedge --enable-exception-handling module.wasm
wasmedge compile --enable-exception-handling module.wasm module.aot.wasm
```

## Toolchain compatibility

| Toolchain | Version | Compatible | Notes |
|-----------|---------|------------|-------|
| WasmEdge (runtime) | 0.17.x | Yes | Latest EH proposal; use `--enable-exception-handling` |
| Emscripten (`-fwasm-exceptions`) | 3.1.64, 6.0.0 | No | Emits legacy EH (e.g. opcode `0x117` / `delegate`) |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just want to confirm: is there currently no toolchain supporting the final EH proposal?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hydai Based on what we verified for this page:

  • Emscripten 3.1.64 and 6.0.0 with -fwasm-exceptions still emit legacy EH (e.g. delegate / opcode 0x117) and fail to load on WasmEdge 0.17.x.
  • WasmEdge’s EH support is validated via the wasm-3.0-exceptions suite in wasmedge-spectest, not via a C/C++ toolchain.

So for the toolchains listed here: we have not verified a public C/C++ toolchain that emits the final EH proposal and runs successfully on WasmEdge.

There may be opt-in flags (e.g. Emscripten -sWASM_LEGACY_EXCEPTIONS=0, or wasi-sdk with -mllvm -wasm-use-legacy-eh=false) that emit the final proposal, but those were not tested in this PR. Happy to add a short “not verified / opt-in flags may exist” note if you prefer, or to test a specific toolchain/version you recommend.

| `wasm-3.0-exceptions` spec tests | wasmedge-spectest | Yes | Official test inputs used by WasmEdge CI |

WasmEdge does not plan to support legacy EH. Use modules built for the current proposal only.

## How WasmEdge tests EH

CI runs the `wasm-3.0-exceptions` suite from [wasmedge-spectest](https://github.com/WasmEdge/wasmedge-spectest). See `test/spec/CMakeLists.txt` in the [WasmEdge](https://github.com/WasmEdge/WasmEdge) repository.

To run a spec test locally after building tests, or fetch a `.wasm` from that repository:

```bash
wasmedge --enable-exception-handling path/to/test.wasm
```

## Emscripten repro (expected failure today)

`a.cpp`:

```cpp
#include <stdio.h>

int main() {
try {
puts("throw...");
throw 1;
puts("(never reached)");
} catch (...) {
puts("catch!");
}
return 0;
}
```

```bash
emcc -O1 -fwasm-exceptions -sSTANDALONE_WASM a.cpp -o a.wasm
wasmedge --enable-exception-handling a.wasm
```

Typical error: `loading failed: illegal opcode, Code: 0x117` (`Deprecated delegate instruction`).