[libunwind][WebAssembly] Support Wasm EH

[aheejin]

Summary

This adds Wasm-specific libunwind port to support Wasm exception
handling (https://github.com/WebAssembly/exception-handling).

Wasm EH requires __USING_WASM_EXCEPTIONS__ to be defined. This adds
Unwind-wasm.c, which defines libunwind APIs for Wasm. This also adds a
thread_local struct of type _Unwind_LandingPadContext, which serves
as a medium for input/output data between the user code and the
personality function. How all these work is explained in
https://github.com/WebAssembly/tool-conventions/blob/main/EHScheme.md.
(The doc is old and "You Shouldn't Prune Unreachable Resumes" section
doesn't apply anymore, but otherwise it should be good)

The bulk of these changes was added back in Mar 2020 in
https://github.com/emscripten-core/emscripten/pull/10577 to emscripten
repo and has been used ever since. Now we'd like to upstream this so
that other toolchains that don't use emscripten libraries, e.g., WASI,
can use this too.

Companion patch: D158918

[dschuff]

Thanks for posting this.
I don't really have any new comments about the code itself (I guess that's not surprising since I reviewed it before ...)
I notice there are no changes to the build system for this; presumably that's just because we don't have CMake support for building LLVM libraries for wasm in general. I wonder whether LLVM or the libunwind maintainers have any policies about that.

[aheejin]

@dschuff

I notice there are no changes to the build system for this; presumably that's just because we don't have CMake support for building LLVM libraries for wasm in general. I wonder whether LLVM or the libunwind maintainers have any policies about that.

I replied to your similar libc++abi comment here: https://reviews.llvm.org/D158918#4623814
Not sure about the policy, but __USING_SJLJ_EXCEPTIONS__ isn't mentioned in the build system either.

[compnerd]

__USING_SJLJ_EXCEPTIONS__ is compiler defined, it isn't a build system thing. In general, we would like to be able to build the targets that we are claiming to support.

libunwind/include/unwind_itanium.h

27

This is very confusing. Does WASM use SEH? This path is normally for Windows x86.

libunwind/src/Unwind-wasm.c

1

Missing copyright header.

44

Could just return the function rather than assign it to a variable.

76

Why not use the positive form?

if (index == 1)
  ((struct _Unwind_landingPadContext *)context)->selector = value;

libunwind/src/config.h

101

It might be useful to provide warnings should those macros be used on WASM? Right now the use of _LIBUNWIND_WEAK_ALIAS will fail with a weird preprocessor error.

[aheejin]

Address comments

libunwind/include/unwind_itanium.h

27

I actually don't really remember, because I wrote this more than 3 years ago. And note that it is !defined (negative), so I think I simply wanted to exclude them because we were not using them. Not sure what you mean by SEH or Windows x86.

I think I can just delete this. All our tests seem to pass without this change. The data structure can be a little larger but exceptions are rare so it wouldn't be a problem.

libunwind/src/config.h

101

We don't use it in Unwind-wasm.c so I think I just tried to avoid the error. But we also support compilation of weak alias, so I think there's no reason we need to error out. I added defined(__wasm__) with other architectures, like this, and removed this separate elif:

--- a/system/lib/libunwind/src/config.h
+++ b/system/lib/libunwind/src/config.h
@@ -83,7 +83,7 @@
   __asm__(".globl " SYMBOL_NAME(aliasname));                                   \
   __asm__(SYMBOL_NAME(aliasname) " = " SYMBOL_NAME(name));                     \
   _LIBUNWIND_ALIAS_VISIBILITY(SYMBOL_NAME(aliasname))
-#elif defined(__ELF__) || defined(_AIX)
+#elif defined(__ELF__) || defined(_AIX) || defined(__wasm__)
 #define _LIBUNWIND_WEAK_ALIAS(name, aliasname)                                 \
   extern "C" _LIBUNWIND_EXPORT __typeof(name) aliasname                        \
       __attribute__((weak, alias(#name)));
@@ -98,7 +98,6 @@
                                              SYMBOL_NAME(name)))               \
   extern "C" _LIBUNWIND_EXPORT __typeof(name) aliasname;
 #endif
-#elif defined(__wasm__)
 #else
 #error Unsupported target
 #endif

[aheejin]

Gentle ping 😀

[phosek]

LGTM

[dschuff]

LGTM too

[aheejin]

Thank you!

[ldionne]

libunwind/src/Unwind-wasm.c

2

This file isn't tied into the CMakeLists.txt. So for all we know, this code is dead code.

[aheejin]

libunwind/src/Unwind-wasm.c

2

Thanks for pointing that out. Added this to CMakeLists.txt in https://github.com/llvm/llvm-project/pull/67770.

libunwind/include/unwind_itanium.h

 typedef uint64_t _Unwind_Exception_Class;
 
 struct _Unwind_Exception {
   _Unwind_Exception_Class exception_class;
   void (*exception_cleanup)(_Unwind_Reason_Code reason,
                             _Unwind_Exception *exc);
 #if defined(__SEH__) && !defined(__USING_SJLJ_EXCEPTIONS__)
   uintptr_t private_[6];
-#else
+#elif !defined(__USING_WASM_EXCEPTIONS__)
   uintptr_t private_1; // non-zero means forced unwind
   uintptr_t private_2; // holds sp that phase1 found for phase2 to use
 #endif
 #if __SIZEOF_POINTER__ == 4
   // The implementation of _Unwind_Exception uses an attribute mode on the
   // above fields which has the side effect of causing this whole struct to
   // round up to 32 bytes in size (48 with SEH). To be more explicit, we add
   // pad fields added for binary compatibility.

libunwind/src/Unwind-wasm.c

+#include "config.h"
+#include "unwind.h"
+#include <stdbool.h>
+#include <threads.h>
+
+#ifdef __USING_WASM_EXCEPTIONS__
+
+_Unwind_Reason_Code __gxx_personality_wasm0(int version, _Unwind_Action actions,
+                                            uint64_t exceptionClass,
+                                            _Unwind_Exception *unwind_exception,
+                                            _Unwind_Context *context);
+
+struct _Unwind_LandingPadContext {
+  // Input information to personality function
+  uintptr_t lpad_index; // landing pad index
+  uintptr_t lsda;       // LSDA address
+
+  // Output information computed by personality function
+  uintptr_t selector; // selector value
+};
+
+// Communication channel between compiler-generated user code and personality
+// function
+thread_local struct _Unwind_LandingPadContext __wasm_lpad_context;
+
+/// Calls to this function is in landing pads in compiler-generated user code.
+/// In other EH schemes, stack unwinding is done by libunwind library, which
+/// calls the personality function for each each frame it lands. On the other
+/// hand, WebAssembly stack unwinding process is performed by a VM, and the
+/// personality function cannot be called from there. So the compiler inserts
+/// a call to this function in landing pads in the user code, which in turn
+/// calls the personality function.
+_Unwind_Reason_Code _Unwind_CallPersonality(void *exception_ptr) {
+  struct _Unwind_Exception *exception_object =
+      (struct _Unwind_Exception *)exception_ptr;
+  _LIBUNWIND_TRACE_API("_Unwind_CallPersonality(exception_object=%p)",
+                       (void *)exception_object);
+
+  // Reset the selector.
+  __wasm_lpad_context.selector = 0;
+
+  // Call personality function. Wasm does not have two-phase unwinding, so we
+  // only do the cleanup phase.
+  _Unwind_Reason_Code ret = __gxx_personality_wasm0(
+      1, _UA_SEARCH_PHASE, exception_object->exception_class, exception_object,
+      (struct _Unwind_Context *)&__wasm_lpad_context);
+  return ret;
+}
+
+/// Called by __cxa_throw.
+_LIBUNWIND_EXPORT _Unwind_Reason_Code
+_Unwind_RaiseException(_Unwind_Exception *exception_object) {
+  _LIBUNWIND_TRACE_API("_Unwind_RaiseException(exception_object=%p)",
+                       (void *)exception_object);
+  // Use Wasm EH's 'throw' instruction.
+  __builtin_wasm_throw(0, exception_object);
+}
+
+/// Called by __cxa_end_catch.
+_LIBUNWIND_EXPORT void
+_Unwind_DeleteException(_Unwind_Exception *exception_object) {
+  _LIBUNWIND_TRACE_API("_Unwind_DeleteException(ex_obj=%p)",
+                       (void *)(exception_object));
+  if (exception_object->exception_cleanup != NULL)
+    (*exception_object->exception_cleanup)(_URC_FOREIGN_EXCEPTION_CAUGHT,
+                                           exception_object);
+}
+
+/// Called by personality handler to alter register values.
+_LIBUNWIND_EXPORT void _Unwind_SetGR(struct _Unwind_Context *context, int index,
+                                     uintptr_t value) {
+  _LIBUNWIND_TRACE_API("_Unwind_SetGR(context=%p, index=%d, value=%lu)",
+                       (void *)context, index, value);
+  // We only use this function to set __wasm_lpad_context.selector field, which
+  // is index 1 in the personality function.
+  if (index != 1)
+    return;
+  ((struct _Unwind_LandingPadContext *)context)->selector = value;
+}
+
+/// Called by personality handler to get instruction pointer.
+_LIBUNWIND_EXPORT uintptr_t _Unwind_GetIP(struct _Unwind_Context *context) {
+  // The result will be used as an 1-based index after decrementing 1, so we
+  // increment 2 here
+  uintptr_t result =
+      ((struct _Unwind_LandingPadContext *)context)->lpad_index + 2;
+  _LIBUNWIND_TRACE_API("_Unwind_GetIP(context=%p) => %lu", (void *)context,
+                       result);
+  return result;
+}
+
+/// Not used in Wasm.
+_LIBUNWIND_EXPORT void _Unwind_SetIP(struct _Unwind_Context *context,
+                                     uintptr_t value) {}
+
+/// Called by personality handler to get LSDA for current frame.
+_LIBUNWIND_EXPORT uintptr_t
+_Unwind_GetLanguageSpecificData(struct _Unwind_Context *context) {
+  uintptr_t result = ((struct _Unwind_LandingPadContext *)context)->lsda;
+  _LIBUNWIND_TRACE_API("_Unwind_GetLanguageSpecificData(context=%p) => 0x%lx",
+                       (void *)context, result);
+  return result;
+}
+
+/// Not used in Wasm.
+_LIBUNWIND_EXPORT uintptr_t
+_Unwind_GetRegionStart(struct _Unwind_Context *context) {
+  return 0;
+}
+
+#endif

libunwind/src/config.h

#define _LIBUNWIND_WEAK_ALIAS(name, aliasname)                                 \
   extern "C" _LIBUNWIND_EXPORT __typeof(name) aliasname                        \
       __attribute__((alias(#name)));
 #else
 #define _LIBUNWIND_WEAK_ALIAS(name, aliasname)                                 \
   __pragma(comment(linker, "/alternatename:" SYMBOL_NAME(aliasname) "="        \
                                              SYMBOL_NAME(name)))               \
   extern "C" _LIBUNWIND_EXPORT __typeof(name) aliasname;
 #endif
+#elif defined(__wasm__)
 #else
 #error Unsupported target
 #endif
 
 // Apple/armv7k defaults to DWARF/Compact unwinding, but its libunwind also
 // needs to include the SJLJ APIs.
 #if (defined(__APPLE__) && defined(__arm__)) || defined(__USING_SJLJ_EXCEPTIONS__)
 #define _LIBUNWIND_BUILD_SJLJ_APIS