# 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.

## Numeric Instructions¶

Numeric instructions provide basic operations over numeric values of specific type. These operations closely match respective operations available in hardware.

$\begin{split}\begin{array}{llcl} \def\mathdef1807#1{{}}\mathdef1807{width} & \mathit{nn}, \mathit{mm} &::=& \mathsf{32} ~|~ \mathsf{64} \\ \def\mathdef1807#1{{}}\mathdef1807{signedness} & \href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} &::=& \mathsf{u} ~|~ \mathsf{s} \\ \def\mathdef1807#1{{}}\mathdef1807{instruction} & \href{../syntax/instructions.html#syntax-instr}{\mathit{instr}} &::=& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{const}}~\href{../syntax/values.html#syntax-int}{\def\mathdef1844#1{{\mathit{i#1}}}\mathdef1844{\mathit{nn}}} ~|~ \mathsf{f}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{const}}~\href{../syntax/values.html#syntax-float}{\def\mathdef1845#1{{\mathit{f#1}}}\mathdef1845{\mathit{nn}}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-iunop}{\mathit{iunop}} ~|~ \mathsf{f}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-funop}{\mathit{funop}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-ibinop}{\mathit{ibinop}} ~|~ \mathsf{f}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-fbinop}{\mathit{fbinop}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-itestop}{\mathit{itestop}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-irelop}{\mathit{irelop}} ~|~ \mathsf{f}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-frelop}{\mathit{frelop}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{extend}}\mathsf{8\_s} ~|~ \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{extend}}\mathsf{16\_s} ~|~ \mathsf{i64.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{extend}}\mathsf{32\_s} \\&&|& \mathsf{i32.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{wrap}}\mathsf{\_i64} ~|~ \mathsf{i64.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{extend}}\mathsf{\_i32}\mathsf{\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} ~|~ \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{trunc}}\mathsf{\_f}\mathit{mm}\mathsf{\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{trunc}}\mathsf{\_sat\_f}\mathit{mm}\mathsf{\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} \\&&|& \mathsf{f32.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{demote}}\mathsf{\_f64} ~|~ \mathsf{f64.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{promote}}\mathsf{\_f32} ~|~ \mathsf{f}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{convert}}\mathsf{\_i}\mathit{mm}\mathsf{\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{reinterpret}}\mathsf{\_f}\mathit{nn} ~|~ \mathsf{f}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{reinterpret}}\mathsf{\_i}\mathit{nn} \\&&|& \dots \\ \def\mathdef1807#1{{}}\mathdef1807{integer unary operator} & \href{../syntax/instructions.html#syntax-iunop}{\mathit{iunop}} &::=& \mathsf{clz} ~|~ \mathsf{ctz} ~|~ \mathsf{popcnt} \\ \def\mathdef1807#1{{}}\mathdef1807{integer binary operator} & \href{../syntax/instructions.html#syntax-ibinop}{\mathit{ibinop}} &::=& \mathsf{add} ~|~ \mathsf{sub} ~|~ \mathsf{mul} ~|~ \mathsf{div\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} ~|~ \mathsf{rem\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} \\&&|& \mathsf{and} ~|~ \mathsf{or} ~|~ \mathsf{xor} ~|~ \mathsf{shl} ~|~ \mathsf{shr\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} ~|~ \mathsf{rotl} ~|~ \mathsf{rotr} \\ \def\mathdef1807#1{{}}\mathdef1807{floating-point unary operator} & \href{../syntax/instructions.html#syntax-funop}{\mathit{funop}} &::=& \mathsf{abs} ~|~ \mathsf{neg} ~|~ \mathsf{sqrt} ~|~ \mathsf{ceil} ~|~ \mathsf{floor} ~|~ \mathsf{trunc} ~|~ \mathsf{nearest} \\ \def\mathdef1807#1{{}}\mathdef1807{floating-point binary operator} & \href{../syntax/instructions.html#syntax-fbinop}{\mathit{fbinop}} &::=& \mathsf{add} ~|~ \mathsf{sub} ~|~ \mathsf{mul} ~|~ \mathsf{div} ~|~ \mathsf{min} ~|~ \mathsf{max} ~|~ \mathsf{copysign} \\ \def\mathdef1807#1{{}}\mathdef1807{integer test operator} & \href{../syntax/instructions.html#syntax-itestop}{\mathit{itestop}} &::=& \mathsf{eqz} \\ \def\mathdef1807#1{{}}\mathdef1807{integer relational operator} & \href{../syntax/instructions.html#syntax-irelop}{\mathit{irelop}} &::=& \mathsf{eq} ~|~ \mathsf{ne} ~|~ \mathsf{lt\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} ~|~ \mathsf{gt\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} ~|~ \mathsf{le\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} ~|~ \mathsf{ge\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}} \\ \def\mathdef1807#1{{}}\mathdef1807{floating-point relational operator} & \href{../syntax/instructions.html#syntax-frelop}{\mathit{frelop}} &::=& \mathsf{eq} ~|~ \mathsf{ne} ~|~ \mathsf{lt} ~|~ \mathsf{gt} ~|~ \mathsf{le} ~|~ \mathsf{ge} \\ \end{array}\end{split}$

Numeric instructions are divided by value 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 “$$\mathsf{\_}$$”).

Some integer instructions come in two flavors, where a signedness annotation $$\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}$$ 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.

### Conventions¶

Occasionally, it is convenient to group operators together according to the following grammar shorthands:

$\begin{split}\begin{array}{llll} \def\mathdef1807#1{{}}\mathdef1807{unary operator} & \href{../syntax/instructions.html#syntax-unop}{\mathit{unop}} &::=& \href{../syntax/instructions.html#syntax-iunop}{\mathit{iunop}} ~|~ \href{../syntax/instructions.html#syntax-funop}{\mathit{funop}} ~|~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{extend}}{N}\mathsf{\_s} \\ \def\mathdef1807#1{{}}\mathdef1807{binary operator} & \href{../syntax/instructions.html#syntax-binop}{\mathit{binop}} &::=& \href{../syntax/instructions.html#syntax-ibinop}{\mathit{ibinop}} ~|~ \href{../syntax/instructions.html#syntax-fbinop}{\mathit{fbinop}} \\ \def\mathdef1807#1{{}}\mathdef1807{test operator} & \href{../syntax/instructions.html#syntax-testop}{\mathit{testop}} &::=& \href{../syntax/instructions.html#syntax-itestop}{\mathit{itestop}} \\ \def\mathdef1807#1{{}}\mathdef1807{relational operator} & \href{../syntax/instructions.html#syntax-relop}{\mathit{relop}} &::=& \href{../syntax/instructions.html#syntax-irelop}{\mathit{irelop}} ~|~ \href{../syntax/instructions.html#syntax-frelop}{\mathit{frelop}} \\ \def\mathdef1807#1{{}}\mathdef1807{conversion operator} & \href{../syntax/instructions.html#syntax-cvtop}{\mathit{cvtop}} &::=& \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{wrap}} ~|~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{extend}} ~|~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{trunc}} ~|~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{trunc}}\mathsf{\_sat} ~|~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{convert}} ~|~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{demote}} ~|~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{promote}} ~|~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{reinterpret}} \\ \end{array}\end{split}$

## Parametric Instructions¶

Instructions in this group can operate on operands of any value type.

$\begin{split}\begin{array}{llcl} \def\mathdef1807#1{{}}\mathdef1807{instruction} & \href{../syntax/instructions.html#syntax-instr}{\mathit{instr}} &::=& \dots \\&&|& \href{../syntax/instructions.html#syntax-instr-parametric}{\mathsf{drop}} \\&&|& \href{../syntax/instructions.html#syntax-instr-parametric}{\mathsf{select}} \end{array}\end{split}$

The $$\href{../syntax/instructions.html#syntax-instr-parametric}{\mathsf{drop}}$$ instruction simply throws away a single operand.

The $$\href{../syntax/instructions.html#syntax-instr-parametric}{\mathsf{select}}$$ instruction selects one of its first two operands based on whether its third operand is zero or not.

## Variable Instructions¶

$\begin{split}\begin{array}{llcl} \def\mathdef1807#1{{}}\mathdef1807{instruction} & \href{../syntax/instructions.html#syntax-instr}{\mathit{instr}} &::=& \dots \\&&|& \href{../syntax/instructions.html#syntax-instr-variable}{\mathsf{local.get}}~\href{../syntax/modules.html#syntax-localidx}{\mathit{localidx}} \\&&|& \href{../syntax/instructions.html#syntax-instr-variable}{\mathsf{local.set}}~\href{../syntax/modules.html#syntax-localidx}{\mathit{localidx}} \\&&|& \href{../syntax/instructions.html#syntax-instr-variable}{\mathsf{local.tee}}~\href{../syntax/modules.html#syntax-localidx}{\mathit{localidx}} \\&&|& \href{../syntax/instructions.html#syntax-instr-variable}{\mathsf{global.get}}~\href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}} \\&&|& \href{../syntax/instructions.html#syntax-instr-variable}{\mathsf{global.set}}~\href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}} \\ \end{array}\end{split}$

These instructions get or set the values of variables, respectively. The $$\href{../syntax/instructions.html#syntax-instr-variable}{\mathsf{local.tee}}$$ instruction is like $$\href{../syntax/instructions.html#syntax-instr-variable}{\mathsf{local.set}}$$ but also returns its argument.

## Memory Instructions¶

Instructions in this group are concerned with linear memory.

\begin{split}\begin{array}{llcl} \def\mathdef1807#1{{}}\mathdef1807{memory immediate} & \href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} &::=& \{ \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{offset}}~\href{../syntax/values.html#syntax-int}{\mathit{u32}}, \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{align}}~\href{../syntax/values.html#syntax-int}{\mathit{u32}} \} \\ \def\mathdef1807#1{{}}\mathdef1807{instruction} & \href{../syntax/instructions.html#syntax-instr}{\mathit{instr}} &::=& \dots \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{load}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{f}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{load}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{store}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{f}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{store}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{load}}\mathsf{8\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{load}}\mathsf{16\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{i64.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{load}}\mathsf{32\_}\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{store}}\mathsf{8}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{store}}\mathsf{16}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{i64.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{store}}\mathsf{32}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory.size}} \\&&|& \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory.grow}} \\ \end{array}\end{split}

Memory is accessed with $$\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{load}}$$ and $$\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{store}}$$ instructions for the different value types. They all take a memory immediate $$\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}$$ 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 $$\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}$$ is then required to select appropriate behavior.

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 version of WebAssembly might provide memory instructions with 64 bit address ranges.

The $$\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory.size}}$$ instruction returns the current size of a memory. The $$\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory.grow}}$$ instruction grows memory by a given delta and returns the previous size, or $$-1$$ if enough memory cannot be allocated. Both instructions operate in units of page size.

Note

In the current version of WebAssembly, all memory instructions implicitly operate on memory index $$0$$. This restriction may be lifted in future versions.

## Atomic Memory Instructions¶

Instructions in this group are concerned with accessing linear memory atomically.

$\begin{split}\begin{array}{llcl} \def\mathdef1807#1{{}}\mathdef1807{atomic operator} & \href{../syntax/instructions.html#syntax-atop}{\mathit{atop}} &::=& \href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{add}} ~|~ \href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{sub}} ~|~ \href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{and}} ~|~ \href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{or}} ~|~ \href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{xor}} ~|~ \href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{xchg}} \\ \def\mathdef1807#1{{}}\mathdef1807{instruction} & \href{../syntax/instructions.html#syntax-instr}{\mathit{instr}} &::=& \dots \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.load}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.store}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.load}}\mathsf{8\_u}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.load}}\mathsf{16\_u}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{i64.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.load}}\mathsf{32\_u}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.store}}\mathsf{8}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.store}}\mathsf{16}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} ~|~ \mathsf{i64.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.store}}\mathsf{32}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}\mathsf{.}\href{../syntax/instructions.html#syntax-atop}{\mathit{atop}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}\mathsf{8.}\href{../syntax/instructions.html#syntax-atop}{\mathit{atop}}\mathsf{\_u}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}\mathsf{16.}\href{../syntax/instructions.html#syntax-atop}{\mathit{atop}}\mathsf{\_u}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i64.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}\mathsf{32.}\href{../syntax/instructions.html#syntax-atop}{\mathit{atop}}\mathsf{\_u}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{cmpxchg}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}\mathsf{8.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{cmpxchg}}\mathsf{\_u}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i}\mathit{nn}\mathsf{.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}\mathsf{16.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{cmpxchg}}\mathsf{\_u}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \mathsf{i64.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}\mathsf{32.}\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{cmpxchg}}\mathsf{\_u}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{memory.atomic.notify}}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\&&|& \href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{memory.atomic.wait}}\mathit{nn}~\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}} \\ \end{array}\end{split}$

Memory is accessed atomically using the $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.load}}$$, $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.store}}$$, and $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}$$ instructions. All instructions take a memory immediate $$\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}$$, just like their non-atomic equivalents. Unlike non-atomic memory access instructions, only integer value types can be used. Also unlike non-atomic memory access instructions, there are no sign extension modes; atomic memory accesses are always zero-extending.

The $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{atomic.rmw}}$$ instructions are read-modify-write instructions. They each have an atomic operator, which specifies how memory will be modified. Each instruction returns the value read from memory before modification. The $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{xchg}}$$ operator doesn’t use the read value, but instead stores its argument unmodified. The $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{cmpxchg}}$$ operator is similar, but only performs this action conditionally, if the read value is equal to a provided comparison argument. All other atomic operators have the same behavior as the binary operator of the same name.

The $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{memory.atomic.wait}}$$ and $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{memory.atomic.notify}}$$ instructions provide primitive synchronization between threads. The $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{memory.atomic.wait}}$$ instructions atomically load a value from the calculated effective address and compare it to an expected value. If they are equal, the thread is then suspended until a given timeout expires or another thread wakes it. The $$\href{../syntax/instructions.html#syntax-instr-atomic-memory}{\mathsf{memory.atomic.notify}}$$ instruction wakes threads that are waiting on a given address, up to a given maximum.

## Control Instructions¶

Instructions in this group affect the flow of control.

$\begin{split}\begin{array}{llcl} \def\mathdef1807#1{{}}\mathdef1807{block type} & \href{../syntax/instructions.html#syntax-blocktype}{\mathit{blocktype}} &::=& \href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}} ~|~ \href{../syntax/types.html#syntax-valtype}{\mathit{valtype}}^? \\ \def\mathdef1807#1{{}}\mathdef1807{instruction} & \href{../syntax/instructions.html#syntax-instr}{\mathit{instr}} &::=& \dots \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{nop}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{unreachable}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{block}}~\href{../syntax/instructions.html#syntax-blocktype}{\mathit{blocktype}}~\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}^\ast~\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{end}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{loop}}~\href{../syntax/instructions.html#syntax-blocktype}{\mathit{blocktype}}~\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}^\ast~\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{end}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{if}}~\href{../syntax/instructions.html#syntax-blocktype}{\mathit{blocktype}}~\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}^\ast~\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{else}}~\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}^\ast~\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{end}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br}}~\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br\_if}}~\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br\_table}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}})~\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{return}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{call}}~\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}} \\&&|& \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{call\_indirect}}~\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}} \\ \end{array}\end{split}$

The $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{nop}}$$ instruction does nothing.

The $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{unreachable}}$$ instruction causes an unconditional trap.

The $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{block}}$$, $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{loop}}$$ and $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{if}}$$ instructions are structured instructions. They bracket nested sequences of instructions, called blocks, terminated with, or separated by, $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{end}}$$ or $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{else}}$$ 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 $$[] \href{../syntax/types.html#syntax-functype}{\rightarrow} [\href{../syntax/types.html#syntax-valtype}{\mathit{valtype}}^?]$$.

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 $$0$$ 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 $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{block}}$$ or $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{if}}$$ it is a forward jump, resuming execution after the matching $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{end}}$$. In case of $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{loop}}$$ it is a backward jump to the beginning of the loop.

Note

This enforces structured control flow. Intuitively, a branch targeting a $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{block}}$$ or $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{if}}$$ behaves like a $$\mathsf{break}$$ statement in most C-like languages, while a branch targeting a $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{loop}}$$ behaves like a $$\mathsf{continue}$$ statement.

Branch instructions come in several flavors: $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br}}$$ performs an unconditional branch, $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br\_if}}$$ performs a conditional branch, and $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br\_table}}$$ 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 $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{return}}$$ 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 $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{call}}$$ instruction invokes another function, consuming the necessary arguments from the stack and returning the result values of the call. The $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{call\_indirect}}$$ instruction calls a function indirectly through an operand indexing into a table. Since tables may contain function elements of heterogeneous type $$\href{../syntax/types.html#syntax-elemtype}{\mathsf{funcref}}$$, the callee is dynamically checked against the function type indexed by the instruction’s immediate, and the call aborted with a trap if it does not match.

Note

In the current version of WebAssembly, $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{call\_indirect}}$$ implicitly operates on table index $$0$$. This restriction may be lifted in future versions.

## Expressions¶

Function bodies, initialization values for globals, and offsets of element or data segments are given as expressions, which are sequences of instructions terminated by an $$\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{end}}$$ marker.

$\begin{split}\begin{array}{llll} \def\mathdef1807#1{{}}\mathdef1807{expression} & \href{../syntax/instructions.html#syntax-expr}{\mathit{expr}} &::=& \href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}^\ast~\href{../syntax/instructions.html#syntax-instr-control}{\mathsf{end}} \\ \end{array}\end{split}$

In some places, validation restricts expressions to be constant, which limits the set of allowable instructions.