[EH] Add new test setting for new Wasm EH (#21906)

`with_all_eh_sjlj` and `with_all_sjlj` decorators (previously
`with_both_eh_sjlj` and `with_both_sjlj` but recently got renamed)
currently tests two modes: Emscripten EH and Wasm EH (pre-2023). We
decided to switch to a new version of the Wasm EH proposal in Oct 2023,
so this adds a new test setting for the new Wasm EH proposal in those
decorators.

Currently we have two parameters:
- ``: Emscripten EH
- `wasm`: Wasm EH (pre-2023)

This changes it to these three parameters:
- `emscripten`: Emscripten EH
- `wasm`: Wasm EH (pre-2023)
- `wasm_exnref`: Wasm EH (New proposal adopted on Oct 2023)

To use the new mode in the command line, you use `-fwasm-exceptions` as
in the old Wasm EH, but add `-sWASM_EXNREF` additionally.

This currently uses the Binaryen translator that translates old Wasm EH
instruction to the new ones
(https://github.com/WebAssembly/binaryen/blob/main/src/passes/TranslateEH.cpp)
at the end of the Binaryen pipeline to produce new binaries.

site/source/docs/tools_reference/settings_reference.rst

@@ -994,6 +994,17 @@ ASSERTIONS is enabled. This option is for users who want exceptions' stack
 traces but do not want other overheads ASSERTIONS can incur.
 This option implies EXPORT_EXCEPTION_HANDLING_HELPERS.
 
+.. _wasm_exnref:
+
+WASM_EXNREF
+===========
+
+Emit instructions for the new Wasm exception handling proposal with exnref,
+which was adopted on Oct 2023. The implementation of the new proposal is
+still in progress and this feature is currently experimental.
+
+.. note:: Applicable during both linking and compilation
+
 .. _nodejs_catch_exit:
 
 NODEJS_CATCH_EXIT

src/settings.js

@@ -779,6 +779,12 @@ var EXPORT_EXCEPTION_HANDLING_HELPERS = false;
 // [link]
 var EXCEPTION_STACK_TRACES = false;
 
+// Emit instructions for the new Wasm exception handling proposal with exnref,
+// which was adopted on Oct 2023. The implementation of the new proposal is
+// still in progress and this feature is currently experimental.
+// [compile+link]
+var WASM_EXNREF = false;
+
 // Emscripten throws an ExitStatus exception to unwind when exit() is called.
 // Without this setting enabled this can show up as a top level unhandled
 // exception.

test/common.py

@@ -285,6 +285,16 @@ def decorated(self, *args, **kwargs):
   return decorated
 
 
+def requires_wasm_exnref(func):
+  assert callable(func)
+
+  def decorated(self, *args, **kwargs):
+    self.require_wasm_exnref()
+    return func(self, *args, **kwargs)
+
+  return decorated
+
+
 def requires_v8(func):
   assert callable(func)
 
@@ -500,24 +510,29 @@ def metafunc(self, standalone):
 
 
 # Tests exception handling / setjmp/longjmp handling in Emscripten EH/SjLj mode
-# and if possible, new wasm EH/SjLj mode. This tests two combinations:
+# and new wasm EH/SjLj modes. This tests three combinations:
 # - Emscripten EH + Emscripten SjLj
-# - Wasm EH + Wasm SjLj
+# - Wasm EH + Wasm SjLj (Phase 3, to be deprecated)
+# - Wasm EH + Wasm SjLj (New proposal witn exnref, experimental)
 def with_all_eh_sjlj(f):
   assert callable(f)
 
   @wraps(f)
-  def metafunc(self, is_native, *args, **kwargs):
-    if is_native:
+  def metafunc(self, mode, *args, **kwargs):
+    if mode == 'wasm' or mode == 'wasm_exnref':
       # Wasm EH is currently supported only in wasm backend and V8
       if self.is_wasm2js():
         self.skipTest('wasm2js does not support wasm EH/SjLj')
-      self.require_wasm_eh()
       # FIXME Temporarily disabled. Enable this later when the bug is fixed.
       if '-fsanitize=address' in self.emcc_args:
         self.skipTest('Wasm EH does not work with asan yet')
       self.emcc_args.append('-fwasm-exceptions')
       self.set_setting('SUPPORT_LONGJMP', 'wasm')
+      if mode == 'wasm':
+        self.require_wasm_eh()
+      if mode == 'wasm_exnref':
+        self.require_wasm_exnref()
+        self.set_setting('WASM_EXNREF')
       f(self, *args, **kwargs)
     else:
       self.set_setting('DISABLE_EXCEPTION_CATCHING', 0)
@@ -529,8 +544,9 @@ def metafunc(self, is_native, *args, **kwargs):
       self.set_setting('DEFAULT_TO_CXX')
       f(self, *args, **kwargs)
 
-  parameterize(metafunc, {'': (False,),
-                          'wasm': (True,)})
+  parameterize(metafunc, {'emscripten': ('emscripten',),
+                          'wasm': ('wasm',),
+                          'wasm_exnref': ('wasm_exnref',)})
   return metafunc
 
 
@@ -540,22 +556,27 @@ def with_all_sjlj(f):
   assert callable(f)
 
   @wraps(f)
-  def metafunc(self, is_native):
-    if is_native:
+  def metafunc(self, mode):
+    if mode == 'wasm' or mode == 'wasm_exnref':
       if self.is_wasm2js():
         self.skipTest('wasm2js does not support wasm SjLj')
-      self.require_wasm_eh()
       # FIXME Temporarily disabled. Enable this later when the bug is fixed.
       if '-fsanitize=address' in self.emcc_args:
         self.skipTest('Wasm EH does not work with asan yet')
       self.set_setting('SUPPORT_LONGJMP', 'wasm')
+      if mode == 'wasm':
+        self.require_wasm_eh()
+      if mode == 'wasm_exnref':
+        self.require_wasm_exnref()
+        self.set_setting('WASM_EXNREF')
       f(self)
     else:
       self.set_setting('SUPPORT_LONGJMP', 'emscripten')
       f(self)
 
-  parameterize(metafunc, {'': (False,),
-                          'wasm': (True,)})
+  parameterize(metafunc, {'emscripten': ('emscripten',),
+                          'wasm': ('wasm',),
+                          'wasm_exnref': ('wasm_exnref',)})
   return metafunc
 
 
@@ -877,6 +898,26 @@ def require_wasm_eh(self):
     else:
       self.fail('either d8 or node >= 17 required to run wasm-eh tests.  Use EMTEST_SKIP_EH to skip')
 
+  def require_wasm_exnref(self):
+    nodejs = self.get_nodejs()
+    if nodejs:
+      version = shared.get_node_version(nodejs)
+      if version >= (22, 0, 0):
+        self.js_engines = [nodejs]
+        self.node_args.append('--experimental-wasm-exnref')
+        return
+
+    if config.V8_ENGINE and config.V8_ENGINE in self.js_engines:
+      self.emcc_args.append('-sENVIRONMENT=shell')
+      self.js_engines = [config.V8_ENGINE]
+      self.v8_args.append('--experimental-wasm-exnref')
+      return
+
+    if 'EMTEST_SKIP_EH' in os.environ:
+      self.skipTest('test requires node >= 22 or d8 (and EMTEST_SKIP_EH is set)')
+    else:
+      self.fail('either d8 or node >= 22 required to run wasm-eh tests.  Use EMTEST_SKIP_EH to skip')
+
   def require_jspi(self):
     # emcc warns about stack switching being experimental, and we build with
     # warnings-as-errors, so disable that warning

test/test_core.py

@@ -1557,6 +1557,7 @@ def clear_all_relevant_settings(self):
       self.clear_setting('DISABLE_EXCEPTION_CATCHING')
       self.clear_setting('SUPPORT_LONGJMP')
       self.clear_setting('ASYNCIFY')
+      self.clear_setting('WASM_EXNREF')
 
     # Emscripten EH and Wasm EH cannot be enabled at the same time
     self.set_setting('DISABLE_EXCEPTION_CATCHING', 0)

tools/link.py

@@ -427,6 +427,10 @@ def check_human_readable_list(items):
     extras = settings.BINARYEN_EXTRA_PASSES.split(',')
     passes += [('--' + p) if p[0] != '-' else p for p in extras if p]
 
+  # Run the translator to the new EH instructions with exnref
+  if settings.WASM_EXNREF:
+    passes += ['--experimental-new-eh']
+
   return passes