From 6472aa49caf777b53f5d5eb9f14f3fb0b865cff7 Mon Sep 17 00:00:00 2001 From: dcode Date: Tue, 11 Apr 2023 14:02:13 +0200 Subject: [PATCH] Document relaxed SIMD feature --- src/compiler.md | 2 + src/stdlib/globals.md | 155 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 154 insertions(+), 3 deletions(-) diff --git a/src/compiler.md b/src/compiler.md index cd58bfcca..d5a9c11fb 100644 --- a/src/compiler.md +++ b/src/compiler.md @@ -107,6 +107,8 @@ There are several flags that enable or disable specific WebAssembly or compiler simd SIMD types and operations. reference-types Reference types and operations. gc Garbage collection (WIP). + stringref String reference types. + relaxed-simd Relaxed SIMD operations. --disable Disables WebAssembly features being enabled by default. diff --git a/src/stdlib/globals.md b/src/stdlib/globals.md index 2d4a1291f..04ea59a51 100644 --- a/src/stdlib/globals.md +++ b/src/stdlib/globals.md @@ -862,9 +862,9 @@ Likewise, these represent the [WebAssembly SIMD](https://github.com/WebAssembly/ Performs the bitwise `!a` operation on each lane. * ```ts - function v128.bitselect(a: v128, b: v128, mask: v128): v128 + function v128.bitselect(v1: v128, v2: v128, mask: v128): v128 ``` - Selects bits of either vector according to the specified mask. + Selects bits of either vector according to the specified mask. Selects from `v1` if the bit in `mask` is `1`, otherwise from `v2`. * ```ts function v128.any_true(a: v128): bool @@ -1279,7 +1279,7 @@ Likewise, these represent the [WebAssembly SIMD](https://github.com/WebAssembly/ * ```ts function v128.q15mulr_sat(a: v128, b: v128): v128 ``` -
Performs the line-wise saturating rounding multiplication in Q15 format. +
Performs the line-wise saturating rounding multiplication in Q15 format ((a[i] * b[i] + (1 << (Q - 1))) >> Q where Q=15). | T | Instruction |-----|------------- @@ -1348,6 +1348,155 @@ Likewise, these represent the [WebAssembly SIMD](https://github.com/WebAssembly/ ``` Initializes a 128-bit vector from two 64-bit float values. +#### Relaxed SIMD 🦄 + +The following instructions represent the [WebAssembly Relaxed SIMD](https://github.com/WebAssembly/relaxed-simd) specification. Must be enabled with `--enable relaxed-simd`. + +* ```ts + function v128.relaxed_swizzle(a: v128, s: v128): v128 + ``` + Selects 8-bit lanes from `a` using indices in `s`. Indices in the range \[0-15] select the i-th element of `a`. + + Unlike `v128.swizzle`, the result of an out of bounds index is implementation-defined, depending on hardware capabilities: Either `0` or `a[s[i]%16]`. + +* ```ts + function v128.relaxed_trunc(a: v128): v128 + ``` +
Truncates each lane of a vector from 32-bit floating point to a 32-bit signed or unsigned integer as indicated by T. + + | T | Instruction + |----------|------------- + | i32 | i32x4.relaxed_trunc_f32x4_s + | u32 | i32x4.relaxed_trunc_f32x4_u +
+ + Unlike `v128.trunc_sat`, the result of lanes out of bounds of the target type is implementation defined, depending on hardware capabilities: + - If the input lane contains `NaN`, the result is either `0` or the respective maximum integer value. + - If the input lane contains a value otherwise out of bounds of the target type, the result is either the saturatated result or maximum integer value. + +* ```ts + function v128.relaxed_trunc_zero(a: v128): v128 + ``` +
Truncates each lane of a vector from 64-bit floating point to a 32-bit signed or unsigned integer as indicated by T. Unused higher integer lanes of the result are initialized to zero. + + | T | Instruction + |----------|------------- + | i32 | i32x4.relaxed_trunc_f64x2_s_zero + | u32 | i32x4.relaxed_trunc_f64x2_u_zero +
+ + Unlike `v128.trunc_sat_zero`, the result of lanes out of bounds of the target type is implementation defined, depending on hardware capabilities: + - If the input lane contains `NaN`, the result is either `0` or the respective maximum integer value. + - If the input lane contains a value otherwise out of bounds of the target type, the result is either the saturatated result or maximum integer value. + +* ```ts + function v128.relaxed_madd(a: v128, b: v128, c: v128): v128 + ``` +
Performs the fused multiply-add operation (a * b + c) on 32- or 64-bit floating point lanes as indicated by T. + + | T | Instruction + |----------|------------- + | f32 | f32x4.relaxed_madd + | f64 | f64x2.relaxed_madd +
+ + The result is implementation defined, depending on hardware capabilities: + - Either `a * b` is rounded once and the final result rounded again, or + - The expression is evaluated with higher precision and only rounded once + +* ```ts + function v128.relaxed_nmadd(a: v128, b: v128, c: v128): v128 + ``` +
Performs the fused negative multiply-add operation (-(a * b) + c) on 32- or 64-bit floating point lanes as indicated by T. + + | T | Instruction + |----------|------------- + | f32 | f32x4.relaxed_nmadd + | f64 | f64x2.relaxed_nmadd +
+ + The result is implementation defined, depending on hardware capabilities: + - Either `a * b` is rounded once and the final result rounded again, or + - The expression is evaluated with higher precision and only rounded once + +* ```ts + function v128.relaxed_laneselect(a: v128, b: v128, m: v128): v128 + ``` +
Selects 8-, 16-, 32- or 64-bit integer lanes as indicated by T from a or b based on masks in m. + + | T | Instruction + |----------|------------- + | i8, u8 | i8x16.relaxed_laneselect + | i16, u16 | i16x8.relaxed_laneselect + | i32, u32 | i32x4.relaxed_laneselect + | i64, u64 | i64x2.relaxed_laneselect +
+ + Behaves like `v128.bitselect` if masks in `m` do have all bits either set (result is `a[i]`) or unset (result is `b[i]`). Otherwise the result is implementation-defined, depending on hardware capabilities: If the most significant bit of `m` is set, the result is either `bitselect(a[i], b[i], mask)` or `a[i]`, otherwise the result is `b[i]`. + +* ```ts + function v128.relaxed_min(a: v128, b: v128): v128 + ``` +
Computes the minimum of each 32- or 64-bit floating point lane as indicated by T. + + | T | Instruction + |----------|------------- + | f32 | f32x4.relaxed_min + | f64 | f64x2.relaxed_min +
+ + Unlike `v128.min`, the result is implementation-defined if either value is `NaN` or both are `-0.0` and `+0.0`, depending on hardware capabilities: Either `a[i]` or `b[i]`. + +* ```ts + function v128.relaxed_max(a: v128, b: v128): v128 + ``` +
Computes the maximum of each 32- or 64-bit floating point lane as indicated by T. + + | T | Instruction + |----------|------------- + | f32 | f32x4.relaxed_max + | f64 | f64x2.relaxed_max +
+ + Unlike `v128.max`, the result is implementation-defined if either value is `NaN` or both are `-0.0` and `+0.0`, depending on hardware capabilities: Either `a[i]` or `b[i]`. + +* ```ts + function v128.relaxed_q15mulr(a: v128, b: v128): v128 + ``` +
Performs the lane-wise rounding multiplication in Q15 format ((a[i] * b[i] + (1 << (Q - 1))) >> Q where Q=15). + + | T | Instruction + |----------|------------- + | i16 | i16x8.relaxed_q15mulr_s +
+ + Unlike `v128.q15mulr_sat`, the result is implementation-defined if both inputs are the minimum signed value: Either the minimum or maximum signed value. + +* ```ts + function v128.relaxed_dot(a: v128, b: v128): v128 + ``` +
Computes the dot product of two 8-bit integer lanes each, yielding lanes one size wider than the input. + + | T | Instruction + |----------|------------- + | i16 | i16x8.relaxed_dot_i8x16_i7x16_s +
+ + Unlike `v128.dot`, if the most significant bit of `b[i]` is set, whether `b[i]` is interpreted as signed or unsigned by the intermediate multiplication is implementation-defined. + +* ```ts + function v128.relaxed_dot_add(a: v128, b: v128, c: v128): v128 + ``` +
Computes the dot product of two 8-bit integer lanes each, yielding lanes two sizes wider than the input with the lanes of c accumulated into the result. + + | T | Instruction + |----------|------------- + | i32 | i32x4.relaxed_dot_i8x16_i7x16_add_s +
+ + Unlike `v128.dot`, if the most significant bit of `b[i]` is set, whether `b[i]` is interpreted as signed or unsigned by the intermediate multiplication is implementation-defined. + + ### Inline instructions In addition to using the generic builtins above, most WebAssembly instructions can be written directly in AssemblyScript code. For example, the following is equivalent: