Spec binary format

document/core/binary/instructions.rst

@@ -26,6 +26,7 @@ Control Instructions
 :ref:`Block types <syntax-blocktype>` are encoded in special compressed form, by either the byte :math:`\hex{40}` indicating the empty type, as a single :ref:`value type <binary-valtype>`, or as a :ref:`type index <binary-typeidx>` encoded as a positive :ref:`signed integer <binary-sint>`.
 
 .. _binary-blocktype:
+.. _binary-castflags:
 .. _binary-nop:
 .. _binary-unreachable:
 .. _binary-block:
@@ -36,6 +37,8 @@ Control Instructions
 .. _binary-br_table:
 .. _binary-br_on_null:
 .. _binary-br_on_non_null:
+.. _binary-br_on_cast:
+.. _binary-br_on_cast_fail:
 .. _binary-return:
 .. _binary-call:
 .. _binary-call_ref:
@@ -44,11 +47,11 @@ Control Instructions
 .. _binary-return_call_indirect:
 
 .. math::
-   \begin{array}{llcllll}
+   \begin{array}{@{}llcllll}
    \production{block type} & \Bblocktype &::=&
      \hex{40} &\Rightarrow& \epsilon \\ &&|&
      t{:}\Bvaltype &\Rightarrow& t \\ &&|&
-     x{:}\Bs33 &\Rightarrow& x & (\iff x \geq 0) \\
+     x{:}\Bs33 &\Rightarrow& x \qquad (\iff x \geq 0) \\
    \production{instruction} & \Binstr &::=&
      \hex{00} &\Rightarrow& \UNREACHABLE \\ &&|&
      \hex{01} &\Rightarrow& \NOP \\ &&|&
@@ -58,7 +61,7 @@ Control Instructions
        &\Rightarrow& \LOOP~\X{bt}~\X{in}^\ast~\END \\ &&|&
      \hex{04}~~\X{bt}{:}\Bblocktype~~(\X{in}{:}\Binstr)^\ast~~\hex{0B}
        &\Rightarrow& \IF~\X{bt}~\X{in}^\ast~\ELSE~\epsilon~\END \\ &&|&
-     \hex{04}~~\X{bt}{:}\Bblocktype~~(\X{in}_1{:}\Binstr)^\ast~~
+     \hex{04}~~\X{bt}{:}\Bblocktype~~(\X{in}_1{:}\Binstr)^\ast\\&&&~~
        \hex{05}~~(\X{in}_2{:}\Binstr)^\ast~~\hex{0B}
        &\Rightarrow& \IF~\X{bt}~\X{in}_1^\ast~\ELSE~\X{in}_2^\ast~\END \\ &&|&
      \hex{0C}~~l{:}\Blabelidx &\Rightarrow& \BR~l \\ &&|&
@@ -73,7 +76,14 @@ Control Instructions
      \hex{14}~~x{:}\Btypeidx &\Rightarrow& \CALLREF~x \\ &&|&
      \hex{15}~~x{:}\Btypeidx &\Rightarrow& \RETURNCALLREF~x \\ &&|&
      \hex{D4}~~l{:}\Blabelidx &\Rightarrow& \BRONNULL~l \\ &&|&
-     \hex{D6}~~l{:}\Blabelidx &\Rightarrow& \BRONNONNULL~l \\
+     \hex{D6}~~l{:}\Blabelidx &\Rightarrow& \BRONNONNULL~l \\ &&|&
+     \hex{FB}~~78{:}\Bu32~~(\NULL_1^?,\NULL_2^?){:}\Bcastflags\\&&&~~~~l{:}\Blabelidx~~\X{ht}_1{:}\Bheaptype~~\X{ht}_2{:}\Bheaptype &\Rightarrow& \BRONCAST~l~(\REF~\NULL_1^?~\X{ht}_1)~(\REF~\NULL_2^?~\X{ht}_2) \\ &&|&
+     \hex{FB}~~79{:}\Bu32~~(\NULL_1^?,\NULL_2^?){:}\Bcastflags\\&&&~~~~l{:}\Blabelidx~~\X{ht}_1{:}\Bheaptype~~\X{ht}_2{:}\Bheaptype &\Rightarrow& \BRONCASTFAIL~l~(\REF~\NULL_1^?~\X{ht}_1)~(\REF~\NULL_2^?~\X{ht}_2) \\
+   \production{cast flags} & \Bcastflags &::=&
+     0{:}\Bu8 &\Rightarrow& (\epsilon, \epsilon) \\ &&|&
+     1{:}\Bu8 &\Rightarrow& (\NULL, \epsilon) \\ &&|&
+     2{:}\Bu8 &\Rightarrow& (\epsilon, \NULL) \\ &&|&
+     3{:}\Bu8 &\Rightarrow& (\NULL, \NULL) \\
    \end{array}
 
 .. note::
@@ -90,23 +100,73 @@ Control Instructions
 Reference Instructions
 ~~~~~~~~~~~~~~~~~~~~~~
 
-:ref:`Reference instructions <syntax-instr-ref>` are represented by single byte codes.
+Generic :ref:`reference instructions <syntax-instr-ref>` are represented by single byte codes, others use prefixes and type operands.
 
 .. _binary-ref.null:
 .. _binary-ref.func:
 .. _binary-ref.is_null:
 .. _binary-ref.as_non_null:
+.. _binary-struct.new:
+.. _binary-struct.new_default:
+.. _binary-struct.get:
+.. _binary-struct.get_s:
+.. _binary-struct.get_u:
+.. _binary-struct.set:
+.. _binary-array.new:
+.. _binary-array.new_default:
+.. _binary-array.new_fixed:
+.. _binary-array.new_elem:
+.. _binary-array.new_data:
+.. _binary-array.get:
+.. _binary-array.get_s:
+.. _binary-array.get_u:
+.. _binary-array.set:
+.. _binary-array.len:
+.. _binary-i31.new:
+.. _binary-i31.get_s:
+.. _binary-i31.get_u:
+.. _binary-ref.test:
+.. _binary-ref.cast:
+.. _binary-extern.internalize:
+.. _binary-extern.externalize:
 
 .. math::
    \begin{array}{llclll}
    \production{instruction} & \Binstr &::=& \dots \\ &&|&
      \hex{D0}~~t{:}\Bheaptype &\Rightarrow& \REFNULL~t \\ &&|&
      \hex{D1} &\Rightarrow& \REFISNULL \\ &&|&
      \hex{D2}~~x{:}\Bfuncidx &\Rightarrow& \REFFUNC~x \\ &&|&
-     \hex{D3} &\Rightarrow& \REFASNONNULL \\
+     \hex{D3} &\Rightarrow& \REFASNONNULL \\ &&|&
+     \hex{D5} &\Rightarrow& \REFEQ \\ &&|&
+     \hex{FB}~~1{:}\Bu32~~x{:}\Btypeidx &\Rightarrow& \STRUCTNEW~x \\ &&|&
+     \hex{FB}~~2{:}\Bu32~~x{:}\Btypeidx &\Rightarrow& \STRUCTNEWDEFAULT~x \\ &&|&
+     \hex{FB}~~3{:}\Bu32~~x{:}\Btypeidx~~i{:}\Bu32 &\Rightarrow& \STRUCTGET~x~i \\ &&|&
+     \hex{FB}~~4{:}\Bu32~~x{:}\Btypeidx~~i{:}\Bu32 &\Rightarrow& \STRUCTGETS~x~i \\ &&|&
+     \hex{FB}~~5{:}\Bu32~~x{:}\Btypeidx~~i{:}\Bu32 &\Rightarrow& \STRUCTGETU~x~i \\ &&|&
+     \hex{FB}~~6{:}\Bu32~~x{:}\Btypeidx~~i{:}\Bu32 &\Rightarrow& \STRUCTSET~x~i \\ &&|&
+     \hex{FB}~~17{:}\Bu32~~x{:}\Btypeidx &\Rightarrow& \ARRAYNEW~x \\ &&|&
+     \hex{FB}~~18{:}\Bu32~~x{:}\Btypeidx &\Rightarrow& \ARRAYNEWDEFAULT~x \\ &&|&
+     \hex{FB}~~19{:}\Bu32~~x{:}\Btypeidx &\Rightarrow& \ARRAYGET~x \\ &&|&
+     \hex{FB}~~20{:}\Bu32~~x{:}\Btypeidx &\Rightarrow& \ARRAYGETS~x \\ &&|&
+     \hex{FB}~~21{:}\Bu32~~x{:}\Btypeidx &\Rightarrow& \ARRAYGETU~x \\ &&|&
+     \hex{FB}~~22{:}\Bu32~~x{:}\Btypeidx &\Rightarrow& \ARRAYSET~x \\ &&|&
+     \hex{FB}~~23{:}\Bu32 &\Rightarrow& \ARRAYLEN \\ &&|&
+     \hex{FB}~~25{:}\Bu32~~x{:}\Btypeidx~~n{:}\Bu32 &\Rightarrow& \ARRAYNEWFIXED~x~n \\ &&|&
+     \hex{FB}~~27{:}\Bu32~~x{:}\Btypeidx~~y{:}\Bdataidx &\Rightarrow& \ARRAYNEWDATA~x~y \\ &&|&
+     \hex{FB}~~28{:}\Bu32~~x{:}\Btypeidx~~y{:}\Belemidx &\Rightarrow& \ARRAYNEWELEM~x~y \\ &&|&
+     \hex{FB}~~32{:}\Bu32 &\Rightarrow& \I31NEW \\ &&|&
+     \hex{FB}~~33{:}\Bu32 &\Rightarrow& \I31GETS \\ &&|&
+     \hex{FB}~~34{:}\Bu32 &\Rightarrow& \I31GETU \\ &&|&
+     \hex{FB}~~64{:}\Bu32~~\X{ht}{:}\Bheaptype &\Rightarrow& \REFTEST~(\REF~\X{ht}) \\ &&|&
+     \hex{FB}~~65{:}\Bu32~~\X{ht}{:}\Bheaptype &\Rightarrow& \REFCAST~(\REF~\X{ht}) \\ &&|&
+     \hex{FB}~~72{:}\Bu32~~\X{ht}{:}\Bheaptype &\Rightarrow& \REFTEST~(\REF~\NULL~\X{ht}) \\ &&|&
+     \hex{FB}~~73{:}\Bu32~~\X{ht}{:}\Bheaptype &\Rightarrow& \REFCAST~(\REF~\NULL~\X{ht}) \\ &&|&
+     \hex{FB}~~112{:}\Bu32 &\Rightarrow& \EXTERNINTERNALIZE \\ &&|&
+     \hex{FB}~~113{:}\Bu32 &\Rightarrow& \EXTERNEXTERNALIZE \\
    \end{array}
 
 
+
 .. index:: parametric instruction, value type, polymorphism
    pair: binary format; instruction
 .. _binary-instr-parametric:

document/core/binary/modules.rst

@@ -127,7 +127,7 @@ Their contents consist of a :ref:`name <syntax-name>` further identifying the cu
    If an implementation interprets the data of a custom section, then errors in that data, or the placement of the section, must not invalidate the module.
 
 
-.. index:: ! type section, type definition
+.. index:: ! type section, type definition, recursive type
    pair: binary format; type section
    pair: section; type
 .. _binary-typedef:
@@ -137,12 +137,12 @@ Type Section
 ~~~~~~~~~~~~
 
 The *type section* has the id 1.
-It decodes into a vector of :ref:`function types <syntax-functype>` that represent the |MTYPES| component of a :ref:`module <syntax-module>`.
+It decodes into a vector of :ref:`recursive types <syntax-rectype>` that represent the |MTYPES| component of a :ref:`module <syntax-module>`.
 
 .. math::
    \begin{array}{llclll}
    \production{type section} & \Btypesec &::=&
-     \X{ft}^\ast{:\,}\Bsection_1(\Bvec(\Bfunctype)) &\Rightarrow& \X{ft}^\ast \\
+     \X{rt}^\ast{:\,}\Bsection_1(\Bvec(\Brectype)) &\Rightarrow& \X{rt}^\ast \\
    \end{array}
 
 
@@ -525,7 +525,7 @@ Furthermore, it must be present if any :ref:`data index <syntax-dataidx>` occurs
      \Bmagic \\ &&&
      \Bversion \\ &&&
      \Bcustomsec^\ast \\ &&&
-     \functype^\ast{:\,}\Btypesec \\ &&&
+     \rectype^\ast{:\,}\Btypesec \\ &&&
      \Bcustomsec^\ast \\ &&&
      \import^\ast{:\,}\Bimportsec \\ &&&
      \Bcustomsec^\ast \\ &&&
@@ -551,7 +551,7 @@ Furthermore, it must be present if any :ref:`data index <syntax-dataidx>` occurs
      \Bcustomsec^\ast
      \quad\Rightarrow\quad \{~
        \begin{array}[t]{@{}l@{}}
-       \MTYPES~\functype^\ast, \\
+       \MTYPES~\rectype^\ast, \\
        \MFUNCS~\func^n, \\
        \MTABLES~\table^\ast, \\
        \MMEMS~\mem^\ast, \\

document/core/binary/types.rst

@@ -48,6 +48,7 @@ Vector Types
 .. index:: heap type
    pair: binary format; heap type
 .. _binary-heaptype:
+.. _binary-absheaptype:
 
 Heap Types
 ~~~~~~~~~~
@@ -56,9 +57,19 @@ Heap Types
 
 .. math::
    \begin{array}{llclll@{\qquad\qquad}l}
-   \production{heap type} & \Bheaptype &::=&
+   \production{abstract heap type} & \Babsheaptype &::=&
+     \hex{65} &\Rightarrow& \NONE \\ &&|&
+     \hex{66} &\Rightarrow& \ARRAY \\ &&|&
+     \hex{67} &\Rightarrow& \STRUCT \\ &&|&
+     \hex{68} &\Rightarrow& \NOEXTERN \\ &&|&
+     \hex{69} &\Rightarrow& \NOFUNC \\ &&|&
+     \hex{6A} &\Rightarrow& \I31 \\ &&|&
+     \hex{6D} &\Rightarrow& \EQT \\ &&|&
+     \hex{6E} &\Rightarrow& \ANY \\ &&|&
      \hex{6F} &\Rightarrow& \EXTERN \\ &&|&
-     \hex{70} &\Rightarrow& \FUNC \\ &&|&
+     \hex{70} &\Rightarrow& \FUNC \\
+   \production{heap type} & \Bheaptype &::=&
+     \X{ht}{:}\Babsheaptype &\Rightarrow& \X{ht} \\ &&|&
      x{:}\Bs33 &\Rightarrow& x & (\iff x \geq 0) \\
    \end{array}
 
@@ -70,15 +81,14 @@ Heap Types
 Reference Types
 ~~~~~~~~~~~~~~~
 
-:ref:`Reference types <syntax-reftype>` are either encoded by a single byte followed by a :ref:`heap type <binary-heaptype>`, or, as a short form, directly as a non-index heap type.
+:ref:`Reference types <syntax-reftype>` are either encoded by a single byte followed by a :ref:`heap type <binary-heaptype>`, or, as a short form, directly as an :ref:`abstract heap type <binary-absheaptype>`.
 
 .. math::
    \begin{array}{llclll@{\qquad\qquad}l}
    \production{reference type} & \Breftype &::=&
      \hex{6B}~~\X{ht}{:}\Bheaptype &\Rightarrow& \REF~\X{ht} \\ &&|&
      \hex{6C}~~\X{ht}{:}\Bheaptype &\Rightarrow& \REF~\NULL~\X{ht} \\ &&|&
-     \hex{6F} &\Rightarrow& \EXTERNREF \\ &&|&
-     \hex{70} &\Rightarrow& \FUNCREF \\
+     \X{ht}{:}\Babsheaptype &\Rightarrow& \REF~\NULL~\X{ht} \\
    \end{array}
 
 
@@ -129,16 +139,109 @@ Result Types
 Function Types
 ~~~~~~~~~~~~~~
 
-:ref:`Function types <syntax-functype>` are encoded by the byte :math:`\hex{60}` followed by the respective :ref:`vectors <binary-vec>` of parameter and result types.
+:ref:`Function types <syntax-functype>` are encoded by the respective :ref:`vectors <binary-vec>` of parameter and result types.
 
 .. math::
    \begin{array}{llclll@{\qquad\qquad}l}
    \production{function type} & \Bfunctype &::=&
-     \hex{60}~~\X{rt}_1{:\,}\Bresulttype~~\X{rt}_2{:\,}\Bresulttype
+     \X{rt}_1{:\,}\Bresulttype~~\X{rt}_2{:\,}\Bresulttype
        &\Rightarrow& \X{rt}_1 \to \X{rt}_2 \\
    \end{array}
 
 
+.. index:: aggregate type, value type, structure type, array type, field type, storage type, packed type, mutability
+   pair: binary format; aggregate type
+   pair: binary format; structure type
+   pair: binary format; array type
+   pair: binary format; field type
+   pair: binary format; storage type
+   pair: binary format; packed type
+.. _binary-aggrtype:
+.. _binary-structtype:
+.. _binary-arraytype:
+.. _binary-fieldtype:
+.. _binary-storagetype:
+.. _binary-packedtype:
+
+Aggregate Types
+~~~~~~~~~~~~~~~
+
+:ref:`Aggregate types <syntax-aggrtype>` are encoded with their respective :ref:`field types <syntax-fieldtype>`.
+
+.. math::
+   \begin{array}{llclll@{\qquad\qquad}l}
+   \production{array type} & \Barraytype &::=&
+     \X{ft}{:\,}\Bfieldtype
+       &\Rightarrow& \X{ft} \\
+   \production{structure type} & \Bstructtype &::=&
+     \X{ft}^\ast{:\,}\Bvec(\Bfieldtype)
+       &\Rightarrow& \X{ft}^\ast \\
+   \production{field type} & \Bfieldtype &::=&
+     \X{st}{:}\Bstoragetype~~m{:}\Bmut
+       &\Rightarrow& m~\X{st} \\
+   \production{storage type} & \Bstoragetype &::=&
+     t{:}\Bvaltype
+       &\Rightarrow& t \\ &&|&
+     t{:}\Bpackedtype
+       &\Rightarrow& t \\
+   \production{packed type} & \Bpackedtype &::=&
+     \hex{7A}
+       &\Rightarrow& \I8 \\ &&|&
+     \hex{79}
+       &\Rightarrow& \I16 \\
+   \end{array}
+
+
+.. index:: compound type, structure type, array type, function type
+   pair: binary format; compound type
+.. _binary-comptype:
+
+Compound Types
+~~~~~~~~~~~~~~
+
+:ref:`Compound types <syntax-comptype>` are encoded by a distinct byte followed by a type encoding of the respective form.
+
+.. math::
+   \begin{array}{llclll@{\qquad\qquad}l}
+   \production{compound type} & \Bcomptype &::=&
+     \hex{5E}~~\X{at}{:}\Barraytype
+       &\Rightarrow& \TARRAY~\X{at} \\ &&|&
+     \hex{5F}~~\X{st}{:}\Bstructtype
+       &\Rightarrow& \TSTRUCT~\X{st} \\ &&|&
+     \hex{60}~~\X{ft}{:}\Bfunctype
+       &\Rightarrow& \TFUNC~\X{ft} \\
+   \end{array}
+
+
+.. index:: recursive type, sub type, compound type
+   pair: binary format; recursive type
+   pair: binary format; sub type
+.. _binary-rectype:
+.. _binary-subtype:
+
+Recursive Types
+~~~~~~~~~~~~~~~
+
+:ref:`Recursive types <syntax-rectype>` are encoded by the byte :math:`\hex{31}` followed by a :ref:`vector <binary-vec>` of :ref:`sub types <syntax-subtype>`.
+Additional shorthands are recognized for unary recursions and sub types without super types.
+
+.. math::
+   \begin{array}{llclll@{\qquad\qquad}l}
+   \production{recursive type} & \Brectype &::=&
+     \hex{4F}~~\X{st}^\ast{:\,}\Bvec(\Bsubtype)
+       &\Rightarrow& \TREC~\X{st}^\ast \\ &&|&
+     \X{st}{:}\Bsubtype
+       &\Rightarrow& \TREC~\X{st} \\
+   \production{sub type} & \Bsubtype &::=&
+     \hex{50}~~x^\ast{:\,}\Bvec(\Btypeidx)~~\X{ct}{:}\Bcomptype
+       &\Rightarrow& \TSUB~x^\ast~\X{ct} \\ &&|&
+     \hex{4E}~~x^\ast{:\,}\Bvec(\Btypeidx)~~\X{ct}{:}\Bcomptype
+       &\Rightarrow& \TSUB~\TFINAL~x^\ast~\X{ct} \\ &&|&
+     \X{ct}{:}\Bcomptype
+       &\Rightarrow& \TSUB~\TFINAL~\epsilon~\X{ct} \\
+   \end{array}
+
+
 .. index:: limits
    pair: binary format; limits
 .. _binary-limits:

document/core/util/macros.def

@@ -689,11 +689,20 @@
 .. |Bnumtype| mathdef:: \xref{binary/types}{binary-numtype}{\B{numtype}}
 .. |Bvectype| mathdef:: \xref{binary/types}{binary-vectype}{\B{vectype}}
 .. |Bheaptype| mathdef:: \xref{binary/types}{binary-heaptype}{\B{heaptype}}
+.. |Babsheaptype| mathdef:: \xref{binary/types}{binary-absheaptype}{\B{absheaptype}}
 .. |Breftype| mathdef:: \xref{binary/types}{binary-reftype}{\B{reftype}}
 .. |Bvaltype| mathdef:: \xref{binary/types}{binary-valtype}{\B{valtype}}
 .. |Bresulttype| mathdef:: \xref{binary/types}{binary-resulttype}{\B{resulttype}}
 .. |Bfunctype| mathdef:: \xref{binary/types}{binary-functype}{\B{functype}}
-.. |Bdeftype| mathdef:: \xref{binary/types}{binary-deftype}{\B{deftype}}
+.. |Bstructtype| mathdef:: \xref{binary/types}{binary-structtype}{\B{structtype}}
+.. |Barraytype| mathdef:: \xref{binary/types}{binary-arraytype}{\B{arraytype}}
+.. |Baggrtype| mathdef:: \xref{binary/types}{binary-aggrtype}{\B{aggrtype}}
+.. |Bfieldtype| mathdef:: \xref{binary/types}{binary-fieldtype}{\B{fieldtype}}
+.. |Bstoragetype| mathdef:: \xref{binary/types}{binary-storagetype}{\B{storagetype}}
+.. |Bpackedtype| mathdef:: \xref{binary/types}{binary-packedtype}{\B{packedtype}}
+.. |Bcomptype| mathdef:: \xref{binary/types}{binary-comptype}{\B{comptype}}
+.. |Bsubtype| mathdef:: \xref{binary/types}{binary-subtype}{\B{subtype}}
+.. |Brectype| mathdef:: \xref{binary/types}{binary-rectype}{\B{rectype}}
 .. |Bglobaltype| mathdef:: \xref{binary/types}{binary-globaltype}{\B{globaltype}}
 .. |Btabletype| mathdef:: \xref{binary/types}{binary-tabletype}{\B{tabletype}}
 .. |Bmemtype| mathdef:: \xref{binary/types}{binary-memtype}{\B{memtype}}
@@ -759,6 +768,7 @@
 
 .. |Bmemarg| mathdef:: \xref{binary/instructions}{binary-memarg}{\B{memarg}}
 .. |Bblocktype| mathdef:: \xref{binary/instructions}{binary-blocktype}{\B{blocktype}}
+.. |Bcastflags| mathdef:: \xref{binary/instructions}{binary-castflags}{\B{castflags}}
 
 .. |Binstr| mathdef:: \xref{binary/instructions}{binary-instr}{\B{instr}}
 .. |Bexpr| mathdef:: \xref{binary/instructions}{binary-expr}{\B{expr}}

interpreter/binary/decode.ml

@@ -385,9 +385,7 @@ let rec instr s =
   | 0x14 -> call_ref (at var s)
   | 0x15 -> return_call_ref (at var s)
 
-  | 0x16 as b -> illegal s pos b
-
-  | 0x17 | 0x18 | 0x19 as b -> illegal s pos b
+  | 0x16 | 0x17 | 0x18 | 0x19 as b -> illegal s pos b
 
   | 0x1a -> drop
   | 0x1b -> select None