Instructions¶
WebAssembly code consists of sequences ofinstructions.Its computational model is based on astack machine in that instructions manipulate values on an implicitoperand stack,consuming (popping) argument values and producing or returning (pushing) result values.
In addition to dynamic operands from the stack, some instructions also have staticimmediate arguments,typicallyindices or type annotations,which are part of the instruction itself.
Some instructions arestructured in that they contain nested sequences of instructions.
The following sections group instructions into a number of different categories.
The syntax of instruction is furtherextended with additional forms for the purpose of specifyingexecution.
Parametric Instructions¶
Instructions in this group can operate on operands of anyvalue type.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}} & ::= & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{nop}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{unreachable}} \\& & | & \href{../syntax/instructions.html#syntax-instr-parametric}{\mathsf{drop}} \\& & | & \href{../syntax/instructions.html#syntax-instr-parametric}{\mathsf{select}}~{({{\href{../syntax/types.html#syntax-valtype}{\mathit{valtype}}}^\ast})^?} \\\end{array}\end{split}\]
The\(\mathsf{nop}\) instruction does nothing.
The\(\mathsf{unreachable}\) instruction causes an unconditionaltrap.
The\(\mathsf{drop}\) instruction simply throws away a single operand.
The\(\mathsf{select}\) instruction selects one of its first two operands based on whether its third operand is zero or not.It may include avalue type determining the type of these operands.If missing, the operands must be ofnumeric orvector type.
Note
In future versions of WebAssembly, the type annotation on\(\mathsf{select}\) may allow for more than a single value being selected at the same time.
Control Instructions¶
Instructions in this group affect the flow of control.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}} & ::= & \dots \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{block}}~{\href{../syntax/types.html#syntax-blocktype}{\mathit{blocktype}}}~{{\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}}^\ast} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{loop}}~{\href{../syntax/types.html#syntax-blocktype}{\mathit{blocktype}}}~{{\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}}^\ast} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{if}}~{\href{../syntax/types.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{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/modules.html#syntax-labelidx}{\mathit{labelidx}}}^\ast}~{\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br\_on\_null}}~{\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br\_on\_non\_null}}~{\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br\_on\_cast}}~{\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}}~{\href{../syntax/types.html#syntax-reftype}{\mathit{reftype}}}~{\href{../syntax/types.html#syntax-reftype}{\mathit{reftype}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{br\_on\_cast\_fail}}~{\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}}~{\href{../syntax/types.html#syntax-reftype}{\mathit{reftype}}}~{\href{../syntax/types.html#syntax-reftype}{\mathit{reftype}}} \\& & | & \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\_ref}}~{\href{../syntax/types.html#syntax-typeuse}{\mathit{typeuse}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{call\_indirect}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}}~{\href{../syntax/types.html#syntax-typeuse}{\mathit{typeuse}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{return}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{return\_call}}~{\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{return\_call\_ref}}~{\href{../syntax/types.html#syntax-typeuse}{\mathit{typeuse}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{return\_call\_indirect}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}}~{\href{../syntax/types.html#syntax-typeuse}{\mathit{typeuse}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{throw}}~{\href{../syntax/modules.html#syntax-tagidx}{\mathit{tagidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{throw\_ref}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{try\_table}}~{\href{../syntax/types.html#syntax-blocktype}{\mathit{blocktype}}}~{\href{../syntax/conventions.html#syntax-list}{\mathit{list}}}({\href{../syntax/instructions.html#syntax-catch}{\mathit{catch}}})~{{\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}}^\ast} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-catch}{\mathit{catch}}} & ::= & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{catch}}~{\href{../syntax/modules.html#syntax-tagidx}{\mathit{tagidx}}}~{\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{catch\_ref}}~{\href{../syntax/modules.html#syntax-tagidx}{\mathit{tagidx}}}~{\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{catch\_all}}~{\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-control}{\mathsf{catch\_all\_ref}}~{\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}} \\\end{array}\end{split}\]
The\(\mathsf{block}\),\(\mathsf{loop}\),\(\mathsf{if}\) and\(\mathsf{try\_table}\) instructions arestructured instructions.They bracket nested sequences of instructions, calledblocks.As the grammar prescribes, they must be well-nested.
A structured instruction can consumeinput and produceoutput on the operand stack according to its annotatedblock type.
Each structured control instruction introduces an implicitlabel.Labels are targets for branch instructions that reference them withlabel indices.Unlike with otherindex 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 fromwithin 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\(\mathsf{block}\) or\(\mathsf{if}\) it is aforward jump,resuming execution after the end of the block.In case of\(\mathsf{loop}\) it is abackward jump to the beginning of the loop.
Note
This enforcesstructured control flow.Intuitively, a branch targeting a\(\mathsf{block}\) or\(\mathsf{if}\) behaves like a\(\mathsf{break}\) statement in most C-like languages,while a branch targeting a\(\mathsf{loop}\) behaves like a\(\mathsf{continue}\) statement.
Branch instructions come in several flavors:\(\mathsf{br}\) performs an unconditional branch,\(\mathsf{br\_if}\) performs a conditional branch,and\(\mathsf{br\_table}\) performs an indirect branch through an operand indexing into the label list that is an immediate to the instruction, or to a default target if the operand is out of bounds.The\(\mathsf{br\_on\_null}\) and\(\mathsf{br\_on\_non\_null}\) instructions check whether a reference operand isnull and branch if that is the case or not the case, respectively.Similarly,\(\mathsf{br\_on\_cast}\) and\(\mathsf{br\_on\_cast\_fail}\) attempt a downcast on a reference operand and branch if that succeeds, or fails, respectively.
The\(\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 branchunwinds 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\(\mathsf{call}\) instruction invokes anotherfunction, consuming the necessary arguments from the stack and returning the result values of the call.The\(\mathsf{call\_ref}\) instruction invokes a function indirectly through afunction reference operand.The\(\mathsf{call\_indirect}\) instruction calls a function indirectly through an operand indexing into atable that is denoted by atable index and must containfunction references.Since it may contain functions of heterogeneous type,the callee is dynamically checked against thefunction type indexed by the instruction’s second immediate, and the call is aborted with atrap if it does not match.
The\(\mathsf{return\_call}\),\(\mathsf{return\_call\_ref}\), and\(\mathsf{return\_call\_indirect}\) instructions aretail-call variants of the previous ones.That is, they first return from the current function before actually performing the respective call.It is guaranteed that no sequence of nested calls using only these instructions can cause resource exhaustion due to hitting animplementation’s limit on the number of active calls.
The instructions\(\mathsf{throw}\),\(\mathsf{throw\_ref}\), and\(\mathsf{try\_table}\) are concerned withexceptions.The\(\mathsf{throw}\) and\(\mathsf{throw\_ref}\) instructions raise and reraise an exception, respectively, and transfers control to the innermost enclosing exception handler that has a matching catch clause.The\(\mathsf{try\_table}\) instruction installs an exceptionhandler that handles exceptions as specified by its catch clauses.
Variable Instructions¶
Variable instructions are concerned with access tolocal orglobal variables.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\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 respective variables.The\(\mathsf{local{.}tee}\) instruction is like\(\mathsf{local{.}set}\) but also returns its argument.
Table Instructions¶
Instructions in this group are concerned with tablestable.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}} & ::= & \dots \\& & | & \href{../syntax/instructions.html#syntax-instr-table}{\mathsf{table{.}get}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-table}{\mathsf{table{.}set}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-table}{\mathsf{table{.}size}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-table}{\mathsf{table{.}grow}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-table}{\mathsf{table{.}fill}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-table}{\mathsf{table{.}copy}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-table}{\mathsf{table{.}init}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}}~{\href{../syntax/modules.html#syntax-elemidx}{\mathit{elemidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-table}{\mathsf{elem{.}drop}}~{\href{../syntax/modules.html#syntax-elemidx}{\mathit{elemidx}}} \\\end{array}\end{split}\]
The\(\mathsf{table{.}get}\) and\(\mathsf{table{.}set}\) instructions load or store an element in a table, respectively.
The\(\mathsf{table{.}size}\) instruction returns the current size of a table.The\(\mathsf{table{.}grow}\) instruction grows table by a given delta and returns the previous size, or\({-1}\) if enough space cannot be allocated.It also takes an initialization value for the newly allocated entries.
The\(\mathsf{table{.}fill}\) instruction sets all entries in a range to a given value.The\(\mathsf{table{.}copy}\) instruction copies elements from a source table region to a possibly overlapping destination region; the first index denotes the destination.The\(\mathsf{table{.}init}\) instruction copies elements from apassive element segment into a table.
The\(\mathsf{elem{.}drop}\) 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.
Note
An additional instruction that accesses a table is thecontrol instruction\(\mathsf{call\_indirect}\).
Memory Instructions¶
Instructions in this group are concerned with linearmemory.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}} & ::= & \{ \begin{array}[t]{@{}l@{}l@{}}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{align}}~{\href{../syntax/values.html#syntax-int}{\mathit{u\scriptstyle\kern-0.1em32}}} , \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{offset}}~{\href{../syntax/values.html#syntax-int}{\mathit{u\scriptstyle\kern-0.1em64}}} \} \\\end{array} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-loadop}{\mathit{loadop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & {{\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ {\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}} < N \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-storeop}{\mathit{storeop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & {\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}} & \quad \mbox{if}~ {\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}} < N \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vloadop}{\mathit{vloadop}}}}_{{\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}}} & ::= & {{\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ {\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}} \cdot M = {|{\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}}|} / 2 \\& & | & {{\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{splat}}} \\& & | & {{\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{zero}}} & \quad \mbox{if}~ {\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}} \geq \mathsf{{\scriptstyle 32}} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}} & ::= & \dots \\& & | & {{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{load}}}{{{{\href{../syntax/instructions.html#syntax-loadop}{\mathit{loadop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}}^?}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}}~{\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}} \\& & | & {{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{store}}}{{{{\href{../syntax/instructions.html#syntax-storeop}{\mathit{storeop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}}^?}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}}~{\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}} \\& & | & {{\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}}{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{load}}}{{{{\href{../syntax/instructions.html#syntax-vloadop}{\mathit{vloadop}}}}_{{\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}}}^?}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}}~{\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}} \\& & | & {{\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}}{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{load}}}{{\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{lane}}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}}~{\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}}~{\href{../syntax/instructions.html#syntax-laneidx}{\mathit{laneidx}}} \\& & | & {\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}}{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{store}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}}~{\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}} \\& & | & {{\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}}{.}\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{store}}}{{\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{lane}}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}}~{\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}}~{\href{../syntax/instructions.html#syntax-laneidx}{\mathit{laneidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory{.}size}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory{.}grow}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory{.}fill}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory{.}copy}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory{.}init}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}}~{\href{../syntax/modules.html#syntax-dataidx}{\mathit{dataidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{data{.}drop}}~{\href{../syntax/modules.html#syntax-dataidx}{\mathit{dataidx}}} \\\end{array}\end{split}\]
Memory is accessed with\(\mathsf{load}\) and\(\mathsf{store}\) instructions for the differentnumber types andvector types.They all take amemory index and amemory argument\({\href{../syntax/instructions.html#syntax-memarg}{\mathit{memarg}}}\) that contains an addressoffset and the expectedalignment (expressed as the exponent of a power of 2).
Integer loads and stores can optionally specify astorage size\({\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}}\) that is smaller than thebit 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.
Vector loads can specify a shape that is half thebit width of\(\mathsf{v{\scriptstyle 128}}\). Each lane is half its usual size, and the sign extension mode\({\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}\) then specifies how the smaller lane is extended to the larger lane.Alternatively, vector loads can perform asplat, 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 or 65-biteffective address that is the zero-based index at which the memory is accessed.All values are read and written inlittle endian byte order.Atrap results if any of the accessed memory bytes lies outside the address range implied by the memory’s current size.
The\(\mathsf{memory{.}size}\) instruction returns the current size of a memory.The\(\mathsf{memory{.}grow}\) instruction grows a memory by a given delta and returns the previous size, or\({-1}\) if enough memory cannot be allocated.Both instructions operate in units ofpage size.
The\(\mathsf{memory{.}fill}\) instruction sets all values in a region of memory to a given byte.The\(\mathsf{memory{.}copy}\) instruction copies data from a source memory region to a possibly overlapping destination region in another or the same memory; the first index denotes the destination.The\(\mathsf{memory{.}init}\) instruction copies data from apassive data segment into a memory.
The\(\mathsf{data{.}drop}\) 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.
Reference Instructions¶
Instructions in this group are concerned with accessingreferences.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}} & ::= & \dots \\& & | & \href{../syntax/instructions.html#syntax-instr-ref}{\mathsf{ref{.}func}}~{\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-ref}{\mathsf{ref{.}null}}~{\href{../syntax/types.html#syntax-heaptype}{\mathit{heaptype}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-ref}{\mathsf{ref{.}is\_null}} \\& & | & \href{../syntax/instructions.html#syntax-instr-ref}{\mathsf{ref{.}as\_non\_null}} \\& & | & \href{../syntax/instructions.html#syntax-instr-ref}{\mathsf{ref{.}eq}} \\& & | & \href{../syntax/instructions.html#syntax-instr-ref}{\mathsf{ref{.}test}}~{\href{../syntax/types.html#syntax-reftype}{\mathit{reftype}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-ref}{\mathsf{ref{.}cast}}~{\href{../syntax/types.html#syntax-reftype}{\mathit{reftype}}} \\\end{array}\end{split}\]
The\(\mathsf{ref{.}null}\) and\(\mathsf{ref{.}func}\) instructions produce anull reference or a reference to a given function, respectively.
The instruction\(\mathsf{ref{.}is\_null}\) checks for null,while\(\mathsf{ref{.}as\_non\_null}\) converts anullable to a non-null one, andtraps if it encounters null.
The\(\mathsf{ref{.}eq}\) compares two references.
The instructions\(\mathsf{ref{.}test}\) and\(\mathsf{ref{.}cast}\) test thedynamic type of a reference operand.The former merely returns the result of the test,while the latter performs a downcast andtraps if the operand’s type does not match.
Note
The\(\mathsf{br\_on\_null}\) and\(\mathsf{br\_on\_non\_null}\) instructions provide versions of\(\mathsf{ref{.}as\_null}\) that branch depending on the success of failure of a null test instead of trapping.Similarly, the\(\mathsf{br\_on\_cast}\) and\(\mathsf{br\_on\_cast\_fail}\) instructions provides versions of\(\mathsf{ref{.}cast}\) that branch depending on the success of the downcast instead of trapping.
An additional instruction operating on function references is thecontrol instruction\(\mathsf{call\_ref}\).
Aggregate Instructions¶
Instructions in this group are concerned with creating and accessingreferences toaggregate types.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}} & ::= & \dots \\& & | & \href{../syntax/instructions.html#syntax-instr-struct}{\mathsf{struct{.}new}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-struct}{\mathsf{struct{.}new\_default}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-struct}{\mathsf{struct{.}get}}}{\mathsf{\_}}{{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}^?}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}}~{\href{../syntax/values.html#syntax-int}{\mathit{u\scriptstyle\kern-0.1em32}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-struct}{\mathsf{struct{.}set}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}}~{\href{../syntax/values.html#syntax-int}{\mathit{u\scriptstyle\kern-0.1em32}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}new}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}new\_default}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}new\_fixed}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}}~{\href{../syntax/values.html#syntax-int}{\mathit{u\scriptstyle\kern-0.1em32}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}new\_data}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}}~{\href{../syntax/modules.html#syntax-dataidx}{\mathit{dataidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}new\_elem}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}}~{\href{../syntax/modules.html#syntax-elemidx}{\mathit{elemidx}}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}get}}}{\mathsf{\_}}{{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}^?}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}set}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}len}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}fill}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}copy}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}init\_data}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}}~{\href{../syntax/modules.html#syntax-dataidx}{\mathit{dataidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-array}{\mathsf{array{.}init\_elem}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}}~{\href{../syntax/modules.html#syntax-elemidx}{\mathit{elemidx}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-i31}{\mathsf{ref{.}i\scriptstyle31}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-i31}{\mathsf{i{\scriptstyle31}{.}get}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-extern}{\mathsf{extern{.}convert\_any}} \\& & | & \href{../syntax/instructions.html#syntax-instr-extern}{\mathsf{any{.}convert\_extern}} \\\end{array}\end{split}\]
The instructions\(\mathsf{struct{.}new}\) and\(\mathsf{struct{.}new\_default}\) allocate a newstructure, initializing them either with operands or with default values.The remaining instructions on structs access individual fields,allowing for different sign extension modes in the case ofpacked storage types.
Similarly,arrays can be allocated either with an explicit initialization operand or a default value.Furthermore,\(\mathsf{array{.}new\_fixed}\) allocates an array with statically fixed size,and\(\mathsf{array{.}new\_data}\) and\(\mathsf{array{.}new\_elem}\) allocate an array and initialize it from adata orelement segment, respectively.The instructions\(\mathsf{array{.}get}\),\(\mathsf{array{.}get}~{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}\), and\(\mathsf{array{.}set}\) access individual slots,again allowing for different sign extension modes in the case of apacked storage type;\(\mathsf{array{.}len}\) produces the length of an array;\(\mathsf{array{.}fill}\) fills a specified slice of an array with a given value and\(\mathsf{array{.}copy}\),\(\mathsf{array{.}init\_data}\), and\(\mathsf{array{.}init\_elem}\) copy elements to a specified slice of an array from a given array, data segment, or element segment, respectively.
The instructions\(\mathsf{ref{.}i{\scriptstyle 31}}\) and\(\mathsf{i{\scriptstyle 31}{.}get}~{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}\) convert between type\(\mathsf{i{\scriptstyle 32}}\) and an unboxedscalar.
The instructions\(\mathsf{any{.}convert\_extern}\) and\(\mathsf{extern{.}convert\_any}\) allow lossless conversion between references represented as type\((\href{../syntax/types.html#syntax-reftype}{\mathsf{ref}}~\href{../syntax/types.html#syntax-reftype}{\mathsf{null}}~\href{../syntax/types.html#syntax-heaptype}{\mathsf{extern}})\) and as\((\href{../syntax/types.html#syntax-reftype}{\mathsf{ref}}~\href{../syntax/types.html#syntax-reftype}{\mathsf{null}}~\href{../syntax/types.html#syntax-heaptype}{\mathsf{any}})\).
Numeric Instructions¶
Numeric instructions provide basic operations over numericvalues of specifictype.These operations closely match respective operations available in hardware.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}} & ::= & \mathsf{{\scriptstyle 8}} ~~|~~ \mathsf{{\scriptstyle 16}} ~~|~~ \mathsf{{\scriptstyle 32}} ~~|~~ \mathsf{{\scriptstyle 64}} \\& {\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}} & ::= & \href{../syntax/instructions.html#syntax-sx}{\mathsf{u}} ~~|~~ \href{../syntax/instructions.html#syntax-sx}{\mathsf{s}} \\[0.8ex]& {{\href{../exec/runtime.html#syntax-num}{\mathit{num}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & {{\href{../syntax/values.html#syntax-int}{\mathit{i}\kern-0.1em}}}{N} \\& {{\href{../exec/runtime.html#syntax-num}{\mathit{num}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & {{\href{../syntax/values.html#syntax-float}{\mathit{f}\kern-0.15em}}}{N} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}} & ::= & \dots \\& & | & {\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{const}}~{{\href{../exec/runtime.html#syntax-num}{\mathit{num}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}} \\& & | & {\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}} {.} {{\href{../syntax/instructions.html#syntax-unop}{\mathit{unop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}} \\& & | & {\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}} {.} {{\href{../syntax/instructions.html#syntax-binop}{\mathit{binop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}} \\& & | & {\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}} {.} {{\href{../syntax/instructions.html#syntax-testop}{\mathit{testop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}} \\& & | & {\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}} {.} {{\href{../syntax/instructions.html#syntax-relop}{\mathit{relop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}} \\& & | & {\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}_1 {.} {{{\href{../syntax/instructions.html#syntax-cvtop}{\mathit{cvtop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}_2, {\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}_1}}{\mathsf{\_}}{{\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}}_2} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-unop}{\mathit{unop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{clz}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{ctz}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{popcnt}} ~~|~~ {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{extend}}}{{\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-sx}{\mathsf{s}}} & \quad \mbox{if}~ {\href{../syntax/instructions.html#syntax-sz}{\mathit{sz}}} < N \\& {{\href{../syntax/instructions.html#syntax-unop}{\mathit{unop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{abs}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{neg}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{sqrt}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{ceil}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{floor}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{trunc}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{nearest}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-binop}{\mathit{binop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{add}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{sub}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{mul}} ~~|~~ {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{div}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} ~~|~~ {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{rem}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{and}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{or}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{xor}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{shl}} ~~|~~ {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{shr}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{rotl}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{rotr}} \\& {{\href{../syntax/instructions.html#syntax-binop}{\mathit{binop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{add}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{sub}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{mul}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{div}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{min}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{max}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{copysign}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-testop}{\mathit{testop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{eqz}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-relop}{\mathit{relop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{eq}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{ne}} ~~|~~ {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{lt}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} ~~|~~ {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{gt}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} ~~|~~ {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{le}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} ~~|~~ {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{ge}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} \\& {{\href{../syntax/instructions.html#syntax-relop}{\mathit{relop}}}}_{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}} & ::= & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{eq}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{ne}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{lt}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{gt}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{le}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{ge}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-cvtop}{\mathit{cvtop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1, {{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2} & ::= & {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{extend}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N_1 < N_2 \\& & | & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{wrap}} & \quad \mbox{if}~ N_1 > N_2 \\& {{\href{../syntax/instructions.html#syntax-cvtop}{\mathit{cvtop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1, {{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2} & ::= & {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{convert}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{reinterpret}} & \quad \mbox{if}~ N_1 = N_2 \\& {{\href{../syntax/instructions.html#syntax-cvtop}{\mathit{cvtop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1, {{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2} & ::= & {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{trunc}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{trunc\_sat}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} \\& & | & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{reinterpret}} & \quad \mbox{if}~ N_1 = N_2 \\& {{\href{../syntax/instructions.html#syntax-cvtop}{\mathit{cvtop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1, {{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2} & ::= & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{promote}} & \quad \mbox{if}~ N_1 < N_2 \\& & | & \href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{demote}} & \quad \mbox{if}~ N_1 > N_2 \\\end{array}\end{split}\]
Numeric instructions are divided bynumber 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 beinterpreted asunsigned orsigned 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.
Vector Instructions¶
Vector instructions (also known asSIMD instructions,single instruction multiple data) provide basic operations overvalues ofvector type.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-lanetype}{\mathit{lanetype}}} & ::= & {\href{../syntax/types.html#syntax-numtype}{\mathit{numtype}}} ~~|~~ {\href{../syntax/types.html#syntax-packtype}{\mathit{packtype}}} \\& {\href{../syntax/instructions.html#syntax-dim}{\mathit{dim}}} & ::= & \mathsf{{\scriptstyle 1}} ~~|~~ \mathsf{{\scriptstyle 2}} ~~|~~ \mathsf{{\scriptstyle 4}} ~~|~~ \mathsf{{\scriptstyle 8}} ~~|~~ \mathsf{{\scriptstyle 16}} \\& {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}} & ::= & {{\href{../syntax/instructions.html#syntax-lanetype}{\mathit{lanetype}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{{\href{../syntax/instructions.html#syntax-dim}{\mathit{dim}}}} & \quad \mbox{if}~ {|{\href{../syntax/instructions.html#syntax-lanetype}{\mathit{lanetype}}}|} \cdot {\href{../syntax/instructions.html#syntax-dim}{\mathit{dim}}} = 128 \\& {\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}} & ::= & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}} & \quad \mbox{if}~ {\href{../syntax/instructions.html#aux-lanetype}{\mathrm{lanetype}}}({\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}) = {\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}} \\& {\href{../syntax/instructions.html#syntax-shape}{\mathit{bshape}}} & ::= & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}} & \quad \mbox{if}~ {\href{../syntax/instructions.html#aux-lanetype}{\mathrm{lanetype}}}({\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}) = \href{../syntax/types.html#syntax-storagetype}{\mathsf{i\scriptstyle8}} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-half}{\mathit{half}}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{low}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{high}} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-zero}{\mathit{zero}}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{zero}} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-laneidx}{\mathit{laneidx}}} & ::= & {\href{../syntax/values.html#syntax-int}{\mathit{u\scriptstyle\kern-0.1em8}}} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}} & ::= & \dots \\& & | & {\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}}{.}\href{../syntax/instructions.html#syntax-instr-numeric}{\mathsf{const}}~{{\href{../exec/runtime.html#syntax-vec}{\mathit{vec}}}}_{{\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}}} \\& & | & {\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}} {.} {\href{../syntax/instructions.html#syntax-vvunop}{\mathit{vvunop}}} \\& & | & {\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}} {.} {\href{../syntax/instructions.html#syntax-vvbinop}{\mathit{vvbinop}}} \\& & | & {\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}} {.} {\href{../syntax/instructions.html#syntax-vvternop}{\mathit{vvternop}}} \\& & | & {\href{../syntax/types.html#syntax-vectype}{\mathit{vectype}}} {.} {\href{../syntax/instructions.html#syntax-vvtestop}{\mathit{vvtestop}}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}} {.} {{\href{../syntax/instructions.html#syntax-vunop}{\mathit{vunop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}} {.} {{\href{../syntax/instructions.html#syntax-vbinop}{\mathit{vbinop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}} {.} {{\href{../syntax/instructions.html#syntax-vternop}{\mathit{vternop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}} {.} {{\href{../syntax/instructions.html#syntax-vrelop}{\mathit{vtestop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}} {.} {{\href{../syntax/instructions.html#syntax-vrelop}{\mathit{vrelop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}} {.} {{\href{../syntax/instructions.html#syntax-vshiftop}{\mathit{vshiftop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}{.}\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{bitmask}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{bshape}}} {.} {{\href{../syntax/instructions.html#syntax-vswizzlop}{\mathit{vswizzlop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{bshape}}}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{bshape}}}{.}\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{shuffle}}~{{\href{../syntax/instructions.html#syntax-laneidx}{\mathit{laneidx}}}^\ast} & \quad \mbox{if}~ {|{{\href{../syntax/instructions.html#syntax-laneidx}{\mathit{laneidx}}}^\ast}|} = {\href{../syntax/instructions.html#aux-dim}{\mathrm{dim}}}({\href{../syntax/instructions.html#syntax-shape}{\mathit{bshape}}}) \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_1 {.} {{{\href{../syntax/instructions.html#syntax-vextunop}{\mathit{vextunop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_2, {\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_1}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_2} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_1 {.} {{{\href{../syntax/instructions.html#syntax-vextbinop}{\mathit{vextbinop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_2, {\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_1}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_2} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_1 {.} {{{\href{../syntax/instructions.html#syntax-vextternop}{\mathit{vextternop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_2, {\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_1}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_2} \\& & | & {{\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_1{.}\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{narrow}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_2}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ {|{\href{../syntax/instructions.html#aux-lanetype}{\mathrm{lanetype}}}({\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_2)|} = 2 \cdot {|{\href{../syntax/instructions.html#aux-lanetype}{\mathrm{lanetype}}}({\href{../syntax/instructions.html#syntax-shape}{\mathit{ishape}}}_1)|} \leq \mathsf{{\scriptstyle 32}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}_1 {.} {{{\href{../syntax/instructions.html#syntax-vcvtop}{\mathit{vcvtop}}}}_{{\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}_2, {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}_1}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}_2} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}{.}\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{splat}} \\& & | & {{\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}{.}\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{extract\_lane}}}{\mathsf{\_}}{{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}^?}}~{\href{../syntax/instructions.html#syntax-laneidx}{\mathit{laneidx}}} & \quad \mbox{if}~ {{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}^?} = \epsilon \Leftrightarrow {\href{../syntax/instructions.html#aux-lanetype}{\mathrm{lanetype}}}({\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}) \in \href{../syntax/types.html#syntax-numtype}{\mathsf{i\scriptstyle32}}~\href{../syntax/types.html#syntax-numtype}{\mathsf{i\scriptstyle64}}~\href{../syntax/types.html#syntax-numtype}{\mathsf{f\scriptstyle32}}~\href{../syntax/types.html#syntax-numtype}{\mathsf{f\scriptstyle64}} \\& & | & {\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}}{.}\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{replace\_lane}}~{\href{../syntax/instructions.html#syntax-laneidx}{\mathit{laneidx}}} \\\end{array}\end{split}\]
Vector instructions have a naming convention involving ashape prefix thatdetermines how their operands will be interpreted,written\({t}{\mathsf{x}}{N}\), and consisting of alane type\(t\), a possiblypackednumeric type, and itsdimension\(N\), which denotes the number of lanes of that type.Operations are performed point-wise on the values of each lane.
Instructions prefixed with\(\mathsf{v{\scriptstyle 128}}\) do not involve a specific interpretation, and treat the\(\mathsf{v{\scriptstyle 128}}\) as either an\({\mathit{i{\kern-0.1em\scriptstyle 128}}}\) value or a vector of\(128\) individual bits.
Note
For example, the shape\({\href{../syntax/types.html#syntax-numtype}{\mathsf{i\scriptstyle32}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{\mathsf{{\scriptstyle 4}}}\) interprets the operandas four\({\mathit{i{\kern-0.1em\scriptstyle 32}}}\) values, packed into an\({\mathit{i{\kern-0.1em\scriptstyle 128}}}\).The bit width of the lane type\(t\) times\(N\) always is\(128\).
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-vvunop}{\mathit{vvunop}}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{not}} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-vvbinop}{\mathit{vvbinop}}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{and}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{andnot}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{or}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{xor}} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-vvternop}{\mathit{vvternop}}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{bitselect}} \\[0.8ex]& {\href{../syntax/instructions.html#syntax-vvtestop}{\mathit{vvtestop}}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{any\_true}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vunop}{\mathit{vunop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{abs}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{neg}} \\& & | & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{popcnt}} & \quad \mbox{if}~ N = \mathsf{{\scriptstyle 8}} \\& {{\href{../syntax/instructions.html#syntax-vunop}{\mathit{vunop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{abs}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{neg}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{sqrt}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{ceil}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{floor}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{trunc}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{nearest}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vbinop}{\mathit{vbinop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{add}} \\& & | & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{sub}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{add\_sat}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N \leq \mathsf{{\scriptstyle 16}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{sub\_sat}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N \leq \mathsf{{\scriptstyle 16}} \\& & | & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{mul}} & \quad \mbox{if}~ N \geq \mathsf{{\scriptstyle 16}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{avgr}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-sx}{\mathsf{u}}} & \quad \mbox{if}~ N \leq \mathsf{{\scriptstyle 16}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{q{\scriptstyle15}mulr\_sat}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-sx}{\mathsf{s}}} & \quad \mbox{if}~ N = \mathsf{{\scriptstyle 16}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_q15mulr}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-sx}{\mathsf{s}}} & \quad \mbox{if}~ N = \mathsf{{\scriptstyle 16}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{min}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N \leq \mathsf{{\scriptstyle 32}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{max}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N \leq \mathsf{{\scriptstyle 32}} \\& {{\href{../syntax/instructions.html#syntax-vbinop}{\mathit{vbinop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{add}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{sub}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{mul}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{div}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{min}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{max}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{pmin}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{pmax}} \\& & | & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_min}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_max}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vternop}{\mathit{vternop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_laneselect}} \\& {{\href{../syntax/instructions.html#syntax-vternop}{\mathit{vternop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_madd}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_nmadd}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vrelop}{\mathit{vtestop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{all\_true}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vrelop}{\mathit{vrelop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{eq}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{ne}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{lt}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N \neq \mathsf{{\scriptstyle 64}} \lor {\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}} = \href{../syntax/instructions.html#syntax-sx}{\mathsf{s}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{gt}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N \neq \mathsf{{\scriptstyle 64}} \lor {\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}} = \href{../syntax/instructions.html#syntax-sx}{\mathsf{s}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{le}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N \neq \mathsf{{\scriptstyle 64}} \lor {\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}} = \href{../syntax/instructions.html#syntax-sx}{\mathsf{s}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{ge}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N \neq \mathsf{{\scriptstyle 64}} \lor {\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}} = \href{../syntax/instructions.html#syntax-sx}{\mathsf{s}} \\& {{\href{../syntax/instructions.html#syntax-vrelop}{\mathit{vrelop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{eq}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{ne}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{lt}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{gt}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{le}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{ge}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vswizzlop}{\mathit{vswizzlop}}}}_{{\href{../syntax/types.html#syntax-storagetype}{\mathsf{i\scriptstyle8}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{swizzle}} ~~|~~ \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_swizzle}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vshiftop}{\mathit{vshiftop}}}}_{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M}} & ::= & \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{shl}} ~~|~~ {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{shr}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vextunop}{\mathit{vextunop}}}}_{{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_1}, {{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_2}} & ::= & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{extadd\_pairwise}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ 16 \leq 2 \cdot N_1 = N_2 \leq \mathsf{{\scriptstyle 32}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vextbinop}{\mathit{vextbinop}}}}_{{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_1}, {{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_2}} & ::= & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{extmul}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-half}{\mathit{half}}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ 2 \cdot N_1 = N_2 \geq \mathsf{{\scriptstyle 16}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{dot}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-sx}{\mathsf{s}}} & \quad \mbox{if}~ 2 \cdot N_1 = N_2 = \mathsf{{\scriptstyle 32}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_dot}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-sx}{\mathsf{s}}} & \quad \mbox{if}~ 2 \cdot N_1 = N_2 = \mathsf{{\scriptstyle 16}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vextternop}{\mathit{vextternop}}}}_{{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_1}, {{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_2}} & ::= & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_dot\_add}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-sx}{\mathsf{s}}} & \quad \mbox{if}~ 4 \cdot N_1 = N_2 = \mathsf{{\scriptstyle 32}} \\[0.8ex]& {{\href{../syntax/instructions.html#syntax-vcvtop}{\mathit{vcvtop}}}}_{{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_1}, {{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_2}} & ::= & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{extend}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-half}{\mathit{half}}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N_2 = 2 \cdot N_1 \\& {{\href{../syntax/instructions.html#syntax-vcvtop}{\mathit{vcvtop}}}}_{{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_1}, {{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_2}} & ::= & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{convert}}}{\mathsf{\_}}{{{\href{../syntax/instructions.html#syntax-half}{\mathit{half}}}^?}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}} & \quad \mbox{if}~ N_2 = N_1 = \mathsf{{\scriptstyle 32}} \land {{\href{../syntax/instructions.html#syntax-half}{\mathit{half}}}^?} = \epsilon \lor N_2 = 2 \cdot N_1 \land {{\href{../syntax/instructions.html#syntax-half}{\mathit{half}}}^?} = \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{low}} \\& {{\href{../syntax/instructions.html#syntax-vcvtop}{\mathit{vcvtop}}}}_{{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_1}, {{{\href{../syntax/types.html#syntax-numtype}{\mathsf{i}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_2}} & ::= & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{trunc\_sat}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}}{\mathsf{\_}}{{{\href{../syntax/instructions.html#syntax-zero}{\mathit{zero}}}^?}} & \quad \mbox{if}~ N_1 = N_2 = \mathsf{{\scriptstyle 32}} \land {{\href{../syntax/instructions.html#syntax-zero}{\mathit{zero}}}^?} = \epsilon \lor N_1 = 2 \cdot N_2 \land {{\href{../syntax/instructions.html#syntax-zero}{\mathit{zero}}}^?} = \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{zero}} \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{relaxed\_trunc}}}{\mathsf{\_}}{{\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}}{\mathsf{\_}}{{{\href{../syntax/instructions.html#syntax-zero}{\mathit{zero}}}^?}} & \quad \mbox{if}~ N_1 = N_2 = \mathsf{{\scriptstyle 32}} \land {{\href{../syntax/instructions.html#syntax-zero}{\mathit{zero}}}^?} = \epsilon \lor N_1 = 2 \cdot N_2 \land {{\href{../syntax/instructions.html#syntax-zero}{\mathit{zero}}}^?} = \href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{zero}} \\& {{\href{../syntax/instructions.html#syntax-vcvtop}{\mathit{vcvtop}}}}_{{{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_1}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_1}, {{{\href{../syntax/types.html#syntax-numtype}{\mathsf{f}}}{{\href{../syntax/types.html#syntax-numtype}{\scriptstyle\kern-0.1emN}}}}_2}{\href{../syntax/instructions.html#syntax-shape}{\mathsf{x}}}{M_2}} & ::= & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{demote}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{zero}}} & \quad \mbox{if}~ N_1 = 2 \cdot N_2 \\& & | & {\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{promote}}}{\mathsf{\_}}{\href{../syntax/instructions.html#syntax-instr-vec}{\mathsf{low}}} & \quad \mbox{if}~ 2 \cdot N_1 = N_2 \\\end{array}\end{split}\]
Vector instructions can be grouped into several subcategories:
Constants: return a static constant.
Unary Operations: consume one\(\mathsf{v{\scriptstyle 128}}\) operand and produce one\(\mathsf{v{\scriptstyle 128}}\) result.
Binary Operations: consume two\(\mathsf{v{\scriptstyle 128}}\) operands and produce one\(\mathsf{v{\scriptstyle 128}}\) result.
Ternary Operations: consume three\(\mathsf{v{\scriptstyle 128}}\) operands and produce one\(\mathsf{v{\scriptstyle 128}}\) result.
Tests: consume one\(\mathsf{v{\scriptstyle 128}}\) operand and produce a Boolean integer result.
Shifts: consume a\(\mathsf{v{\scriptstyle 128}}\) operand and an\(\mathsf{i{\scriptstyle 32}}\) operand, producing one\(\mathsf{v{\scriptstyle 128}}\) result.
Splats: consume a value of numeric type and produce a\(\mathsf{v{\scriptstyle 128}}\) result of a specified shape.
Extract lanes: consume a\(\mathsf{v{\scriptstyle 128}}\) operand and return the numeric value in a given lane.
Replace lanes: consume a\(\mathsf{v{\scriptstyle 128}}\) operand and a numeric value for a given lane, and produce a\(\mathsf{v{\scriptstyle 128}}\) result.
Some vector instructions have a signedness annotation\({\href{../syntax/instructions.html#syntax-sx}{\mathit{sx}}}\) which distinguishes whether the elements in the operands are to beinterpreted asunsigned orsigned 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.
Conventions¶
The function\({\href{../syntax/instructions.html#aux-lanetype}{\mathrm{lanetype}}}({\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}})\) extracts the lane type of a shape.
The function\({\href{../syntax/instructions.html#aux-dim}{\mathrm{dim}}}({\href{../syntax/instructions.html#syntax-shape}{\mathit{shape}}})\) extracts the dimension of a shape.
The function\({\href{../syntax/instructions.html#aux-zeroop}{\mathrm{zeroop}}}({\href{../syntax/instructions.html#syntax-vcvtop}{\mathit{vcvtop}}})\) extracts the\(\mathsf{zero}\) flag from a vector conversion operator, or returns\(\epsilon\) if it does not contain any.
The function\({\href{../syntax/instructions.html#aux-halfop}{\mathrm{halfop}}}({\href{../syntax/instructions.html#syntax-vcvtop}{\mathit{vcvtop}}})\) extracts the\({\href{../syntax/instructions.html#syntax-half}{\mathit{half}}}\) flag from a vector conversion operator, or returns\(\epsilon\) if it does not contain any.
Expressions¶
Function bodies, initialization values forglobals, elements and offsets ofelement segments, and offsets ofdata segments are given as expressions, which are sequences ofinstructions.
\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}}& {\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}}} & ::= & {{\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}}^\ast} \\\end{array}\end{split}\]
In some places, validationrestricts expressions to beconstant, which limits the set of allowable instructions.
