Clarify docs around exceptions in Cranelift (#11601)

* Clarify docs around exceptions in Cranelift

This is a result of today's Cranelift meeting with some of my questions
around the ABI bits here and there. Notably:

* Cranelift is audited and now documented to always consider the callee
  calling convention in `try_call`, disregarding the caller calling convention.

* Wasmtime's exception throw now explicitly names the `tailcc` in the
  name to indicate that it's only compatible with the tail calling convention.

* The verifier test for exceptions is expanded with a few more cases
  here and there that I could think of.

* Backends now assert that the size of the calling-convention list of
  payload types is the same as the size of the list of registers the
  backend places results into.

* Fix a typo

Author: alexcrichton

cranelift/codegen/src/isa/call_conv.rs

@@ -90,6 +90,16 @@ impl CallConv {
     }
 
     /// What types do the exception payload value(s) have?
+    ///
+    /// Note that this function applies to the *callee* of a `try_call`
+    /// instruction. The calling convention of the callee may differ from the
+    /// caller, but the exceptional payload types available are defined by the
+    /// callee calling convention.
+    ///
+    /// Also note that individual backends are responsible for reporting
+    /// register destinations for exceptional types. Internally Cranelift
+    /// asserts that the backend supports the exact same number of register
+    /// destinations as this return value.
     pub fn exception_payload_types(&self, pointer_ty: Type) -> &[Type] {
         match self {
             CallConv::Tail | CallConv::SystemV => match pointer_ty {

cranelift/codegen/src/machinst/abi.rs

@@ -601,7 +601,12 @@ pub trait ABIMachineSpec {
 
     /// Get the exception payload registers, if any, for a calling
     /// convention.
-    fn exception_payload_regs(_call_conv: isa::CallConv) -> &'static [Reg] {
+    ///
+    /// Note that the argument here is the calling convention of the *callee*.
+    /// This might differ from the caller but the exceptional payloads that are
+    /// available are defined by the callee, not the caller.
+    fn exception_payload_regs(callee_conv: isa::CallConv) -> &'static [Reg] {
+        let _ = callee_conv;
         &[]
     }
 }
@@ -2021,6 +2026,15 @@ impl<M: ABIMachineSpec> Callee<M> {
         assert!(outputs.next().is_none());
 
         if let Some(try_call_payloads) = try_call_payloads {
+            // Let `M` say where the payload values are going to end up and then
+            // double-check it's the same size as the calling convention's
+            // reported number of exception types.
+            let pregs = M::exception_payload_regs(callee_conv);
+            assert_eq!(
+                callee_conv.exception_payload_types(M::word_type()).len(),
+                pregs.len()
+            );
+
             // We need to update `defs` to contain the exception
             // payload regs as well. We have two sources of info that
             // we join:
@@ -2040,7 +2054,6 @@ impl<M: ABIMachineSpec> Callee<M> {
             // handle the two cases below for each payload register:
             // overlaps a return value (and we alias to it) or not
             // (and we add a def).
-            let pregs = M::exception_payload_regs(callee_conv);
             for (i, &preg) in pregs.iter().enumerate() {
                 let vreg = try_call_payloads[i];
                 if let Some(existing) = defs.iter().find(|def| match def.location {

cranelift/codegen/src/machinst/lower.rs

@@ -437,6 +437,10 @@ impl<'func, I: VCodeInst> Lower<'func, I> {
                     try_call_rets.insert(inst, rets);
 
                     let mut payloads = smallvec![];
+                    // Note that this is intentionally using the calling
+                    // convention of the callee to determine what payload types
+                    // are available. The callee defines that, not the calling
+                    // convention of the caller.
                     for &ty in sig
                         .call_conv
                         .exception_payload_types(I::ABIMachineSpec::word_type())

cranelift/filetests/filetests/verifier/exceptions.clif

@@ -131,3 +131,81 @@ function %f5(i32) -> i32 {
         v10 = iconst.i32 3
         return v10
 }
+
+;; Use the payloads of the callee, not the caller
+function %f5() windows_fastcall {
+    sig0 = () tail
+    fn0 = %g() tail
+
+    block0():
+        try_call fn0(), sig0, block1(), [ tag1: block2(exn0), default: block3(exn1) ]
+
+    block1():
+        return
+
+    block2(v0: i64):
+        return
+
+    block3(v1: i64):
+        return
+}
+
+;; Out-of-bounds `exnN` paylaod
+function %f5() {
+    sig0 = () tail
+    fn0 = %g() tail
+
+    block0():
+        try_call fn0(), sig0, block1(), [ default: block2(exn2) ] ; error: out-of-bounds `exnN` block argument
+
+    block1():
+        return
+
+    block2(v1: i64):
+        return
+}
+
+;; `exnN` only allowed in exceptional blocks
+function %f5() {
+    sig0 = () tail
+    fn0 = %g() tail
+
+    block0():
+        try_call fn0(), sig0, block1(exn0), [ default: block2() ] ; error: `exnN` block argument used outside normal-return target of `try_call`
+
+    block1(v1: i64):
+        return
+
+    block2():
+        return
+}
+
+;; `retN` only allowed in normal return
+function %f5() {
+    sig0 = () -> i32 tail
+    fn0 = %g() -> i32 tail
+
+    block0():
+        try_call fn0(), sig0, block1(ret0), [ default: block2(ret0) ] ; error: `retN` block argument used outside normal-return target of `try_call`
+
+    block1(v1: i32):
+        return
+
+    block2(v2: i32):
+        return
+}
+
+;; `system_v` has two payload slots
+function %f5() {
+    sig0 = () system_v
+    fn0 = %g() system_v
+
+    block0():
+        try_call fn0(), sig0, block1(), [ default: block2(exn0, exn1) ]
+
+    block1():
+        return
+
+    block2(v1: i64, v2: i64):
+        return
+}

cranelift/filetests/src/function_runner.rs

@@ -682,7 +682,7 @@ extern "C-unwind" fn __cranelift_throw(
             exit_fp,
             entry_fp,
         ) {
-            Some(handler) => handler.resume(payload1, payload2),
+            Some(handler) => handler.resume_tailcc(payload1, payload2),
             None => {
                 panic!("Expected a handler to exit for throw of tag {tag} at pc {exit_pc:x}");
             }

crates/unwinder/src/arch/mod.rs

@@ -62,7 +62,10 @@ cfg_if::cfg_if! {
             /// - The Rust frames between the unwind destination and this
             ///   frame to be unwind-safe: that is, they cannot have `Drop`
             ///   handlers for which safety requires that they run.
-            pub unsafe fn resume(
+            ///
+            /// - The Cranelift-generated `try_call` that we're unwinding to was
+            ///   invoking the callee with the `tail` calling convention.
+            pub unsafe fn resume_tailcc(
                 &self,
                 payload1: usize,
                 payload2: usize,

crates/wasmtime/src/runtime/vm/traphandlers.rs

@@ -944,7 +944,7 @@ impl CallThreadState {
                     r.resume_to_exception_handler(handler, payload1, payload2)
                 }
                 #[cfg(has_host_compiler_backend)]
-                ExecutorRef::Native => handler.resume(payload1, payload2),
+                ExecutorRef::Native => handler.resume_tailcc(payload1, payload2),
             }
         }
     }