WIP: initial WebAssembly exception-handling support.

This PR introduces support for the [Wasm exception-handling proposal],
which introduces a conventional try/catch mechanism to WebAssembly. The
PR supports modules that use `try_table` to register handlers for a
lexical scope; and provides `throw` and `throw_ref` that allocate (in
the first case) and throw exception objects.

This PR builds on top of the work in #10510 for Cranelift-level
exception support, #10919 for an unwinder, and #11230 for exception
objects built on top of GC, in addition a bunch of smaller fix and
enabling PRs around those.

This PR does not yet provide host-boundary-crossing exceptions;
exceptions that are not caught in a given Wasm activation become traps
at the host boundary. That support will come in a subsequent PR.

Because exceptions do not yet cross the host boundary, this also does
not yet enable the `assert_exception` wast directive, and so cannot yet
support the spec-tests. That will also come in a subsequent PR.

[Wasm exception-handling proposal]: https://github.com/WebAssembly/exception-handling/

Author: cfallin

Cargo.lock

@@ -58,6 +58,7 @@ wasmtime-wasi-tls = { workspace = true, optional = true }
 wasmtime-wasi-keyvalue = { workspace = true, optional = true }
 wasmtime-wasi-threads = { workspace = true, optional = true }
 wasmtime-wasi-http = { workspace = true, optional = true }
+wasmtime-unwinder = { workspace = true }
 clap = { workspace = true }
 clap_complete = { workspace = true, optional = true }
 anyhow = { workspace = true, features = ['std'] }

Cargo.toml

@@ -976,7 +976,7 @@ impl MachInst for Inst {
         //
         // See the note in [crate::isa::aarch64::abi::is_caller_save_reg] for
         // more information on this ABI-implementation hack.
-        let caller_clobbers = AArch64MachineDeps::get_regs_clobbered_by_call(caller, is_exception);
+        let caller_clobbers = AArch64MachineDeps::get_regs_clobbered_by_call(caller, false);
         let callee_clobbers = AArch64MachineDeps::get_regs_clobbered_by_call(callee, is_exception);
 
         let mut all_clobbers = caller_clobbers;

cranelift/codegen/src/isa/aarch64/inst/mod.rs

@@ -648,21 +648,32 @@ extern "C-unwind" fn __cranelift_throw(
 ) -> ! {
     let compiled_test_file = unsafe { &*COMPILED_TEST_FILE.get() };
     let unwind_host = wasmtime_unwinder::UnwindHost;
-    let module_lookup = |pc| {
-        compiled_test_file
+    let frame_handler = |frame: &wasmtime_unwinder::Frame| -> Option<usize> {
+        let (base, table) = compiled_test_file
             .module
             .as_ref()
             .unwrap()
-            .lookup_wasmtime_exception_data(pc)
+            .lookup_wasmtime_exception_data(frame.pc())?;
+        let relative_pc = u32::try_from(
+            frame
+                .pc()
+                .checked_sub(base)
+                .expect("module lookup did not return a module base below the PC"),
+        )
+        .expect("module larger than 4GiB");
+
+        table.lookup_pc_tag(relative_pc, tag).map(|handler| {
+            base.checked_add(usize::try_from(handler).unwrap())
+                .expect("Handler address computation overflowed")
+        })
     };
     unsafe {
         match wasmtime_unwinder::compute_throw_action(
             &unwind_host,
-            module_lookup,
+            frame_handler,
             exit_pc,
             exit_fp,
             entry_fp,
-            tag,
         ) {
             wasmtime_unwinder::ThrowAction::Handler { pc, sp, fp } => {
                 wasmtime_unwinder::resume_to_exception_handler(pc, sp, fp, payload1, payload2);

cranelift/filetests/src/function_runner.rs

@@ -395,8 +395,6 @@ wasmtime_option_group! {
         pub extended_const: Option<bool>,
         /// Configure support for the exceptions proposal.
         pub exceptions: Option<bool>,
-        /// DEPRECATED: Configure support for the legacy exceptions proposal.
-        pub legacy_exceptions: Option<bool>,
     }
 
     enum Wasm {
@@ -1018,13 +1016,6 @@ impl CommonOptions {
         if let Some(enable) = self.wasm.extended_const.or(all) {
             config.wasm_extended_const(enable);
         }
-        if let Some(enable) = self.wasm.exceptions.or(all) {
-            config.wasm_exceptions(enable);
-        }
-        if let Some(enable) = self.wasm.legacy_exceptions.or(all) {
-            #[expect(deprecated, reason = "forwarding CLI flag")]
-            config.wasm_legacy_exceptions(enable);
-        }
 
         macro_rules! handle_conditionally_compiled {
             ($(($feature:tt, $field:tt, $method:tt))*) => ($(
@@ -1049,6 +1040,7 @@ impl CommonOptions {
             ("gc", gc, wasm_gc)
             ("gc", reference_types, wasm_reference_types)
             ("gc", function_references, wasm_function_references)
+            ("gc", exceptions, wasm_exceptions)
             ("stack-switching", stack_switching, wasm_stack_switching)
         }
 

crates/cli-flags/src/lib.rs

@@ -34,6 +34,7 @@ wasmtime-versioned-export-macros = { workspace = true }
 itertools = { workspace = true }
 pulley-interpreter = { workspace = true, optional = true }
 wasmtime-math = { workspace = true }
+wasmtime-unwinder = { workspace = true, features = ["cranelift"] }
 
 [features]
 all-arch = ["cranelift-codegen/all-arch"]

crates/cranelift/Cargo.toml

@@ -14,7 +14,7 @@ use cranelift_codegen::isa::{
     unwind::{UnwindInfo, UnwindInfoKind},
 };
 use cranelift_codegen::print_errors::pretty_error;
-use cranelift_codegen::{CompiledCode, Context};
+use cranelift_codegen::{CompiledCode, Context, FinalizedMachCallSite};
 use cranelift_entity::PrimaryMap;
 use cranelift_frontend::FunctionBuilder;
 use object::write::{Object, StandardSegment, SymbolId};
@@ -28,13 +28,15 @@ use std::ops::Range;
 use std::path;
 use std::sync::{Arc, Mutex};
 use wasmparser::{FuncValidatorAllocations, FunctionBody};
+use wasmtime_environ::obj::ELF_WASMTIME_EXCEPTIONS;
 use wasmtime_environ::{
     AddressMapSection, BuiltinFunctionIndex, CacheStore, CompileError, CompiledFunctionBody,
     DefinedFuncIndex, FlagValue, FuncIndex, FunctionBodyData, FunctionLoc, HostCall,
     InliningCompiler, ModuleTranslation, ModuleTypesBuilder, PtrSize, RelocationTarget,
     StackMapSection, StaticModuleIndex, TrapEncodingBuilder, TrapSentinel, TripleExt, Tunables,
     VMOffsets, WasmFuncType, WasmValType,
 };
+use wasmtime_unwinder::ExceptionTableBuilder;
 
 #[cfg(feature = "component-model")]
 mod component;
@@ -483,6 +485,7 @@ impl wasmtime_environ::Compiler for Compiler {
         let mut addrs = AddressMapSection::default();
         let mut traps = TrapEncodingBuilder::default();
         let mut stack_maps = StackMapSection::default();
+        let mut exception_tables = ExceptionTableBuilder::default();
 
         let mut ret = Vec::with_capacity(funcs.len());
         for (i, (sym, func)) in funcs.iter().enumerate() {
@@ -498,6 +501,11 @@ impl wasmtime_environ::Compiler for Compiler {
                 func.buffer.user_stack_maps(),
             );
             traps.push(range.clone(), &func.traps().collect::<Vec<_>>());
+            clif_to_env_exception_tables(
+                &mut exception_tables,
+                range.clone(),
+                func.buffer.call_sites(),
+            )?;
             builder.append_padding(self.linkopts.padding_between_functions);
             let info = FunctionLoc {
                 start: u32::try_from(range.start).unwrap(),
@@ -514,6 +522,15 @@ impl wasmtime_environ::Compiler for Compiler {
         stack_maps.append_to(obj);
         traps.append_to(obj);
 
+        let exception_section = obj.add_section(
+            obj.segment_name(StandardSegment::Data).to_vec(),
+            ELF_WASMTIME_EXCEPTIONS.as_bytes().to_vec(),
+            SectionKind::ReadOnlyData,
+        );
+        exception_tables.serialize(|bytes| {
+            obj.append_section_data(exception_section, bytes, 1);
+        });
+
         Ok(ret)
     }
 
@@ -1253,6 +1270,21 @@ fn clif_to_env_stack_maps(
     }
 }
 
+/// Convert from Cranelift's representation of exception handler
+/// metadata to Wasmtime's compiler-agnostic representation.
+///
+/// Here `builder` is the wasmtime-unwinder exception section being
+/// created and `range` is the range of the function being added. The
+/// `call_sites` iterator is the raw iterator over callsite metadata
+/// (including exception handlers) from Cranelift.
+fn clif_to_env_exception_tables<'a>(
+    builder: &mut ExceptionTableBuilder,
+    range: Range<u64>,
+    call_sites: impl Iterator<Item = FinalizedMachCallSite<'a>>,
+) -> anyhow::Result<()> {
+    builder.add_func(CodeOffset::try_from(range.start).unwrap(), call_sites)
+}
+
 fn declare_and_call(
     builder: &mut FunctionBuilder,
     signature: ir::Signature,