Adding Support for Exception Handling

[woodsmc]

This issue has been created to track the implementation of exception handling support. This is based on the:

1. Exception proposal.
2. Exception WASM Specification.

Current Status

Exception handling is currently supported by Web browsers and the Emscripten compiler tool chain, but at the time of writing there isn't support for the exception handling in WAMR. Indeed exception handling in general appears to be missing from many non-browser based runtimes.

Current Focus

This work focuses on the addition of support for exception handling in the WAMR runtime. It excludes work on language run times (e.g. C++ RT), and compiler tool chains. It is assumed that this work has already been completed, see current status above and Emscripten's existing support.

Plan

Source Control Guidance - Working Branch

Implementation will be done on a git branch, dev/exce_handling. When the code on this branch is stable and the necessary quality bar and tests have passed then, this branch will be peer reviewed and merged into the main branch.

Feature Switch for Exception Handling

The feature will be developed with a switch, enabling it to be turned on / off. This feature switch is WAMR_BUILD_EXCE_HANDLING and can be enabled by specifying the following at the command line:

    cmake -DWAMR_BUILD_EXCE_HANDLING=1

This can be turned on / off within build-scripts or defined in config_common.cmake.

This means that the code base will use the WASM_ENABLE_EXCE_HANDLING C macro to control the feature in code, e.g.

    #ifdef WASM_ENABLE_EXCE_HANDLING
    // Feature implementatation here
    // ... 
    // ...
    #endif // WASM_ENABLE_EXCE_HANDLING

Approach

The proposal breaks down adding exception handling into three key steps, each step reflecting execution style used by WAMR.

• Step 1 : The initial focus will be on the fully interpreted mode, it will deliberatly exclude any JIT implementations. This allows us to ensure that the implementation is correct and behaves as expected.
• Step 2 : Once Step 1 is completed, Step 2 will start. This is focused on the Fast JIT and LLVM JIT implementation. At the moment this is considered out of scope.
• Step 3 : The final step focuses on the AOT implementation, ensuring that the behaviour and performance is a expected. At the moment this is considered out of scope.

At the time of writing focus is only on Step 1.

Step 1 Task Breakdown

• [x] Complete the Design (Jan 2022)
• [x] Implement and Manually Test the Classic Interpreter (estimated Feb 2022)
• [x] Push to git branch dev/exce_handling
• [x] Peer review code for the Classic Interpreter
• [x] Investigate implementation within JIT and AOT and determine feasibility/effort
• [ ] Possibly implement within JIT and AOT
• [x] Integrate tests into WAMR test scripts and CI
• [x] Push to git branch dev/exce_handling
• [x] Update documentation and push to git branch dev/exce_handling
• [ ] Peer review code and tests and update as needed
• [ ] Merge to main branch once complete

Design

• The new Tag section will be parsed and stored, the new opcodes (try, catch, catch_all, delegate, throw, rethrow) will be added to the code.
• The new opcodes will be handled somewhat similarly to the if/block/loop/else opcodes, with a new label type for the "try".
• Exceptions are already "caught" in the current WAMR code in that a common method is now called when they occur due to executing op code
• Modification to the design will be needed to determine if within a try block, with the ability to search up through nested try blocks. If there is a catch, the enclosing label from the catch will be searched for and the stack shifted to that location.
• An additional modification to the existing WAMR exception handling is that the current strings used for exceptions will have to become a more easily matched type or enumeration.

Implementation

• Implementation will start with the parsing
• Interested parties are welcome to assist

Compatibility

See Open Questions (below).. .

Test

• The spec cases in the spec proposal must pass: https://github.com/WebAssembly/exception-handling/tree/main/test/core

• Once these tests pass manually, they will then need to be integrated into the existing WAMR scripted tests

• See also LLVM tests for Exceptions such as llvm-project\lldb\test\API\lang\cpp\exceptions\exceptions.cpp and in \llvm-project\clang-tools-extra\test\clang-tidy\checkers\bugprone

Open Questions

• The specification (documentation) is not clear, it currently has text which says "todo" (see below), can the authors provide any additional clarity?

  Todo
  Add prose for the following execution steps.
  (...)
  Todo
  Add explainer note.

• When a catch is meant to catch just a specific type of exception mapping to the specific catch of that type might still be problematic, e.g. how to map from the "integer overflow" string in WAMR to a C++ std::overflow_error exception type and match that up to specific catch in the WASI bytecode - this has not yet been prototyped.

• What other sources for C++ Exception examples exist?

• What level of testing is appropriate for languages other than C++? - Was this addressed by the previous browser implementations?

• Compiling to WASM with Emscripten using -fwasm-exceptions and compiling with clang++ using -fwasm-exceptions produces different results; why ?

• Attempts to compile code with exceptions using the WASI SDK result in linker errors. It appears as if the C++ runtime used by WASI SDK excludes the functions necessary for correct handling of exceptions. Why is this the case? Are we just missing a linker statement to include an exception handling C++ RT library? Or is the C++ exception handling library simply missing from the WASI C++

• For compatibility purposes it should be possible to build WASM binaries using Emscripten and execute these within the WAMR runtime. Initial investigation shows additional function links between the Emscripten WASM binary and the browser runtime. TASK: We should double check to ensure that no additional interdependcies exists.

• Future Question (out of scope - for Step 3) : AOT will need to be implemented differently than the interpreter for handling the exceptions

[shenlongxing]

Is there any new progress?

[woodsmc]

I apologize for the radio silence. Yes, we've made considerable progress and will post a design document next week (I'll add to this issue). An initial contribution to the exception branch is expected within the next two weeks.

[woodsmc]

The approach as outlined originally (above) changed somewhat. Focusing on the unclear specifications we worked on trying to provide clarity. This resulted in a light weight, WAMR specific specification document, we called this a Spec-Let.

Following this we worked on what the implementation should be, this resulted in another document a light weight design document, we called this a Design-Let.

The aim is to provide our implementation and code along with the spec-let and design-let documents. As mentioned above, the documentation should come next week, and the code within, probably, the next two weeks.

[raguilar755]

We concluded with PART2 of exception handling implementation. This contribution includes the following behavior: Inside the classic interpreter only:

• Implementation of [exception] tags: loading of import and export tags
• Implementation of dynamic runtime for loading imported and exported tags, and exception handling.
• Updates to the classic interpreter to use the tag instances structure.
• Core tests successfully executed, related to EH: throw.wast, tag.wast, try_catch.wast, try_delegate.wast, and rethrow.wast
• Bug fixes and naming convention improvements
• Additional CI /CD changes to validate ENABLE_EXCE_HANDLING switch builds

A PR #2683 has been generated to be accepted in the dev/exce_handling branch.

[woodsmc]

Since this issue has been created, a new approach to exception handling was adopted by the CG - Extern Ref B-Prime . This requires some additional reworking of the runtime to be supported.

[fredldotme]

I've been trying to get exception support into my forks of LLVM 17, WASI SDK & WAMR, pretty much everything should be in place (including libunwind enablement) and Clang is successfully able to create WASM-EH binaries.

When run using WAMR it always fails at "unknown label" during load time, no matter the platform. Any hints would be greatly appreciated, it's for my Tide IDE (for iPadOS as well as macOS & Linux).

EDIT: To add more context, it is also possible to wasm2wat the binary back into textual representation, assuming one enables exceptions through --enable-exceptions.

[yamt]

is anyone here working on a new version of the proposal with exnref?

[woodsmc]

I've been trying to get exception support into my forks of LLVM 17, WASI SDK & WAMR, pretty much everything should be in place (including libunwind enablement) and Clang is successfully able to create WASM-EH binaries.

When run using WAMR it always fails at "unknown label" during load time, no matter the platform. Any hints would be greatly appreciated, it's for my Tide IDE (for iPadOS as well as macOS & Linux).

EDIT: To add more context, it is also possible to wasm2wat the binary back into textual representation, assuming one enables exceptions through --enable-exceptions.

At the moment the exception handling support is only available for the fully interpreted mode of WAMR. So that might be the cause, not this means that at the moment the JIT, fast-JIT and AoT implementations of WAMR do not support exception handling (sorry).

[woodsmc]

is anyone here working on a new version of the proposal with exnref?

We've done some initial comparison work, and it looks like the exnref version would be able to mostly use the same code as the existing specification for exception handling, if anything it's a little more streamlined. There are some discussions around implementing this, if you are interested in contributing drop me a note, I'd be happy to share more.

[edit: clarity]

[fredldotme]

I've been trying to get exception support into my forks of LLVM 17, WASI SDK & WAMR, pretty much everything should be in place (including libunwind enablement) and Clang is successfully able to create WASM-EH binaries. When run using WAMR it always fails at "unknown label" during load time, no matter the platform. Any hints would be greatly appreciated, it's for my Tide IDE (for iPadOS as well as macOS & Linux). EDIT: To add more context, it is also possible to wasm2wat the binary back into textual representation, assuming one enables exceptions through --enable-exceptions.

At the moment the exception handling support is only available for the fully interpreted mode of WAMR. So that might be the cause, not this means that at the moment the JIT, fast-JIT and AoT implementations of WAMR do not support exception handling (sorry).

Hey, thanks for the quick response. Yeah I am pretty sure my configurations for my WAMR-based WASM loaders/runners are correct, to compare: the iPadOS/Darwin codepaths are the main target release I personally test with, using wasmrunnerfast and wasmrunner (debug) which should provide compatibility with the flag you probably mean. More here: https://github.com/fredldotme/Tide/tree/main/src/lib

Anyway, I personally believe it is more of an "Clang doesn't support it (anymore) for whatever reason" type of situation. Though my Clang is highly patched too to even run in this environment it completely fulfills the needs of running Clang reliably on the iPad as the main center of attraction in terms of App Store release priority.

Thank you.

[woodsmc]

I've been trying to get exception support into my forks of LLVM 17, WASI SDK & WAMR, pretty much everything should be in place (including libunwind enablement) and Clang is successfully able to create WASM-EH binaries. When run using WAMR it always fails at "unknown label" during load time, no matter the platform. Any hints would be greatly appreciated, it's for my Tide IDE (for iPadOS as well as macOS & Linux). EDIT: To add more context, it is also possible to wasm2wat the binary back into textual representation, assuming one enables exceptions through --enable-exceptions.

At the moment the exception handling support is only available for the fully interpreted mode of WAMR. So that might be the cause, not this means that at the moment the JIT, fast-JIT and AoT implementations of WAMR do not support exception handling (sorry).

Hey, thanks for the quick response. Yeah I am pretty sure my configurations for my WAMR-based WASM loaders/runners are correct, to compare: the iPadOS/Darwin codepaths are the main target release I personally test with, using wasmrunnerfast and wasmrunner (debug) which should provide compatibility with the flag you probably mean. More here: https://github.com/fredldotme/Tide/tree/main/src/lib

Anyway, I personally believe it is more of an "Clang doesn't support it (anymore) for whatever reason" type of situation. Though my Clang is highly patched too to even run in this environment it completely fulfills the needs of running Clang reliably on the iPad as the main center of attraction in terms of App Store release priority.

Thank you.

That is weird. Can I ask you to open an issue with this, and we can take a look ? - We'll need to try to replicate it our side. Thanks!

[fredldotme]

I've been trying to get exception support into my forks of LLVM 17, WASI SDK & WAMR, pretty much everything should be in place (including libunwind enablement) and Clang is successfully able to create WASM-EH binaries.

When run using WAMR it always fails at "unknown label" during load time, no matter the platform. Any hints would be greatly appreciated, it's for my Tide IDE (for iPadOS as well as macOS & Linux).

EDIT: To add more context, it is also possible to wasm2wat the binary back into textual representation, assuming one enables exceptions through --enable-exceptions.

At the moment the exception handling support is only available for the fully interpreted mode of WAMR. So that might be the cause, not this means that at the moment the JIT, fast-JIT and AoT implementations of WAMR do not support exception handling (sorry).

Hey, thanks for the quick response. Yeah I am pretty sure my configurations for my WAMR-based WASM loaders/runners are correct, to compare: the iPadOS/Darwin codepaths are the main target release I personally test with, using wasmrunnerfast and wasmrunner (debug) which should provide compatibility with the flag you probably mean. More here: https://github.com/fredldotme/Tide/tree/main/src/lib

Anyway, I personally believe it is more of an "Clang doesn't support it (anymore) for whatever reason" type of situation. Though my Clang is highly patched too to even run in this environment it completely fulfills the needs of running Clang reliably on the iPad as the main center of attraction in terms of App Store release priority.

Thank you.

That is weird. Can I ask you to open an issue with this, and we can take a look ? - We'll need to try to replicate it our side. Thanks!

Sure, here we go: https://github.com/bytecodealliance/wasm-micro-runtime/issues/3087

[yamt]

When run using WAMR it always fails at "unknown label" during load time, no matter the platform. Any hints would be greatly appreciated, it's for my Tide IDE (for iPadOS as well as macOS & Linux).

i looked at the code on the branch a bit. it's probably loader bug(s).

• it seems that the loader is looking at a wrong block when checking delegate label. (off-by-one calculation because it wrongly counts the try-delegate block itself. if i read the spec correctly, label 0 should be the block surrounding the try-delegate block.)
• it seems that the loader assumes the delegate label points to a try block. as far as i read the spec it's actually ok to be any blocks, including the function exit. llvm-produced code seems using delegate to function exit much.

i guess you can reproduce the issue with:

(module
  (func
    block
      try
      delegate 1
    end
  )
)

[yamt]

There are some discussions around implementing this, if you are interested in contributing drop me a note, I'd be happy to share more.

i'm interested to help.

i think i'm reasonably familiar with the latest EH proposal (try_table etc) because i recently implemented it for other runtime. https://github.com/yamt/toywasm/pull/134 let me share some random notes.

• wabt doesn't support the latest version of the proposal.
  • wasm2wat/wat2wasm doesn't support it yet. for now, you can use wasm-tools instead.
  • wast2json doesn't support it either. https://github.com/WebAssembly/wabt/issues/2374 while we (wamr) don't use it, our equivalent might need an update.
• the latest binaryen has a conversion between old and new EH proposals. https://github.com/WebAssembly/binaryen/pull/6210 it seems working reasonably, at least when converting LLVM-generated bytecode to the new EH.
• i wrote some small/simple tests, which can be used w/o wast stuff. https://github.com/yamt/toywasm/tree/master/wat/eh
• it seems possible to support both of old (try etc) and new (try_table etc) instructions at the same time. is it something we are interested to have?
• wrt migration to the new instructions:
  • in toywasm, i abandoned the old incomplete EH (try) support and added a new one. (try_table)
  • tag import/export stuff was same.
  • the instructions are very different and i had to redo from scratch.
  • the new instructions were much simpler to implement than old ones. i hate the lexical context the old proposal had.
  • it was tricky to implement exnref w/o requiring GC. https://github.com/WebAssembly/exception-handling/issues/287

[loganek]

i'm interested to help.

Hi all, because a few teams are interested in the exception handling support in WAMR, I'll be hosting a meeting 1st of February at 7AM GMT to discuss the next steps. Please contact me directly on Zulip if you want to be invited. @yamt you should already have an invite in your mail box :)