Merge pull request #122 from WebAssembly/merge-upstream2

Author: rossberg

.travis.yml

@@ -6,15 +6,21 @@ dist: bionic
 addons:
   apt:
     sources:
+      - sourceline: 'ppa:avsm/ppa'
       - sourceline: 'deb https://dl.yarnpkg.com/debian/ stable main'
         key_url: 'https://dl.yarnpkg.com/debian/pubkey.gpg'
+    update: true
     packages:
-      - ocaml
-      - ocamlbuild
+      - opam
       - texlive-full
       - yarn
 
 install:
+  - opam init --auto-setup --compiler=4.07.1
+  - eval $(opam env)
+  - opam --version
+  - ocaml --version
+  - opam install --yes ocamlbuild.0.14.0
   - pip install Sphinx==2.4.4
   - git clone https://github.com/tabatkins/bikeshed.git
   - pip install --editable $PWD/bikeshed

README.md

@@ -34,3 +34,7 @@ should take place in
 [the WebAssembly design repository](https://github.com/WebAssembly/design)
 first, so that this spec repository can remain focused. And please follow the
 [guidelines for contributing](Contributing.md).
+
+# citing
+
+For citing WebAssembly in LaTeX, use [this bibtex file](wasm-specs.bib).

document/README.md

@@ -21,3 +21,98 @@ To build everything and update [webassembly.github.io/spec](https://webassembly.
 make publish
 ```
 Please make sure to only use that once a change has approval.
+
+## Step by step guide to building the spec
+
+### Prerequisites
+
+You will need `python3.7`, and `pip`. `pip` should come with Python, if not follow [these installation instructions for `pip`](https://pip.pypa.io/en/stable/installing/), or check your system package manager for `pip3`.
+
+> Important: you will need the version of pip that works with `python3.7`.
+
+
+Use something like [`pipenv`](https://pipenv.pypa.io/) to keep your system installation of Python clean.
+
+```
+pip install pipenv
+pipenv --python 3.7
+pipenv shell
+```
+
+Install Python dependencies:
+
+```
+pip install Sphinx==2.4.4
+```
+
+### Checking out the repository
+
+Make sure this repository was cloned with `--recursive`:
+
+```
+git clone --recursive https://github.com/WebAssembly/spec
+```
+
+If you have already cloned but without `--recursive`, you can delete and re-clone, or `cd` into `spec` and run:
+
+```
+git submodule update --init --recursive
+```
+
+The rest of these instructions assume you are in the directory where is README is:
+
+```
+cd spec/document
+```
+
+### Building the multi-page HTML document
+
+You can now build the [multi-page html document](https://webassembly.github.io/spec/core/):
+
+```
+make -C core html
+```
+
+### Building the single-page HTML document
+
+To build the [single-page W3C version](https://webassembly.github.io/spec/core/bikeshed/), there are more dependencies to install. First, get [Bikeshed](https://github.com/tabatkins/bikeshed):
+
+```
+# cd back to root of git directory
+git clone https://github.com/tabatkins/bikeshed.git
+pip install --editable bikeshed
+bikeshed update
+```
+
+You will also need `npm` and `yarn` for all the LaTeX goodness. `npm` might already be available on your system, you can also use something like [`nvm`](https://github.com/nvm-sh/nvm) to prevent messing with system packages:
+
+```
+npm install -g yarn
+cd document/core
+make -C core bikeshed
+```
+
+### Building the PDF
+
+To build the [PDF](https://webassembly.github.io/spec/core/_download/WebAssembly.pdf), you will need `texlive-full`, install it using your system package manager:
+
+```
+apt install texlive-full
+make -C core pdf
+```
+
+### Building the JavaScript Embedding API
+
+To build the [JavaScript Embedding API](https://webassembly.github.io/spec/js-api/index.html), you will need `bikeshed` as describe in the section [Building the single-page HTML document](#building-the-single-page-html-document):
+
+```
+make -C js-api
+```
+
+### Building the Web Embedding API
+
+To build the [Web Embedding API](https://webassembly.github.io/spec/web-api/index.html), you will need `bikeshed` as describe in the section [Building the single-page HTML document](#building-the-single-page-html-document):
+
+```
+make -C web-api
+```

document/core/Makefile

@@ -89,8 +89,12 @@ bikeshed-keep:
 	  echo Downloaded Bikeshed.
 
 
+.PHONY: index
+index:
+	(cd appendix; ./gen-index-instructions.py)
+
 .PHONY: pdf
-pdf:	latexpdf
+pdf:	index latexpdf
 	mkdir -p $(BUILDDIR)/html/$(DOWNLOADDIR)
 	ln -f $(BUILDDIR)/latex/$(NAME).pdf $(BUILDDIR)/html/$(DOWNLOADDIR)/$(NAME).pdf
 
@@ -101,7 +105,7 @@ clean:
 	rm -rf $(STATICDIR)
 
 .PHONY: html
-html:
+html: index
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	for file in `ls $(BUILDDIR)/html/*.html`; \
 	do \

document/core/appendix/gen-index-instructions.py

@@ -168,12 +168,12 @@ Table Instructions
    \production{instruction} & \Binstr &::=& \dots \\ &&|&
      \hex{25}~~x{:}\Btableidx &\Rightarrow& \TABLEGET~x \\ &&|&
      \hex{26}~~x{:}\Btableidx &\Rightarrow& \TABLESET~x \\ &&|&
-     \hex{FC}~\hex{0F}~~x{:}\Btableidx &\Rightarrow& \TABLEGROW~x \\ &&|&
-     \hex{FC}~\hex{10}~~x{:}\Btableidx &\Rightarrow& \TABLESIZE~x \\ &&|&
-     \hex{FC}~\hex{11}~~x{:}\Btableidx &\Rightarrow& \TABLEFILL~x \\
-     \hex{FC}~\hex{0C}~~y{:}\Belemidx~~x{:}\Btableidx &\Rightarrow& \TABLEINIT~x~y \\ &&|&
-     \hex{FC}~\hex{0D}~~x{:}\Belemidx &\Rightarrow& \ELEMDROP~x \\ &&|&
-     \hex{FC}~\hex{0E}~~x{:}\Btableidx~~y{:}\Btableidx &\Rightarrow& \TABLECOPY~x~y \\
+     \hex{FC}~~12{:}\Bu32~~y{:}\Belemidx~~x{:}\Btableidx &\Rightarrow& \TABLEINIT~x~y \\ &&|&
+     \hex{FC}~~13{:}\Bu32~~x{:}\Belemidx &\Rightarrow& \ELEMDROP~x \\ &&|&
+     \hex{FC}~~14{:}\Bu32~~x{:}\Btableidx~~y{:}\Btableidx &\Rightarrow& \TABLECOPY~x~y \\
+     \hex{FC}~~15{:}\Bu32~~x{:}\Btableidx &\Rightarrow& \TABLEGROW~x \\ &&|&
+     \hex{FC}~~16{:}\Bu32~~x{:}\Btableidx &\Rightarrow& \TABLESIZE~x \\ &&|&
+     \hex{FC}~~17{:}\Bu32~~x{:}\Btableidx &\Rightarrow& \TABLEFILL~x \\
    \end{array}
 
 
@@ -228,10 +228,10 @@ Each variant of :ref:`memory instruction <syntax-instr-memory>` is encoded with
      \hex{3E}~~m{:}\Bmemarg &\Rightarrow& \I64.\STORE\K{32}~m \\ &&|&
      \hex{3F}~~\hex{00} &\Rightarrow& \MEMORYSIZE \\ &&|&
      \hex{40}~~\hex{00} &\Rightarrow& \MEMORYGROW \\ &&|&
-     \hex{FC}~\hex{08}~~x{:}\Bdataidx~~\hex{00} &\Rightarrow& \MEMORYINIT~x \\ &&|&
-     \hex{FC}~\hex{09}~~x{:}\Bdataidx &\Rightarrow& \DATADROP~x \\ &&|&
-     \hex{FC}~\hex{0A}~~\hex{00}~~\hex{00} &\Rightarrow& \MEMORYCOPY \\ &&|&
-     \hex{FC}~\hex{0B}~~\hex{00} &\Rightarrow& \MEMORYFILL \\
+     \hex{FC}~~8{:}\Bu32~~x{:}\Bdataidx~\hex{00} &\Rightarrow& \MEMORYINIT~x \\ &&|&
+     \hex{FC}~~9{:}\Bu32~~x{:}\Bdataidx &\Rightarrow& \DATADROP~x \\ &&|&
+     \hex{FC}~~10{:}\Bu32~~\hex{00}~~\hex{00} &\Rightarrow& \MEMORYCOPY \\ &&|&
+     \hex{FC}~~11{:}\Bu32~~\hex{00} &\Rightarrow& \MEMORYFILL \\
    \end{array}
 
 .. note::
@@ -438,24 +438,6 @@ All other numeric instructions are plain opcodes without any immediates.
      \hex{BF} &\Rightarrow& \F64.\REINTERPRET\K{\_}\I64 \\
    \end{array}
 
-.. _binary-cvtop-trunc-sat:
-
-The saturating truncation instructions all have a one byte prefix.
-
-.. math::
-   \begin{array}{llclll}
-   \production{instruction} & \Binstr &::=& \dots && \phantom{thisshouldbeenough} \\&&|&
-     \hex{FC}~\hex{00} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F32\K{\_s} \\ &&|&
-     \hex{FC}~\hex{01} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F32\K{\_u} \\ &&|&
-     \hex{FC}~\hex{02} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F64\K{\_s} \\ &&|&
-     \hex{FC}~\hex{03} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F64\K{\_u} \\ &&|&
-     \hex{FC}~\hex{04} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F32\K{\_s} \\ &&|&
-     \hex{FC}~\hex{05} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F32\K{\_u} \\ &&|&
-     \hex{FC}~\hex{06} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F64\K{\_s} \\ &&|&
-     \hex{FC}~\hex{07} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F64\K{\_u} \\
-   \end{array}
-
-
 .. math::
    \begin{array}{llclll}
    \phantom{\production{instruction}} & \phantom{\Binstr} &\phantom{::=}& \phantom{\dots} && \phantom{thisshouldbeenough} \\[-2ex] &&|&
@@ -466,6 +448,24 @@ The saturating truncation instructions all have a one byte prefix.
      \hex{C4} &\Rightarrow& \I64.\EXTEND\K{32\_s} \\
    \end{array}
 
+.. _binary-cvtop-trunc-sat:
+
+The saturating truncation instructions all have a one byte prefix,
+whereas the actual opcode is encoded by a variable-length :ref:`unsigned integer <binary-uint>`.
+
+.. math::
+   \begin{array}{llclll}
+   \production{instruction} & \Binstr &::=& \dots && \phantom{thisshouldbeenough} \\&&|&
+     \hex{FC}~~0{:}\Bu32 &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F32\K{\_s} \\ &&|&
+     \hex{FC}~~1{:}\Bu32 &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F32\K{\_u} \\ &&|&
+     \hex{FC}~~2{:}\Bu32 &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F64\K{\_s} \\ &&|&
+     \hex{FC}~~3{:}\Bu32 &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F64\K{\_u} \\ &&|&
+     \hex{FC}~~4{:}\Bu32 &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F32\K{\_s} \\ &&|&
+     \hex{FC}~~5{:}\Bu32 &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F32\K{\_u} \\ &&|&
+     \hex{FC}~~6{:}\Bu32 &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F64\K{\_s} \\ &&|&
+     \hex{FC}~~7{:}\Bu32 &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F64\K{\_u} \\
+   \end{array}
+
 
 .. index:: expression
    pair: binary format; expression

document/core/appendix/index-instructions.rst

@@ -1058,12 +1058,14 @@ This non-deterministic result is expressed by the following auxiliary function p
 
 * If :math:`z` is a NaN, then return an element of :math:`\nans_N\{z\}`.
 
-* Else if :math:`z` has a negative sign, then return an element of :math:`\nans_N\{\}`.
+* Else if :math:`z` is negative infinity, then return an element of :math:`\nans_N\{\}`.
 
 * Else if :math:`z` is positive infinity, then return positive infinity.
 
 * Else if :math:`z` is a zero, then return that zero.
 
+* Else if :math:`z` has a negative sign, then return an element of :math:`\nans_N\{\}`.
+
 * Else return the square root of :math:`z`.
 
 .. math::
@@ -1601,7 +1603,7 @@ Conversions
 
 .. math::
    \begin{array}{lll@{\qquad}l}
-   \convertu_{M,N}(i) &=& \ieee_N(\signed_M(i)) \\
+   \converts_{M,N}(i) &=& \ieee_N(\signed_M(i)) \\
    \end{array}
 
 

document/core/binary/instructions.rst

@@ -494,6 +494,8 @@ and a reference to the function's own :ref:`module instance <syntax-moduleinst>`
 The values of the locals are mutated by respective :ref:`variable instructions <syntax-instr-variable>`.
 
 
+.. _exec-expand:
+
 Conventions
 ...........
 

document/core/exec/numerics.rst

@@ -8,7 +8,7 @@ TR: https://www.w3.org/TR/wasm-core-1/
 ED: https://webassembly.github.io/spec/core/bikeshed/
 Editor: Andreas Rossberg (Dfinity Stiftung)
 Repository: WebAssembly/spec
-Markup Shorthands: css no, markdown yes, algorithm no, idl no
+Markup Shorthands: css no, markdown no, algorithm no, idl no
 Abstract: This document describes version 1.0 of the core WebAssembly standard, a safe, portable, low-level code format designed for efficient execution and compact representation.
 Prepare For TR: true
 </pre>

document/core/exec/runtime.rst

@@ -22,11 +22,6 @@ The following sections group instructions into a number of different categories.
    pair: abstract syntax; instruction
 .. _syntax-sx:
 .. _syntax-const:
-.. _syntax-unop:
-.. _syntax-binop:
-.. _syntax-testop:
-.. _syntax-relop:
-.. _syntax-cvtop:
 .. _syntax-iunop:
 .. _syntax-ibinop:
 .. _syntax-itestop:
@@ -144,6 +139,12 @@ where a signedness annotation |sx| distinguishes whether the operands are to be
 For the other integer instructions, the use of two's complement for the signed interpretation means that they behave the same regardless of signedness.
 
 
+.. _syntax-unop:
+.. _syntax-binop:
+.. _syntax-testop:
+.. _syntax-relop:
+.. _syntax-cvtop:
+
 Conventions
 ...........
 

document/core/index.bs

@@ -492,20 +492,20 @@ Numeric Instructions
      \text{i32.trunc\_f32\_u} &\Rightarrow& \I32.\TRUNC\K{\_}\F32\K{\_u} \\ &&|&
      \text{i32.trunc\_f64\_s} &\Rightarrow& \I32.\TRUNC\K{\_}\F64\K{\_s} \\ &&|&
      \text{i32.trunc\_f64\_u} &\Rightarrow& \I32.\TRUNC\K{\_}\F64\K{\_u} \\ &&|&
-     \text{i32.trunc\_sat_f32\_s} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F32\K{\_s} \\ &&|&
-     \text{i32.trunc\_sat_f32\_u} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F32\K{\_u} \\ &&|&
-     \text{i32.trunc\_sat_f64\_s} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F64\K{\_s} \\ &&|&
-     \text{i32.trunc\_sat_f64\_u} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F64\K{\_u} \\ &&|&
+     \text{i32.trunc\_sat\_f32\_s} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F32\K{\_s} \\ &&|&
+     \text{i32.trunc\_sat\_f32\_u} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F32\K{\_u} \\ &&|&
+     \text{i32.trunc\_sat\_f64\_s} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F64\K{\_s} \\ &&|&
+     \text{i32.trunc\_sat\_f64\_u} &\Rightarrow& \I32.\TRUNC\K{\_sat\_}\F64\K{\_u} \\ &&|&
      \text{i64.extend\_i32\_s} &\Rightarrow& \I64.\EXTEND\K{\_}\I32\K{\_s} \\ &&|&
      \text{i64.extend\_i32\_u} &\Rightarrow& \I64.\EXTEND\K{\_}\I32\K{\_u} \\ &&|&
      \text{i64.trunc\_f32\_s} &\Rightarrow& \I64.\TRUNC\K{\_}\F32\K{\_s} \\ &&|&
      \text{i64.trunc\_f32\_u} &\Rightarrow& \I64.\TRUNC\K{\_}\F32\K{\_u} \\ &&|&
      \text{i64.trunc\_f64\_s} &\Rightarrow& \I64.\TRUNC\K{\_}\F64\K{\_s} \\ &&|&
      \text{i64.trunc\_f64\_u} &\Rightarrow& \I64.\TRUNC\K{\_}\F64\K{\_u} \\ &&|&
-     \text{i64.trunc\_sat_f32\_s} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F32\K{\_s} \\ &&|&
-     \text{i64.trunc\_sat_f32\_u} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F32\K{\_u} \\ &&|&
-     \text{i64.trunc\_sat_f64\_s} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F64\K{\_s} \\ &&|&
-     \text{i64.trunc\_sat_f64\_u} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F64\K{\_u} \\ &&|&
+     \text{i64.trunc\_sat\_f32\_s} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F32\K{\_s} \\ &&|&
+     \text{i64.trunc\_sat\_f32\_u} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F32\K{\_u} \\ &&|&
+     \text{i64.trunc\_sat\_f64\_s} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F64\K{\_s} \\ &&|&
+     \text{i64.trunc\_sat\_f64\_u} &\Rightarrow& \I64.\TRUNC\K{\_sat\_}\F64\K{\_u} \\ &&|&
      \text{f32.convert\_i32\_s} &\Rightarrow& \F32.\CONVERT\K{\_}\I32\K{\_s} \\ &&|&
      \text{f32.convert\_i32\_u} &\Rightarrow& \F32.\CONVERT\K{\_}\I32\K{\_u} \\ &&|&
      \text{f32.convert\_i64\_s} &\Rightarrow& \F32.\CONVERT\K{\_}\I64\K{\_s} \\ &&|&

document/core/syntax/instructions.rst

@@ -954,7 +954,7 @@
 
 .. Stack, meta functions
 
-.. |expand| mathdef:: \xref{exec/runtime}{syntax-frame}{\F{expand}}
+.. |expand| mathdef:: \xref{exec/runtime}{exec-expand}{\F{expand}}
 
 
 .. Administrative Instructions, terminals

document/core/text/instructions.rst

@@ -112,7 +112,7 @@ def ReplaceMath(cache, data):
   if p.returncode != 0:
     sys.stderr.write('BEFORE:\n' + old + '\n')
     sys.stderr.write('AFTER:\n' + data + '\n')
-    return ''
+    raise Exception()
   ret = ret.strip()
   ret = ret[ret.find('<span class="katex-html"'):]
   ret = '<span class="katex-display"><span class="katex">' + ret
@@ -225,22 +225,24 @@ def ExtractMath(match):
   sys.stderr.write('Processing %d fragments.\n' % len(fixups))
 
   done_fixups = []
+  success = True
 
   def Worker():
+    nonlocal success
     while True:
       cls_before, cls_after, spans, mth, start, end = q.get()
       try:
         fixed = ('class="' + cls_before + ' ' + cls_after + '">' +
                  spans + ReplaceMath(cache, mth) + '<')
         done_fixups.append((start, end, fixed))
       except Exception:
-        sys.stderr.write('!!! Error processing fragment')
+        success = False
 
       q.task_done()
       sys.stderr.write('.')
 
   q = queue.Queue()
-  for i in range(40):
+  for i in range(len(os.sched_getaffinity(0))):
     t = threading.Thread(target=Worker)
     t.daemon = True
     t.start()
@@ -249,6 +251,11 @@ def Worker():
     q.put(item)
   q.join()
 
+  if not success:
+      sys.stderr.write('\n!!! Error processing fragments\n')
+      cache.close()
+      sys.exit(1)
+
   result = []
   last = 0
   for start, end, value in sorted(done_fixups):