WebAssembly Reference Interpreter
This repository implements an interpreter for WebAssembly. It is written for clarity and simplicity, not speed. It is intended as a playground for trying out ideas and a device for nailing down their exact semantics. For that purpose, the code is written in a fairly declarative, "speccy" way.
The interpreter can
- decode/parse and validate modules in binary or text format
- execute scripts with module definitions, invocations, and assertions
- convert between binary and text format (both directions)
- export test scripts to self-contained JavaScript test cases
- run as an interactive interpreter
The text format defines modules in S-expression syntax. Moreover, it is generalised to a form of script that can define multiples module and a batch of invocations, assertions, and conversions between them. As such it is richer than the binary format, with the additional functionality purely intended as testing infrastructure. (See below for details.)
Building
You'll need OCaml 4.12 or higher. Instructions for installing a recent version of OCaml on multiple platforms are available here. On most platforms, the recommended way is through Opam.
You'll also need to install the dune build system. See the installation instructions.
And you need to install the Menhir parser generator:
opam install menhir
Once you have OCaml, simply do
make
You'll get an executable named ./wasm.
To run the test suite,
make test
To do everything:
make all
Building on Windows
The instructions depend on how you installed OCaml on Windows.
-
Cygwin: If you want to build a native code executable, or want to hack on the interpreter (i.e., use incremental compilation), then you need to install the Cygwin core that is included with the OCaml installer. Then you can build the interpreter using
makein the Cygwin terminal, as described above. -
Windows Subsystem for Linux (WSL): You can build the interpreter using
make, as described above.
In any way, in order to run the test suite you'll need to have Python installed. If you used Option 3, you can invoke the test runner runtests.py directly instead of doing it through make.
Cross-compiling the Interpreter to JavaScript
The Makefile also provides a target to compile (parts of) the interpreter into a JavaScript library:
make wast.js
Building this target requires js_of_ocaml, which can be installed with OPAM:
opam install js_of_ocaml js_of_ocaml-ppx
Synopsis
Running Modules or Scripts
You can call the executable with
wasm [option | file ...]
where file, depending on its extension, either should be a binary (.wasm) or textual (.wat) module file to be loaded, or a script file (.wast, see below) to be run.
By default, the interpreter validates all modules.
The -u option selects "unchecked mode", which skips validation and runs code as is.
Runtime type errors will be captured and reported appropriately.
Converting Modules or Scripts
A file prefixed by -o is taken to be an output file. Depending on its extension, this will write out the preceding module definition in either S-expression or binary format. This option can be used to convert between the two in both directions, e.g.:
wasm -d module.wat -o module.wasm
wasm -d module.wasm -o module.wat
In the second case, the produced script contains exactly one module definition.
The -d option selects "dry mode" and ensures that the input module is not run, even if it has a start section.
In addition, the -u option for "unchecked mode" can be used to convert even modules that do not validate.
The interpreter can also convert entire test scripts:
wasm -d script.wast -o script.bin.wast
wasm -d script.wast -o script2.wast
wasm -d script.wast -o script.js
The first creates a new test scripts where all embedded modules are converted to binary, the second one where all are converted to textual.
The last invocation produces an equivalent, self-contained JavaScript test file.
The flag -h can be used to omit the test harness from the converted file;
it then is the client's responsibility to provide versions of the necessary functions.
Command Line Expressions
Finally, the option -e allows to provide arbitrary script commands directly on the command line. For example:
wasm module.wasm -e '(invoke "foo")'
Interactive Mode
If neither a file nor any of the previous options is given, you'll land in the REPL and can enter script commands interactively. You can also get into the REPL by explicitly passing - as a file name. You can do that in combination to giving a module or script file, so that you can then invoke its exports interactively, e.g.:
wasm module.wat -
See wasm -h for (the few) additional options.
JavaScript Library
The file wast.js generated by the respective Makefile target is a self-contained JavaScript library for making the S-expression syntax available directly within JavaScript.
It provides a global object named WebAssemblyText that currently provides two methods,
WebAssemblyText.encode(source)
which turns a module in S-expression syntax into a WebAssembly binary, and
WebAssemblyText.decode(binary, width)
which pretty-prints a binary back into a canonicalised S-expression string.
For example:
let source = '(module (func (export "f") (param i32 i32) (result i32) (i32.add (local.get 0) (local.get 1))))'
let binary = WebAssemblyText.encode(source)
(new WebAssembly.Instance(new WebAssembly.Module(binary))).exports.f(3, 4)
// => 7
WebAssemblyText.decode(binary, 80)
// =>
// (module
// (type $0 (func (param i32 i32) (result i32)))
// (func $0 (type 0) (local.get 0) (local.get 1) (i32.add))
// (export "f" (func 0))
// )
Depending on how you load the library, the object may be accessed in different ways. For example, using require in node.js:
let wast = require("./wast.js");
let binary = wast.WebAssemblyText.encode("(module)");
Or using load from a JavaScript shell:
load("./wast.js");
let binary = WebAssemblyText.encode("(module)");
S-Expression Syntax
The implementation consumes a WebAssembly AST given in S-expression syntax. Here is an overview of the grammar of types, expressions, functions, and modules, mirroring what's described in the design doc.
Note: The grammar is shown here for convenience, the definite source is the specification of the text format.
num: <digit>(_? <digit>)*
hexnum: <hexdigit>(_? <hexdigit>)*
nat: <num> | 0x<hexnum>
int: <nat> | +<nat> | -<nat>
float: <num>.<num>?(e|E <num>)? | 0x<hexnum>.<hexnum>?(p|P <num>)?
name: $(<letter> | <digit> | _ | . | + | - | * | / | \ | ^ | ~ | = | < | > | ! | ? | @ | # | $ | % | & | | | : | ' | `)+
string: "(<char> | \n | \t | \\ | \' | \" | \<hex><hex> | \u{<hex>+})*"
num: <int> | <float>
var: <nat> | <name>
unop: ctz | clz | popcnt | ...
binop: add | sub | mul | ...
relop: eq | ne | lt | ...
sign: s | u
offset: offset=<nat>
align: align=(1|2|4|8|...)
cvtop: trunc | extend | wrap | ...
castop: data | array | i31
externop: internalize | externalize
num_type: i32 | i64 | f32 | f64
vec_type: v128
vec_shape: i8x16 | i16x8 | i32x4 | i64x2 | f32x4 | f64x2 | v128
heap_type: any | eq | i31 | data | array | func | extern | none | nofunc | noextern | <var> | (rtt <var>)
ref_type:
( ref null? <heap_type> )
( rtt <var> ) ;; = (ref (rtt <var>))
anyref ;; = (ref null any)
eqref ;; = (ref null eq)
i31ref ;; = (ref i31)
dataref ;; = (ref null data)
arrayref ;; = (ref null array)
funcref ;; = (ref null func)
externref ;; = (ref null extern)
nullref ;; = (ref null none)
nullfuncref ;; = (ref null nofunc)
nullexternref ;; = (ref null noextern)
val_type: <num_type> | <vec_type> | <ref_type>
block_type : ( result <val_type>* )*
func_type: ( type <var> )? <param>* <result>*
global_type: <val_type> | ( mut <val_type> )
table_type: <nat> <nat>? <ref_type>
memory_type: <nat> <nat>?
tag_type: ( type <var> )? <param>*
num: <int> | <float>
var: <nat> | <name>
unop: ctz | clz | popcnt | ...
binop: add | sub | mul | ...
testop: eqz
relop: eq | ne | lt | ...
sign: s | u
offset: offset=<nat>
align: align=(1|2|4|8|...)
cvtop: trunc | extend | wrap | ...
vecunop: abs | neg | ...
vecbinop: add | sub | min_<sign> | ...
vecternop: bitselect
vectestop: all_true | any_true
vecrelop: eq | ne | lt | ...
veccvtop: extend_low | extend_high | trunc_sat | ...
vecshiftop: shl | shr_<sign>
expr:
( <op> )
( <op> <expr>+ ) ;; = <expr>+ (<op>)
( block <name>? <block_type> <instr>* )
( loop <name>? <block_type> <instr>* )
( if <name>? <block_type> ( then <instr>* ) ( else <instr>* )? )
( if <name>? <block_type> <expr>+ ( then <instr>* ) ( else <instr>* )? ) ;; = <expr>+ (if <name>? <block_type> (then <instr>*) (else <instr>*)?)
( try_table <name>? <block_type> <catch>* <instr>* )
instr:
<expr>
<op> ;; = (<op>)
block <name>? <block_type> <instr>* end <name>? ;; = (block <name>? <block_type> <instr>*)
loop <name>? <block_type> <instr>* end <name>? ;; = (loop <name>? <block_type> <instr>*)
if <name>? <block_type> <instr>* end <name>? ;; = (if <name>? <block_type> (then <instr>*))
if <name>? <block_type> <instr>* else <name>? <instr>* end <name>? ;; = (if <name>? <block_type> (then <instr>*) (else <instr>*))
try_table <name>? <block_type> <catch>* <instr>* end <name>? ;; = (try_table <name>? <block_type> <catch>* <instr>*)
op:
unreachable
nop
drop
select
br <var>
br_if <var>
br_table <var>+
br_on_null <var>
br_on_non_null <var>
br_on_cast <var> <ref_type> <ref_type>
br_on_cast_fail <var> <ref_type> <ref_type>
call <var>
call_ref <var>
call_indirect <var>? (type <var>)? <func_type>
return
return_call <var>
return_call_ref <var>
return_call_indirect <var>? (type <var>)? <func_type>
throw <tag_type>
throw_ref
local.get <var>
local.set <var>
local.tee <var>
global.get <var>
global.set <var>
table.get <var>?
table.set <var>?
table.size <var>?
table.grow <var>?
table.fill <var>?
table.copy <var>? <var>?
table.init <var>? <var>
elem.drop <var>
<num_type>.load((8|16|32)_<sign>)? <offset>? <align>?
<num_type>.store(8|16|32)? <offset>? <align>?
<vec_type>.load((8x8|16x4|32x2)_<sign>)? <offset>? <align>?
<vec_type>.store <offset>? <align>?
<vec_type>.load(8|16|32|64)_(lane|splat|zero) <offset>? <align>?
<vec_type>.store(8|16|32|64)_lane <offset>? <align>?
memory.size
memory.grow
memory.fill
memory.copy
memory.init <var>
data.drop <var>
ref.null <heap_type>
ref.func <var>
ref.is_null
ref_as_non_null
ref.test <var>
ref.cast <var>
ref.eq
i31.new
i31.get_<sign>
struct.new(_<default>)? <var>
struct.get(_<sign>)? <var> <var>
struct.set <var> <var>
array.new(_<default>)? <var>
array.new_fixed <var> <nat>
array.new_elem <var> <var>
array.new_data <var> <var>
array.get(_<sign>)? <var>
array.set <var>
array.len <var>
extern.<externop>
<num_type>.const <num>
<num_type>.<unop>
<num_type>.<binop>
<num_type>.<testop>
<num_type>.<relop>
<num_type>.<cvtop>_<num_type>(_<sign>)?
<vec_type>.const <vec_shape> <num>+
<vec_shape>.<vecunop>
<vec_shape>.<vecbinop>
<vec_shape>.<vecternop>
<vec_shape>.<vectestop>
<vec_shape>.<vecrelop>
<vec_shape>.<veccvtop>_<vec_shape>(_<sign>)?(_<zero>)?
<vec_shape>.<vecshiftop>
<vec_shape>.bitmask
<vec_shape>.splat
<vec_shape>.extract_lane(_<sign>)? <nat>
<vec_shape>.replace_lane <nat>
catch:
catch <var> <var>
catch_ref <var> <var>
catch_all <var>
catch_all_ref <var>
func: ( func <name>? <func_type> <local>* <instr>* )
( func <name>? ( export <string> ) <...> ) ;; = (export <string> (func <N>)) (func <name>? <...>)
( func <name>? ( import <string> <string> ) <func_type>) ;; = (import <string> <string> (func <name>? <func_type>))
param: ( param <val_type>* ) | ( param <name> <val_type> )
result: ( result <val_type>* )
local: ( local <val_type>* ) | ( local <name> <val_type> )
global: ( global <name>? <global_type> <instr>* )
( global <name>? ( export <string> ) <...> ) ;; = (export <string> (global <N>)) (global <name>? <...>)
( global <name>? ( import <string> <string> ) <global_type> ) ;; = (import <string> <string> (global <name>? <global_type>))
table: ( table <name>? <table_type> )
( table <name>? ( export <string> ) <...> ) ;; = (export <string> (table <N>)) (table <name>? <...>)
( table <name>? ( import <string> <string> ) <table_type> ) ;; = (import <string> <string> (table <name>? <table_type>))
( table <name>? ( export <string> )* <ref_type> ( elem <var>* ) ) ;; = (table <name>? ( export <string> )* <size> <size> <ref_type>) (elem (i32.const 0) <var>*)
elem: ( elem <var>? (offset <instr>* ) <var>* )
( elem <var>? <expr> <var>* ) ;; = (elem <var>? (offset <expr>) <var>*)
( elem <var>? declare <ref_type> <var>* )
elem: ( elem <name>? ( table <var> )? <offset> <ref_type> <item>* )
( elem <name>? ( table <var> )? <offset> func <var>* ) ;; = (elem <name>? ( table <var> )? <offset> funcref (ref.func <var>)*)
( elem <var>? declare? <ref_type> <var>* )
( elem <name>? declare? func <var>* ) ;; = (elem <name>? declare? funcref (ref.func <var>)*)
offset: ( offset <instr>* )
<expr> ;; = ( offset <expr> )
item: ( item <instr>* )
<expr> ;; = ( item <expr> )
memory: ( memory <name>? <memory_type> )
( memory <name>? ( export <string> ) <...> ) ;; = (export <string> (memory <N>))+ (memory <name>? <...>)
( memory <name>? ( import <string> <string> ) <memory_type> ) ;; = (import <string> <string> (memory <name>? <memory_type>))
( memory <name>? ( export <string> )* ( data <string>* ) ) ;; = (memory <name>? ( export <string> )* <size> <size>) (data (i32.const 0) <string>*)
data: ( data <name>? ( memory <var> )? <offset> <string>* )
start: ( start <var> )
typedef: ( type <name>? ( func <param>* <result>* ) )
import: ( import <string> <string> <imkind> )
imkind: ( func <name>? <func_type> )
( global <name>? <global_type> )
( table <name>? <table_type> )
( memory <name>? <memory_type> )
export: ( export <string> <exkind> )
exkind: ( func <var> )
( global <var> )
( table <var> )
( memory <var> )
module: ( module <name>? <typedef>* <func>* <import>* <export>* <table>* <memory>? <global>* <elem>* <data>* <start>? )
<typedef>* <func>* <import>* <export>* <table>* <memory>? <global>* <elem>* <data>* <start>? ;; =
( module <typedef>* <func>* <import>* <export>* <table>* <memory>? <global>* <elem>* <data>* <start>? )
Here, productions marked with respective comments are abbreviation forms for equivalent expansions (see the explanation of the AST below).
In particular, WebAssembly is a stack machine, so that all expressions of the form (<op> <expr>+) are merely abbreviations of a corresponding post-order sequence of instructions.
For raw instructions, the syntax allows omitting the parentheses around the operator name and its immediate operands. In the case of control operators (block, loop, if), this requires marking the end of the nested sequence with an explicit end keyword.
Any form of naming via <name> and <var> (including expression labels) is merely notational convenience of this text format. The actual AST has no names, and all bindings are referred to via ordered numeric indices; consequently, names are immediately resolved in the parser and replaced by indices. Indices can also be used directly in the text format.
The segment strings in the memory field are used to initialize the consecutive memory at the given offset.
The <size> in the expansion of the two short-hand forms for table and memory is the minimal size that can hold the segment: the number of <var>s for tables, and the accumulative length of the strings rounded up to page size for memories.
In addition to the grammar rules above, the fields of a module may appear in any order, except that all imports must occur before the first proper definition of a function, table, memory, or global.
Comments can be written in one of two ways:
comment:
;; <char>* <eol>
(; (<char> | <comment>)* ;)
In particular, comments of the latter form nest properly.
Scripts
In order to be able to check and run modules for testing purposes, the S-expression format is interpreted as a very simple notion of "script", with commands as follows: