1. Introduction
1.1. Introduction
WebAssembly (abbreviated Wasm [1]) is a safe, portable, low-level code format designed for efficient execution and compact representation. Its main goal is to enable high performance applications on the Web, but it does not make any Web-specific assumptions or provide Web-specific features, so it can be employed in other environments as well.
WebAssembly is an open standard developed by a W3C Community Group.
This document describes version 2.0 (Draft 2024-08-22) of the core WebAssembly standard. It is intended that it will be superseded by new incremental releases with additional features in the future.
1.1.1. Design Goals
The design goals of WebAssembly are the following:
-
Fast, safe, and portable semantics:
-
Fast: executes with near native code performance, taking advantage of capabilities common to all contemporary hardware.
-
Safe: code is validated and executes in a memory-safe [2], sandboxed environment preventing data corruption or security breaches.
-
Well-defined: fully and precisely defines valid programs and their behavior in a way that is easy to reason about informally and formally.
-
Hardware-independent: can be compiled on all modern architectures, desktop or mobile devices and embedded systems alike.
-
Language-independent: does not privilege any particular language, programming model, or object model.
-
Platform-independent: can be embedded in browsers, run as a stand-alone VM, or integrated in other environments.
-
Open: programs can interoperate with their environment in a simple and universal manner.
-
-
Efficient and portable representation:
-
Compact: has a binary format that is fast to transmit by being smaller than typical text or native code formats.
-
Modular: programs can be split up in smaller parts that can be transmitted, cached, and consumed separately.
-
Efficient: can be decoded, validated, and compiled in a fast single pass, equally with either just-in-time (JIT) or ahead-of-time (AOT) compilation.
-
Streamable: allows decoding, validation, and compilation to begin as soon as possible, before all data has been seen.
-
Parallelizable: allows decoding, validation, and compilation to be split into many independent parallel tasks.
-
Portable: makes no architectural assumptions that are not broadly supported across modern hardware.
-
WebAssembly code is also intended to be easy to inspect and debug, especially in environments like web browsers, but such features are beyond the scope of this specification.
1.1.2. Scope
At its core, WebAssembly is a virtual instruction set architecture (virtual ISA). As such, it has many use cases and can be embedded in many different environments. To encompass their variety and enable maximum reuse, the WebAssembly specification is split and layered into several documents.
This document is concerned with the core ISA layer of WebAssembly. It defines the instruction set, binary encoding, validation, and execution semantics, as well as a textual representation. It does not, however, define how WebAssembly programs can interact with a specific environment they execute in, nor how they are invoked from such an environment.
Instead, this specification is complemented by additional documents defining interfaces to specific embedding environments such as the Web. These will each define a WebAssembly application programming interface (API) suitable for a given environment.
1.1.3. Security Considerations
WebAssembly provides no ambient access to the computing environment in which code is executed. Any interaction with the environment, such as I/O, access to resources, or operating system calls, can only be performed by invoking functions provided by the embedder and imported into a WebAssembly module. An embedder can establish security policies suitable for a respective environment by controlling or limiting which functional capabilities it makes available for import. Such considerations are an embedder’s responsibility and the subject of API definitions for a specific environment.
Because WebAssembly is designed to be translated into machine code running directly on the host’s hardware, it is potentially vulnerable to side channel attacks on the hardware level. In environments where this is a concern, an embedder may have to put suitable mitigations into place to isolate WebAssembly computations.
1.1.4. Dependencies
WebAssembly depends on two existing standards:
-
[IEEE-754-2019], for the representation of floating-point data and the semantics of respective numeric operations.
-
[UNICODE], for the representation of import/export names and the text format.
However, to make this specification self-contained, relevant aspects of the aforementioned standards are defined and formalized as part of this specification, such as the binary representation and rounding of floating-point values, and the value range and UTF-8 encoding of Unicode characters.
Note
The aforementioned standards are the authoritative source of all respective definitions. Formalizations given in this specification are intended to match these definitions. Any discrepancy in the syntax or semantics described is to be considered an error.
1.2. Overview
1.2.1. Concepts
WebAssembly encodes a low-level, assembly-like programming language. This language is structured around the following concepts.
- Values
-
WebAssembly provides only four basic number types. These are integers and [IEEE-754-2019] numbers, each in 32 and 64 bit width. 32 bit integers also serve as Booleans and as memory addresses. The usual operations on these types are available, including the full matrix of conversions between them. There is no distinction between signed and unsigned integer types. Instead, integers are interpreted by respective operations as either unsigned or signed in two’s complement representation.
In addition to these basic number types, there is a single 128 bit wide vector type representing different types of packed data. The supported representations are 4 32-bit, or 2 64-bit [IEEE-754-2019] numbers, or different widths of packed integer values, specifically 2 64-bit integers, 4 32-bit integers, 8 16-bit integers, or 16 8-bit integers.
Finally, values can consist of opaque references that represent pointers towards different sorts of entities. Unlike with other types, their size or representation is not observable.
- Instructions
-
The computational model of WebAssembly is based on a stack machine. Code consists of sequences of instructions that are executed in order. Instructions manipulate values on an implicit operand stack [1] and fall into two main categories. Simple instructions perform basic operations on data. They pop arguments from the operand stack and push results back to it. Control instructions alter control flow. Control flow is structured, meaning it is expressed with well-nested constructs such as blocks, loops, and conditionals. Branches can only target such constructs.
- Traps
-
Under some conditions, certain instructions may produce a trap, which immediately aborts execution. Traps cannot be handled by WebAssembly code, but are reported to the outside environment, where they typically can be caught.
- Functions
-
Code is organized into separate functions. Each function takes a sequence of values as parameters and returns a sequence of values as results. Functions can call each other, including recursively, resulting in an implicit call stack that cannot be accessed directly. Functions may also declare mutable local variables that are usable as virtual registers.
- Tables
-
A table is an array of opaque values of a particular element type. It allows programs to select such values indirectly through a dynamic index operand. Currently, the only available element type is an untyped function reference or a reference to an external host value. Thereby, a program can call functions indirectly through a dynamic index into a table. For example, this allows emulating function pointers by way of table indices.
- Linear Memory
-
A linear memory is a contiguous, mutable array of raw bytes. Such a memory is created with an initial size but can be grown dynamically. A program can load and store values from/to a linear memory at any byte address (including unaligned). Integer loads and stores can specify a storage size which is smaller than the size of the respective value type. A trap occurs if an access is not within the bounds of the current memory size.
- Modules
-
A WebAssembly binary takes the form of a module that contains definitions for functions, tables, and linear memories, as well as mutable or immutable global variables. Definitions can also be imported, specifying a module/name pair and a suitable type. Each definition can optionally be exported under one or more names. In addition to definitions, modules can define initialization data for their memories or tables that takes the form of segments copied to given offsets. They can also define a start function that is automatically executed.
- Embedder
-
A WebAssembly implementation will typically be embedded into a host environment. This environment defines how loading of modules is initiated, how imports are provided (including host-side definitions), and how exports can be accessed. However, the details of any particular embedding are beyond the scope of this specification, and will instead be provided by complementary, environment-specific API definitions.
In practice, implementations need not maintain an actual operand stack. Instead, the stack can be viewed as a set of anonymous registers that are implicitly referenced by instructions. The type system ensures that the stack height, and thus any referenced register, is always known statically.
1.2.2. Semantic Phases
Conceptually, the semantics of WebAssembly is divided into three phases. For each part of the language, the specification specifies each of them.
- Decoding
-
WebAssembly modules are distributed in a binary format. Decoding processes that format and converts it into an internal representation of a module. In this specification, this representation is modelled by abstract syntax, but a real implementation could compile directly to machine code instead.
- Validation
-
A decoded module has to be valid. Validation checks a number of well-formedness conditions to guarantee that the module is meaningful and safe. In particular, it performs type checking of functions and the instruction sequences in their bodies, ensuring for example that the operand stack is used consistently.
- Execution
-
Finally, a valid module can be executed. Execution can be further divided into two phases:
Instantiation. A module instance is the dynamic representation of a module, complete with its own state and execution stack. Instantiation executes the module body itself, given definitions for all its imports. It initializes globals, memories and tables and invokes the module’s start function if defined. It returns the instances of the module’s exports.
Invocation. Once instantiated, further WebAssembly computations can be initiated by invoking an exported function on a module instance. Given the required arguments, that executes the respective function and returns its results.
Instantiation and invocation are operations within the embedding environment.
2. Structure
2.1. Conventions
WebAssembly is a programming language that has multiple concrete representations (its binary format and the text format). Both map to a common structure. For conciseness, this structure is described in the form of an abstract syntax. All parts of this specification are defined in terms of this abstract syntax.
2.1.1. Grammar Notation
The following conventions are adopted in defining grammar rules for abstract syntax.
-
Terminal symbols (atoms) are written in sans-serif font or in symbolic form: .
-
Nonterminal symbols are written in italic font: .
-
is a sequence of iterations of .
-
is a possibly empty sequence of iterations of . (This is a shorthand for used where is not relevant.)
-
is a non-empty sequence of iterations of . (This is a shorthand for where .)
-
is an optional occurrence of . (This is a shorthand for where .)
-
Productions are written .
-
Large productions may be split into multiple definitions, indicated by ending the first one with explicit ellipses, , and starting continuations with ellipses, .
-
Some productions are augmented with side conditions in parentheses, “”, that provide a shorthand for a combinatorial expansion of the production into many separate cases.
-
If the same meta variable or non-terminal symbol appears multiple times in a production, then all those occurrences must have the same instantiation. (This is a shorthand for a side condition requiring multiple different variables to be equal.)
2.1.2. Auxiliary Notation
When dealing with syntactic constructs the following notation is also used:
-
denotes the empty sequence.
-
denotes the length of a sequence .
-
denotes the -th element of a sequence , starting from .
-
denotes the sub-sequence of a sequence .
-
denotes the same sequence as , except that the -th element is replaced with .
-
denotes the same sequence as , except that the sub-sequence is replaced with .
-
denotes the flat sequence formed by concatenating all sequences in .
Moreover, the following conventions are employed:
-
The notation , where is a non-terminal symbol, is treated as a meta variable ranging over respective sequences of (similarly for , , ).
-
When given a sequence , then the occurrences of in a sequence written are assumed to be in point-wise correspondence with (similarly for , , ). This implicitly expresses a form of mapping syntactic constructions over a sequence.
Productions of the following form are interpreted as records that map a fixed set of fields to “values” , respectively:
The following notation is adopted for manipulating such records:
-
denotes the contents of the component of .
-
denotes the same record as , except that the contents of the component is replaced with .
-
denotes the composition of two records with the same fields of sequences by appending each sequence point-wise:
-
denotes the composition of a sequence of records, respectively; if the sequence is empty, then all fields of the resulting record are empty.
The update notation for sequences and records generalizes recursively to nested components accessed by “paths” :
-
is short for ,
-
is short for ,
where is shortened to .
2.1.3. Vectors
Vectors are bounded sequences of the form (or ), where the can either be values or complex constructions. A vector can have at most elements.
2.2. Values
WebAssembly programs operate on primitive numeric values. Moreover, in the definition of programs, immutable sequences of values occur to represent more complex data, such as text strings or other vectors.
2.2.1. Bytes
The simplest form of value are raw uninterpreted bytes. In the abstract syntax they are represented as hexadecimal literals.
2.2.1.1. Conventions
-
The meta variable ranges over bytes.
-
Bytes are sometimes interpreted as natural numbers .
2.2.2. Integers
Different classes of integers with different value ranges are distinguished by their bit width and by whether they are unsigned or signed.
The class defines uninterpreted integers, whose signedness interpretation can vary depending on context. In the abstract syntax, they are represented as unsigned values. However, some operations convert them to signed based on a two’s complement interpretation.
Note
The main integer types occurring in this specification are , , , , , , , . However, other sizes occur as auxiliary constructions, e.g., in the definition of floating-point numbers.
2.2.2.1. Conventions
-
The meta variables range over integers.
-
Numbers may be denoted by simple arithmetics, as in the grammar above. In order to distinguish arithmetics like from sequences like , the latter is distinguished with parentheses.
2.2.3. Floating-Point
Floating-point data represents 32 or 64 bit values that correspond to the respective binary formats of the [IEEE-754-2019] standard (Section 3.3).
Every value has a sign and a magnitude. Magnitudes can either be expressed as normal numbers of the form , where is the exponent and is the significand whose most significant bit is , or as a subnormal number where the exponent is fixed to the smallest possible value and is ; among the subnormals are positive and negative zero values. Since the significands are binary values, normals are represented in the form , where is the bit width of ; similarly for subnormals.
Possible magnitudes also include the special values (infinity) and (NaN, not a number). NaN values have a payload that describes the mantissa bits in the underlying binary representation. No distinction is made between signalling and quiet NaNs.
where and with
A canonical NaN is a floating-point value where is a payload whose most significant bit is while all others are :
An arithmetic NaN is a floating-point value with , such that the most significant bit is while all others are arbitrary.
Note
In the abstract syntax, subnormals are distinguished by the leading 0 of the significand. The exponent of subnormals has the same value as the smallest possible exponent of a normal number. Only in the binary representation the exponent of a subnormal is encoded differently than the exponent of any normal number.
The notion of canonical NaN defined here is unrelated to the notion of canonical NaN that the [IEEE-754-2019] standard (Section 3.5.2) defines for decimal interchange formats.
2.2.3.1. Conventions
-
The meta variable ranges over floating-point values where clear from context.
2.2.4. Vectors
Numeric vectors are 128-bit values that are processed by vector instructions (also known as SIMD instructions, single instruction multiple data). They are represented in the abstract syntax using . The interpretation of lane types (integer or floating-point numbers) and lane sizes are determined by the specific instruction operating on them.
2.2.5. Names
Names are sequences of characters, which are scalar values as defined by [UNICODE] (Section 2.4).
Due to the limitations of the binary format, the length of a name is bounded by the length of its UTF-8 encoding.
2.2.5.1. Convention
-
Characters (Unicode scalar values) are sometimes used interchangeably with natural numbers .
2.3. Types
Various entities in WebAssembly are classified by types. Types are checked during validation, instantiation, and possibly execution.
2.3.1. Number Types
Number types classify numeric values.
The types and classify 32 and 64 bit integers, respectively. Integers are not inherently signed or unsigned, their interpretation is determined by individual operations.
The types and classify 32 and 64 bit floating-point data, respectively. They correspond to the respective binary floating-point representations, also known as single and double precision, as defined by the [IEEE-754-2019] standard (Section 3.3).
Number types are transparent, meaning that their bit patterns can be observed. Values of number type can be stored in memories.
2.3.1.1. Conventions
-
The notation denotes the bit width of a number type . That is, and .
2.3.2. Vector Types
Vector types classify vectors of numeric values processed by vector instructions (also known as SIMD instructions, single instruction multiple data).
The type corresponds to a 128 bit vector of packed integer or floating-point data. The packed data can be interpreted as signed or unsigned integers, single or double precision floating-point values, or a single 128 bit type. The interpretation is determined by individual operations.
Vector types, like number types are transparent, meaning that their bit patterns can be observed. Values of vector type can be stored in memories.
2.3.2.1. Conventions
-
The notation for bit width extends to vector types as well, that is, .
2.3.3. Reference Types
Reference types classify first-class references to objects in the runtime store.
The type denotes the infinite union of all references to functions, regardless of their function types.
The type denotes the infinite union of all references to objects owned by the embedder and that can be passed into WebAssembly under this type.
Reference types are opaque, meaning that neither their size nor their bit pattern can be observed. Values of reference type can be stored in tables.
2.3.4. Value Types
Value types classify the individual values that WebAssembly code can compute with and the values that a variable accepts. They are either number types, vector types, or reference types.
2.3.4.1. Conventions
-
The meta variable ranges over value types or subclasses thereof where clear from context.
2.3.5. Result Types
Result types classify the result of executing instructions or functions, which is a sequence of values, written with brackets.
2.3.6. Function Types
Function types classify the signature of functions, mapping a vector of parameters to a vector of results. They are also used to classify the inputs and outputs of instructions.
2.3.7. Limits
Limits classify the size range of resizeable storage associated with memory types and table types.
If no maximum is given, the respective storage can grow to any size.
2.3.8. Memory Types
Memory types classify linear memories and their size range.
The limits constrain the minimum and optionally the maximum size of a memory. The limits are given in units of page size.
2.3.9. Table Types
Table types classify tables over elements of reference type within a size range.
Like memories, tables are constrained by limits for their minimum and optionally maximum size. The limits are given in numbers of entries.
Note
In future versions of WebAssembly, additional element types may be introduced.
2.3.10. Global Types
Global types classify global variables, which hold a value and can either be mutable or immutable.
2.3.11. External Types
External types classify imports and external values with their respective types.
2.3.11.1. Conventions
The following auxiliary notation is defined for sequences of external types. It filters out entries of a specific kind in an order-preserving fashion:
2.4. Instructions
WebAssembly code consists of sequences of instructions. Its computational model is based on a stack machine in that instructions manipulate values on an implicit operand stack, consuming (popping) argument values and producing or returning (pushing) result values.
In addition to dynamic operands from the stack, some instructions also have static immediate arguments, typically indices or type annotations, which are part of the instruction itself.
Some instructions are structured in that they bracket nested sequences of instructions.
The following sections group instructions into a number of different categories.
2.4.1. Numeric Instructions
Numeric instructions provide basic operations over numeric values of specific type. These operations closely match respective operations available in hardware.
Numeric instructions are divided by number type. For each type, several subcategories can be distinguished:
-
Constants: return a static constant.
-
Unary Operations: consume one operand and produce one result of the respective type.
-
Binary Operations: consume two operands and produce one result of the respective type.
-
Tests: consume one operand of the respective type and produce a Boolean integer result.
-
Comparisons: consume two operands of the respective type and produce a Boolean integer result.
-
Conversions: consume a value of one type and produce a result of another (the source type of the conversion is the one after the “”).
Some integer instructions come in two flavors, where a signedness annotation distinguishes whether the operands are to be interpreted as unsigned or signed integers. For the other integer instructions, the use of two’s complement for the signed interpretation means that they behave the same regardless of signedness.
2.4.1.1. Conventions
Occasionally, it is convenient to group operators together according to the following grammar shorthands:
2.4.2. Vector Instructions
Vector instructions (also known as SIMD instructions, single instruction multiple data) provide basic operations over values of vector type.
Vector instructions have a naming convention involving a prefix that determines how their operands will be interpreted. This prefix describes the shape of the operand, written , and consisting of a packed numeric type and the number of lanes of that type. Operations are performed point-wise on the values of each lane.
Note
For example, the shape interprets the operand as four values, packed into an . The bitwidth of the numeric type times always is 128.
Instructions prefixed with do not involve a specific interpretation, and treat the as an value or a vector of 128 individual bits.
Vector instructions can be grouped into several subcategories:
-
Constants: return a static constant.
-
Unary Operations: consume one operand and produce one result.
-
Binary Operations: consume two operands and produce one result.
-
Ternary Operations: consume three operands and produce one result.
-
Tests: consume one operand and produce a Boolean integer result.
-
Shifts: consume a operand and a operand, producing one result.
-
Splats: consume a value of numeric type and produce a result of a specified shape.
-
Extract lanes: consume a operand and return the numeric value in a given lane.
-
Replace lanes: consume a operand and a numeric value for a given lane, and produce a result.
Some vector instructions have a signedness annotation which distinguishes whether the elements in the operands are to be interpreted as unsigned or signed integers. For the other vector instructions, the use of two’s complement for the signed interpretation means that they behave the same regardless of signedness.
2.4.2.1. Conventions
Occasionally, it is convenient to group operators together according to the following grammar shorthands:
2.4.3. Reference Instructions
Instructions in this group are concerned with accessing references.
These instructions produce a null value, check for a null value, or produce a reference to a given function, respectively.
2.4.4. Parametric Instructions
Instructions in this group can operate on operands of any value type.
The instruction simply throws away a single operand.
The instruction selects one of its first two operands based on whether its third operand is zero or not. It may include a value type determining the type of these operands. If missing, the operands must be of numeric type.
Note
In future versions of WebAssembly, the type annotation on may allow for more than a single value being selected at the same time.
2.4.5. Variable Instructions
Variable instructions are concerned with access to local or global variables.
These instructions get or set the values of variables, respectively. The instruction is like but also returns its argument.
2.4.6. Table Instructions
Instructions in this group are concerned with tables table.
The and instructions load or store an element in a table, respectively.
The instruction returns the current size of a table. The instruction grows table by a given delta and returns the previous size, or if enough space cannot be allocated. It also takes an initialization value for the newly allocated entries.
The instruction sets all entries in a range to a given value.
The instruction copies elements from a source table region to a possibly overlapping destination region; the first index denotes the destination. The instruction copies elements from a passive element segment into a table. The instruction prevents further use of a passive element segment. This instruction is intended to be used as an optimization hint. After an element segment is dropped its elements can no longer be retrieved, so the memory used by this segment may be freed.
An additional instruction that accesses a table is the control instruction .
2.4.7. Memory Instructions
Instructions in this group are concerned with linear memory.
Memory is accessed with and instructions for the different number types. They all take a memory immediate that contains an address offset and the expected alignment (expressed as the exponent of a power of 2). Integer loads and stores can optionally specify a storage size that is smaller than the bit width of the respective value type. In the case of loads, a sign extension mode is then required to select appropriate behavior.
Vector loads can specify a shape that is half the bit width of . Each lane is half its usual size, and the sign extension mode then specifies how the smaller lane is extended to the larger lane. Alternatively, vector loads can perform a splat, such that only a single lane of the specified storage size is loaded, and the result is duplicated to all lanes.
The static address offset is added to the dynamic address operand, yielding a 33 bit effective address that is the zero-based index at which the memory is accessed. All values are read and written in little endian byte order. A trap results if any of the accessed memory bytes lies outside the address range implied by the memory’s current size.
Note
Future versions of WebAssembly might provide memory instructions with 64 bit address ranges.
The instruction returns the current size of a memory. The instruction grows memory by a given delta and returns the previous size, or if enough memory cannot be allocated. Both instructions operate in units of page size.
The instruction sets all values in a region to a given byte. The instruction copies data from a source memory region to a possibly overlapping destination region. The instruction copies data from a passive data segment into a memory. The instruction prevents further use of a passive data segment. This instruction is intended to be used as an optimization hint. After a data segment is dropped its data can no longer be retrieved, so the memory used by this segment may be freed.
2.4.8. Control Instructions
Instructions in this group affect the flow of control.
The instruction does nothing.
The instruction causes an unconditional trap.
The , and instructions are structured instructions. They bracket nested sequences of instructions, called blocks, terminated with, or separated by, or pseudo-instructions. As the grammar prescribes, they must be well-nested.
A structured instruction can consume input and produce output on the operand stack according to its annotated block type. It is given either as a type index that refers to a suitable function type, or as an optional value type inline, which is a shorthand for the function type .
Each structured control instruction introduces an implicit label. Labels are targets for branch instructions that reference them with label indices. Unlike with other index spaces, indexing of labels is relative by nesting depth, that is, label refers to the innermost structured control instruction enclosing the referring branch instruction, while increasing indices refer to those farther out. Consequently, labels can only be referenced from within the associated structured control instruction. This also implies that branches can only be directed outwards, “breaking” from the block of the control construct they target. The exact effect depends on that control construct. In case of or it is a forward jump, resuming execution after the matching . In case of it is a backward jump to the beginning of the loop.
Note
This enforces structured control flow. Intuitively, a branch targeting a or behaves like a statement in most C-like languages, while a branch targeting a behaves like a statement.
Branch instructions come in several flavors: performs an unconditional branch, performs a conditional branch, and performs an indirect branch through an operand indexing into the label vector that is an immediate to the instruction, or to a default target if the operand is out of bounds. The instruction is a shortcut for an unconditional branch to the outermost block, which implicitly is the body of the current function. Taking a branch unwinds the operand stack up to the height where the targeted structured control instruction was entered. However, branches may additionally consume operands themselves, which they push back on the operand stack after unwinding. Forward branches require operands according to the output of the targeted block’s type, i.e., represent the values produced by the terminated block. Backward branches require operands according to the input of the targeted block’s type, i.e., represent the values consumed by the restarted block.
The instruction invokes another function, consuming the necessary arguments from the stack and returning the result values of the call. The instruction calls a function indirectly through an operand indexing into a table that is denoted by a table index and must have type . Since it may contain functions of heterogeneous type, the callee is dynamically checked against the function type indexed by the instruction’s second immediate, and the call is aborted with a trap if it does not match.
2.4.9. Expressions
Function bodies, initialization values for globals, elements and offsets of element segments, and offsets of data segments are given as expressions, which are sequences of instructions terminated by an marker.
In some places, validation restricts expressions to be constant, which limits the set of allowable instructions.
2.5. Modules
WebAssembly programs are organized into modules, which are the unit of deployment, loading, and compilation. A module collects definitions for types, functions, tables, memories, and globals. In addition, it can declare imports and exports and provide initialization in the form of data and element segments, or a start function.
Each of the vectors – and thus the entire module – may be empty.
2.5.1. Indices
Definitions are referenced with zero-based indices. Each class of definition has its own index space, as distinguished by the following classes.
The index space for functions, tables, memories and globals includes respective imports declared in the same module. The indices of these imports precede the indices of other definitions in the same index space.
Element indices reference element segments and data indices reference data segments.
The index space for locals is only accessible inside a function and includes the parameters of that function, which precede the local variables.
Label indices reference structured control instructions inside an instruction sequence.
2.5.1.1. Conventions
-
The meta variable ranges over label indices.
-
The meta variables range over indices in any of the other index spaces.
-
The notation denotes the set of indices from index space occurring free in . Sometimes this set is reinterpreted as the vector of its elements.
Note
For example, if is , then , or equivalently, the vector .
2.5.2. Types
The component of a module defines a vector of function types.
All function types used in a module must be defined in this component. They are referenced by type indices.
Note
Future versions of WebAssembly may add additional forms of type definitions.
2.5.3. Functions
The component of a module defines a vector of functions with the following structure:
The of a function declares its signature by reference to a type defined in the module. The parameters of the function are referenced through 0-based local indices in the function’s body; they are mutable.
The declare a vector of mutable local variables and their types. These variables are referenced through local indices in the function’s body. The index of the first local is the smallest index not referencing a parameter.
The is an instruction sequence that upon termination must produce a stack matching the function type’s result type.
Functions are referenced through function indices, starting with the smallest index not referencing a function import.
2.5.4. Tables
The component of a module defines a vector of tables described by their table type:
A table is a vector of opaque values of a particular reference type. The size in the limits of the table type specifies the initial size of that table, while its , if present, restricts the size to which it can grow later.
Tables can be initialized through element segments.
Tables are referenced through table indices, starting with the smallest index not referencing a table import. Most constructs implicitly reference table index .
2.5.5. Memories
The component of a module defines a vector of linear memories (or memories for short) as described by their memory type:
A memory is a vector of raw uninterpreted bytes. The size in the limits of the memory type specifies the initial size of that memory, while its , if present, restricts the size to which it can grow later. Both are in units of page size.
Memories can be initialized through data segments.
Memories are referenced through memory indices, starting with the smallest index not referencing a memory import. Most constructs implicitly reference memory index .
Note
In the current version of WebAssembly, at most one memory may be defined or imported in a single module, and all constructs implicitly reference this memory . This restriction may be lifted in future versions.
2.5.6. Globals
The component of a module defines a vector of global variables (or globals for short):
Each global stores a single value of the given global type. Its also specifies whether a global is immutable or mutable. Moreover, each global is initialized with an value given by a constant initializer expression.
Globals are referenced through global indices, starting with the smallest index not referencing a global import.
2.5.7. Element Segments
The initial contents of a table is uninitialized. Element segments can be used to initialize a subrange of a table from a static vector of elements.
The component of a module defines a vector of element segments. Each element segment defines a reference type and a corresponding list of constant element expressions.
Element segments have a mode that identifies them as either passive, active, or declarative. A passive element segment’s elements can be copied to a table using the instruction. An active element segment copies its elements into a table during instantiation, as specified by a table index and a constant expression defining an offset into that table. A declarative element segment is not available at runtime but merely serves to forward-declare references that are formed in code with instructions like .
The is given by a constant expression.
Element segments are referenced through element indices.
2.5.8. Data Segments
The initial contents of a memory are zero bytes. Data segments can be used to initialize a range of memory from a static vector of bytes.
The component of a module defines a vector of data segments.
Like element segments, data segments have a mode that identifies them as either passive or active. A passive data segment’s contents can be copied into a memory using the instruction. An active data segment copies its contents into a memory during instantiation, as specified by a memory index and a constant expression defining an offset into that memory.
Data segments are referenced through data indices.
Note
In the current version of WebAssembly, at most one memory is allowed in a module. Consequently, the only valid is .
2.5.9. Start Function
The component of a module declares the function index of a start function that is automatically invoked when the module is instantiated, after tables and memories have been initialized.
Note
The start function is intended for initializing the state of a module. The module and its exports are not accessible externally before this initialization has completed.
2.5.10. Exports
The component of a module defines a set of exports that become accessible to the host environment once the module has been instantiated.
Each export is labeled by a unique name. Exportable definitions are functions, tables, memories, and globals, which are referenced through a respective descriptor.
2.5.10.1. Conventions
The following auxiliary notation is defined for sequences of exports, filtering out indices of a specific kind in an order-preserving fashion:
2.5.11. Imports
The component of a module defines a set of imports that are required for instantiation.
Each import is labeled by a two-level name space, consisting of a name and a for an entity within that module. Importable definitions are functions, tables, memories, and globals. Each import is specified by a descriptor with a respective type that a definition provided during instantiation is required to match.
Every import defines an index in the respective index space. In each index space, the indices of imports go before the first index of any definition contained in the module itself.
Note
Unlike export names, import names are not necessarily unique. It is possible to import the same / pair multiple times; such imports may even have different type descriptions, including different kinds of entities. A module with such imports can still be instantiated depending on the specifics of how an embedder allows resolving and supplying imports. However, embedders are not required to support such overloading, and a WebAssembly module itself cannot implement an overloaded name.
3. Validation
3.1. Conventions
Validation checks that a WebAssembly module is well-formed. Only valid modules can be instantiated.
Validity is defined by a type system over the abstract syntax of a module and its contents. For each piece of abstract syntax, there is a typing rule that specifies the constraints that apply to it. All rules are given in two equivalent forms:
-
In prose, describing the meaning in intuitive form.
-
In formal notation, describing the rule in mathematical form. [1]
Note
The prose and formal rules are equivalent, so that understanding of the formal notation is not required to read this specification. The formalism offers a more concise description in notation that is used widely in programming languages semantics and is readily amenable to mathematical proof.
In both cases, the rules are formulated in a declarative manner. That is, they only formulate the constraints, they do not define an algorithm. The skeleton of a sound and complete algorithm for type-checking instruction sequences according to this specification is provided in the appendix.
3.1.1. Contexts
Validity of an individual definition is specified relative to a context, which collects relevant information about the surrounding module and the definitions in scope:
-
Types: the list of types defined in the current module.
-
Functions: the list of functions declared in the current module, represented by their function type.
-
Tables: the list of tables declared in the current module, represented by their table type.
-
Memories: the list of memories declared in the current module, represented by their memory type.
-
Globals: the list of globals declared in the current module, represented by their global type.
-
Element Segments: the list of element segments declared in the current module, represented by their element type.
-
Data Segments: the list of data segments declared in the current module, each represented by an entry.
-
Locals: the list of locals declared in the current function (including parameters), represented by their value type.
-
Labels: the stack of labels accessible from the current position, represented by their result type.
-
Return: the return type of the current function, represented as an optional result type that is absent when no return is allowed, as in free-standing expressions.
-
References: the list of function indices that occur in the module outside functions and can hence be used to form references inside them.
In other words, a context contains a sequence of suitable types for each index space, describing each defined entry in that space. Locals, labels and return type are only used for validating instructions in function bodies, and are left empty elsewhere. The label stack is the only part of the context that changes as validation of an instruction sequence proceeds.
More concretely, contexts are defined as records with abstract syntax:
In addition to field access written the following notation is adopted for manipulating contexts:
-
When spelling out a context, empty fields are omitted.
-
denotes the same context as but with the elements prepended to its component sequence.
Note
Indexing notation like is used to look up indices in their respective index space in the context. Context extension notation is primarily used to locally extend relative index spaces, such as label indices. Accordingly, the notation is defined to append at the front of the respective sequence, introducing a new relative index and shifting the existing ones.
3.1.2. Prose Notation
Validation is specified by stylised rules for each relevant part of the abstract syntax. The rules not only state constraints defining when a phrase is valid, they also classify it with a type. The following conventions are adopted in stating these rules.
-
A phrase is said to be “valid with type ” if and only if all constraints expressed by the respective rules are met. The form of depends on what is.
Note
For example, if is a function, then is a function type; for an that is a global, is a global type; and so on.
-
The rules implicitly assume a given context .
-
In some places, this context is locally extended to a context with additional entries. The formulation “Under context , … statement …” is adopted to express that the following statement must apply under the assumptions embodied in the extended context.
3.1.3. Formal Notation
Note
This section gives a brief explanation of the notation for specifying typing rules formally. For the interested reader, a more thorough introduction can be found in respective text books. [2]
The proposition that a phrase has a respective type is written . In general, however, typing is dependent on a context . To express this explicitly, the complete form is a judgement , which says that holds under the assumptions encoded in .
The formal typing rules use a standard approach for specifying type systems, rendering them into deduction rules. Every rule has the following general form:
Such a rule is read as a big implication: if all premises hold, then the conclusion holds. Some rules have no premises; they are axioms whose conclusion holds unconditionally. The conclusion always is a judgment , and there is one respective rule for each relevant construct of the abstract syntax.
Note
For example, the typing rule for the instruction can be given as an axiom:
The instruction is always valid with type (saying that it consumes two values and produces one), independent of any side conditions.
An instruction like can be typed as follows:
Here, the premise enforces that the immediate local index exists in the context. The instruction produces a value of its respective type (and does not consume any values). If does not exist then the premise does not hold, and the instruction is ill-typed.
Finally, a structured instruction requires a recursive rule, where the premise is itself a typing judgement:
A instruction is only valid when the instruction sequence in its body is. Moreover, the result type must match the block’s annotation . If so, then the instruction has the same type as the body. Inside the body an additional label of the corresponding result type is available, which is expressed by extending the context with the additional label information for the premise.
The semantics is derived from the following article: Andreas Haas, Andreas Rossberg, Derek Schuff, Ben Titzer, Dan Gohman, Luke Wagner, Alon Zakai, JF Bastien, Michael Holman. Bringing the Web up to Speed with WebAssembly. Proceedings of the 38th ACM SIGPLAN Conference on Programming Language Design and Implementation (PLDI 2017). ACM 2017.
For example: Benjamin Pierce. Types and Programming Languages. The MIT Press 2002
3.2. Types
Most types are universally valid. However, restrictions apply to limits, which must be checked during validation. Moreover, block types are converted to plain function types for ease of processing.
3.2.1. Limits
Limits must have meaningful bounds that are within a given range.
3.2.1.1.
-
The value of must not be larger than .
-
If the maximum is not empty, then:
-
Its value must not be larger than .
-
Its value must not be smaller than .
-
-
Then the limit is valid within range .
3.2.2. Block Types
Block types may be expressed in one of two forms, both of which are converted to plain function types by the following rules.
3.2.2.1.
-
The type must be defined in the context.
-
Then the block type is valid as function type .
3.2.2.2.
-
The block type is valid as function type .
3.2.3. Function Types
Function types are always valid.
3.2.3.1.
-
The function type is valid.
3.2.4. Table Types
3.2.4.1.
-
The limits must be valid within range .
-
Then the table type is valid.
3.2.5. Memory Types
3.2.5.1.
-
The limits must be valid within range .
-
Then the memory type is valid.
3.2.6. Global Types
3.2.6.1.
-
The global type is valid.
3.2.7. External Types
3.2.7.1.
-
The function type must be valid.
-
Then the external type is valid.
3.2.7.2.
-
The table type must be valid.
-
Then the external type is valid.
3.2.7.3.
-
The memory type must be valid.
-
Then the external type is valid.
3.2.7.4.
-
The global type must be valid.
-
Then the external type is valid.
3.2.8. Import Subtyping
When instantiating a module, external values must be provided whose types are matched against the respective external types classifying each import. In some cases, this allows for a simple form of subtyping (written “” formally), as defined here.
3.2.8.1. Limits
Limits match limits if and only if:
-
is larger than or equal to .
-
Either:
-
is empty.
-
-
Or:
-
Both and are non-empty.
-
is smaller than or equal to .
-
3.2.8.2. Functions
An external type matches if and only if:
-
Both and are the same.
3.2.8.3. Tables
An external type matches if and only if:
-
Limits match .
-
Both and are the same.
3.2.8.4. Memories
An external type matches if and only if:
-
Limits match .
3.2.8.5. Globals
An external type matches if and only if:
-
Both and are the same.
3.3. Instructions
Instructions are classified by stack types that describe how instructions manipulate the operand stack.
The types describe the required input stack with operand types that an instruction pops off and the provided output stack with result values of types that it pushes back. Stack types are akin to function types, except that they allow individual operands to be classified as (bottom), indicating that the type is unconstrained. As an auxiliary notion, an operand type matches another operand type , if is either or equal to . This is extended to stack types in a point-wise manner.
Note
For example, the instruction has type , consuming two values and producing one.
Typing extends to instruction sequences . Such a sequence has a stack type if the accumulative effect of executing the instructions is consuming values of types off the operand stack and pushing new values of types .
For some instructions, the typing rules do not fully constrain the type, and therefore allow for multiple types. Such instructions are called polymorphic. Two degrees of polymorphism can be distinguished:
-
value-polymorphic: the value type of one or several individual operands is unconstrained. That is the case for all parametric instructions like and .
-
stack-polymorphic: the entire (or most of the) stack type of the instruction is unconstrained. That is the case for all control instructions that perform an unconditional control transfer, such as , , , and .
In both cases, the unconstrained types or type sequences can be chosen arbitrarily, as long as they meet the constraints imposed for the surrounding parts of the program.
Note
For example, the instruction is valid with type , for any possible number type . Consequently, both instruction sequences
and
are valid, with in the typing of being instantiated to or , respectively.
The instruction is valid with type for any possible sequences of operand types and . Consequently,
is valid by assuming type for the instruction. In contrast,
is invalid, because there is no possible type to pick for the instruction that would make the sequence well-typed.
The Appendix describes a type checking algorithm that efficiently implements validation of instruction sequences as prescribed by the rules given here.
3.3.1. Numeric Instructions
3.3.1.1.
-
The instruction is valid with type .
3.3.1.2.
-
The instruction is valid with type .
3.3.1.3.
-
The instruction is valid with type .
3.3.1.4.
-
The instruction is valid with type .
3.3.1.5.
-
The instruction is valid with type .
3.3.1.6.
-
The instruction is valid with type .
3.3.2. Reference Instructions
3.3.2.1.
-
The instruction is valid with type .
Note
In future versions of WebAssembly, there may be reference types for which no null reference is allowed.
3.3.2.2.
-
The instruction is valid with type , for any reference type .
3.3.2.3.
-
The function must be defined in the context.
-
The function index must be contained in .
-
The instruction is valid with type .
3.3.3. Vector Instructions
Vector instructions can have a prefix to describe the shape of the operand. Packed numeric types, and , are not value types. An auxiliary function maps such packed type shapes to value types:
The following auxiliary function denotes the number of lanes in a vector shape, i.e., its dimension:
3.3.3.1.
-
The instruction is valid with type .
3.3.3.2.
-
The instruction is valid with type .
3.3.3.3.
-
The instruction is valid with type .
3.3.3.4.
-
The instruction is valid with type .
3.3.3.5.
-
The instruction is valid with type .
3.3.3.6.
-
The instruction is valid with type .
3.3.3.7.
-
For all , in , must be smaller than .
-
The instruction is valid with type .
3.3.3.8.
-
Let be .
-
The instruction is valid with type .
3.3.3.9.
-
The lane index must be smaller than .
-
The instruction is valid with type .
3.3.3.10.
-
The lane index must be smaller than .
-
Let be .
-
The instruction is valid with type .
3.3.3.11.
-
The instruction is valid with type .
3.3.3.12.
-
The instruction is valid with type .
3.3.3.13.
-
The instruction is valid with type .
3.3.3.14.
-
The instruction is valid with type .
3.3.3.15.
-
The instruction is valid with type .
3.3.3.16.
-
The instruction is valid with type .
3.3.3.17.
-
The instruction is valid with type .
3.3.3.18.
-
The instruction is valid with type .
3.3.3.19.
-
The instruction is valid with type .
3.3.3.20.
-
The instruction is valid with type .
3.3.3.21.
-
The instruction is valid with type .
3.3.4. Parametric Instructions
3.3.4.1.
-
The instruction is valid with type , for any operand type .
Note
Both and without annotation are value-polymorphic instructions.
3.3.4.2.
-
If is present, then:
-
The length of must be .
-
Then the instruction is valid with type .
-
-
Else:
-
The instruction is valid with type , for any operand type that matches some number type or vector type.
-
Note
In future versions of WebAssembly, may allow more than one value per choice.
3.3.5. Variable Instructions
3.3.5.1.
-
The local must be defined in the context.
-
Let be the value type .
-
Then the instruction is valid with type .
3.3.5.2.
-
The local must be defined in the context.
-
Let be the value type .
-
Then the instruction is valid with type .
3.3.5.3.
-
The local must be defined in the context.
-
Let be the value type .
-
Then the instruction is valid with type .
3.3.5.4.
-
The global must be defined in the context.
-
Let be the global type .
-
Then the instruction is valid with type .
3.3.5.5.
-
The global must be defined in the context.
-
Let be the global type .
-
The mutability must be .
-
Then the instruction is valid with type .
3.3.6. Table Instructions
3.3.6.1.
-
The table must be defined in the context.
-
Let be the table type .
-
Then the instruction is valid with type .
3.3.6.2.
-
The table must be defined in the context.
-
Let be the table type .
-
Then the instruction is valid with type .
3.3.6.3.
-
The table must be defined in the context.
-
Then the instruction is valid with type .
3.3.6.4.
-
The table must be defined in the context.
-
Let be the table type .
-
Then the instruction is valid with type .
3.3.6.5.
-
The table must be defined in the context.
-
Let be the table type .
-
Then the instruction is valid with type .
3.3.6.6.
-
The table must be defined in the context.
-
Let be the table type .
-
The table must be defined in the context.
-
Let be the table type .
-
The reference type must be the same as .
-
Then the instruction is valid with type .
3.3.6.7.
-
The table must be defined in the context.
-
Let be the table type .
-
The element segment must be defined in the context.
-
Let be the reference type .
-
The reference type must be the same as .
-
Then the instruction is valid with type .
3.3.6.8.
-
The element segment must be defined in the context.
-
Then the instruction is valid with type .
3.3.7. Memory Instructions
3.3.7.1.
-
The memory must be defined in the context.
-
The alignment must not be larger than the bit width of divided by .
-
Then the instruction is valid with type .
3.3.7.2.
-
The memory must be defined in the context.
-
The alignment must not be larger than .
-
Then the instruction is valid with type .
3.3.7.3.
-
The memory must be defined in the context.
-
The alignment must not be larger than the bit width of divided by .
-
Then the instruction is valid with type .
3.3.7.4.
-
The memory must be defined in the context.
-
The alignment must not be larger than .
-
Then the instruction is valid with type .
3.3.7.5.
-
The memory must be defined in the context.
-
The alignment must not be larger than .
-
Then the instruction is valid with type .
3.3.7.6.
-
The memory must be defined in the context.
-
The alignment must not be larger than .
-
Then the instruction is valid with type .
3.3.7.7.
-
The memory must be defined in the context.
-
The alignment must not be larger than .
-
Then the instruction is valid with type .
3.3.7.8.
-
The lane index must be smaller than .
-
The memory must be defined in the context.
-
The alignment must not be larger than .
-
Then the instruction is valid with type .
3.3.7.9.
-
The lane index must be smaller than .
-
The memory must be defined in the context.
-
The alignment must not be larger than .
-
Then the instruction is valid with type .
3.3.7.10.
-
The memory must be defined in the context.
-
Then the instruction is valid with type .
3.3.7.11.
-
The memory must be defined in the context.
-
Then the instruction is valid with type .
3.3.7.12.
-
The memory must be defined in the context.
-
Then the instruction is valid with type .
3.3.7.13.
-
The memory must be defined in the context.
-
Then the instruction is valid with type .
3.3.7.14.
-
The memory must be defined in the context.
-
The data segment must be defined in the context.
-
Then the instruction is valid with type .
3.3.7.15.
-
The data segment must be defined in the context.
-
Then the instruction is valid with type .
3.3.8. Control Instructions
3.3.8.1.
-
The instruction is valid with type .
3.3.8.2.
-
The instruction is valid with type , for any sequences of operand types and .
Note
The instruction is stack-polymorphic.
3.3.8.3.
-
The block type must be valid as some function type .
-
Let be the same context as , but with the result type prepended to the vector.
-
Under context , the instruction sequence must be valid with type .
-
Then the compound instruction is valid with type .
Note
The notation inserts the new label type at index , shifting all others.
3.3.8.4.
-
The block type must be valid as some function type .
-
Let be the same context as , but with the result type prepended to the vector.
-
Under context , the instruction sequence must be valid with type .
-
Then the compound instruction is valid with type .
Note
The notation inserts the new label type at index , shifting all others.
3.3.8.5.
-
The block type must be valid as some function type .
-
Let be the same context as , but with the result type prepended to the vector.
-
Under context , the instruction sequence must be valid with type .
-
Under context , the instruction sequence must be valid with type .
-
Then the compound instruction is valid with type .
Note
The notation inserts the new label type at index , shifting all others.
3.3.8.6.
-
The label must be defined in the context.
-
Let be the result type .
-
Then the instruction is valid with type , for any sequences of operand types and .
Note
The label index space in the context contains the most recent label first, so that performs a relative lookup as expected.
The instruction is stack-polymorphic.
3.3.8.7.
-
The label must be defined in the context.
-
Let be the result type .
-
Then the instruction is valid with type .
Note
The label index space in the context contains the most recent label first, so that performs a relative lookup as expected.
3.3.8.8.
-
The label must be defined in the context.
-
For each label in , the label must be defined in the context.
-
There must be a sequence of operand types, such that:
-
The length of the sequence is the same as the length of the sequence .
-
For each operand type in and corresponding type in , matches .
-
For each label in :
-
The length of the sequence is the same as the length of the sequence .
-
For each operand type in and corresponding type in , matches .
-
-
-
Then the instruction is valid with type , for any sequences of operand types and .
Note
The label index space in the context contains the most recent label first, so that performs a relative lookup as expected.
The instruction is stack-polymorphic.
3.3.8.9.
-
The return type must not be absent in the context.
-
Let be the result type of .
-
Then the instruction is valid with type , for any sequences of operand types and .
Note
The instruction is stack-polymorphic.
is absent (set to ) when validating an expression that is not a function body. This differs from it being set to the empty result type (), which is the case for functions not returning anything.
3.3.8.10.
-
The function must be defined in the context.
-
Then the instruction is valid with type .
3.3.8.11.
-
The table must be defined in the context.
-
Let be the table type .
-
The reference type must be .
-
The type must be defined in the context.
-
Let be the function type .
-
Then the instruction is valid with type .
3.3.9. Instruction Sequences
Typing of instruction sequences is defined recursively.
3.3.9.1. Empty Instruction Sequence:
-
The empty instruction sequence is valid with type , for any sequence of operand types .
3.3.9.2. Non-empty Instruction Sequence:
-
The instruction sequence must be valid with type , for some sequences of operand types and .
-
The instruction must be valid with type , for some sequences of operand types and .
-
There must be a sequence of operand types , such that where the type sequence is as long as .
-
For each operand type in and corresponding type in , matches .
-
Then the combined instruction sequence is valid with type .
3.3.10. Expressions
Expressions are classified by result types of the form .
3.3.10.1.
-
The instruction sequence must be valid with some stack type .
-
For each operand type in and corresponding value type in , matches .
-
Then the expression is valid with result type .
3.3.10.2. Constant Expressions
-
In a constant expression all instructions in must be constant.
-
A constant instruction must be:
-
either of the form ,
-
or of the form ,
-
or of the form ,
-
or of the form , in which case must be a global type of the form .
-
Note
Currently, constant expressions occurring in globals, element, or data segments are further constrained in that contained instructions are only allowed to refer to imported globals. This is enforced in the validation rule for modules by constraining the context accordingly.
The definition of constant expression may be extended in future versions of WebAssembly.
3.4. Modules
Modules are valid when all the components they contain are valid. Furthermore, most definitions are themselves classified with a suitable type.
3.4.1. Functions
Functions are classified by function types of the form .
3.4.1.1.
-
The type must be defined in the context.
-
Let be the function type .
-
Let be the same context as , but with:
-
set to the sequence of value types , concatenating parameters and locals,
-
set to the singular sequence containing only result type .
-
set to the result type .
-
-
Under the context , the expression must be valid with type .
-
Then the function definition is valid with type .
3.4.2. Tables
Tables are classified by table types.
3.4.2.1.
-
The table type must be valid.
-
Then the table definition is valid with type .
3.4.3. Memories
Memories are classified by memory types.
3.4.3.1.
-
The memory type must be valid.
-
Then the memory definition is valid with type .
3.4.4. Globals
Globals are classified by global types of the form .
3.4.4.1.
-
The global type must be valid.
-
The expression must be valid with result type .
-
The expression must be constant.
-
Then the global definition is valid with type .
3.4.5. Element Segments
Element segments are classified by the reference type of their elements.
3.4.5.1.
-
For each in :
-
The expression must be valid with some result type .
-
The expression must be constant.
-
-
The element mode must be valid with reference type .
-
Then the element segment is valid with reference type .
3.4.5.2.
-
The element mode is valid with any reference type.
3.4.5.3.
-
The table must be defined in the context.
-
Let be the table type .
-
The expression must be valid with result type .
-
The expression must be constant.
-
Then the element mode is valid with reference type .
3.4.5.4.
-
The element mode is valid with any reference type.
3.4.6. Data Segments
Data segments are not classified by any type but merely checked for well-formedness.
3.4.6.1.
-
The data mode must be valid.
-
Then the data segment is valid.
3.4.6.2.
-
The data mode is valid.
3.4.6.3.
-
The memory must be defined in the context.
-
The expression must be valid with result type .
-
The expression must be constant.
-
Then the data mode is valid.
3.4.7. Start Function
Start function declarations are not classified by any type.
3.4.7.1.
-
The function must be defined in the context.
-
The type of must be .
-
Then the start function is valid.
3.4.8. Exports
Exports and export descriptions are classified by their external type.
3.4.8.1.
-
The export description must be valid with external type .
-
Then the export is valid with external type .
3.4.8.2.
-
The function must be defined in the context.
-
Then the export description is valid with external type .
3.4.8.3.
-
The table must be defined in the context.
-
Then the export description is valid with external type .
3.4.8.4.
-
The memory must be defined in the context.
-
Then the export description is valid with external type .
3.4.8.5.
-
The global must be defined in the context.
-
Then the export description is valid with external type .
3.4.9. Imports
Imports and import descriptions are classified by external types.
3.4.9.1.
-
The import description must be valid with type .
-
Then the import is valid with type .
3.4.9.2.
-
The function must be defined in the context.
-
Let be the function type .
-
Then the import description is valid with type .
3.4.9.3.
-
The table type must be valid.
-
Then the import description is valid with type .
3.4.9.4.
-
The memory type must be valid.
-
Then the import description is valid with type .
3.4.9.5.
-
The global type must be valid.
-
Then the import description is valid with type .
3.4.10. Modules
Modules are classified by their mapping from the external types of their imports to those of their exports.
A module is entirely closed, that is, its components can only refer to definitions that appear in the module itself. Consequently, no initial context is required. Instead, the context for validation of the module’s content is constructed from the definitions in the module.
-
Let be the module to validate.
-
Let be a context where:
-
is ,
-
is concatenated with , with the import’s external types and the internal function types as determined below,
-
is concatenated with , with the import’s external types and the internal table types as determined below,
-
is concatenated with , with the import’s external types and the internal memory types as determined below,
-
is concatenated with , with the import’s external types and the internal global types as determined below,
-
is as determined below,
-
is , where is the length of the vector ,
-
is empty,
-
is empty,
-
is empty.
-
is the set , i.e., the set of function indices occurring in the module, except in its functions or start function.
-
-
Let be the same context as , except that is just the sequence .
-
For each in , the function type must be valid.
-
Under the context :
-
For each in , the definition must be valid with a table type .
-
For each in , the definition must be valid with a memory type .
-
For each in , the definition must be valid with a global type .
-
For each in , the segment must be valid with reference type .
-
For each in , the segment must be valid.
-
-
Under the context :
-
For each in , the definition must be valid with a function type .
-
If is non-empty, then must be valid.
-
For each in , the segment must be valid with an external type .
-
For each in , the segment must be valid with external type .
-
-
The length of must not be larger than .
-
All export names must be different.
-
Let be the concatenation of the internal function types , in index order.
-
Let be the concatenation of the internal table types , in index order.
-
Let be the concatenation of the internal memory types , in index order.
-
Let be the concatenation of the internal global types , in index order.
-
Let be the concatenation of the reference types , in index order.
-
Let be the concatenation of external types of the imports, in index order.
-
Let be the concatenation of external types of the exports, in index order.
-
Then the module is valid with external types .
Note
Most definitions in a module – particularly functions – are mutually recursive. Consequently, the definition of the context in this rule is recursive: it depends on the outcome of validation of the function, table, memory, and global definitions contained in the module, which itself depends on . However, this recursion is just a specification device. All types needed to construct can easily be determined from a simple pre-pass over the module that does not perform any actual validation.
Globals, however, are not recursive and not accessible within constant expressions when they are defined locally. The effect of defining the limited context for validating certain definitions is that they can only access functions and imported globals and nothing else.
Note
The restriction on the number of memories may be lifted in future versions of WebAssembly.
4. Execution
4.1. Conventions
WebAssembly code is executed when instantiating a module or invoking an exported function on the resulting module instance.
Execution behavior is defined in terms of an abstract machine that models the program state. It includes a stack, which records operand values and control constructs, and an abstract store containing global state.
For each instruction, there is a rule that specifies the effect of its execution on the program state. Furthermore, there are rules describing the instantiation of a module. As with validation, all rules are given in two equivalent forms:
-
In prose, describing the execution in intuitive form.
-
In formal notation, describing the rule in mathematical form. [1]
Note
As with validation, the prose and formal rules are equivalent, so that understanding of the formal notation is not required to read this specification. The formalism offers a more concise description in notation that is used widely in programming languages semantics and is readily amenable to mathematical proof.
4.1.1. Prose Notation
Execution is specified by stylised, step-wise rules for each instruction of the abstract syntax. The following conventions are adopted in stating these rules.
-
The execution rules implicitly assume a given store .
-
The execution rules also assume the presence of an implicit stack that is modified by pushing or popping values, labels, and frames.
-
Certain rules require the stack to contain at least one frame. The most recent frame is referred to as the current frame.
-
Both the store and the current frame are mutated by replacing some of their components. Such replacement is assumed to apply globally.
-
The execution of an instruction may trap, in which case the entire computation is aborted and no further modifications to the store are performed by it. (Other computations can still be initiated afterwards.)
-
The execution of an instruction may also end in a jump to a designated target, which defines the next instruction to execute.
-
Execution can enter and exit instruction sequences that form blocks.
-
Instruction sequences are implicitly executed in order, unless a trap or jump occurs.
-
In various places the rules contain assertions expressing crucial invariants about the program state.
4.1.2. Formal Notation
Note
This section gives a brief explanation of the notation for specifying execution formally. For the interested reader, a more thorough introduction can be found in respective text books. [2]
The formal execution rules use a standard approach for specifying operational semantics, rendering them into reduction rules. Every rule has the following general form:
A configuration is a syntactic description of a program state. Each rule specifies one step of execution. As long as there is at most one reduction rule applicable to a given configuration, reduction – and thereby execution – is deterministic. WebAssembly has only very few exceptions to this, which are noted explicitly in this specification.
For WebAssembly, a configuration typically is a tuple consisting of the current store , the call frame of the current function, and the sequence of instructions that is to be executed. (A more precise definition is given later.)
To avoid unnecessary clutter, the store and the frame are omitted from reduction rules that do not touch them.
There is no separate representation of the stack. Instead, it is conveniently represented as part of the configuration’s instruction sequence. In particular, values are defined to coincide with instructions, and a sequence of instructions can be interpreted as an operand “stack” that grows to the right.
Note
For example, the reduction rule for the instruction can be given as follows:
Per this rule, two instructions and the instruction itself are removed from the instruction stream and replaced with one new instruction. This can be interpreted as popping two values off the stack and pushing the result.
When no result is produced, an instruction reduces to the empty sequence:
Labels and frames are similarly defined to be part of an instruction sequence.
The order of reduction is determined by the definition of an appropriate evaluation context.
Reduction terminates when no more reduction rules are applicable. Soundness of the WebAssembly type system guarantees that this is only the case when the original instruction sequence has either been reduced to a sequence of instructions, which can be interpreted as the values of the resulting operand stack, or if a trap occurred.
Note
For example, the following instruction sequence,
terminates after three steps:
where and and .
The semantics is derived from the following article: Andreas Haas, Andreas Rossberg, Derek Schuff, Ben Titzer, Dan Gohman, Luke Wagner, Alon Zakai, JF Bastien, Michael Holman. Bringing the Web up to Speed with WebAssembly. Proceedings of the 38th ACM SIGPLAN Conference on Programming Language Design and Implementation (PLDI 2017). ACM 2017.
For example: Benjamin Pierce. Types and Programming Languages. The MIT Press 2002
4.2. Runtime Structure
Store, stack, and other runtime structure forming the WebAssembly abstract machine, such as values or module instances, are made precise in terms of additional auxiliary syntax.
4.2.1. Values
WebAssembly computations manipulate values of either the four basic number types, i.e., integers and floating-point data of 32 or 64 bit width each, or vectors of 128 bit width, or of reference type.
In most places of the semantics, values of different types can occur. In order to avoid ambiguities, values are therefore represented with an abstract syntax that makes their type explicit. It is convenient to reuse the same notation as for the instructions and producing them.
References other than null are represented with additional administrative instructions. They either are function references, pointing to a specific function address, or external references pointing to an uninterpreted form of extern address that can be defined by the embedder to represent its own objects.
Note
Future versions of WebAssembly may add additional forms of reference.
Each value type has an associated default value; it is the respective value for number types, for vector types, and null for reference types.
4.2.1.1. Convention
-
The meta variable ranges over reference values where clear from context.
4.2.2. Results
A result is the outcome of a computation. It is either a sequence of values or a trap.
4.2.3. Store
The store represents all global state that can be manipulated by WebAssembly programs. It consists of the runtime representation of all instances of functions, tables, memories, and globals, element segments, and data segments that have been allocated during the life time of the abstract machine. [1]
It is an invariant of the semantics that no element or data instance is addressed from anywhere else but the owning module instances.
Syntactically, the store is defined as a record listing the existing instances of each category:
In practice, implementations may apply techniques like garbage collection to remove objects from the store that are no longer referenced. However, such techniques are not semantically observable, and hence outside the scope of this specification.
4.2.3.1. Convention
-
The meta variable ranges over stores where clear from context.
4.2.4. Addresses
Function instances, table instances, memory instances, and global instances, element instances, and data instances in the store are referenced with abstract addresses. These are simply indices into the respective store component. In addition, an embedder may supply an uninterpreted set of host addresses.
An embedder may assign identity to exported store objects corresponding to their addresses, even where this identity is not observable from within WebAssembly code itself (such as for function instances or immutable globals).
Note
Addresses are dynamic, globally unique references to runtime objects, in contrast to indices, which are static, module-local references to their original definitions. A memory address denotes the abstract address of a memory instance in the store, not an offset inside a memory instance.
There is no specific limit on the number of allocations of store objects, hence logical addresses can be arbitrarily large natural numbers.
4.2.5. Module Instances
A module instance is the runtime representation of a module. It is created by instantiating a module, and collects runtime representations of all entities that are imported, defined, or exported by the module.
Each component references runtime instances corresponding to respective declarations from the original module – whether imported or defined – in the order of their static indices. Function instances, table instances, memory instances, and global instances are referenced with an indirection through their respective addresses in the store.
It is an invariant of the semantics that all export instances in a given module instance have different names.
4.2.6. Function Instances
A function instance is the runtime representation of a function. It effectively is a closure of the original function over the runtime module instance of its originating module. The module instance is used to resolve references to other definitions during execution of the function.
A host function is a function expressed outside WebAssembly but passed to a module as an import. The definition and behavior of host functions are outside the scope of this specification. For the purpose of this specification, it is assumed that when invoked, a host function behaves non-deterministically, but within certain constraints that ensure the integrity of the runtime.
4.2.7. Table Instances
A table instance is the runtime representation of a table. It records its type and holds a vector of reference values.
Table elements can be mutated through table instructions, the execution of an active element segment, or by external means provided by the embedder.
It is an invariant of the semantics that all table elements have a type equal to the element type of . It also is an invariant that the length of the element vector never exceeds the maximum size of , if present.
4.2.8. Memory Instances
A memory instance is the runtime representation of a linear memory. It records its type and holds a vector of bytes.
The length of the vector always is a multiple of the WebAssembly page size, which is defined to be the constant – abbreviated .
The bytes can be mutated through memory instructions, the execution of an active data segment, or by external means provided by the embedder.
It is an invariant of the semantics that the length of the byte vector, divided by page size, never exceeds the maximum size of , if present.
4.2.9. Global Instances
A global instance is the runtime representation of a global variable. It records its type and holds an individual value.
The value of mutable globals can be mutated through variable instructions or by external means provided by the embedder.
It is an invariant of the semantics that the value has a type equal to the value type of .
4.2.10. Element Instances
An element instance is the runtime representation of an element segment. It holds a vector of references and their common type.
4.2.11. Data Instances
An data instance is the runtime representation of a data segment. It holds a vector of bytes.
4.2.12. Export Instances
An export instance is the runtime representation of an export. It defines the export’s name and the associated external value.
4.2.13. External Values
An external value is the runtime representation of an entity that can be imported or exported. It is an address denoting either a function instance, table instance, memory instance, or global instances in the shared store.
4.2.13.1. Conventions
The following auxiliary notation is defined for sequences of external values. It filters out entries of a specific kind in an order-preserving fashion:
4.2.14. Stack
Besides the store, most instructions interact with an implicit stack. The stack contains three kinds of entries:
-
Values: the operands of instructions.
-
Labels: active structured control instructions that can be targeted by branches.
-
Activations: the call frames of active function calls.
These entries can occur on the stack in any order during the execution of a program. Stack entries are described by abstract syntax as follows.
Note
It is possible to model the WebAssembly semantics using separate stacks for operands, control constructs, and calls. However, because the stacks are interdependent, additional book keeping about associated stack heights would be required. For the purpose of this specification, an interleaved representation is simpler.
4.2.14.1. Values
Values are represented by themselves.
4.2.14.2. Labels
Labels carry an argument arity and their associated branch target, which is expressed syntactically as an instruction sequence:
Intuitively, is the continuation to execute when the branch is taken, in place of the original control construct.
Note
For example, a loop label has the form
When performing a branch to this label, this executes the loop, effectively restarting it from the beginning. Conversely, a simple block label has the form
When branching, the empty continuation ends the targeted block, such that execution can proceed with consecutive instructions.
4.2.14.3. Activation Frames
Activation frames carry the return arity of the respective function, hold the values of its locals (including arguments) in the order corresponding to their static local indices, and a reference to the function’s own module instance:
The values of the locals are mutated by respective variable instructions.
4.2.14.4. Conventions
-
The meta variable ranges over labels where clear from context.
-
The meta variable ranges over frame states where clear from context.
-
The following auxiliary definition takes a block type and looks up the function type that it denotes in the current frame:
4.2.15. Administrative Instructions
Note
This section is only relevant for the formal notation.
In order to express the reduction of traps, calls, and control instructions, the syntax of instructions is extended to include the following administrative instructions:
The instruction represents the occurrence of a trap. Traps are bubbled up through nested instruction sequences, ultimately reducing the entire program to a single instruction, signalling abrupt termination.
The instruction represents function reference values. Similarly, represents external references.
The instruction represents the imminent invocation of a function instance, identified by its address. It unifies the handling of different forms of calls.
The and instructions model labels and frames “on the stack”. Moreover, the administrative syntax maintains the nesting structure of the original structured control instruction or function body and their instruction sequences with an marker. That way, the end of the inner instruction sequence is known when part of an outer sequence.
Note
For example, the reduction rule for is:
This replaces the block with a label instruction, which can be interpreted as “pushing” the label on the stack. When is reached, i.e., the inner instruction sequence has been reduced to the empty sequence – or rather, a sequence of instructions representing the resulting values – then the instruction is eliminated courtesy of its own reduction rule:
This can be interpreted as removing the label from the stack and only leaving the locally accumulated operand values.
4.2.15.1. Block Contexts
In order to specify the reduction of branches, the following syntax of block contexts is defined, indexed by the count of labels surrounding a hole that marks the place where the next step of computation is taking place:
This definition allows to index active labels surrounding a branch or return instruction.
Note
For example, the reduction of a simple branch can be defined as follows:
Here, the hole of the context is instantiated with a branch instruction. When a branch occurs, this rule replaces the targeted label and associated instruction sequence with the label’s continuation. The selected label is identified through the label index , which corresponds to the number of surrounding instructions that must be hopped over – which is exactly the count encoded in the index of a block context.
4.2.15.2. Configurations
A configuration consists of the current store and an executing thread.
A thread is a computation over instructions that operates relative to the state of a current frame referring to the module instance in which the computation runs, i.e., where the current function originates from.
Note
The current version of WebAssembly is single-threaded, but configurations with multiple threads may be supported in the future.
4.2.15.3. Evaluation Contexts
Finally, the following definition of evaluation context and associated structural rules enable reduction inside instruction sequences and administrative forms as well as the propagation of traps:
Reduction terminates when a thread’s instruction sequence has been reduced to a result, that is, either a sequence of values or to a .
Note
The restriction on evaluation contexts rules out contexts like and for which .
For an example of reduction under evaluation contexts, consider the following instruction sequence.
This can be decomposed into where
Moreover, this is the only possible choice of evaluation context where the contents of the hole matches the left-hand side of a reduction rule.
4.3. Numerics
Numeric primitives are defined in a generic manner, by operators indexed over a bit width .
Some operators are non-deterministic, because they can return one of several possible results (such as different NaN values). Technically, each operator thus returns a set of allowed values. For convenience, deterministic results are expressed as plain values, which are assumed to be identified with a respective singleton set.
Some operators are partial, because they are not defined on certain inputs. Technically, an empty set of results is returned for these inputs.
In formal notation, each operator is defined by equational clauses that apply in decreasing order of precedence. That is, the first clause that is applicable to the given arguments defines the result. In some cases, similar clauses are combined into one by using the notation or . When several of these placeholders occur in a single clause, then they must be resolved consistently: either the upper sign is chosen for all of them or the lower sign.
Note
For example, the operator is defined as follows:
This definition is to be read as a shorthand for the following expansion of each clause into two separate ones:
Numeric operators are lifted to input sequences by applying the operator element-wise, returning a sequence of results. When there are multiple inputs, they must be of equal length.
Note
For example, the unary operator , when given a sequence of floating-point values, return a sequence of floating-point results:
The binary operator , when given two sequences of integers of the same length, , return a sequence of integer results:
Conventions:
-
The meta variable is used to range over single bits.
-
The meta variable is used to range over (signless) magnitudes of floating-point values, including and .
-
The meta variable is used to range over (signless) rational magnitudes, excluding or .
-
The notation denotes the inverse of a bijective function .
-
Truncation of rational values is written , with the usual mathematical definition:
-
Saturation of integers is written and . The arguments to these two functions range over arbitrary signed integers.
-
Unsigned saturation, clamps to between and :
-
Signed saturation, clamps to between and :
-
4.3.1. Representations
Numbers and numeric vectors have an underlying binary representation as a sequence of bits:
Each of these functions is a bijection, hence they are invertible.
4.3.1.1. Integers
Integers are represented as base two unsigned numbers:
Boolean operators like , , or are lifted to bit sequences of equal length by applying them pointwise.
4.3.1.2. Floating-Point
Floating-point values are represented in the respective binary format defined by [IEEE-754-2019] (Section 3.4):
where and .
4.3.1.3. Vectors
Numeric vectors of type have the same underlying representation as an . They can also be interpreted as a sequence of numeric values packed into a with a particular , provided that .
This function is a bijection on , hence it is invertible.
4.3.1.4. Storage
When a number is stored into memory, it is converted into a sequence of bytes in little endian byte order:
Again these functions are invertible bijections.
4.3.2. Integer Operations
4.3.2.1. Sign Interpretation
Integer operators are defined on values. Operators that use a signed interpretation convert the value using the following definition, which takes the two’s complement when the value lies in the upper half of the value range (i.e., its most significant bit is ):
This function is bijective, and hence invertible.
4.3.2.2. Boolean Interpretation
The integer result of predicates – i.e., tests and relational operators – is defined with the help of the following auxiliary function producing the value or depending on a condition.
4.3.2.3.
-
Return the result of adding and modulo .
4.3.2.4.
-
Return the result of subtracting from modulo .
4.3.2.5.
-
Return the result of multiplying and modulo .
4.3.2.6.
-
If is , then the result is undefined.
-
Else, return the result of dividing by , truncated toward zero.
Note
This operator is partial.
4.3.2.7.
-
Let be the signed interpretation of .
-
Let be the signed interpretation of .
-
If is , then the result is undefined.
-
Else if divided by is , then the result is undefined.
-
Else, return the result of dividing by , truncated toward zero.
Note
This operator is partial. Besides division by , the result of is not representable as an -bit signed integer.
4.3.2.8.
-
If is , then the result is undefined.
-
Else, return the remainder of dividing by .
4.3.2.9.
-
Let be the signed interpretation of .
-
Let be the signed interpretation of .
-
If is , then the result is undefined.
-
Else, return the remainder of dividing by , with the sign of the dividend .
4.3.2.10.
-
Return the bitwise negation of .
4.3.2.11.
-
Return the bitwise conjunction of and .
4.3.2.12.
-
Return the bitwise conjunction of and the bitwise negation of .
4.3.2.13.
-
Return the bitwise disjunction of and .
4.3.2.14.
-
Return the bitwise exclusive disjunction of and .
4.3.2.15.
-
Let be modulo .
-
Return the result of shifting left by bits, modulo .
4.3.2.16.
-
Let be modulo .
-
Return the result of shifting right by bits, extended with bits.
4.3.2.17.
-
Let be modulo .
-
Return the result of shifting right by bits, extended with the most significant bit of the original value.
4.3.2.18.
-
Let be modulo .
-
Return the result of rotating left by bits.
4.3.2.19.
-
Let be modulo .
-
Return the result of rotating right by bits.
4.3.2.20.
-
Return the count of leading zero bits in ; all bits are considered leading zeros if is .
4.3.2.21.
-
Return the count of trailing zero bits in ; all bits are considered trailing zeros if is .
4.3.2.22.
-
Return the count of non-zero bits in .
4.3.2.23.
-
Return if is zero, otherwise.
4.3.2.24.
-
Return if equals , otherwise.
4.3.2.25.
-
Return if does not equal , otherwise.
4.3.2.26.
-
Return if is less than , otherwise.
4.3.2.27.
-
Let be the signed interpretation of .
-
Let be the signed interpretation of .
-
Return if is less than , otherwise.
4.3.2.28.
-
Return if is greater than , otherwise.
4.3.2.29.
-
Let be the signed interpretation of .
-
Let be the signed interpretation of .
-
Return if is greater than , otherwise.
4.3.2.30.
-
Return if is less than or equal to , otherwise.
4.3.2.31.
-
Let be the signed interpretation of .
-
Let be the signed interpretation of .
-
Return if is less than or equal to , otherwise.
4.3.2.32.
-
Return if is greater than or equal to , otherwise.
4.3.2.33.
-
Let be the signed interpretation of .
-
Let be the signed interpretation of .
-
Return if is greater than or equal to , otherwise.
4.3.2.34.
-
Let be the result of computing .
-
Return .
4.3.2.35.
-
Let be the bitwise conjunction of and .
-
Let be the bitwise negation of .
-
Let be the bitwise conjunction of and .
-
Return the bitwise disjunction of and .
4.3.2.36.
-
Let be the signed interpretation of .
-
If is greater than or equal to , then return .
-
Else return the negation of j, modulo .
4.3.2.37.
-
Return the result of negating , modulo .
4.3.2.38.
-
Return if is , return otherwise.
4.3.2.39.
-
Return if is , return otherwise.
4.3.2.40.
-
Return if is , return otherwise.
4.3.2.41.
-
Return if is , return otherwise.
4.3.2.42.
-
Let be the result of adding and .
-
Return .
4.3.2.43.
-
Let be the signed interpretation of
-
Let be the signed interpretation of
-
Let be the result of adding and .
-
Return .
4.3.2.44.
-
Let be the result of subtracting from .
-
Return .
4.3.2.45.
-
Let be the signed interpretation of
-
Let be the signed interpretation of
-
Let be the result of subtracting from .
-
Return .
4.3.2.46.
-
Let be the result of adding , , and .
-
Return the result of dividing by , truncated toward zero.
4.3.2.47.
-
Return the result of .
4.3.3. Floating-Point Operations
Floating-point arithmetic follows the [IEEE-754-2019] standard, with the following qualifications:
-
All operators use round-to-nearest ties-to-even, except where otherwise specified. Non-default directed rounding attributes are not supported.
-
Following the recommendation that operators propagate NaN payloads from their operands is permitted but not required.
-
All operators use “non-stop” mode, and floating-point exceptions are not otherwise observable. In particular, neither alternate floating-point exception handling attributes nor operators on status flags are supported. There is no observable difference between quiet and signalling NaNs.
Note
Some of these limitations may be lifted in future versions of WebAssembly.
4.3.3.1. Rounding
Rounding always is round-to-nearest ties-to-even, in correspondence with [IEEE-754-2019] (Section 4.3.1).
An exact floating-point number is a rational number that is exactly representable as a floating-point number of given bit width .
A limit number for a given floating-point bit width is a positive or negative number whose magnitude is the smallest power of that is not exactly representable as a floating-point number of width (that magnitude is for and for ).
A candidate number is either an exact floating-point number or a positive or negative limit number for the given bit width .
A candidate pair is a pair of candidate numbers, such that no candidate number exists that lies between the two.
A real number is converted to a floating-point value of bit width as follows:
-
If is , then return .
-
Else if is an exact floating-point number, then return .
-
Else if greater than or equal to the positive limit, then return .
-
Else if is less than or equal to the negative limit, then return .
-
Else if and are a candidate pair such that , then:
-
If , then let be .
-
Else if , then let be .
-
Else if and the significand of is even, then let be .
-
Else, let be .
-
-
If is , then:
-
If , then return .
-
Else, return .
-
-
Else if is a limit number, then:
-
If , then return .
-
Else, return .
-
-
Else, return .
where:
4.3.3.2. NaN Propagation
When the result of a floating-point operator other than , , or is a NaN, then its sign is non-deterministic and the payload is computed as follows:
-
If the payload of all NaN inputs to the operator is canonical (including the case that there are no NaN inputs), then the payload of the output is canonical as well.
-
Otherwise the payload is picked non-deterministically among all arithmetic NaNs; that is, its most significant bit is and all others are unspecified.
This non-deterministic result is expressed by the following auxiliary function producing a set of allowed outputs from a set of inputs:
4.3.3.3.
-
If either or is a NaN, then return an element of .
-
Else if both and are infinities of opposite signs, then return an element of .
-
Else if both and are infinities of equal sign, then return that infinity.
-
Else if either or is an infinity, then return that infinity.
-
Else if both and are zeroes of opposite sign, then return positive zero.
-
Else if both and are zeroes of equal sign, then return that zero.
-
Else if either or is a zero, then return the other operand.
-
Else if both and are values with the same magnitude but opposite signs, then return positive zero.
-
Else return the result of adding and , rounded to the nearest representable value.
4.3.3.4.
-
If either or is a NaN, then return an element of .
-
Else if both and are infinities of equal signs, then return an element of .
-
Else if both and are infinities of opposite sign, then return .
-
Else if is an infinity, then return that infinity.
-
Else if is an infinity, then return that infinity negated.
-
Else if both and are zeroes of equal sign, then return positive zero.
-
Else if both and are zeroes of opposite sign, then return .
-
Else if is a zero, then return .
-
Else if is a zero, then return negated.
-
Else if both and are the same value, then return positive zero.
-
Else return the result of subtracting from , rounded to the nearest representable value.
Note
Up to the non-determinism regarding NaNs, it always holds that .
4.3.3.5.
-
If either or is a NaN, then return an element of .
-
Else if one of and is a zero and the other an infinity, then return an element of .
-
Else if both and are infinities of equal sign, then return positive infinity.
-
Else if both and are infinities of opposite sign, then return negative infinity.
-
Else if either or is an infinity and the other a value with equal sign, then return positive infinity.
-
Else if either or is an infinity and the other a value with opposite sign, then return negative infinity.
-
Else if both and are zeroes of equal sign, then return positive zero.
-
Else if both and are zeroes of opposite sign, then return negative zero.
-
Else return the result of multiplying and , rounded to the nearest representable value.
4.3.3.6.
-
If either or is a NaN, then return an element of .
-
Else if both and are infinities, then return an element of .
-
Else if both and are zeroes, then return an element of .
-
Else if is an infinity and a value with equal sign, then return positive infinity.
-
Else if is an infinity and a value with opposite sign, then return negative infinity.
-
Else if is an infinity and a value with equal sign, then return positive zero.
-
Else if is an infinity and a value with opposite sign, then return negative zero.
-
Else if is a zero and a value with equal sign, then return positive zero.
-
Else if is a zero and a value with opposite sign, then return negative zero.
-
Else if is a zero and a value with equal sign, then return positive infinity.
-
Else if is a zero and a value with opposite sign, then return negative infinity.
-
Else return the result of dividing by , rounded to the nearest representable value.
4.3.3.7.
-
If either or is a NaN, then return an element of .
-
Else if either or is a negative infinity, then return negative infinity.
-
Else if either or is a positive infinity, then return the other value.
-
Else if both and are zeroes of opposite signs, then return negative zero.
-
Else return the smaller value of and .
4.3.3.8.
-
If either or is a NaN, then return an element of .
-
Else if either or is a positive infinity, then return positive infinity.
-
Else if either or is a negative infinity, then return the other value.
-
Else if both and are zeroes of opposite signs, then return positive zero.
-
Else return the larger value of and .
4.3.3.9.
-
If and have the same sign, then return .
-
Else return with negated sign.
4.3.3.10.
-
If is a NaN, then return with positive sign.
-
Else if is an infinity, then return positive infinity.
-
Else if is a zero, then return positive zero.
-
Else if is a positive value, then .
-
Else return negated.
4.3.3.11.
-
If is a NaN, then return with negated sign.
-
Else if is an infinity, then return that infinity negated.
-
Else if is a zero, then return that zero negated.
-
Else return negated.
4.3.3.12.
-
If is a NaN, then return an element of .
-
Else if is negative infinity, then return an element of .
-
Else if is positive infinity, then return positive infinity.
-
Else if is a zero, then return that zero.
-
Else if has a negative sign, then return an element of .
-
Else return the square root of .
4.3.3.13.
-
If is a NaN, then return an element of .
-
Else if is an infinity, then return .
-
Else if is a zero, then return .
-
Else if is smaller than but greater than , then return negative zero.
-
Else return the smallest integral value that is not smaller than .
4.3.3.14.
-
If is a NaN, then return an element of .
-
Else if is an infinity, then return .
-
Else if is a zero, then return .
-
Else if is greater than but smaller than , then return positive zero.
-
Else return the largest integral value that is not larger than .
4.3.3.15.
-
If is a NaN, then return an element of .
-
Else if is an infinity, then return .
-
Else if is a zero, then return .
-
Else if is greater than but smaller than , then return positive zero.
-
Else if is smaller than but greater than , then return negative zero.
-
Else return the integral value with the same sign as and the largest magnitude that is not larger than the magnitude of .
4.3.3.16.
-
If is a NaN, then return an element of .
-
Else if is an infinity, then return .
-
Else if is a zero, then return .
-
Else if is greater than but smaller than or equal to , then return positive zero.
-
Else if is smaller than but greater than or equal to , then return negative zero.
-
Else return the integral value that is nearest to ; if two values are equally near, return the even one.
4.3.3.17.
-
If either or is a NaN, then return .
-
Else if both and are zeroes, then return .
-
Else if both and are the same value, then return .
-
Else return .
4.3.3.18.
-
If either or is a NaN, then return .
-
Else if both and are zeroes, then return .
-
Else if both and are the same value, then return .
-
Else return .
4.3.3.19.
-
If either or is a NaN, then return .
-
Else if and are the same value, then return .
-
Else if is positive infinity, then return .
-
Else if is negative infinity, then return .
-
Else if is positive infinity, then return .
-
Else if is negative infinity, then return .
-
Else if both and are zeroes, then return .
-
Else if is smaller than , then return .
-
Else return .
4.3.3.20.
-
If either or is a NaN, then return .
-
Else if and are the same value, then return .
-
Else if is positive infinity, then return .
-
Else if is negative infinity, then return .
-
Else if is positive infinity, then return .
-
Else if is negative infinity, then return .
-
Else if both and are zeroes, then return .
-
Else if is larger than , then return .
-
Else return .
4.3.3.21.
-
If either or is a NaN, then return .
-
Else if and are the same value, then return .
-
Else if is positive infinity, then return .
-
Else if is negative infinity, then return .
-
Else if is positive infinity, then return .
-
Else if is negative infinity, then return .
-
Else if both and are zeroes, then return .
-
Else if is smaller than or equal to , then return .
-
Else return .
4.3.3.22.
-
If either or is a NaN, then return .
-
Else if and are the same value, then return .
-
Else if is positive infinity, then return .
-
Else if is negative infinity, then return .
-
Else if is positive infinity, then return .
-
Else if is negative infinity, then return .
-
Else if both and are zeroes, then return .
-
Else if is smaller than or equal to , then return .
-
Else return .
4.3.3.23.
-
If is less than then return .
-
Else return .
4.3.3.24.
-
If is less than then return .
-
Else return .
4.3.4. Conversions
4.3.4.1.
-
Return .
Note
In the abstract syntax, unsigned extension just reinterprets the same value.
4.3.4.2.
-
Let be the signed interpretation of of size .
-
Return the two’s complement of relative to size .
4.3.4.3.
-
Return modulo .
4.3.4.4.
-
If is a NaN, then the result is undefined.
-
Else if is an infinity, then the result is undefined.
-
Else if is a number and is a value within range of the target type, then return that value.
-
Else the result is undefined.
Note
This operator is partial. It is not defined for NaNs, infinities, or values for which the result is out of range.
4.3.4.5.
-
If is a NaN, then the result is undefined.
-
Else if is an infinity, then the result is undefined.
-
If is a number and is a value within range of the target type, then return that value.
-
Else the result is undefined.
Note
This operator is partial. It is not defined for NaNs, infinities, or values for which the result is out of range.
4.3.4.6.
-
If is a NaN, then return .
-
Else if is negative infinity, then return .
-
Else if is positive infinity, then return .
-
Else, return .
4.3.4.7.
-
If is a NaN, then return .
-
Else if is negative infinity, then return .
-
Else if is positive infinity, then return .
-
Else, return .
4.3.4.8.
-
If is a canonical NaN, then return an element of (i.e., a canonical NaN of size ).
-
Else if is a NaN, then return an element of (i.e., any arithmetic NaN of size ).
-
Else, return .
4.3.4.9.
-
If is a canonical NaN, then return an element of (i.e., a canonical NaN of size ).
-
Else if is a NaN, then return an element of (i.e., any NaN of size ).
-
Else if is an infinity, then return that infinity.
-
Else if is a zero, then return that zero.
-
Else, return .
4.3.4.10.
-
Return .
4.3.4.11.
-
Let be the signed interpretation of .
-
Return .
4.3.4.12.
-
Let be the bit sequence .
-
Return the constant for which .
4.3.4.13.
-
Let be the signed interpretation of of size .
-
Return .
4.3.4.14.
-
Let be the signed interpretation of of size .
-
Return .
4.4. Instructions
WebAssembly computation is performed by executing individual instructions.
4.4.1. Numeric Instructions
Numeric instructions are defined in terms of the generic numeric operators. The mapping of numeric instructions to their underlying operators is expressed by the following definition:
And for conversion operators:
Where the underlying operators are partial, the corresponding instruction will trap when the result is not defined. Where the underlying operators are non-deterministic, because they may return one of multiple possible NaN values, so are the corresponding instructions.
Note
For example, the result of instruction applied to operands invokes , which maps to the generic via the above definition. Similarly, applied to invokes , which maps to the generic .
4.4.1.1.
-
Push the value to the stack.
Note
No formal reduction rule is required for this instruction, since instructions already are values.
4.4.1.2.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is defined, then:
-
Let be a possible result of computing .
-
Push the value to the stack.
-
-
Else:
-
Trap.
-
4.4.1.3.
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
If is defined, then:
-
Let be a possible result of computing .
-
Push the value to the stack.
-
-
Else:
-
Trap.
-
4.4.1.4.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Push the value to the stack.
4.4.1.5.
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Push the value to the stack.
4.4.1.6.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is defined:
-
Let be a possible result of computing .
-
Push the value to the stack.
-
-
Else:
-
Trap.
-
4.4.2. Reference Instructions
4.4.2.1.
-
Push the value to the stack.
Note
No formal reduction rule is required for this instruction, since the instruction is already a value.
4.4.2.2.
-
Assert: due to validation, a reference value is on the top of the stack.
-
Pop the value from the stack.
-
If is , then:
-
Push the value to the stack.
-
-
Else:
-
Push the value to the stack.
-
4.4.2.3.
-
Assert: due to validation, exists.
-
Let be the function address .
-
Push the value to the stack.
4.4.3. Vector Instructions
Vector instructions that operate bitwise are handled as integer operations of respective width.
Most other vector instructions are defined in terms of numeric operators that are applied lane-wise according to the given shape.
Note
For example, the result of instruction applied to operands invokes , which maps to , where and are sequences resulting from invoking and respectively.
4.4.3.1.
-
Push the value to the stack.
Note
No formal reduction rule is required for this instruction, since instructions coincide with values.
4.4.3.2.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Push the value to the stack.
4.4.3.3.
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Push the value to the stack.
4.4.3.4.
-
Assert: due to validation, three values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Push the value to the stack.
4.4.3.5.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Push the value onto the stack.
4.4.3.6.
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the concatenation of the two sequences and .
-
Let be the result of computing .
-
Push the value onto the stack.
4.4.3.7.
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Assert: due to validation, for all in it holds that .
-
Pop the value from the stack.
-
Let be the result of computing .
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the concatenation of the two sequences and .
-
Let be the result of computing .
-
Push the value onto the stack.
4.4.3.8.
-
Let be the type .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the integer .
-
Let be the result of computing .
-
Push the value to the stack.
4.4.3.9.
-
Assert: due to validation, .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the type .
-
Let be the result of computing .
-
Push the value to the stack.
4.4.3.10.
-
Assert: due to validation, .
-
Let be the type .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Push on the stack.
4.4.3.11.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Push the value to the stack.
4.4.3.12.
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
If is defined:
-
Let be a possible result of computing .
-
Push the value to the stack.
-
-
Else:
-
Trap.
-
4.4.3.13.
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value to the stack.
4.4.3.14.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value to the stack.
4.4.3.15.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value onto the stack.
4.4.3.16.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the bit width of value type .
-
Let be the result of computing .
-
Let be the concatenation of the two sequences and .
-
Let be the result of computing .
-
Push the value onto the stack.
4.4.3.17.
-
Assert: due to syntax, .
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the concatenation of the two sequences and .
-
Let be the result of computing .
-
Push the value onto the stack.
4.4.3.18.
-
Assert: due to syntax, .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value onto the stack.
4.4.3.19.
-
Assert: due to syntax, .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
If is , then:
-
Let be the sequence .
-
-
Else:
-
Let be the sequence .
-
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value onto the stack.
where:
4.4.3.20.
-
Assert: due to syntax, .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the concatenation of the two sequences and .
-
Let be the result of computing .
-
Push the value onto the stack.
4.4.3.21.
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value onto the stack.
4.4.3.22.
-
Assert: due to syntax, .
-
Assert: due to validation, two values of value type are on the top of the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
If is , then:
-
Let be the sequence .
-
Let be the sequence .
-
-
Else:
-
Let be the sequence .
-
Let be the sequence .
-
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value onto the stack.
where:
4.4.3.23.
-
Assert: due to syntax, .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value to the stack.
4.4.4. Parametric Instructions
4.4.4.1.
-
Assert: due to validation, a value is on the top of the stack.
-
Pop the value from the stack.
4.4.4.2.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, two more values (of the same value type) are on the top of the stack.
-
Pop the value from the stack.
-
Pop the value from the stack.
-
If is not , then:
-
Push the value back to the stack.
-
-
Else:
-
Push the value back to the stack.
-
Note
In future versions of WebAssembly, may allow more than one value per choice.
4.4.5. Variable Instructions
4.4.5.1.
-
Assert: due to validation, exists.
-
Let be the value .
-
Push the value to the stack.
4.4.5.2.
-
Assert: due to validation, exists.
-
Assert: due to validation, a value is on the top of the stack.
-
Pop the value from the stack.
-
Replace with the value .
4.4.5.3.
-
Assert: due to validation, a value is on the top of the stack.
-
Pop the value from the stack.
-
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
4.4.5.4.
-
Assert: due to validation, exists.
-
Let be the global address .
-
Assert: due to validation, exists.
-
Let be the global instance .
-
Let be the value .
-
Push the value to the stack.
4.4.5.5.
-
Assert: due to validation, exists.
-
Let be the global address .
-
Assert: due to validation, exists.
-
Let be the global instance .
-
Assert: due to validation, a value is on the top of the stack.
-
Pop the value from the stack.
-
Replace with the value .
Note
Validation ensures that the global is, in fact, marked as mutable.
4.4.6. Table Instructions
4.4.6.1.
-
Assert: due to validation, exists.
-
Let be the table address .
-
Assert: due to validation, exists.
-
Let be the table instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is not smaller than the length of , then:
-
Trap.
-
-
Let be the value .
-
Push the value to the stack.
4.4.6.2.
-
Assert: due to validation, exists.
-
Let be the table address .
-
Assert: due to validation, exists.
-
Let be the table instance .
-
Assert: due to validation, a reference value is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is not smaller than the length of , then:
-
Trap.
-
-
Replace the element with .
4.4.6.3.
-
Assert: due to validation, exists.
-
Let be the table address .
-
Assert: due to validation, exists.
-
Let be the table instance .
-
Let be the length of .
-
Push the value to the stack.
4.4.6.4.
-
Assert: due to validation, exists.
-
Let be the table address .
-
Assert: due to validation, exists.
-
Let be the table instance .
-
Let be the length of .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a reference value is on the top of the stack.
-
Pop the value from the stack.
-
Let be the value , for which is .
-
Either:
If growing by entries with initialization value succeeds, then:
Push the value to the stack.
Else:
Push the value to the stack.
-
Or:
push the value to the stack.
Note
The instruction is non-deterministic. It may either succeed, returning the old table size , or fail, returning . Failure must occur if the referenced table instance has a maximum size defined that would be exceeded. However, failure can occur in other cases as well. In practice, the choice depends on the resources available to the embedder.
4.4.6.5.
-
Assert: due to validation, exists.
-
Let be the table address .
-
Assert: due to validation, exists.
-
Let be the table instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a reference value is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is larger than the length of , then:
-
Trap.
-
-
If is , then:
-
Return.
-
-
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
-
Push the value to the stack.
-
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
4.4.6.6.
-
Assert: due to validation, exists.
-
Let be the table address .
-
Assert: due to validation, exists.
-
Let be the table instance .
-
Assert: due to validation, exists.
-
Let be the table address .
-
Assert: due to validation, exists.
-
Let be the table instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is larger than the length of or is larger than the length of , then:
-
Trap.
-
-
If , then:
Return.
-
If , then:
Push the value to the stack.
Push the value to the stack.
Execute the instruction .
Execute the instruction .
Assert: due to the earlier check against the table size, .
Push the value to the stack.
Assert: due to the earlier check against the table size, .
Push the value to the stack.
-
Else:
Assert: due to the earlier check against the table size, .
Push the value to the stack.
Assert: due to the earlier check against the table size, .
Push the value to the stack.
Execute the instruction .
Execute the instruction .
Push the value to the stack.
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
4.4.6.7.
-
Assert: due to validation, exists.
-
Let be the table address .
-
Assert: due to validation, exists.
-
Let be the table instance .
-
Assert: due to validation, exists.
-
Let be the element address .
-
Assert: due to validation, exists.
-
Let be the element instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is larger than the length of or is larger than the length of , then:
-
Trap.
-
-
If , then:
-
Return.
-
-
Let be the reference value .
-
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
-
Assert: due to the earlier check against the table size, .
-
Push the value to the stack.
-
Assert: due to the earlier check against the segment size, .
-
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
4.4.6.8.
-
Assert: due to validation, exists.
-
Let be the element address .
-
Assert: due to validation, exists.
-
Replace with .
4.4.7. Memory Instructions
Note
The alignment in load and store instructions does not affect the semantics. It is an indication that the offset at which the memory is accessed is intended to satisfy the property . A WebAssembly implementation can use this hint to optimize for the intended use. Unaligned access violating that property is still allowed and must succeed regardless of the annotation. However, it may be substantially slower on some hardware.
4.4.7.1. and
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the integer .
-
If is not part of the instruction, then:
-
Let be the bit width of number type .
-
-
If is larger than the length of , then:
-
Trap.
-
-
Let be the byte sequence .
-
If and are part of the instruction, then:
-
Let be the integer for which .
-
Let be the result of computing .
-
-
Else:
-
Let be the constant for which .
-
-
Push the value to the stack.
4.4.7.2.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the integer .
-
If is larger than the length of , then:
-
Trap.
-
-
Let be the byte sequence .
-
Let be the integer for which .
-
Let be the integer .
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value to the stack.
4.4.7.3.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the integer .
-
If is larger than the length of , then:
-
Trap.
-
-
Let be the byte sequence .
-
Let be the integer for which .
-
Let be the integer .
-
Let be the result of computing .
-
Push the value to the stack.
4.4.7.4.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the integer .
-
If is larger than the length of , then:
-
Trap.
-
-
Let be the byte sequence .
-
Let be the integer for which .
-
Let be the result of computing .
-
Push the value to the stack.
4.4.7.5.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the integer .
-
If is larger than the length of , then:
-
Trap.
-
-
Let be the byte sequence .
-
Let be the constant for which .
-
Let be .
-
Let be the result of computing .
-
Let be the result of computing .
-
Push the value to the stack.
4.4.7.6. and
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the integer .
-
If is not part of the instruction, then:
-
Let be the bit width of number type .
-
-
If is larger than the length of , then:
-
Trap.
-
-
If is part of the instruction, then:
-
Let be the result of computing .
-
Let be the byte sequence .
-
-
Else:
-
Let be the byte sequence .
-
-
Replace the bytes with .
4.4.7.7.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the integer .
-
If is larger than the length of , then:
-
Trap.
-
-
Let be .
-
Let be the result of computing .
-
Let be the result of computing .
-
Replace the bytes with .
4.4.7.8.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Let be the length of divided by the page size.
-
Push the value to the stack.
4.4.7.9.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Let be the length of divided by the page size.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Let be the value , for which is .
-
Either:
-
Or:
Push the value to the stack.
Note
The instruction is non-deterministic. It may either succeed, returning the old memory size , or fail, returning . Failure must occur if the referenced memory instance has a maximum size defined that would be exceeded. However, failure can occur in other cases as well. In practice, the choice depends on the resources available to the embedder.
4.4.7.10.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is larger than the length of , then:
-
Trap.
-
-
If , then:
-
Return.
-
-
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
-
Assert: due to the earlier check against the memory size, .
-
Push the value to the stack.
-
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
4.4.7.11.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is larger than the length of or is larger than the length of , then:
-
Trap.
-
-
If , then:
Return.
-
If , then:
Push the value to the stack.
Push the value to the stack.
Execute the instruction .
Execute the instruction .
Assert: due to the earlier check against the memory size, .
Push the value to the stack.
Assert: due to the earlier check against the memory size, .
Push the value to the stack.
-
Else:
Assert: due to the earlier check against the memory size, .
Push the value to the stack.
Assert: due to the earlier check against the memory size, .
Push the value to the stack.
Execute the instruction .
Execute the instruction .
Push the value to the stack.
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
4.4.7.12.
-
Assert: due to validation, exists.
-
Let be the memory address .
-
Assert: due to validation, exists.
-
Let be the memory instance .
-
Assert: due to validation, exists.
-
Let be the data address .
-
Assert: due to validation, exists.
-
Let be the data instance .
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is larger than the length of or is larger than the length of , then:
-
Trap.
-
-
If , then:
-
Return.
-
-
Let be the byte .
-
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
-
Assert: due to the earlier check against the memory size, .
-
Push the value to the stack.
-
Assert: due to the earlier check against the memory size, .
-
Push the value to the stack.
-
Push the value to the stack.
-
Execute the instruction .
4.4.7.13.
-
Assert: due to validation, exists.
-
Let be the data address .
-
Assert: due to validation, exists.
-
Replace with the data instance .
4.4.8. Control Instructions
4.4.8.1.
-
Do nothing.
4.4.8.2.
-
Trap.
4.4.8.3.
-
Assert: due to validation, is defined.
-
Let be the function type .
-
Let be the label whose arity is and whose continuation is the end of the block.
-
Assert: due to validation, there are at least values on the top of the stack.
-
Pop the values from the stack.
-
Enter the block with label .
4.4.8.4.
-
Assert: due to validation, is defined.
-
Let be the function type .
-
Let be the label whose arity is and whose continuation is the start of the loop.
-
Assert: due to validation, there are at least values on the top of the stack.
-
Pop the values from the stack.
-
Enter the block with label .
4.4.8.5.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is non-zero, then:
-
Execute the block instruction .
-
-
Else:
-
Execute the block instruction .
-
4.4.8.6.
-
Assert: due to validation, the stack contains at least labels.
-
Let be the -th label appearing on the stack, starting from the top and counting from zero.
-
Let be the arity of .
-
Assert: due to validation, there are at least values on the top of the stack.
-
Pop the values from the stack.
-
Repeat times:
-
While the top of the stack is a value, do:
-
Pop the value from the stack.
-
-
Assert: due to validation, the top of the stack now is a label.
-
Pop the label from the stack.
-
-
Push the values to the stack.
-
Jump to the continuation of .
4.4.8.7.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is non-zero, then:
-
Execute the instruction .
-
-
Else:
-
Do nothing.
-
4.4.8.8.
-
Assert: due to validation, a value of value type is on the top of the stack.
-
Pop the value from the stack.
-
If is smaller than the length of , then:
-
Let be the label .
-
Execute the instruction .
-
-
Else:
-
Execute the instruction .
-
4.4.8.9.
-
Let be the arity of .
-
Assert: due to validation, there are at least values on the top of the stack.
-
Pop the results from the stack.
-
Assert: due to validation, the stack contains at least one frame.
-
While the top of the stack is not a frame, do:
-
Pop the top element from the stack.
-
-
Assert: the top of the stack is the frame .
-
Pop the frame from the stack.
-
Push to the stack.
-
Jump to the instruction after the original call that pushed the frame.
4.4.8.10.
-
Assert: due to validation, exists.
-
Let be the function address .
-
Invoke the function instance at address .
4.4.8.11.
-
Assert: due to validation, exists.
-
Let be the table address .
-
Assert: due to validation, exists.
-
Let be the table instance .
-
Assert: due to validation, exists.
-
Let be the function type .
-
Assert: due to validation, a value with value type is on the top of the stack.
-
Pop the value from the stack.
-
If is not smaller than the length of , then:
-
Trap.
-
-
Let be the reference .
-
If is , then:
-
Trap.
-
-
Assert: due to validation of table mutation, is a function reference.
-
Let be the function reference .
-
Assert: due to validation of table mutation, exists.
-
Let be the function instance .
-
Let be the function type .
-
If and differ, then:
-
Trap.
-
-
Invoke the function instance at address .
4.4.9. Blocks
The following auxiliary rules define the semantics of executing an instruction sequence that forms a block.
4.4.9.1. Entering with label
-
Push to the stack.
-
Jump to the start of the instruction sequence .
Note
No formal reduction rule is needed for entering an instruction sequence, because the label is embedded in the administrative instruction that structured control instructions reduce to directly.
4.4.9.2. Exiting with label
When the end of a block is reached without a jump or trap aborting it, then the following steps are performed.
-
Pop all values from the top of the stack.
-
Assert: due to validation, the label is now on the top of the stack.
-
Pop the label from the stack.
-
Push back to the stack.
-
Jump to the position after the of the structured control instruction associated with the label .
Note
This semantics also applies to the instruction sequence contained in a instruction. Therefore, execution of a loop falls off the end, unless a backwards branch is performed explicitly.
4.4.10. Function Calls
The following auxiliary rules define the semantics of invoking a function instance through one of the call instructions and returning from it.
4.4.10.1. Invocation of function address
-
Assert: due to validation, exists.
-
Let be the function instance, .
-
Let be the function type .
-
Let be the list of value types .
-
Let be the expression .
-
Assert: due to validation, values are on the top of the stack.
-
Pop the values from the stack.
-
Let be the frame .
-
Push the activation of with arity to the stack.
-
Let be the label whose arity is and whose continuation is the end of the function.
-
Enter the instruction sequence with label .
4.4.10.2. Returning from a function
When the end of a function is reached without a jump (i.e., ) or trap aborting it, then the following steps are performed.
-
Let be the arity of the activation of .
-
Assert: due to validation, there are values on the top of the stack.
-
Pop the results from the stack.
-
Assert: due to validation, the frame is now on the top of the stack.
-
Pop the frame from the stack.
-
Push back to the stack.
-
Jump to the instruction after the original call.
4.4.10.3. Host Functions
Invoking a host function has non-deterministic behavior. It may either terminate with a trap or return regularly. However, in the latter case, it must consume and produce the right number and types of WebAssembly values on the stack, according to its function type.
A host function may also modify the store. However, all store modifications must result in an extension of the original store, i.e., they must only modify mutable contents and must not have instances removed. Furthermore, the resulting store must be valid, i.e., all data and code in it is well-typed.
Here, denotes the implementation-defined execution of host function in current store with arguments . It yields a set of possible outcomes, where each element is either a pair of a modified store and a result or the special value indicating divergence. A host function is non-deterministic if there is at least one argument for which the set of outcomes is not singular.
For a WebAssembly implementation to be sound in the presence of host functions, every host function instance must be valid, which means that it adheres to suitable pre- and post-conditions: under a valid store , and given arguments matching the ascribed parameter types , executing the host function must yield a non-empty set of possible outcomes each of which is either divergence or consists of a valid store that is an extension of and a result matching the ascribed return types . All these notions are made precise in the Appendix.
4.4.11. Expressions
An expression is evaluated relative to a current frame pointing to its containing module instance.
-
Jump to the start of the instruction sequence of the expression.
-
Execute the instruction sequence.
-
Assert: due to validation, the top of the stack contains a value.
-
Pop the value from the stack.
The value is the result of the evaluation.
Note
Evaluation iterates this reduction rule until reaching a value. Expressions constituting function bodies are executed during function invocation.
4.5. Modules
For modules, the execution semantics primarily defines instantiation, which allocates instances for a module and its contained definitions, initializes tables and memories from contained element and data segments, and invokes the start function if present. It also includes invocation of exported functions.
Instantiation depends on a number of auxiliary notions for type-checking imports and allocating instances.
4.5.1. External Typing
For the purpose of checking external values against imports, such values are classified by external types. The following auxiliary typing rules specify this typing relation relative to a store in which the referenced instances live.
4.5.1.1.
-
The store entry must exist.
-
Then is valid with external type .
4.5.1.2.
-
The store entry must exist.
-
Then is valid with external type .
4.5.1.3.
-
The store entry must exist.
-
Then is valid with external type .
4.5.1.4.
-
The store entry must exist.
-
Then is valid with external type .
4.5.2. Value Typing
For the purpose of checking argument values against the parameter types of exported functions, values are classified by value types. The following auxiliary typing rules specify this typing relation relative to a store in which possibly referenced addresses live.
4.5.2.1. Numeric Values
-
The value is valid with number type .
4.5.2.2. Null References
-
The value is valid with reference type .
4.5.2.3. Function References
-
The external value must be valid.
-
Then the value is valid with reference type .
4.5.2.4. External References
-
The value is valid with reference type .
4.5.3. Allocation
New instances of functions, tables, memories, and globals are allocated in a store , as defined by the following auxiliary functions.
4.5.3.1. Functions
-
Let be the function to allocate and its module instance.
-
Let be the first free function address in .
-
Let be the function type .
-
Let be the function instance .
-
Append to the of .
-
Return .
4.5.3.2. Host Functions
-
Let be the host function to allocate and its function type.
-
Let be the first free function address in .
-
Let be the function instance .
-
Append to the of .
-
Return .
Note
Host functions are never allocated by the WebAssembly semantics itself, but may be allocated by the embedder.
4.5.3.3. Tables
-
Let be the table type to allocate and the initialization value.
-
Let be the structure of table type .
-
Let be the first free table address in .
-
Let be the table instance with elements set to .
-
Append to the of .
-
Return .
4.5.3.4. Memories
-
Let be the memory type to allocate.
-
Let be the structure of memory type .
-
Let be the first free memory address in .
-
Let be the memory instance that contains pages of zeroed bytes.
-
Append to the of .
-
Return .
4.5.3.5. Globals
-
Let be the global type to allocate and the value to initialize the global with.
-
Let be the first free global address in .
-
Let be the global instance .
-
Append to the of .
-
Return .
4.5.3.6. Element segments
-
Let be the elements’ type and the vector of references to allocate.
-
Let be the first free element address in .
-
Let be the element instance .
-
Append to the of .
-
Return .
4.5.3.7. Data segments
-
Let be the vector of bytes to allocate.
-
Let be the first free data address in .
-
Let be the data instance .
-
Append to the of .
-
Return .
4.5.3.8. Growing tables
-
Let be the table instance to grow, the number of elements by which to grow it, and the initialization value.
-
Let be added to the length of .
-
If is larger than or equal to , then fail.
-
Let be the structure of table type .
-
Let be with updated to .
-
If is not valid, then fail.
-
Append to .
-
Set to the table type .
4.5.3.9. Growing memories
-
Let be the memory instance to grow and the number of pages by which to grow it.
-
Assert: The length of is divisible by the page size .
-
Let be added to the length of divided by the page size .
-
If is larger than , then fail.
-
Let be the structure of memory type .
-
Let be with updated to .
-
If is not valid, then fail.
-
Append times bytes with value to .
-
Set to the memory type .
4.5.3.10. Modules
The allocation function for modules requires a suitable list of external values that are assumed to match the import vector of the module, a list of initialization values for the module’s globals, and list of reference vectors for the module’s element segments.
-
Let be the module to allocate and the vector of external values providing the module’s imports, the initialization values of the module’s globals, and the reference vectors of the module’s element segments.
-
For each function in , do:
-
Let be the function address resulting from allocating for the module instance defined below.
-
-
For each table in , do:
-
Let be the table type .
-
Let be the table address resulting from allocating with initialization value .
-
-
For each memory in , do:
-
Let be the memory address resulting from allocating .
-
-
For each global in , do:
-
Let be the global address resulting from allocating with initializer value .
-
-
For each element segment in , do:
-
Let be the element address resulting from allocating an element instance of reference type with contents .
-
-
For each data segment in , do:
-
Let be the data address resulting from allocating a data instance with contents .
-
-
Let be the concatenation of the function addresses in index order.
-
Let be the concatenation of the table addresses in index order.
-
Let be the concatenation of the memory addresses in index order.
-
Let be the concatenation of the global addresses in index order.
-
Let be the concatenation of the element addresses in index order.
-
Let be the concatenation of the data addresses in index order.
-
Let be the list of function addresses extracted from , concatenated with .
-
Let be the list of table addresses extracted from , concatenated with .
-
Let be the list of memory addresses extracted from , concatenated with .
-
Let be the list of global addresses extracted from , concatenated with .
-
For each export in , do:
-
If is a function export for function index , then let be the external value .
-
Else, if is a table export for table index , then let be the external value .
-
Else, if is a memory export for memory index , then let be the external value .
-
Else, if is a global export for global index , then let be the external value .
-
Let be the export instance .
-
-
Let be the concatenation of the export instances in index order.
-
Let be the module instance .
-
Return .
where:
Here, the notation is shorthand for multiple allocations of object kind , defined as follows:
Moreover, if the dots are a sequence (as for globals or tables), then the elements of this sequence are passed to the allocation function pointwise.
Note
The definition of module allocation is mutually recursive with the allocation of its associated functions, because the resulting module instance is passed to the function allocator as an argument, in order to form the necessary closures. In an implementation, this recursion is easily unraveled by mutating one or the other in a secondary step.
4.5.4. Instantiation
Given a store , a module is instantiated with a list of external values supplying the required imports as follows.
Instantiation checks that the module is valid and the provided imports match the declared types, and may fail with an error otherwise. Instantiation can also result in a trap from initializing a table or memory from an active segment or from executing the start function. It is up to the embedder to define how such conditions are reported.
-
If is not valid, then:
-
Fail.
-
-
Assert: is valid with external types classifying its imports.
-
If the number of imports is not equal to the number of provided external values, then:
-
Fail.
-
-
For each external value in and external type in , do:
-
If is not valid with an external type in store , then:
-
Fail.
-
-
If does not match , then:
-
Fail.
-
-
-
Let be the auxiliary module instance that only consists of the imported globals and the imported and allocated functions from the final module instance , defined below.
-
Let be the auxiliary frame .
-
Push the frame to the stack.
-
Let be the vector of global initialization values determined by and . These may be calculated as follows.
-
For each global in , do:
-
Let be the result of evaluating the initializer expression .
-
-
Assert: due to validation, the frame is now on the top of the stack.
-
Let be the concatenation of in index order.
-
-
Let be the list of reference vectors determined by the element segments in . These may be calculated as follows.
-
For each element segment in , and for each element expression in , do:
-
Let be the result of evaluating the initializer expression .
-
-
Let be the concatenation of function elements in order of index .
-
Let be the concatenation of function element vectors in order of index .
-
-
Pop the frame from the stack.
-
Let be a new module instance allocated from in store with imports , global initializer values , and element segment contents , and let be the extended store produced by module allocation.
-
Let be the auxiliary frame .
-
Push the frame to the stack.
-
For each element segment in whose mode is of the form , do:
-
For each element segment in whose mode is of the form , do:
-
Execute the instruction .
-
-
For each data segment in whose mode is of the form , do:
-
If the start function is not empty, then:
-
Let be the start function .
-
Execute the instruction .
-
-
Assert: due to validation, the frame is now on the top of the stack.
-
Pop the frame from the stack.
where:
Note
Module allocation and the evaluation of global initializers and element segments are mutually recursive because the global initialization values and element segment contents are passed to the module allocator while depending on the module instance and store returned by allocation. However, this recursion is just a specification device. In practice, the initialization values can be determined beforehand by staging module allocation such that first, the module’s own function instances are pre-allocated in the store, then the initializer expressions are evaluated, then the rest of the module instance is allocated, and finally the new function instances’ fields are set to that module instance. This is possible because validation ensures that initialization expressions cannot actually call a function, only take their reference.
All failure conditions are checked before any observable mutation of the store takes place. Store mutation is not atomic; it happens in individual steps that may be interleaved with other threads.
Evaluation of constant expressions does not affect the store.
4.5.5. Invocation
Once a module has been instantiated, any exported function can be invoked externally via its function address in the store and an appropriate list of argument values.
Invocation may fail with an error if the arguments do not fit the function type. Invocation can also result in a trap. It is up to the embedder to define how such conditions are reported.
Note
If the embedder API performs type checks itself, either statically or dynamically, before performing an invocation, then no failure other than traps can occur.
The following steps are performed:
-
Assert: exists.
-
Let be the function instance .
-
Let be the function type .
-
If the length of the provided argument values is different from the number of expected arguments, then:
-
Fail.
-
-
For each value type in and corresponding value in , do:
-
If is not valid with value type , then:
-
Fail.
-
-
-
Let be the dummy frame .
-
Push the frame to the stack.
-
Push the values to the stack.
-
Invoke the function instance at address .
Once the function has returned, the following steps are executed:
-
Assert: due to validation, values are on the top of the stack.
-
Pop from the stack.
-
Assert: due to validation, the frame is now on the top of the stack.
-
Pop the frame from the stack.
The values are returned as the results of the invocation.
5. Binary Format
5.1. Conventions
The binary format for WebAssembly modules is a dense linear encoding of their abstract syntax. [1]
The format is defined by an attribute grammar whose only terminal symbols are bytes. A byte sequence is a well-formed encoding of a module if and only if it is generated by the grammar.
Each production of this grammar has exactly one synthesized attribute: the abstract syntax that the respective byte sequence encodes. Thus, the attribute grammar implicitly defines a decoding function (i.e., a parsing function for the binary format).
Except for a few exceptions, the binary grammar closely mirrors the grammar of the abstract syntax.
Note
Some phrases of abstract syntax have multiple possible encodings in the binary format. For example, numbers may be encoded as if they had optional leading zeros. Implementations of decoders must support all possible alternatives; implementations of encoders can pick any allowed encoding.
The recommended extension for files containing WebAssembly modules in binary format is “” and the recommended Media Type is “”.
Additional encoding layers – for example, introducing compression – may be defined on top of the basic representation defined here. However, such layers are outside the scope of the current specification.
5.1.1. Grammar
The following conventions are adopted in defining grammar rules for the binary format. They mirror the conventions used for abstract syntax. In order to distinguish symbols of the binary syntax from symbols of the abstract syntax, font is adopted for the former.
-
Terminal symbols are bytes expressed in hexadecimal notation: .
-
Nonterminal symbols are written in typewriter font: .
-
is a sequence of iterations of .
-
is a possibly empty sequence of iterations of . (This is a shorthand for used where is not relevant.)
-
is an optional occurrence of . (This is a shorthand for where .)
-
denotes the same language as the nonterminal , but also binds the variable to the attribute synthesized for . A pattern may also be used instead of a variable, e.g., .
-
Productions are written , where each is the attribute that is synthesized for in the given case, usually from attribute variables bound in .
-
Some productions are augmented by side conditions in parentheses, which restrict the applicability of the production. They provide a shorthand for a combinatorial expansion of the production into many separate cases.
-
If the same meta variable or non-terminal symbol appears multiple times in a production (in the syntax or in an attribute), then all those occurrences must have the same instantiation. (This is a shorthand for a side condition requiring multiple different variables to be equal.)
Note
For example, the binary grammar for number types is given as follows:
Consequently, the byte encodes the type , encodes the type , and so forth. No other byte value is allowed as the encoding of a number type.
The binary grammar for limits is defined as follows:
That is, a limits pair is encoded as either the byte followed by the encoding of a value, or the byte followed by two such encodings. The variables and name the attributes of the respective nonterminals, which in this case are the actual unsigned integers those decode into. The attribute of the complete production then is the abstract syntax for the limit, expressed in terms of the former values.
5.1.2. Auxiliary Notation
When dealing with binary encodings the following notation is also used:
-
denotes the empty byte sequence.
-
is the length of the byte sequence generated from the production in a derivation.
5.1.3. Vectors
Vectors are encoded with their length followed by the encoding of their element sequence.
5.2. Values
5.2.1. Bytes
Bytes encode themselves.
5.2.2. Integers
All integers are encoded using the LEB128 variable-length integer encoding, in either unsigned or signed variant.
Unsigned integers are encoded in unsigned LEB128 format. As an additional constraint, the total number of bytes encoding a value of type must not exceed bytes.
Signed integers are encoded in signed LEB128 format, which uses a two’s complement representation. As an additional constraint, the total number of bytes encoding a value of type must not exceed bytes.
Uninterpreted integers are encoded as signed integers.
Note
The side conditions in the productions for non-terminal bytes of the and encodings restrict the encoding’s length. However, “trailing zeros” are still allowed within these bounds. For example, and are both well-formed encodings for the value as a . Similarly, either of and and are well-formed encodings of the value as a .
The side conditions on the value of terminal bytes further enforce that any unused bits in these bytes must be for positive values and for negative ones. For example, is malformed as a encoding. Similarly, both and are malformed as encodings.
5.2.3. Floating-Point
Floating-point values are encoded directly by their [IEEE-754-2019] (Section 3.4) bit pattern in little endian byte order:
5.2.4. Names
Names are encoded as a vector of bytes containing the [UNICODE] (Section 3.9) UTF-8 encoding of the name’s character sequence.
The auxiliary function expressing this encoding is defined as follows:
Note
Unlike in some other formats, name strings are not 0-terminated.
5.3. Types
Note
In some places, possible types include both type constructors or types denoted by type indices. Thus, the binary format for type constructors corresponds to the encodings of small negative values, such that they can unambiguously occur in the same place as (positive) type indices.
5.3.1. Number Types
Number types are encoded by a single byte.
5.3.2. Vector Types
Vector types are also encoded by a single byte.
5.3.3. Reference Types
Reference types are also encoded by a single byte.
5.3.4. Value Types
Value types are encoded with their respective encoding as a number type, vector type, or reference type.
Note
Value types can occur in contexts where type indices are also allowed, such as in the case of block types. Thus, the binary format for types corresponds to the signed LEB128 encoding of small negative values, so that they can coexist with (positive) type indices in the future.
5.3.5. Result Types
Result types are encoded by the respective vectors of value types.
5.3.6. Function Types
Function types are encoded by the byte followed by the respective vectors of parameter and result types.
5.3.7. Limits
Limits are encoded with a preceding flag indicating whether a maximum is present.
5.3.8. Memory Types
Memory types are encoded with their limits.
5.3.9. Table Types
Table types are encoded with their limits and the encoding of their element reference type.
5.3.10. Global Types
Global types are encoded by their value type and a flag for their mutability.
5.4. Instructions
Instructions are encoded by opcodes. Each opcode is represented by a single byte, and is followed by the instruction’s immediate arguments, where present. The only exception are structured control instructions, which consist of several opcodes bracketing their nested instruction sequences.
Note
Gaps in the byte code ranges for encoding instructions are reserved for future extensions.
5.4.1. Control Instructions
Control instructions have varying encodings. For structured instructions, the instruction sequences forming nested blocks are terminated with explicit opcodes for and .
Block types are encoded in special compressed form, by either the byte indicating the empty type, as a single value type, or as a type index encoded as a positive signed integer.
Note
The opcode in the encoding of an instruction can be omitted if the following instruction sequence is empty.
Unlike any other occurrence, the type index in a block type is encoded as a positive signed integer, so that its signed LEB128 bit pattern cannot collide with the encoding of value types or the special code , which correspond to the LEB128 encoding of negative integers. To avoid any loss in the range of allowed indices, it is treated as a 33 bit signed integer.
5.4.2. Reference Instructions
Reference instructions are represented by single byte codes.
5.4.3. Parametric Instructions
Parametric instructions are represented by single byte codes, possibly followed by a type annotation.
5.4.4. Variable Instructions
Variable instructions are represented by byte codes followed by the encoding of the respective index.
5.4.5. Table Instructions
Table instructions are represented either by a single byte or a one byte prefix followed by a variable-length unsigned integer.
5.4.6. Memory Instructions
Each variant of memory instruction is encoded with a different byte code. Loads and stores are followed by the encoding of their immediate.
Note
In future versions of WebAssembly, the additional zero bytes occurring in the encoding of the , , , and instructions may be used to index additional memories.
5.4.7. Numeric Instructions
All variants of numeric instructions are represented by separate byte codes.
The instructions are followed by the respective literal.
All other numeric instructions are plain opcodes without any immediates.
The saturating truncation instructions all have a one byte prefix, whereas the actual opcode is encoded by a variable-length unsigned integer.
5.4.8. Vector Instructions
All variants of vector instructions are represented by separate byte codes. They all have a one byte prefix, whereas the actual opcode is encoded by a variable-length unsigned integer.
Vector loads and stores are followed by the encoding of their immediate.
The instruction is followed by 16 immediate bytes, which are converted into a in byte order:
The instruction is also followed by the encoding of 16 immediates.
and instructions are followed by the encoding of a immediate.
All other vector instructions are plain opcodes without any immediates.
5.4.9. Expressions
Expressions are encoded by their instruction sequence terminated with an explicit opcode for .
5.5. Modules
The binary encoding of modules is organized into sections. Most sections correspond to one component of a module record, except that function definitions are split into two sections, separating their type declarations in the function section from their bodies in the code section.
Note
This separation enables parallel and streaming compilation of the functions in a module.
5.5.1. Indices
All indices are encoded with their respective value.
5.5.2. Sections
Each section consists of
-
a one-byte section id,
-
the size of the contents, in bytes,
-
the actual contents, whose structure is dependent on the section id.
Every section is optional; an omitted section is equivalent to the section being present with empty contents.
The following parameterized grammar rule defines the generic structure of a section with id and contents described by the grammar .
For most sections, the contents encodes a vector. In these cases, the empty result is interpreted as the empty vector.
Note
Other than for unknown custom sections, the is not required for decoding, but can be used to skip sections when navigating through a binary. The module is malformed if the size does not match the length of the binary contents .
The following section ids are used:
Id |
Section |
---|---|
0 | |
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 | |
8 | |
9 | |
10 | |
11 | |
12 |
Note
Section ids do not always correspond to the order of sections in the encoding of a module.
5.5.3. Custom Section
Custom sections have the id 0. They are intended to be used for debugging information or third-party extensions, and are ignored by the WebAssembly semantics. Their contents consist of a name further identifying the custom section, followed by an uninterpreted sequence of bytes for custom use.
Note
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.
5.5.4. Type Section
The type section has the id 1. It decodes into a vector of function types that represent the component of a module.
5.5.5. Import Section
The import section has the id 2. It decodes into a vector of imports that represent the component of a module.
5.5.6. Function Section
The function section has the id 3. It decodes into a vector of type indices that represent the fields of the functions in the component of a module. The and fields of the respective functions are encoded separately in the code section.
5.5.7. Table Section
The table section has the id 4. It decodes into a vector of tables that represent the component of a module.
5.5.8. Memory Section
The memory section has the id 5. It decodes into a vector of memories that represent the component of a module.
5.5.9. Global Section
The global section has the id 6. It decodes into a vector of globals that represent the component of a module.
5.5.10. Export Section
The export section has the id 7. It decodes into a vector of exports that represent the component of a module.
5.5.11. Start Section
The start section has the id 8. It decodes into an optional start function that represents the component of a module.
5.5.12. Element Section
The element section has the id 9. It decodes into a vector of element segments that represent the component of a module.
Note
The initial integer can be interpreted as a bitfield. Bit 0 distinguishes a passive or declarative segment from an active segment, bit 1 indicates the presence of an explicit table index for an active segment and otherwise distinguishes passive from declarative segments, bit 2 indicates the use of element type and element expressions instead of element kind and element indices.
Additional element kinds may be added in future versions of WebAssembly.
5.5.13. Code Section
The code section has the id 10. It decodes into a vector of code entries that are pairs of value type vectors and expressions. They represent the and field of the functions in the component of a module. The fields of the respective functions are encoded separately in the function section.
The encoding of each code entry consists of
-
the size of the function code in bytes,
-
the actual function code, which in turn consists of
-
the declaration of locals,
-
the function body as an expression.
-
Local declarations are compressed into a vector whose entries consist of
-
a count,
-
a value type,
denoting count locals of the same value type.
Here, ranges over pairs . The meta function concatenates all sequences in . Any code for which the length of the resulting sequence is out of bounds of the maximum size of a vector is malformed.
Note
Like with sections, the code is not needed for decoding, but can be used to skip functions when navigating through a binary. The module is malformed if a size does not match the length of the respective function code.
5.5.14. Data Section
The data section has the id 11. It decodes into a vector of data segments that represent the component of a module.
Note
The initial integer can be interpreted as a bitfield. Bit 0 indicates a passive segment, bit 1 indicates the presence of an explicit memory index for an active segment.
In the current version of WebAssembly, at most one memory may be defined or imported in a single module, so all valid active data segments have a value of .
5.5.15. Data Count Section
The data count section has the id 12. It decodes into an optional u32 that represents the number of data segments in the data section. If this count does not match the length of the data segment vector, the module is malformed.
Note
The data count section is used to simplify single-pass validation. Since the data section occurs after the code section, the and instructions would not be able to check whether the data segment index is valid until the data section is read. The data count section occurs before the code section, so a single-pass validator can use this count instead of deferring validation.
5.5.16. Modules
The encoding of a module starts with a preamble containing a 4-byte magic number (the string ) and a version field. The current version of the WebAssembly binary format is 1.
The preamble is followed by a sequence of sections. Custom sections may be inserted at any place in this sequence, while other sections must occur at most once and in the prescribed order. All sections can be empty.
The lengths of vectors produced by the (possibly empty) function and code section must match up.
Similarly, the optional data count must match the length of the data segment vector. Furthermore, it must be present if any data index occurs in the code section.
where for each in ,
Note
The version of the WebAssembly binary format may increase in the future if backward-incompatible changes have to be made to the format. However, such changes are expected to occur very infrequently, if ever. The binary format is intended to be forward-compatible, such that future extensions can be made without incrementing its version.
6. Text Format
6.1. Conventions
The textual format for WebAssembly modules is a rendering of their abstract syntax into S-expressions.
Like the binary format, the text format is defined by an attribute grammar. A text string is a well-formed description of a module if and only if it is generated by the grammar. Each production of this grammar has at most one synthesized attribute: the abstract syntax that the respective character sequence expresses. Thus, the attribute grammar implicitly defines a parsing function. Some productions also take a context as an inherited attribute that records bound identifiers.
Except for a few exceptions, the core of the text grammar closely mirrors the grammar of the abstract syntax. However, it also defines a number of abbreviations that are “syntactic sugar” over the core syntax.
The recommended extension for files containing WebAssembly modules in text format is “”. Files with this extension are assumed to be encoded in UTF-8, as per [UNICODE] (Section 2.5).
6.1.1. Grammar
The following conventions are adopted in defining grammar rules of the text format. They mirror the conventions used for abstract syntax and for the binary format. In order to distinguish symbols of the textual syntax from symbols of the abstract syntax, font is adopted for the former.
-
Terminal symbols are either literal strings of characters enclosed in quotes or expressed as [UNICODE] scalar values: , . (All characters written literally are unambiguously drawn from the 7-bit ASCII subset of Unicode.)
-
Nonterminal symbols are written in typewriter font: .
-
is a sequence of iterations of .
-
is a possibly empty sequence of iterations of . (This is a shorthand for used where is not relevant.)
-
is a sequence of one or more iterations of . (This is a shorthand for where .)
-
is an optional occurrence of . (This is a shorthand for where .)
-
denotes the same language as the nonterminal , but also binds the variable to the attribute synthesized for . A pattern may also be used instead of a variable, e.g., .
-
Productions are written , where each is the attribute that is synthesized for in the given case, usually from attribute variables bound in .
-
Some productions are augmented by side conditions in parentheses, which restrict the applicability of the production. They provide a shorthand for a combinatorial expansion of the production into many separate cases.
-
If the same meta variable or non-terminal symbol appears multiple times in a production (in the syntax or in an attribute), then all those occurrences must have the same instantiation.
-
A distinction is made between lexical and syntactic productions. For the latter, arbitrary white space is allowed in any place where the grammar contains spaces. The productions defining lexical syntax and the syntax of values are considered lexical, all others are syntactic.
Note
For example, the textual grammar for number types is given as follows:
The textual grammar for limits is defined as follows:
The variables and name the attributes of the respective nonterminals, which in this case are the actual unsigned integers those parse into. The attribute of the complete production then is the abstract syntax for the limit, expressed in terms of the former values.
6.1.2. Abbreviations
In addition to the core grammar, which corresponds directly to the abstract syntax, the textual syntax also defines a number of abbreviations that can be used for convenience and readability.
Abbreviations are defined by rewrite rules specifying their expansion into the core syntax:
These expansions are assumed to be applied, recursively and in order of appearance, before applying the core grammar rules to construct the abstract syntax.
6.1.3. Contexts
The text format allows the use of symbolic identifiers in place of indices. To resolve these identifiers into concrete indices, some grammar productions are indexed by an identifier context as a synthesized attribute that records the declared identifiers in each index space. In addition, the context records the types defined in the module, so that parameter indices can be computed for functions.
It is convenient to define identifier contexts as records with abstract syntax as follows:
For each index space, such a context contains the list of identifiers assigned to the defined indices. Unnamed indices are associated with empty () entries in these lists.
An identifier context is well-formed if no index space contains duplicate identifiers.
6.1.3.1. Conventions
To avoid unnecessary clutter, empty components are omitted when writing out identifier contexts. For example, the record is shorthand for an identifier context whose components are all empty.
6.1.4. Vectors
Vectors are written as plain sequences, but with a restriction on the length of these sequence.
6.2. Lexical Format
6.2.1. Characters
The text format assigns meaning to source text, which consists of a sequence of characters. Characters are assumed to be represented as valid [UNICODE] (Section 2.4) scalar values.
6.2.2. Tokens
The character stream in the source text is divided, from left to right, into a sequence of tokens, as defined by the following grammar.
Tokens are formed from the input character stream according to the longest match rule. That is, the next token always consists of the longest possible sequence of characters that is recognized by the above lexical grammar. Tokens can be separated by white space, but except for strings, they cannot themselves contain whitespace.
Keyword tokens are defined either implicitly by an occurrence of a terminal symbol in literal form, such as , in a syntactic production of this chapter, or explicitly where they arise in this chapter.
Any token that does not fall into any of the other categories is considered reserved, and cannot occur in source text.
Note
The effect of defining the set of reserved tokens is that all tokens must be separated by either parentheses, white space, or comments. For example, is a single reserved token, as is . Consequently, they are not recognized as two separate tokens and , or and , respectively, but instead disallowed. This property of tokenization is not affected by the fact that the definition of reserved tokens overlaps with other token classes.
6.2.3. White Space
White space is any sequence of literal space characters, formatting characters, or comments. The allowed formatting characters correspond to a subset of the ASCII format effectors, namely, horizontal tabulation (), line feed (), and carriage return ().
The only relevance of white space is to separate tokens. It is otherwise ignored.
6.3. Values
The grammar productions in this section define lexical syntax, hence no white space is allowed.
6.3.1. Integers
All integers can be written in either decimal or hexadecimal notation. In both cases, digits can optionally be separated by underscores.
The allowed syntax for integer literals depends on size and signedness. Moreover, their value must lie within the range of the respective type.
Uninterpreted integers can be written as either signed or unsigned, and are normalized to unsigned in the abstract syntax.
6.3.2. Floating-Point
Floating-point values can be represented in either decimal or hexadecimal notation.
The value of a literal must not lie outside the representable range of the corresponding [IEEE-754-2019] type (that is, a numeric value must not overflow to ), but it may be rounded to the nearest representable value.
Note
Rounding can be prevented by using hexadecimal notation with no more significant bits than supported by the required type.
Floating-point values may also be written as constants for infinity or canonical NaN (not a number). Furthermore, arbitrary NaN values may be expressed by providing an explicit payload value.
6.3.3. Strings
Strings denote sequences of bytes that can represent both textual and binary data. They are enclosed in quotation marks and may contain any character other than ASCII control characters, quotation marks (), or backslash (), except when expressed with an escape sequence.
Each character in a string literal represents the byte sequence corresponding to its UTF-8 [UNICODE] (Section 2.5) encoding, except for hexadecimal escape sequences , which represent raw bytes of the respective value.
6.3.4. Names
Names are strings denoting a literal character sequence. A name string must form a valid UTF-8 encoding as defined by [UNICODE] (Section 2.5) and is interpreted as a string of Unicode scalar values.
Note
Presuming the source text is itself encoded correctly, strings that do not contain any uses of hexadecimal byte escapes are always valid names.
6.3.5. Identifiers
Indices can be given in both numeric and symbolic form. Symbolic identifiers that stand in lieu of indices start with , followed by any sequence of printable ASCII characters that does not contain a space, quotation mark, comma, semicolon, or bracket.
6.3.5.1. Conventions
The expansion rules of some abbreviations require insertion of a fresh identifier. That may be any syntactically valid identifier that does not already occur in the given source text.
6.4. Types
6.4.1. Number Types
6.4.2. Vector Types
6.4.3. Reference Types
6.4.4. Value Types
6.4.5. Function Types
Note
The optional identifier names for parameters in a function type only have documentation purpose. They cannot be referenced from anywhere.
6.4.5.1. Abbreviations
Multiple anonymous parameters or results may be combined into a single declaration:
6.4.6. Limits
6.4.7. Memory Types
6.4.8. Table Types
6.4.9. Global Types
6.5. Instructions
Instructions are syntactically distinguished into plain and structured instructions.
In addition, as a syntactic abbreviation, instructions can be written as S-expressions in folded form, to group them visually.
6.5.1. Labels
Structured control instructions can be annotated with a symbolic label identifier. They are the only symbolic identifiers that can be bound locally in an instruction sequence. The following grammar handles the corresponding update to the identifier context by composing the context with an additional label entry.
Note
The new label entry is inserted at the beginning of the label list in the identifier context. This effectively shifts all existing labels up by one, mirroring the fact that control instructions are indexed relatively not absolutely.
If a label with the same name already exists, then it is shadowed and the earlier label becomes inaccessible.
6.5.2. Control Instructions
Structured control instructions can bind an optional symbolic label identifier. The same label identifier may optionally be repeated after the corresponding and pseudo instructions, to indicate the matching delimiters.
Their block type is given as a type use, analogous to the type of functions. However, the special case of a type use that is syntactically empty or consists of only a single result is not regarded as an abbreviation for an inline function type, but is parsed directly into an optional value type.
Note
The side condition stating that the identifier context must only contain unnamed entries in the rule for block types enforces that no identifier can be bound in any declaration for a block type.
All other control instruction are represented verbatim.
Note
The side condition stating that the identifier context must only contain unnamed entries in the rule for enforces that no identifier can be bound in any declaration appearing in the type annotation.
6.5.2.1. Abbreviations
The keyword of an instruction can be omitted if the following instruction sequence is empty.
Also, for backwards compatibility, the table index to can be omitted, defaulting to .
6.5.3. Reference Instructions
6.5.4. Parametric Instructions
6.5.5. Variable Instructions
6.5.6. Table Instructions
6.5.6.1. Abbreviations
For backwards compatibility, all table indices may be omitted from table instructions, defaulting to .
6.5.7. Memory Instructions
The offset and alignment immediates to memory instructions are optional. The offset defaults to , the alignment to the storage size of the respective memory access, which is its natural alignment. Lexically, an or phrase is considered a single keyword token, so no white space is allowed around the .
6.5.8. Numeric Instructions
6.5.9. Vector Instructions
Vector memory instructions have optional offset and alignment immediates, like the memory instructions.
Vector constant instructions have a mandatory shape descriptor, which determines how the following values are parsed.
6.5.10. Folded Instructions
Instructions can be written as S-expressions by grouping them into folded form. In that notation, an instruction is wrapped in parentheses and optionally includes nested folded instructions to indicate its operands.
In the case of block instructions, the folded form omits the delimiter. For instructions, both branches have to be wrapped into nested S-expressions, headed by the keywords and .
The set of all phrases defined by the following abbreviations recursively forms the auxiliary syntactic class . Such a folded instruction can appear anywhere a regular instruction can.
Note
For example, the instruction sequence
can be folded into
Folded instructions are solely syntactic sugar, no additional syntactic or type-based checking is implied.
6.5.11. Expressions
Expressions are written as instruction sequences. No explicit keyword is included, since they only occur in bracketed positions.
6.6. Modules
6.6.1. Indices
Indices can be given either in raw numeric form or as symbolic identifiers when bound by a respective construct. Such identifiers are looked up in the suitable space of the identifier context .
6.6.2. Types
Type definitions can bind a symbolic type identifier.
6.6.3. Type Uses
A type use is a reference to a type definition. It may optionally be augmented by explicit inlined parameter and result declarations. That allows binding symbolic identifiers to name the local indices of parameters. If inline declarations are given, then their types must match the referenced function type.
The synthesized attribute of a is a pair consisting of both the used type index and the local identifier context containing possible parameter identifiers. The following auxiliary function extracts optional identifiers from parameters:
Note
Both productions overlap for the case that the function type is . However, in that case, they also produce the same results, so that the choice is immaterial.
The well-formedness condition on ensures that the parameters do not contain duplicate identifiers.
6.6.3.1. Abbreviations
A may also be replaced entirely by inline parameter and result declarations. In that case, a type index is automatically inserted:
where is the smallest existing type index whose definition in the current module is the function type . If no such index exists, then a new type definition of the form
is inserted at the end of the module.
Abbreviations are expanded in the order they appear, such that previously inserted type definitions are reused by consecutive expansions.
6.6.4. Imports
The descriptors in imports can bind a symbolic function, table, memory, or global identifier.
6.6.4.1. Abbreviations
As an abbreviation, imports may also be specified inline with function, table, memory, or global definitions; see the respective sections.
6.6.5. Functions
Function definitions can bind a symbolic function identifier, and local identifiers for its parameters and locals.
The definition of the local identifier context uses the following auxiliary function to extract optional identifiers from locals:
Note
The well-formedness condition on ensures that parameters and locals do not contain duplicate identifiers.
6.6.5.1. Abbreviations
Multiple anonymous locals may be combined into a single declaration:
Functions can be defined as imports or exports inline:
Note
The latter abbreviation can be applied repeatedly, if “” contains additional export clauses. Consequently, a function declaration can contain any number of exports, possibly followed by an import.
6.6.6. Tables
Table definitions can bind a symbolic table identifier.
6.6.6.1. Abbreviations
An element segment can be given inline with a table definition, in which case its offset is and the limits of the table type are inferred from the length of the given segment:
Tables can be defined as imports or exports inline:
Note
The latter abbreviation can be applied repeatedly, if “” contains additional export clauses. Consequently, a table declaration can contain any number of exports, possibly followed by an import.
6.6.7. Memories
Memory definitions can bind a symbolic memory identifier.
6.6.7.1. Abbreviations
A data segment can be given inline with a memory definition, in which case its offset is and the limits of the memory type are inferred from the length of the data, rounded up to page size:
Memories can be defined as imports or exports inline:
Note
The latter abbreviation can be applied repeatedly, if “” contains additional export clauses. Consequently, a memory declaration can contain any number of exports, possibly followed by an import.
6.6.8. Globals
Global definitions can bind a symbolic global identifier.
6.6.8.1. Abbreviations
Globals can be defined as imports or exports inline:
Note
The latter abbreviation can be applied repeatedly, if “” contains additional export clauses. Consequently, a global declaration can contain any number of exports, possibly followed by an import.
6.6.9. Exports
The syntax for exports mirrors their abstract syntax directly.
6.6.9.1. Abbreviations
As an abbreviation, exports may also be specified inline with function, table, memory, or global definitions; see the respective sections.
6.6.10. Start Function
A start function is defined in terms of its index.
Note
At most one start function may occur in a module, which is ensured by a suitable side condition on the grammar.
6.6.11. Element Segments
Element segments allow for an optional table index to identify the table to initialize.
6.6.11.1. Abbreviations
As an abbreviation, a single instruction may occur in place of the offset of an active element segment or as an element expression:
Also, the element list may be written as just a sequence of function indices:
A table use can be omitted, defaulting to . Furthermore, for backwards compatibility with earlier versions of WebAssembly, if the table use is omitted, the keyword can be omitted as well.
As another abbreviation, element segments may also be specified inline with table definitions; see the respective section.
6.6.12. Data Segments
Data segments allow for an optional memory index to identify the memory to initialize. The data is written as a string, which may be split up into a possibly empty sequence of individual string literals.
Note
In the current version of WebAssembly, the only valid memory index is 0 or a symbolic memory identifier resolving to the same value.
6.6.12.1. Abbreviations
As an abbreviation, a single instruction may occur in place of the offset of an active data segment:
Also, a memory use can be omitted, defaulting to .
As another abbreviation, data segments may also be specified inline with memory definitions; see the respective section.
6.6.13. Modules
A module consists of a sequence of fields that can occur in any order. All definitions and their respective bound identifiers scope over the entire module, including the text preceding them.
A module may optionally bind an identifier that names the module. The name serves a documentary role only.
Note
Tools may include the module name in the name section of the binary format.
The following restrictions are imposed on the composition of modules: is defined if and only if
Note
The first condition ensures that there is at most one start function. The second condition enforces that all imports must occur before any regular definition of a function, table, memory, or global, thereby maintaining the ordering of the respective index spaces.
The well-formedness condition on in the grammar for ensures that no namespace contains duplicate identifiers.
The definition of the initial identifier context uses the following auxiliary definition which maps each relevant definition to a singular context with one (possibly empty) identifier:
6.6.13.1. Abbreviations
In a source file, the toplevel surrounding the module body may be omitted.
A Appendix
A.1 Embedding
A WebAssembly implementation will typically be embedded into a host environment. An embedder implements the connection between such a host environment and the WebAssembly semantics as defined in the main body of this specification. An embedder is expected to interact with the semantics in well-defined ways.
This section defines a suitable interface to the WebAssembly semantics in the form of entry points through which an embedder can access it. The interface is intended to be complete, in the sense that an embedder does not need to reference other functional parts of the WebAssembly specification directly.
Note
On the other hand, an embedder does not need to provide the host environment with access to all functionality defined in this interface. For example, an implementation may not support parsing of the text format.
Types
In the description of the embedder interface, syntactic classes from the abstract syntax and the runtime’s abstract machine are used as names for variables that range over the possible objects from that class. Hence, these syntactic classes can also be interpreted as types.
For numeric parameters, notation like is used to specify a symbolic name in addition to the respective value range.
Errors
Failure of an interface operation is indicated by an auxiliary syntactic class:
In addition to the error conditions specified explicitly in this section, implementations may also return errors when specific implementation limitations are reached.
Note
Errors are abstract and unspecific with this definition. Implementations can refine it to carry suitable classifications and diagnostic messages.
Pre- and Post-Conditions
Some operations state pre-conditions about their arguments or post-conditions about their results. It is the embedder’s responsibility to meet the pre-conditions. If it does, the post conditions are guaranteed by the semantics.
In addition to pre- and post-conditions explicitly stated with each operation, the specification adopts the following conventions for runtime objects (, , , addresses):
-
Every runtime object passed as a parameter must be valid per an implicit pre-condition.
-
Every runtime object returned as a result is valid per an implicit post-condition.
Note
As long as an embedder treats runtime objects as abstract and only creates and manipulates them through the interface defined here, all implicit pre-conditions are automatically met.
Store
-
Return the empty store.
Modules
-
If there exists a derivation for the byte sequence as a according to the binary grammar for modules, yielding a module , then return .
-
Else, return .
-
If there exists a derivation for the source as a according to the text grammar for modules, yielding a module , then return .
-
Else, return .
-
If is valid, then return nothing.
-
Else, return .
-
Try instantiating in with external values as imports:
If it succeeds with a module instance , then let be .
Else, let be .
-
Return the new store paired with .
Note
The store may be modified even in case of an error.
-
Pre-condition: is valid with external import types and external export types .
-
Let be the imports .
-
Assert: the length of equals the length of .
-
For each in and corresponding in , do:
Let be the triple .
-
Return the concatenation of all , in index order.
-
Post-condition: each is valid.
-
Pre-condition: is valid with external import types and external export types .
-
Let be the exports .
-
Assert: the length of equals the length of .
-
For each in and corresponding in , do:
Let be the pair .
-
Return the concatenation of all , in index order.
-
Post-condition: each is valid.
Module Instances
-
Assert: due to validity of the module instance , all its export names are different.
-
If there exists an in such that name equals , then:
-
Return the external value .
-
-
Else, return .
Functions
-
Pre-condition: is valid.
-
Let be the result of allocating a host function in with function type and host function code .
-
Return the new store paired with .
Note
This operation assumes that satisfies the pre- and post-conditions required for a function instance with type .
Regular (non-host) function instances can only be created indirectly through module instantiation.
-
Return .
-
Post-condition: the returned function type is valid.
If it succeeds with values as results, then let be .
Else it has trapped, hence let be .
-
Return the new store paired with .
Note
The store may be modified even in case of an error.
Tables
-
Pre-condition: is valid.
-
Let be the result of allocating a table in with table type and initialization value .
-
Return the new store paired with .
-
Return .
-
Post-condition: the returned table type is valid.
-
Let be the table instance .
-
If is larger than or equal to the length of , then return .
-
Else, return the reference value .
-
Let be the table instance .
-
If is larger than or equal to the length of , then return .
-
Replace with the reference value .
-
Return the updated store.
-
Return the length of .
-
Try growing the table instance by elements with initialization value :
-
If it succeeds, return the updated store.
-
Else, return .
-
Memories
-
Pre-condition: is valid.
-
Let be the result of allocating a memory in with memory type .
-
Return the new store paired with .
-
Return .
-
Post-condition: the returned memory type is valid.
-
Let be the memory instance .
-
If is larger than or equal to the length of , then return .
-
Else, return the byte .
-
Let be the memory instance .
-
If is larger than or equal to the length of , then return .
-
Replace with .
-
Return the updated store.
-
Return the length of divided by the page size.
-
Try growing the memory instance by pages:
-
If it succeeds, return the updated store.
-
Else, return .
-
Globals
-
Pre-condition: is valid.
-
Let be the result of allocating a global in with global type and initialization value .
-
Return the new store paired with .
-
Return .
-
Post-condition: the returned global type is valid.
-
Let be the global instance .
-
Return the value .
-
Let be the global instance .
-
Let be the structure of the global type .
-
If is not , then return .
-
Replace with the value .
-
Return the updated store.
A.2 Implementation Limitations
Implementations typically impose additional restrictions on a number of aspects of a WebAssembly module or execution. These may stem from:
-
physical resource limits,
-
constraints imposed by the embedder or its environment,
-
limitations of selected implementation strategies.
This section lists allowed limitations. Where restrictions take the form of numeric limits, no minimum requirements are given, nor are the limits assumed to be concrete, fixed numbers. However, it is expected that all implementations have “reasonably” large limits to enable common applications.
Note
A conforming implementation is not allowed to leave out individual features. However, designated subsets of WebAssembly may be specified in the future.
Syntactic Limits
Structure
An implementation may impose restrictions on the following dimensions of a module:
-
the number of element segments in a module
-
the number of data segments in a module
-
the number of parameters in a function type
-
the number of results in a function type
-
the number of parameters in a block type
-
the number of results in a block type
-
the size of a function body
-
the size of a structured control instruction
-
the number of structured control instructions in a function
-
the nesting depth of structured control instructions
-
the number of label indices in a instruction
-
the length of an element segment
-
the length of a data segment
-
the length of a name
-
the range of characters in a name
If the limits of an implementation are exceeded for a given module, then the implementation may reject the validation, compilation, or instantiation of that module with an embedder-specific error.
Binary Format
For a module given in binary format, additional limitations may be imposed on the following dimensions:
Text Format
For a module given in text format, additional limitations may be imposed on the following dimensions:
-
the size of the source text
-
the size of any syntactic element
-
the size of an individual token
-
the nesting depth of folded instructions
-
the length of symbolic identifiers
-
the range of literal characters allowed in the source text
Validation
An implementation may defer validation of individual functions until they are first invoked.
If a function turns out to be invalid, then the invocation, and every consecutive call to the same function, results in a trap.
Note
This is to allow implementations to use interpretation or just-in-time compilation for functions. The function must still be fully validated before execution of its body begins.
Execution
Restrictions on the following dimensions may be imposed during execution of a WebAssembly program:
-
the number of allocated module instances
-
the number of allocated function instances
-
the number of allocated table instances
-
the number of allocated memory instances
-
the number of allocated global instances
-
the size of a table instance
-
the size of a memory instance
If the runtime limits of an implementation are exceeded during execution of a computation, then it may terminate that computation and report an embedder-specific error to the invoking code.
Some of the above limits may already be verified during instantiation, in which case an implementation may report exceedance in the same manner as for syntactic limits.
Note
Concrete limits are usually not fixed but may be dependent on specifics, interdependent, vary over time, or depend on other implementation- or embedder-specific situations or events.
A.3 Validation Algorithm
The specification of WebAssembly validation is purely declarative. It describes the constraints that must be met by a module or instruction sequence to be valid.
This section sketches the skeleton of a sound and complete algorithm for effectively validating code, i.e., sequences of instructions. (Other aspects of validation are straightforward to implement.)
In fact, the algorithm is expressed over the flat sequence of opcodes as occurring in the binary format, and performs only a single pass over it. Consequently, it can be integrated directly into a decoder.
The algorithm is expressed in typed pseudo code whose semantics is intended to be self-explanatory.
Data Structures
Types are representable as an enumeration.
type val_type = I32 | I64 | F32 | F64 | V128 | Funcref | Externref
func is_num(t : val_type | Unknown) : bool =
return t = I32 || t = I64 || t = F32 || t = F64 || t = Unknown
func is_vec(t : val_type | Unknown) : bool =
return t = V128 || t = Unknown
func is_ref(t : val_type | Unknown) : bool =
return t = Funcref || t = Externref || t = Unknown
The algorithm uses two separate stacks: the value stack and the control stack. The former tracks the types of operand values on the stack, the latter surrounding structured control instructions and their associated blocks.
type val_stack = stack(val_type | Unknown)
type ctrl_stack = stack(ctrl_frame)
type ctrl_frame = {
opcode : opcode
start_types : list(val_type)
end_types : list(val_type)
height : nat
unreachable : bool
}
For each value, the value stack records its value type, or Unknown
when the type is not known.
For each entered block, the control stack records a control frame with the originating opcode, the types on the top of the operand stack at the start and end of the block (used to check its result as well as branches), the height of the operand stack at the start of the block (used to check that operands do not underflow the current block), and a flag recording whether the remainder of the block is unreachable (used to handle stack-polymorphic typing after branches).
For the purpose of presenting the algorithm, the operand and control stacks are simply maintained as global variables:
var vals : val_stackvar ctrls : ctrl_stack
However, these variables are not manipulated directly by the main checking function, but through a set of auxiliary functions:
func push_val(type : val_type | Unknown) = vals.push(type)
func pop_val() : val_type | Unknown =
if (vals.size() = ctrls[0].height && ctrls[0].unreachable) return Unknown
error_if(vals.size() = ctrls[0].height)
return vals.pop()
func pop_val(expect : val_type | Unknown) : val_type | Unknown =
let actual = pop_val()
error_if(actual =/= expect && actual =/= Unknown && expect =/= Unknown)
return actual
func push_vals(types : list(val_type)) = foreach (t in types) push_val(t)
func pop_vals(types : list(val_type)) : list(val_type) =
var popped := []
foreach (t in reverse(types)) popped.prepend(pop_val(t))
return popped
Pushing an operand value simply pushes the respective type to the value stack.
Popping an operand value checks that the value stack does not underflow the current block and then removes one type. But first, a special case is handled where the block contains no known values, but has been marked as unreachable. That can occur after an unconditional branch, when the stack is typed polymorphically. In that case, an unknown type is returned.
A second function for popping an operand value takes an expected type, which the actual operand type is checked against. The types may differ in case one of them is Unknown. The function returns the actual type popped from the stack.
Finally, there are accumulative functions for pushing or popping multiple operand types.
Note
The notation stack[i]
is meant to index the stack from the top,
so that, e.g., ctrls[0]
accesses the element pushed last.
The control stack is likewise manipulated through auxiliary functions:
func push_ctrl(opcode : opcode, in : list(val_type), out : list(val_type)) = let frame = ctrl_frame(opcode, in, out, vals.size(), false)
ctrls.push(frame)
push_vals(in)
func pop_ctrl() : ctrl_frame =
error_if(ctrls.is_empty())
let frame = ctrls[0]
pop_vals(frame.end_types)
error_if(vals.size() =/= frame.height)
ctrls.pop()
return frame
func label_types(frame : ctrl_frame) : list(val_types) =
return (if frame.opcode == loop then frame.start_types else frame.end_types)
func unreachable() =
vals.resize(ctrls[0].height)
ctrls[0].unreachable := true
Pushing a control frame takes the types of the label and result values. It allocates a new frame record recording them along with the current height of the operand stack and marks the block as reachable.
Popping a frame first checks that the control stack is not empty. It then verifies that the operand stack contains the right types of values expected at the end of the exited block and pops them off the operand stack. Afterwards, it checks that the stack has shrunk back to its initial height.
The type of the label associated with a control frame is either that of the stack at the start or the end of the frame, determined by the opcode that it originates from.
Finally, the current frame can be marked as unreachable.
In that case, all existing operand types are purged from the value stack, in order to allow for the stack-polymorphism logic in pop_val
to take effect.
Because every function has an implicit outermost label that corresponds to an implicit block frame,
it is an invariant of the validation algorithm that there always is at least one frame on the control stack when validating an instruction, and hence, ctrls[0] is always defined.
Note
Even with the unreachable flag set, consecutive operands are still pushed to and popped from the operand stack.
That is necessary to detect invalid examples like .
However, a polymorphic stack cannot underflow, but instead generates Unknown
types as needed.
Validation of Opcode Sequences
The following function shows the validation of a number of representative instructions that manipulate the stack. Other instructions are checked in a similar manner.
Note
Various instructions not shown here will additionally require the presence of a validation context for checking uses of indices. That is an easy addition and therefore omitted from this presentation.
func validate(opcode) =switch (opcode)
case (i32.add)
pop_val(I32)
pop_val(I32)
push_val(I32)
case (drop)
pop_val()
case (select)
pop_val(I32)
let t1 = pop_val()
let t2 = pop_val()
error_if(not ((is_num(t1) && is_num(t2)) || (is_vec(t1) && is_vec(t2))))
error_if(t1 =/= t2 && t1 =/= Unknown && t2 =/= Unknown)
push_val(if (t1 = Unknown) t2 else t1)
case (select t)
pop_val(I32)
pop_val(t)
pop_val(t)
push_val(t)
case (unreachable)
unreachable()
case (block t1*->t2*)
pop_vals([t1*])
push_ctrl(block, [t1*], [t2*])
case (loop t1*->t2*)
pop_vals([t1*])
push_ctrl(loop, [t1*], [t2*])
case (if t1*->t2*)
pop_val(I32)
pop_vals([t1*])
push_ctrl(if, [t1*], [t2*])
case (end)
let frame = pop_ctrl()
push_vals(frame.end_types)
case (else)
let frame = pop_ctrl()
error_if(frame.opcode =/= if)
push_ctrl(else, frame.start_types, frame.end_types)
case (br n)
error_if(ctrls.size() < n)
pop_vals(label_types(ctrls[n]))
unreachable()
case (br_if n)
error_if(ctrls.size() < n)
pop_val(I32)
pop_vals(label_types(ctrls[n]))
push_vals(label_types(ctrls[n]))
case (br_table n* m)
pop_val(I32)
error_if(ctrls.size() < m)
let arity = label_types(ctrls[m]).size()
foreach (n in n*)
error_if(ctrls.size() < n)
error_if(label_types(ctrls[n]).size() =/= arity)
push_vals(pop_vals(label_types(ctrls[n])))
pop_vals(label_types(ctrls[m]))
unreachable()
Note
It is an invariant under the current WebAssembly instruction set that an operand of Unknown
type is never duplicated on the stack.
This would change if the language were extended with stack instructions like dup
.
Under such an extension, the above algorithm would need to be refined by replacing the Unknown
type with proper type variables to ensure that all uses are consistent.
A.4 Custom Sections
This appendix defines dedicated custom sections for WebAssembly’s binary format. Such sections do not contribute to, or otherwise affect, the WebAssembly semantics, and like any custom section they may be ignored by an implementation. However, they provide useful meta data that implementations can make use of to improve user experience or take compilation hints.
Currently, only one dedicated custom section is defined, the name section.
Name Section
The name section is a custom section whose name string is itself . The name section should appear only once in a module, and only after the data section.
The purpose of this section is to attach printable names to definitions in a module, which e.g. can be used by a debugger or when parts of the module are to be rendered in text form.
Subsections
The data of a name section consists of a sequence of subsections. Each subsection consists of a
-
a one-byte subsection id,
-
the size of the contents, in bytes,
-
the actual contents, whose structure is dependent on the subsection id.
The following subsection ids are used:
Id |
Subsection |
---|---|
0 | |
1 | |
2 |
Each subsection may occur at most once, and in order of increasing id.
Name Maps
A name map assigns names to indices in a given index space. It consists of a vector of index/name pairs in order of increasing index value. Each index must be unique, but the assigned names need not be.
An indirect name map assigns names to a two-dimensional index space, where secondary indices are grouped by primary indices. It consists of a vector of primary index/name map pairs in order of increasing index value, where each name map in turn maps secondary indices to names. Each primary index must be unique, and likewise each secondary index per individual name map.
Module Names
The module name subsection has the id 0. It simply consists of a single name that is assigned to the module itself.
Function Names
The function name subsection has the id 1. It consists of a name map assigning function names to function indices.
Local Names
The local name subsection has the id 2. It consists of an indirect name map assigning local names to local indices grouped by function indices.
A.5 Soundness
The type system of WebAssembly is sound, implying both type safety and memory safety with respect to the WebAssembly semantics. For example:
-
All types declared and derived during validation are respected at run time; e.g., every local or global variable will only contain type-correct values, every instruction will only be applied to operands of the expected type, and every function invocation always evaluates to a result of the right type (if it does not trap or diverge).
-
No memory location will be read or written except those explicitly defined by the program, i.e., as a local, a global, an element in a table, or a location within a linear memory.
-
There is no undefined behavior, i.e., the execution rules cover all possible cases that can occur in a valid program, and the rules are mutually consistent.
Soundness also is instrumental in ensuring additional properties, most notably, encapsulation of function and module scopes: no locals can be accessed outside their own function and no module components can be accessed outside their own module unless they are explicitly exported or imported.
The typing rules defining WebAssembly validation only cover the static components of a WebAssembly program. In order to state and prove soundness precisely, the typing rules must be extended to the dynamic components of the abstract runtime, that is, the store, configurations, and administrative instructions. [1]
Results
Results can be classified by result types as follows.
Results
-
For each value in :
-
The value is valid with some value type .
-
-
Let be the concatenation of all .
-
Then the result is valid with result type .
Results
-
The result is valid with result type , for any sequence of value types.
Store Validity
The following typing rules specify when a runtime store is valid. A valid store must consist of function, table, memory, global, and module instances that are themselves valid, relative to .
To that end, each kind of instance is classified by a respective function, table, memory, or global type. Module instances are classified by module contexts, which are regular contexts repurposed as module types describing the index spaces defined by a module.
Store
-
Each function instance in must be valid with some function type .
-
Each table instance in must be valid with some table type .
-
Each memory instance in must be valid with some memory type .
-
Each global instance in must be valid with some global type .
-
Each element instance in must be valid with some reference type .
-
Each data instance in must be valid.
-
Then the store is valid.
Function Instances
-
The function type must be valid.
-
The module instance must be valid with some context .
-
Under context , the function must be valid with function type .
-
Then the function instance is valid with function type .
Host Function Instances
-
The function type must be valid.
-
Let be the function type .
-
For every valid store extending and every sequence of values whose types coincide with :
-
Then the function instance is valid with function type .
Note
This rule states that, if appropriate pre-conditions about store and arguments are satisfied, then executing the host function must satisfy appropriate post-conditions about store and results. The post-conditions match the ones in the execution rule for invoking host functions.
Any store under which the function is invoked is assumed to be an extension of the current store. That way, the function itself is able to make sufficient assumptions about future stores.
Table Instances
-
The table type must be valid.
-
The length of must equal .
-
For each reference in the table’s elements :
-
The reference must be valid with reference type .
-
-
Then the table instance is valid with table type .
Memory Instances
-
The memory type must be valid.
-
The length of must equal multiplied by the page size .
-
Then the memory instance is valid with memory type .
Global Instances
-
The global type must be valid.
-
The value must be valid with value type .
-
Then the global instance is valid with global type .
Element Instances
-
For each reference in the elements :
-
The reference must be valid with reference type .
-
-
Then the element instance is valid with reference type .
Data Instances
-
The data instance is valid.
Export Instances
-
The external value must be valid with some external type .
-
Then the export instance is valid.
Module Instances
-
Each function type in must be valid.
-
For each function address in , the external value must be valid with some external type .
-
For each table address in , the external value must be valid with some external type .
-
For each memory address in , the external value must be valid with some external type .
-
For each global address in , the external value must be valid with some external type .
-
For each element address in , the element instance must be valid with some reference type .
-
For each data address in , the data instance must be valid.
-
Each export instance in must be valid.
-
For each export instance in , the name must be different from any other name occurring in .
-
Let be the concatenation of all in order.
-
Let be the concatenation of all in order.
-
Let be the concatenation of all in order.
-
Let be the concatenation of all in order.
-
Let be the concatenation of all in order.
-
Let be the length of .
-
Let be the length of .
-
Let be the sequence of function indices from to .
-
Then the module instance is valid with context .
Configuration Validity
To relate the WebAssembly type system to its execution semantics, the typing rules for instructions must be extended to configurations , which relates the store to execution threads.
Configurations and threads are classified by their result type. In addition to the store , threads are typed under a return type , which controls whether and with which type a instruction is allowed. This type is absent () except for instruction sequences inside an administrative instruction.
Finally, frames are classified with frame contexts, which extend the module contexts of a frame’s associated module instance with the locals that the frame contains.
Configurations
-
Under no allowed return type, the thread must be valid with some result type .
-
Then the configuration is valid with the result type .
Threads
-
Let be the current allowed return type.
-
Let be the same context as , but with set to .
-
Under context , the instruction sequence must be valid with some type .
-
Then the thread is valid with the result type .
Frames
-
The module instance must be valid with some module context .
-
Each value in must be valid with some value type .
-
Let be the concatenation of all in order.
-
Let be the same context as , but with the value types prepended to the vector.
-
Then the frame is valid with frame context .
Administrative Instructions
Typing rules for administrative instructions are specified as follows. In addition to the context , typing of these instructions is defined under a given store . To that end, all previous typing judgements are generalized to include the store, as in , by implicitly adding to all rules – is never modified by the pre-existing rules, but it is accessed in the extra rules for administrative instructions given below.
-
The instruction is valid with type , for any sequences of value types and .
-
The instruction is valid with type .
-
The external function value must be valid with external function type .
-
Then the instruction is valid with type .
-
The external function value must be valid with external function type .
-
Then the instruction is valid with type .
-
The instruction sequence must be valid with some type .
-
Let be the same context as , but with the result type prepended to the vector.
-
Under context , the instruction sequence must be valid with type .
-
Then the compound instruction is valid with type .
-
Under the return type , the thread must be valid with result type .
-
Then the compound instruction is valid with type .
Store Extension
Programs can mutate the store and its contained instances. Any such modification must respect certain invariants, such as not removing allocated instances or changing immutable definitions. While these invariants are inherent to the execution semantics of WebAssembly instructions and modules, host functions do not automatically adhere to them. Consequently, the required invariants must be stated as explicit constraints on the invocation of host functions. Soundness only holds when the embedder ensures these constraints.
The necessary constraints are codified by the notion of store extension: a store state extends state , written , when the following rules hold.
Note
Extension does not imply that the new store is valid, which is defined separately above.
Store
-
The length of must not shrink.
-
The length of must not shrink.
-
The length of must not shrink.
-
The length of must not shrink.
-
The length of must not shrink.
-
The length of must not shrink.
-
For each function instance in the original , the new function instance must be an extension of the old.
-
For each table instance in the original , the new table instance must be an extension of the old.
-
For each memory instance in the original , the new memory instance must be an extension of the old.
-
For each global instance in the original , the new global instance must be an extension of the old.
-
For each element instance in the original , the new element instance must be an extension of the old.
-
For each data instance in the original , the new data instance must be an extension of the old.
Function Instance
-
A function instance must remain unchanged.
Table Instance
-
The table type must remain unchanged.
-
The length of must not shrink.
Memory Instance
-
The memory type must remain unchanged.
-
The length of must not shrink.
Global Instance
-
The global type must remain unchanged.
-
Let be the structure of .
-
If is , then the value must remain unchanged.
Element Instance
-
The vector must either remain unchanged or shrink to length .
Data Instance
-
The vector must either remain unchanged or shrink to length .
Theorems
Given the definition of valid configurations, the standard soundness theorems hold. [2] [3]
Theorem (Preservation). If a configuration is valid with result type (i.e., ), and steps to (i.e., ), then is a valid configuration with the same result type (i.e., ). Furthermore, is an extension of (i.e., ).
A terminal thread is one whose sequence of instructions is a result. A terminal configuration is a configuration whose thread is terminal.
Theorem (Progress). If a configuration is valid (i.e., for some result type ), then either it is terminal, or it can step to some configuration (i.e., ).
From Preservation and Progress the soundness of the WebAssembly type system follows directly.
Corollary (Soundness). If a configuration is valid (i.e., for some result type ), then it either diverges or takes a finite number of steps to reach a terminal configuration (i.e., ) that is valid with the same result type (i.e., ) and where is an extension of (i.e., ).
In other words, every thread in a valid configuration either runs forever, traps, or terminates with a result that has the expected type. Consequently, given a valid store, no computation defined by instantiation or invocation of a valid module can “crash” or otherwise (mis)behave in ways not covered by the execution semantics given in this specification.
The formalization and theorems are derived from the following article: Andreas Haas, Andreas Rossberg, Derek Schuff, Ben Titzer, Dan Gohman, Luke Wagner, Alon Zakai, JF Bastien, Michael Holman. Bringing the Web up to Speed with WebAssembly. Proceedings of the 38th ACM SIGPLAN Conference on Programming Language Design and Implementation (PLDI 2017). ACM 2017.
A machine-verified version of the formalization and soundness proof of the PLDI 2017 paper is described in the following article: Conrad Watt. Mechanising and Verifying the WebAssembly Specification. Proceedings of the 7th ACM SIGPLAN Conference on Certified Programs and Proofs (CPP 2018). ACM 2018.
Machine-verified formalizations and soundness proofs of the semantics from the official specification are described in the following article: Conrad Watt, Xiaojia Rao, Jean Pichon-Pharabod, Martin Bodin, Philippa Gardner. Two Mechanisations of WebAssembly 1.0. Proceedings of the 24th International Symposium on Formal Methods (FM 2021). Springer 2021.
Change History
Since the original release 1.0 of the WebAssembly specification, a number of proposals for extensions have been integrated. The following sections provide an overview of what has changed.
Release 2.0
Sign extension instructions
Added new numeric instructions for performing sign extension within integer representations [1].
-
New numeric instructions:
Non-trapping float-to-int conversions
Added new conversion instructions that avoid trapping when converting a floating-point number to an integer [2].
-
New numeric instructions:
Multiple values
Generalized the result type of blocks and functions to allow for multiple values; in addition, introduced the ability to have block parameters [3].
-
Function types allow more than one result
-
Block types can be arbitrary function types
Reference types
Added and as new value types and respective instructions [4].
-
New value types: reference types and
-
New reference instructions: , ,
-
Enrich parametric instruction: with optional type immediate
-
New declarative form of element segment
Table instructions
Added instructions to directly access and modify tables [4].
-
Table types allow any reference type as element type
-
New table instructions: , , ,
Multiple tables
Added the ability to use multiple tables per module [4].
-
Table instructions take a table index immediate: , , , ,
-
Element segments take a table index
Bulk memory and table instructions
Added instructions that modify ranges of memory or table entries [4] [5]
-
New memory instructions: , , ,
-
New table instructions: , , ,
-
New passive form of data segment
-
New passive form of element segment
-
New data count section in binary format
-
Active data and element segments boundaries are no longer checked at compile time but may trap instead
Vector instructions
Added vector type and instructions that manipulate multiple numeric values in parallel (also known as SIMD, single instruction multiple data) [6]
-
New value type:
-
New memory instructions: , , , , , ,
-
New constant vector instruction:
-
New unary vector instructions: , , , , , , , , , ,
-
New binary vector instructions: , , , , , , , , , , , , , , , , , , , , , , , , , , ,
-
New ternary vector instruction:
-
New test vector instructions: ,
-
New relational vector instructions: , , , , , , , , , , ,
-
New conversion vector instructions:, , , , ,
-
New lane access vector instructions: , , ,
-
New lane splitting/combining vector instructions: , ,
-
New byte reordering vector instructions: ,
-
New injection/projection vector instructions: , ,
https://github.com/WebAssembly/spec/tree/main/proposals/sign-extension-ops/
https://github.com/WebAssembly/spec/tree/main/proposals/nontrapping-float-to-int-conversion/
https://github.com/WebAssembly/spec/tree/main/proposals/multi-value/
https://github.com/WebAssembly/spec/tree/main/proposals/reference-types/
https://github.com/WebAssembly/spec/tree/main/proposals/bulk-memory-operations/
https://github.com/WebAssembly/spec/tree/main/proposals/simd/
A.6 Index of Types
Category |
Constructor |
Binary Opcode |
---|---|---|
|
(positive number as or ) | |
|
(-1 as ) | |
|
(-2 as ) | |
|
(-3 as ) | |
|
(-4 as ) | |
|
(-5 as ) | |
(reserved) |
.. | |
|
(-16 as ) | |
|
(-17 as ) | |
(reserved) |
.. | |
|
(-32 as ) | |
(reserved) |
.. | |
|
(-64 as ) | |
|
(none) | |
|
(none) | |
|
(none) |
A.7 Index of Instructions
Instruction |
Binary Opcode |
Type |
Validation |
Execution |
---|---|---|---|---|
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
|
| |||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
|
|
| ||
|
|
| ||
|
|
| ||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
(reserved) |
| |||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
|
|
| ||
|
|
| ||
|
|
| ||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
(reserved) |
| |||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
|
Note
Multi-byte opcodes are given with the shortest possible encoding in the table. However, what is following the first byte is actually a u32 with variable-length encoding and consequently has multiple possible representations.
A.8 Index of Semantic Rules
Typing of Static Constructs
Construct |
Judgement |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
Typing of Runtime Constructs
Construct |
Judgement |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
Constantness
Construct |
Judgement |
---|---|
| |
|
Matching
Construct |
Judgement |
---|---|
| |
|
Store Extension
Construct |
Judgement |
---|---|
| |
| |
| |
| |
| |
| |
|
Execution
Construct |
Judgement |
---|---|
| |
|
6.2.4. Comments
A comment can either be a line comment, started with a double semicolon ‘;;’ and extending to the end of the line, or a block comment, enclosed in delimiters ‘(;’…‘;)’. Block comments can be nested.
Here, the pseudo token eof indicates the end of the input. The look-ahead restrictions on the productions for blockchar disambiguate the grammar such that only well-bracketed uses of block comment delimiters are allowed.
Note
Any formatting and control characters are allowed inside comments.