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

• Complete the Design (Jan 2022)
• Implement and Manually Test the Classic Interpreter (estimated Feb 2022)
• Push to git branch dev/exce_handling
• Peer review code for the Classic Interpreter
• Investigate implementation within JIT and AOT and determine feasibility/effort
• Possibly implement within JIT and AOT
• Integrate tests into WAMR test scripts and CI
• Push to git branch dev/exce_handling
• 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.