Expand description
Platform-specific intrinsics for the wasm32 platform.
This module provides intrinsics specific to the WebAssembly
architecture. Here you’ll find intrinsics specific to WebAssembly that
aren’t otherwise surfaced somewhere in a cross-platform abstraction of
std, and you’ll also find functions for leveraging WebAssembly
proposals such as atomics and simd.
Intrinsics in the wasm32 module are modeled after the WebAssembly
instructions that they represent. Most functions are named after the
instruction they intend to correspond to, and the arguments/results
correspond to the type signature of the instruction itself. Stable
WebAssembly instructions are documented online.
If a proposal is not yet stable in WebAssembly itself then the functions within this function may be unstable and require the nightly channel of Rust to use. As the proposal itself stabilizes the intrinsics in this module should stabilize as well.
See the module documentation for general information
about the arch module and platform intrinsics.
Atomics
The threads proposal for WebAssembly adds a number of
instructions for dealing with multithreaded programs. Most instructions
added in the atomics proposal are exposed in Rust through the
std::sync::atomic module. Some instructions, however, don’t have
direct equivalents in Rust so they’re exposed here instead.
Note that the instructions added in the atomics proposal can work in
either a context with a shared wasm memory and without. These intrinsics
are always available in the standard library, but you likely won’t be
able to use them too productively unless you recompile the standard
library (and all your code) with -Ctarget-feature=+atomics.
It’s also worth pointing out that multi-threaded WebAssembly and its
story in Rust is still in a somewhat “early days” phase as of the time
of this writing. Pieces should mostly work but it generally requires a
good deal of manual setup. At this time it’s not as simple as “just call
std::thread::spawn”, but it will hopefully get there one day!
SIMD
The simd proposal for WebAssembly added a new v128 type for a
128-bit SIMD register. It also added a large array of instructions to
operate on the v128 type to perform data processing. Using SIMD on
wasm is intended to be similar to as you would on x86_64, for example.
You’d write a function such as:
#[cfg(target_arch = "wasm32")]
#[target_feature(enable = "simd128")]
unsafe fn uses_simd() {
use std::arch::wasm32::*;
// ...
}RunUnlike x86_64, however, WebAssembly does not currently have dynamic
detection at runtime as to whether SIMD is supported (this is one of the
motivators for the conditional sections and feature
detection proposals, but that is still pretty early days). This means
that your binary will either have SIMD and can only run on engines
which support SIMD, or it will not have SIMD at all. For compatibility
the standard library itself does not use any SIMD internally.
Determining how best to ship your WebAssembly binary with SIMD is
largely left up to you as it can can be pretty nuanced depending on
your situation.
To enable SIMD support at compile time you need to do one of two things:
-
First you can annotate functions with
#[target_feature(enable = "simd128")]. This causes just that one function to have SIMD support available to it, and intrinsics will get inlined as usual in this situation. -
Second you can compile your program with
-Ctarget-feature=+simd128. This compilation flag blanket enables SIMD support for your entire compilation. Note that this does not include the standard library unless you recompile the standard library.
If you enable SIMD via either of these routes then you’ll have a WebAssembly binary that uses SIMD instructions, and you’ll need to ship that accordingly. Also note that if you call SIMD intrinsics but don’t enable SIMD via either of these mechanisms, you’ll still have SIMD generated in your program. This means to generate a binary without SIMD you’ll need to avoid both options above plus calling into any intrinsics in this module.
Structs
target_family="wasm"Functions
memory.atomic.notify instructionmemory.atomic.wait32 instructionmemory.atomic.wait64 instructiontarget_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128a < b ? b : atarget_family="wasm" and simd128b < a ? b : atarget_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128a < b ? b : atarget_family="wasm" and simd128b < a ? b : atarget_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i8::MAX.target_family="wasm" and simd128target_family="wasm" and simd128a and produce a scalar mask with
all bits concatenated.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128$a and $b specified in the 16 immediate operands.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i8::MIN.target_family="wasm" and simd128a specified in the second input vector s.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i16::MAX.target_family="wasm" and simd128target_family="wasm" and simd128a and produce a scalar mask with
all bits concatenated.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i8x16_shuffle, except operates as if the inputs were eight
16-bit integers, only taking 8 indices to shuffle.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i16::MIN.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128a and produce a scalar mask with
all bits concatenated.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i8x16_shuffle, except operates as if the inputs were four
32-bit integers, only taking 4 indices to shuffle.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128convertToIntegerTowardZero
function.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128a and produce a scalar mask with
all bits concatenated.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i8x16_shuffle, except operates as if the inputs were two
64-bit integers, only taking 2 indices to shuffle.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm"memory.grow instructiontarget_family="wasm"memory.size instructiontarget_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128u8::MAX.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128a and produce a scalar mask with
all bits concatenated.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128$a and $b specified in the 16 immediate operands.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128a specified in the second input vector s.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128u16::MAX.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128a and produce a scalar mask with
all bits concatenated.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i8x16_shuffle, except operates as if the inputs were eight
16-bit integers, only taking 8 indices to shuffle.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128a and produce a scalar mask with
all bits concatenated.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i8x16_shuffle, except operates as if the inputs were four
32-bit integers, only taking 4 indices to shuffle.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128convertToIntegerTowardZero
function.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128a and produce a scalar mask with
all bits concatenated.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128i8x16_shuffle, except operates as if the inputs were two
64-bit integers, only taking 2 indices to shuffle.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm"unreachable instruction, which causes an unconditional trap.target_family="wasm" and simd128target_family="wasm" and simd128a and the logical inverse of bits of b.target_family="wasm" and simd128true if any bit in a is set, or false otherwise.target_family="wasm" and simd128c to select bits from v1 when 1 and v2 when 0.target_family="wasm" and simd128v128 vector from the given heap address.target_family="wasm" and simd128m and sets lane L of v to that value.target_family="wasm" and simd128target_family="wasm" and simd128m and sets lane L of v to that value.target_family="wasm" and simd128target_family="wasm" and simd128m and sets lane L of v to that value.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128m and sets lane L of v to that value.target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128target_family="wasm" and simd128v128 vector to the given heap address.target_family="wasm" and simd128L of v into mtarget_family="wasm" and simd128L of v into mtarget_family="wasm" and simd128L of v into mtarget_family="wasm" and simd128L of v into mtarget_family="wasm" and simd128