Document a setjmp/longjmp convention

SetjmpLongjmp.md

@@ -0,0 +1,194 @@
+# C setjmp/longjmp in WebAssembly
+
+## Overview
+
+This document describes a convention to implement C setjmp/longjmp via
+[WebAssembly exception-handling proposal].
+
+[WebAssembly exception-handling proposal]: https://github.com/WebAssembly/exception-handling
+
+## Runtime ABI
+
+### Linear memory structures
+
+This convention uses a few structures on the WebAssembly linear memory.
+
+#### Reserved area in jmp_buf
+
+The first 6 words of C jmp_buf is reserved for the use by the runtime.
+It should also have large enough alignment to store C pointers.
+The contents of this area is private to the runtime implementation.
+
+##### Notes about the size of reserved area in jmp_buf
+
+Emscripten has been using 6 words. (`unsigned long [6]`)
+
+GCC and Clang uses `intptr_t [5]` for their [setjmp/longjmp builtins].
+It isn't relevant right now though, because LLVM's WebAssembly target
+doesn't provide these builtins.
+
+[setjmp/longjmp builtins]: https://gcc.gnu.org/onlinedocs/gcc/Nonlocal-Gotos.html
+
+#### __WasmLongjmpArgs
+
+An equivalent of the following structure is used to associate necessary
+data to the WebAssembly exception.
+
+```
+struct __WasmLongjmpArgs {
+   void *env; // a pointer to jmp_buf
+   int val;
+};
+```
+
+The lifetime of this structure is rather short. It lives only during a
+single longjmp execution.
+A runtime can use a part of `jmp_buf` for this structure. It's also ok to use
+a separate thread-local storage to place this structure. A runtime without
+multi-threading support can simply place this structure in a global variable.
+
+### Exception
+
+This convention uses a WebAssembly exception to perform a non-local jump
+for C `longjmp`.
+
+The name of exception is `__c_longjmp`.
+The type of exception is `(param i32)`. (Or, `(param i64)` for [memory64])
+The parameter of the exception is the address of `__WasmLongjmpArgs` structure
+on the linear memory.
+
+[memory64]: https://github.com/WebAssembly/memory64
+
+### functions
+
+```
+void __wasm_setjmp(jmp_buf env, uint32_t label, void *func_invocation_id);
+uint32_t __wasm_setjmp_test(jmp_buf env, void *func_invocation_id);
+void __wasm_longjmp(jmp_buf env, int val);
+```
+
+`__wasm_setjmp` records the necessary data in the `env` so that it can be
+used by `__wasm_longjmp` later.
+`label` is a non-zero identifier to distinguish setjmp call-sites within
+the function. Note that a C function can contain multiple setjmp() calls.
+`func_invocation_id` is the identifier to distinguish invocations of this
+C function. Note that, when a C function which calls setjmp() is invoked
+recursively, setjmp/longjmp needs to distinguish them.
+
+`__wasm_setjmp_test` tests if the longjmp target belongs to the current
+function invocation. if it does, this function returns the `label` value
+saved by `__wasm_setjmp`. Otherwise, it returns 0.
+
+`__wasm_longjmp` is similar to C `longjmp`.
+If `val` is 0, it's `__wasm_longjmp`'s responsibility to convert it to 1.
+It performs a long jump by filling a `__WasmLongjmpArgs` structure and
+throwing `__c_longjmp` exception with its address.
+
+## Code conversion
+
+The C compiler detects `setjmp` and `longjmp` calls in a program and
+converts them into the corresponding WebAssembly exception-handling
+instructions and calls to the above mentioned runtime ABI.
+
+### functions calling setjmp()
+
+On the function entry, the compiler would generate the logic to create
+the identifier of this function invocation, typically by performing an
+equivalent of `alloca(1)`. Note that the alloca size is not important
+because the pointer is merely used as an identifier and never be dereferenced.
+
+Also, the compiler converts C `setjmp` calls to `__wasm_setjmp` calls.
+
+Also, for code blocks which possibly call `longjmp` directly or indirectly,
+the compiler generates instructions to catch and process the
+`__c_longjmp` exception accordingly.
+
+For an example, a C function like this would be converted like
+the following pseudo code.
+```
+    void
+    f(void)
+    {
+        jmp_buf env;
+        if (!setjmp(env)) {
+            might_call_longjmp(env);
+        }
+    }
+```
+
+```
+    $func_invocation_id = alloca(1)
+
+    ;; 100 is a label generated by the compiler
+    call $__wasm_setjmp($env, 100, $func_invocation_id)
+
+    block
+      block (result i32)
+        try_table (catch $__c_longjmp 0)
+          call $might_call_longjmp
+        end
+        ;; might_call_longjmp didn't call longjmp
+        br 1
+      end
+      ;; might_call_longjmp called longjmp
+      pop __WasmLongjmpArgs pointer from the operand stack
+      $env = __WasmLongjmpArgs.env
+      $val = __WasmLongjmpArgs.val
+      $label = $__wasm_setjmp_test($env, $func_invocation_id)
+      if ($label == 0) {
+         ;; not for us. rethrow.
+         call $__wasm_longjmp($env, $val)
+      }
+      ;; ours.
+      ;; somehow jump to the block corresponding to the $label
+      :
+      :
+    end
+```
+
+### longjmp calls
+
+The compiler converts C `longjmp` calls to `__wasm_longjmp` calls.
+
+## Dynamic-linking consideration
+
+In case of [dynamic-linking], it's the dynamic linker's responsibility
+to provide the exception tag for this convention with the name
+"env.__c_longjmp". Modules should import the tag so that cross-module
+longjmp works.
+
+[dynamic-linking]: DynamicLinking.md
+
+## Implementations
+
+* LLVM has a pass ([WebAssemblyLowerEmscriptenEHSjLj.cpp]) to perform
+  the convertion mentioned above.  It can be enabled with the
+  `-mllvm -wasm-enable-sjlj` option.
+
+  Note: older LLVM versions have been using a slightly different runtime ABI,
+  which is supported by Emscripten. It has been switched to the ABI documented
+  above by https://github.com/llvm/llvm-project/pull/84137.
+
+  Note: as of writing this, LLVM produces a bit older version of
+  exception-handling instructions. (`try`, `delegate`, etc)
+  binaryen has a conversion from the old instructions to the latest
+  instructions. (`try_table` etc.)
+
+* Emscripten (TBD version) has the runtime support for the convention
+  documented above. It also supports a few traditional variations of the
+  setjmp/longjmp ABI.
+
+* A PR to add the runtime support to wasi-libc is under review: https://github.com/WebAssembly/wasi-libc/pull/483
+
+[WebAssemblyLowerEmscriptenEHSjLj.cpp]: https://github.com/llvm/llvm-project/blob/70deb7bfe90af91c68454b70683fbe98feaea87d/llvm/lib/Target/WebAssembly/WebAssemblyLowerEmscriptenEHSjLj.cpp
+
+## Future directions
+
+* `__WasmLongjmpArgs` can be replaced with WebAssembly multivalue.
+
+* If/When WebAssembly exception gets more ubiquitous, we might want to move
+  the runtime to compiler-rt.
+
+## References
+
+* [A discussion about the runtime ABI](https://docs.google.com/document/d/1ZvTPT36K5jjiedF8MCXbEmYjULJjI723aOAks1IdLLg/edit#heading=h.metx1fc16ots)