Merge remote-tracking branch 'exn/main' into wasm-3.0+exn

Author: rossberg

.github/workflows/ci-spec.yml

@@ -40,6 +40,25 @@ jobs:
           name: core-rendered
           path: document/core/_build/html
 
+  build-legacy-exceptions-spec:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v2
+        with:
+          submodules: "recursive"
+      - name: Setup TexLive
+        run: sudo apt-get update -y && sudo apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
+      - name: Setup Sphinx
+        run: pip install six && pip install sphinx==5.1.0
+      - name: Build main spec
+        run: cd document/legacy/exceptions && make main
+      - name: Upload artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: legacy-exceptions-rendered
+          path: document/legacy/exceptions/_build/html
+
   build-js-api-spec:
     runs-on: ubuntu-latest
     steps:
@@ -72,7 +91,7 @@ jobs:
 
   publish-spec:
     runs-on: ubuntu-latest
-    needs: [build-core-spec, build-js-api-spec, build-web-api-spec]
+    needs: [build-core-spec, build-legacy-exceptions-spec, build-js-api-spec, build-web-api-spec]
     steps:
       - name: Checkout repo
         uses: actions/checkout@v2
@@ -83,6 +102,11 @@ jobs:
         with:
           name: core-rendered
           path: _output/core
+      - name: Download legacy exceptions spec artifact
+        uses: actions/download-artifact@v2
+        with:
+          name: legacy-exceptions-rendered
+          path: _output/legacy/exceptions
       - name: Download JS API spec artifact
         uses: actions/download-artifact@v2
         with:

document/Makefile

@@ -1,4 +1,4 @@
-DIRS     = core js-api web-api
+DIRS     = core js-api web-api legacy/exceptions
 FILES    = index.html
 BUILDDIR = _build
 

document/core/appendix/algorithm.rst

@@ -32,7 +32,7 @@ Value types are representable as sets of enumerations:
    type vec_type = V128
    type heap_type =
      Any | Eq | I31 | Struct | Array | None |
-     Func | Nofunc | Extern | Noextern | Bot |
+     Func | Nofunc | Exn | Noexn | Extern | Noextern | Bot |
      Def(def : def_type)
    type ref_type = Ref(heap : heap_type, null : bool)
    type val_type = num_type | vec_type | ref_type | Bot
@@ -445,6 +445,28 @@ Other instructions are checked in a similar manner.
          pop_val(Ref(Def(types[x])))
          pop_val(unpack_field(st.fields[n]))
 
+       case (throw x)
+          pop_vals(tags[x].type.params)
+          unreachable()
+
+       case (try_table t1*->t2* handler*)
+         pop_vals([t1*])
+         foreach (handler in handler*)
+           error_if(ctrls.size() < handler.label)
+           push_ctrl(catch, [], label_types(ctrls[handler.label]))
+           switch (handler.clause)
+             case (catch x)
+               push_vals(tags[x].type.params)
+             case (catch_ref x)
+               push_vals(tags[x].type.params)
+               push_val(Exnref)
+             case (catch_all)
+               skip
+             case (catch_all_ref)
+               push_val(Exnref)
+           pop_ctrl()
+         push_ctrl(try_table, [t1*], [t2*])
+
 .. note::
    It is an invariant under the current WebAssembly instruction set that an operand of :code:`Bot` type is never duplicated on the stack.
    This would change if the language were extended with stack instructions like :code:`dup`.

document/core/appendix/changes.rst

@@ -138,9 +138,38 @@ Added vector type and instructions that manipulate multiple numeric values in pa
 * New injection/projection :ref:`vector instructions <syntax-instr-vec>`: :math:`\K{i}\!N\!\K{x}\!M\!\K{.splat}`, :math:`\K{f}\!N\!\K{x}\!M\!\K{.splat}`, :math:`\K{i}\!N\!\K{x}\!M\!\K{.bitmask}`
 
 
-Release 2.?
+.. [#proposal-signext]
+   https://github.com/WebAssembly/spec/tree/main/proposals/sign-extension-ops/
+
+.. [#proposal-cvtsat]
+   https://github.com/WebAssembly/spec/tree/main/proposals/nontrapping-float-to-int-conversion/
+
+.. [#proposal-multivalue]
+   https://github.com/WebAssembly/spec/tree/main/proposals/multi-value/
+
+.. [#proposal-reftype]
+   https://github.com/WebAssembly/spec/tree/main/proposals/reference-types/
+
+.. [#proposal-bulk]
+   https://github.com/WebAssembly/spec/tree/main/proposals/bulk-memory-operations/
+
+.. [#proposal-vectype]
+   https://github.com/WebAssembly/spec/tree/main/proposals/simd/
+
+
+Release 3.0
 ~~~~~~~~~~~
 
+.. index: instruction, function, call
+
+Tail Calls
+..........
+
+Added instructions to perform tail calls [#proposal-tailcall]_.
+
+* New :ref:`control instructions <syntax-instr-control>`: :math:`RETURNCALL` and :math:`RETURNCALLINDIRECT`
+
+
 .. index:: reference, reference type, heap type, value type, local, local type, instruction, instruction type, table, function, function type, matching, subtyping
 
 Typeful References
@@ -193,60 +222,22 @@ Added managed reference types [#proposal-gc]_.
 * Extended set of :ref:`constant instructions <valid-const>` with |REFI31|, |STRUCTNEW|, |STRUCTNEWDEFAULT|, |ARRAYNEW|, |ARRAYNEWDEFAULT|, |ARRAYNEWFIXED|, |ANYCONVERTEXTERN|, |EXTERNCONVERTANY|, and |GLOBALGET| for any previously declared immutable :ref:`global <syntax-global>`
 
 
-.. [#proposal-signext]
-   https://github.com/WebAssembly/spec/tree/main/proposals/sign-extension-ops/
-
-.. [#proposal-cvtsat]
-   https://github.com/WebAssembly/spec/tree/main/proposals/nontrapping-float-to-int-conversion/
+.. index:: instruction, exception, reference type, tag type, tag, handler
 
-.. [#proposal-multivalue]
-   https://github.com/WebAssembly/spec/tree/main/proposals/multi-value/
-
-.. [#proposal-reftype]
-   https://github.com/WebAssembly/spec/tree/main/proposals/reference-types/
-
-.. [#proposal-bulk]
-   https://github.com/WebAssembly/spec/tree/main/proposals/bulk-memory-operations/
-
-.. [#proposal-vectype]
-   https://github.com/WebAssembly/spec/tree/main/proposals/simd/
-
-
-Release 3.0
-~~~~~~~~~~~
-
-.. index: instruction, function, call
-
-Tail calls
-..........
-
-Added instructions to perform tail calls [#proposal-tailcall]_.
-
-* New :ref:`control instructions <syntax-instr-control>`: :math:`RETURNCALL` and :math:`RETURNCALLINDIRECT`
-
-
-.. index:: reference, reference type, heap type, value type, local, local type, instruction, instruction type, table, function, function type, matching, subtyping
-
-Typeful References
+Exception Handling
 ..................
 
-Added more precise types for references [#proposal-typedref]_.
-
-* New generalised form of :ref:`reference types <syntax-reftype>`: :math:`(\REF~\NULL^?~\heaptype)`
-
-* New class of :ref:`heap types <syntax-heaptype>`: |FUNC|, |EXTERN|, :math:`\typeidx`
+Added tag definitions, imports, and exports, and instructions to throw and catch exceptions [#proposal-exn]_
 
-* Basic :ref:`subtyping <match>` on :ref:`reference <match-reftype>` and :ref:`value <match-valtype>` types
+* Modules may :ref:`define <syntax-tagtype>`, :ref:`import <syntax-import>`, and :ref:`export <syntax-export>` tags.
 
-* New :ref:`reference instructions <syntax-instr-ref>`: |REFASNONNULL|, |BRONNULL|, |BRONNONNULL|
+* New :ref:`heap types <syntax-heaptype>`: |EXN|, |NOEXN|
 
-* New :ref:`control instruction <syntax-instr-control>`: |CALLREF|
+* New :ref:`reference type <syntax-reftype>` short-hands: |EXNREF|, |NULLEXNREF|
 
-* Refined typing of :ref:`reference instruction <syntax-instr-ref>` |REFFUNC| with more precise result type
+* New :ref:`control instructions <syntax-instr-control>`: |THROW|, |THROWREF|, and |TRYTABLE|.
 
-* Refined typing of :ref:`local instructions <valid-instr-variable>` and :ref:`instruction sequences <valid-instr-seq>` to track the :ref:`initialization status <syntax-init>` of :ref:`locals <syntax-local>` with non-:ref:`defaultable <valid-defaultable>` type
-
-* Extended :ref:`table definitions <syntax-table>` with optional initializer expression
+* New :ref:`tag section <binary-tagsec>` in binary format.
 
 
 .. [#proposal-tailcall]
@@ -257,3 +248,6 @@ Added more precise types for references [#proposal-typedref]_.
 
 .. [#proposal-gc]
    https://github.com/WebAssembly/spec/tree/main/proposals/gc/
+
+.. [#proposal-exn]
+   https://github.com/WebAssembly/spec/tree/main/proposals/exception-handling/

document/core/appendix/custom.rst

@@ -46,7 +46,8 @@ Each subsection consists of a
      n{:}\Bname & (\iff n = \text{name}) \\ &&&
      \Bmodulenamesubsec^? \\ &&&
      \Bfuncnamesubsec^? \\ &&&
-     \Blocalnamesubsec^? \\
+     \Blocalnamesubsec^? \\ &&&
+     \Btagnamesubsec^? \\
    \production{name subsection} & \Bnamesubsection_N(\B{B}) &::=&
      N{:}\Bbyte~~\X{size}{:}\Bu32~~\B{B}
        & (\iff \X{size} = ||\B{B}||) \\
@@ -62,6 +63,7 @@ Id  Subsection
  2  :ref:`local names <binary-localnamesec>`
  4  :ref:`type names <binary-typenamesec>`
 10  :ref:`field names <binary-fieldnamesec>`
+11  :ref:`tag names <binary-tagnamesec>`
 ==  ===========================================
 
 Each subsection may occur at most once, and in order of increasing id.
@@ -177,3 +179,19 @@ It consists of an :ref:`indirect name map <binary-indirectnamemap>` assigning fi
    \production{field name subsection} & \Bfieldnamesubsec &::=&
      \Bnamesubsection_2(\Bindirectnamemap) \\
    \end{array}
+
+
+.. index:: tag, tag index
+.. _binary-tagnamesec:
+
+Tag Names
+.........
+
+The *tag name subsection* has the id 11.
+It consists of a :ref:`name map <binary-namemap>` assigning tag names to :ref:`tag indices <syntax-tagidx>`.
+
+.. math::
+   \begin{array}{llclll}
+   \production{tag name subsection} & \Btagnamesubsec &::=&
+     \Bnamesubsection_1(\Bnamemap) \\
+   \end{array}

document/core/appendix/embedding.rst

@@ -49,7 +49,7 @@ Failure of an interface operation is indicated by an auxiliary syntactic class:
    \production{error} & \error &::=& \ERROR \\
    \end{array}
 
-In addition to the error conditions specified explicitly in this section, implementations may also return errors when specific :ref:`implementation limitations <impl>` are reached.
+In addition to the error conditions specified explicitly in this section, such as invalid arguments or :ref:`exceptions <exception>` and :ref:`traps <trap>` resulting from :ref:`execution <exec>`, implementations may also return errors when specific :ref:`implementation limitations <impl>` are reached.
 
 .. note::
    Errors are abstract and unspecific with this definition.
@@ -89,7 +89,7 @@ Store
 
 .. math::
    \begin{array}{lclll}
-   \F{store\_init}() &=& \{ \SFUNCS~\epsilon,~ \SMEMS~\epsilon,~ \STABLES~\epsilon,~ \SGLOBALS~\epsilon \} \\
+   \F{store\_init}() &=& \{ \} \\
    \end{array}
 
 
@@ -167,7 +167,7 @@ Modules
 .. math::
    \begin{array}{lclll}
    \F{module\_instantiate}(S, m, \X{ev}^\ast) &=& (S', F.\AMODULE) && (\iff \instantiate(S, m, \X{ev}^\ast) \stepto^\ast S'; F; \epsilon) \\
-   \F{module\_instantiate}(S, m, \X{ev}^\ast) &=& (S', \ERROR) && (\iff \instantiate(S, m, \X{ev}^\ast) \stepto^\ast S'; F; \TRAP) \\
+   \F{module\_instantiate}(S, m, \X{ev}^\ast) &=& (S', \ERROR) && (\otherwise, \iff \instantiate(S, m, \X{ev}^\ast) \stepto^\ast S'; F; \result) \\
    \end{array}
 
 .. note::
@@ -322,7 +322,7 @@ Functions
    ~ \\
    \begin{array}{lclll}
    \F{func\_invoke}(S, a, v^\ast) &=& (S', {v'}^\ast) && (\iff \invoke(S, a, v^\ast) \stepto^\ast S'; F; {v'}^\ast) \\
-   \F{func\_invoke}(S, a, v^\ast) &=& (S', \ERROR) && (\iff \invoke(S, a, v^\ast) \stepto^\ast S'; F; \TRAP) \\
+   \F{func\_invoke}(S, a, v^\ast) &=& (S', \ERROR) && (\iff \invoke(S, a, v^\ast) \stepto^\ast S'; F; \result) \\
    \end{array}
 
 .. note::
@@ -553,6 +553,28 @@ Memories
    \end{array}
 
 
+.. index:: tag, tag address, store, tag instance, tag type, function type
+.. _embed-tag:
+
+Tags
+~~~~
+
+.. _embedd-tag-alloc:
+
+:math:`\F{tag\_alloc}(\store, \tagtype) : (\store, \tagaddr)`
+.............................................................
+
+1. Pre-condition: :math:`tagtype` is :ref:`valid <valid-tagtype>`.
+
+2. Let :math:`\tagaddr` be the result of :ref:`allocating a tag <alloc-tag>` in :math:`\store` with :ref:`tag type <syntax-tagtype>` :math:`\tagtype`.
+
+3. Return the new store paired with :math:`\tagaddr`.
+
+.. math::
+   \begin{array}{lclll}
+   \F{tag\_alloc}(S, \X{tt}) &=& (S', \X{a}) && (\iff \alloctag(S, \X{tt}) = S', \X{a}) \\
+   \end{array}
+
 
 .. index:: global, global address, store, global instance, global type, value
 .. _embed-global:

document/core/appendix/implementation.rst

@@ -24,7 +24,7 @@ However, it is expected that all implementations have "reasonably" large limits
 Syntactic Limits
 ~~~~~~~~~~~~~~~~
 
-.. index:: abstract syntax, module, type, function, table, memory, global, element, data, import, export, parameter, result, local, structured control instruction, instruction, name, Unicode, character
+.. index:: abstract syntax, module, type, function, table, memory, global, tag, element, data, import, export, parameter, result, local, structured control instruction, instruction, name, Unicode, character
 .. _impl-syntax:
 
 Structure
@@ -37,6 +37,7 @@ An implementation may impose restrictions on the following dimensions of a modul
 * the number of :ref:`tables <syntax-table>` in a :ref:`module <syntax-module>`, including imports
 * the number of :ref:`memories <syntax-mem>` in a :ref:`module <syntax-module>`, including imports
 * the number of :ref:`globals <syntax-global>` in a :ref:`module <syntax-module>`, including imports
+* the number of :ref:`tags <syntax-tag>` in a :ref:`module <syntax-module>`, including imports
 * the number of :ref:`element segments <syntax-elem>` in a :ref:`module <syntax-module>`
 * the number of :ref:`data segments <syntax-data>` in a :ref:`module <syntax-module>`
 * the number of :ref:`imports <syntax-import>` to a :ref:`module <syntax-module>`
@@ -131,8 +132,10 @@ Restrictions on the following dimensions may be imposed during :ref:`execution <
 * the number of allocated :ref:`table instances <syntax-tableinst>`
 * the number of allocated :ref:`memory instances <syntax-meminst>`
 * the number of allocated :ref:`global instances <syntax-globalinst>`
+* the number of allocated :ref:`tag instances <syntax-taginst>`
 * the number of allocated :ref:`structure instances <syntax-structinst>`
 * the number of allocated :ref:`array instances <syntax-arrayinst>`
+* the number of allocated :ref:`exception instances <syntax-exninst>`
 * the size of a :ref:`table instance <syntax-tableinst>`
 * the size of a :ref:`memory instance <syntax-meminst>`
 * the size of an :ref:`array instance <syntax-arrayinst>`

document/core/appendix/index-instructions.py

@@ -52,17 +52,26 @@ def RefWrap(s, kind):
         return f':ref:`{kind} <{s}>`'
 
 
-def Instruction(name, opcode, type=None, validation=None, execution=None, operator=None):
+def Instruction(name, opcode, type=None, validation=None, execution=None, operator=None, validation2=None, execution2=None):
     if operator:
         execution_str = RefWrap(execution, 'execution') + ' (' + RefWrap(operator, 'operator') + ')'
+    elif execution2:
+        execution_str = ', '.join([RefWrap(execution, 'execution'),
+                                   RefWrap(execution, 'execution')])
     else:
         execution_str = RefWrap(execution, 'execution')
 
+    if validation2:
+        validation_str = ', '.join([RefWrap(validation, 'validation'),
+                                    RefWrap(validation2, 'validation')])
+    else:
+        validation_str = RefWrap(validation, 'validation')
+
     return (
         MathWrap(name, '(reserved)'),
         MathWrap(opcode),
         MathWrap(type),
-        RefWrap(validation, 'validation'),
+        validation_str,
         execution_str
     )
 
@@ -76,9 +85,9 @@ def Instruction(name, opcode, type=None, validation=None, execution=None, operat
     Instruction(r'\ELSE', r'\hex{05}'),
     Instruction(None, r'\hex{06}'),
     Instruction(None, r'\hex{07}'),
-    Instruction(None, r'\hex{08}'),
+    Instruction(r'\THROW~x', r'\hex{08}', r'[t_1^\ast~t_x^\ast] \to [t_2^\ast]', r'valid-throw', r'exec-throw'),
     Instruction(None, r'\hex{09}'),
-    Instruction(None, r'\hex{0A}'),
+    Instruction(r'\THROWREF', r'\hex{0A}', r'[t_1^\ast~\EXNREF] \to [t_2^\ast]', r'valid-throw_ref', r'exec-throw_ref'),
     Instruction(r'\END', r'\hex{0B}'),
     Instruction(r'\BR~l', r'\hex{0C}', r'[t_1^\ast~t^\ast] \to [t_2^\ast]', r'valid-br', r'exec-br'),
     Instruction(r'\BRIF~l', r'\hex{0D}', r'[t^\ast~\I32] \to [t^\ast]', r'valid-br_if', r'exec-br_if'),
@@ -99,7 +108,7 @@ def Instruction(name, opcode, type=None, validation=None, execution=None, operat
     Instruction(r'\SELECT~t', r'\hex{1C}', r'[t~t~\I32] \to [t]', r'valid-select', r'exec-select'),
     Instruction(None, r'\hex{1D}'),
     Instruction(None, r'\hex{1E}'),
-    Instruction(None, r'\hex{1F}'),
+    Instruction(r'\TRYTABLE~\X{bt}', r'\hex{1F}', r'[t_1^\ast] \to [t_2^\ast]', r'valid-try_table', r'exec-try_table'),
     Instruction(r'\LOCALGET~x', r'\hex{20}', r'[] \to [t]', r'valid-local.get', r'exec-local.get'),
     Instruction(r'\LOCALSET~x', r'\hex{21}', r'[t] \to []', r'valid-local.set', r'exec-local.set'),
     Instruction(r'\LOCALTEE~x', r'\hex{22}', r'[t] \to [t]', r'valid-local.tee', r'exec-local.tee'),