Document Wasm SIMD arithmetic instructions

files/en-us/_redirects.txt

@@ -16886,11 +16886,22 @@
 /en-US/docs/WebAssembly/Reference/Numeric/Population_count	/en-US/docs/WebAssembly/Reference/Numeric/popcnt
 /en-US/docs/WebAssembly/Reference/Numeric/Remainder	/en-US/docs/WebAssembly/Reference/Numeric/rem
 /en-US/docs/WebAssembly/Reference/Numeric/Right_rotate	/en-US/docs/WebAssembly/Reference/Numeric/rotr
-/en-US/docs/WebAssembly/Reference/Numeric/Right_shift	/en-US/docs/WebAssembly/Reference/Numeric/shr
+/en-US/docs/WebAssembly/Reference/Numeric/Right_shift	/en-US/docs/WebAssembly/Reference/Numeric/shr_s
 /en-US/docs/WebAssembly/Reference/Numeric/Square_root	/en-US/docs/WebAssembly/Reference/Numeric/sqrt
 /en-US/docs/WebAssembly/Reference/Numeric/Subtraction	/en-US/docs/WebAssembly/Reference/Numeric/sub
-/en-US/docs/WebAssembly/Reference/Numeric/Truncate_float_to_float	/en-US/docs/WebAssembly/Reference/Numeric/trunc_float
-/en-US/docs/WebAssembly/Reference/Numeric/Truncate_float_to_int	/en-US/docs/WebAssembly/Reference/Numeric/trunc_int
+/en-US/docs/WebAssembly/Reference/Numeric/Truncate_float_to_float	/en-US/docs/WebAssembly/Reference/Numeric/trunc
+/en-US/docs/WebAssembly/Reference/Numeric/Truncate_float_to_int	/en-US/docs/WebAssembly/Reference/Numeric/trunc_f32_s
+/en-US/docs/WebAssembly/Reference/Numeric/promote	/en-US/docs/WebAssembly/Reference/Numeric/promote_32
+/en-US/docs/WebAssembly/Reference/Numeric/shr	/en-US/docs/WebAssembly/Reference/Numeric/shr_s
+/en-US/docs/WebAssembly/Reference/Numeric/trunc_float	/en-US/docs/WebAssembly/Reference/Numeric/trunc
+/en-US/docs/WebAssembly/Reference/Numeric/trunc_int	/en-US/docs/WebAssembly/Reference/Numeric/trunc_f32_s
+/en-US/docs/WebAssembly/Reference/Numeric/wrap	/en-US/docs/WebAssembly/Reference/Numeric/wrap_i64
+/en-US/docs/WebAssembly/Reference/SIMD/bitwise/shl	/en-US/docs/WebAssembly/Reference/Numeric/shl
+/en-US/docs/WebAssembly/Reference/SIMD/bitwise/shr_s	/en-US/docs/WebAssembly/Reference/Numeric/shr_s
+/en-US/docs/WebAssembly/Reference/SIMD/bitwise/shr_u	/en-US/docs/WebAssembly/Reference/Numeric/shr_u
+/en-US/docs/WebAssembly/Reference/SIMD/conversion/ceil	/en-US/docs/WebAssembly/Reference/Numeric/ceil
+/en-US/docs/WebAssembly/Reference/SIMD/conversion/floor	/en-US/docs/WebAssembly/Reference/Numeric/floor
+/en-US/docs/WebAssembly/Reference/SIMD/conversion/trunc	/en-US/docs/WebAssembly/Reference/Numeric/trunc
 /en-US/docs/WebAssembly/Reference/Variables/Local_get	/en-US/docs/WebAssembly/Reference/Variables/local.get
 /en-US/docs/WebAssembly/Reference/Variables/Local_set	/en-US/docs/WebAssembly/Reference/Variables/local.set
 /en-US/docs/WebAssembly/Reference/Variables/Local_tee	/en-US/docs/WebAssembly/Reference/Variables/local.tee

files/en-us/mdn/writing_guidelines/page_structures/page_types/page_type_key/index.md

@@ -157,7 +157,7 @@ This section lists `page-type` values for pages under [WebAssembly/](/en-US/docs
 - `webassembly-instance-property`: an instance property, like [`WebAssembly.Instance.exports`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Instance/exports).
 - `webassembly-instance-method`: an instance method, like [`WebAssembly.Exception.getArg()`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Exception/getArg).
 - `webassembly-static-method`: a static method, like [`WebAssembly.Module.exports()`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module/exports_static).
-- `webassembly-instruction`: an instruction, or a set of instructions, like [`wrap`](/en-US/docs/WebAssembly/Reference/Numeric/wrap).
+- `webassembly-instruction`: an instruction, or a set of instructions, like [`wrap`](/en-US/docs/WebAssembly/Reference/Numeric/wrap_i64).
 
 ### WebDriver page types
 

files/en-us/webassembly/reference/numeric/abs/index.md

@@ -6,7 +6,7 @@ page-type: webassembly-instruction
 sidebar: webassemblysidebar
 ---
 
-The **`abs`** instructions, short for _absolute_, are used to get the absolute value of a number. That is, it returns x if x is positive, and the negation of x if x is negative.
+The **`abs`** instruction, short for _absolute_, is used to get the absolute value of a number. That is, it returns x if x is positive, and the negation of x if x is negative.
 
 {{InteractiveExample("Wat Demo: abs", "tabbed-standard")}}
 
@@ -31,17 +31,107 @@ await WebAssembly.instantiateStreaming(fetch(url), { console });
 
 ## Syntax
 
-```wat
-;; load a number onto the stack
-f32.const -2
+```plain
+value_type.abs
+```
+
+- `value_type`
+  - : The type of value the instruction is being run on. The following types support `abs`:
+    - `f32`
+    - `f64`
+    - [`v128`](/en-US/docs/WebAssembly/Reference/Types/v128) interpretations:
+      - `i8x16`
+      - `i16x8`
+      - `i32x4`
+      - `i64x2`
+      - `f32x4`
+      - `f64x2`
+- `abs`
+  - : The `abs` instruction. Must always be included after the `value_type` and a period (`.`).
+
+### Type
+
+```plain
+[input] -> [output]
+```
+
+- `input`
+  - : The input value.
+- `output`
+  - : The output value.
+
+For a non-SIMD `abs`, the `input` and `output` will be basic numeric values such as `3.5` or `10`.
+
+For a [SIMD](/en-US/docs/WebAssembly/Reference/SIMD) `abs`, the `input` and `output` will be [`v128`](/en-US/docs/WebAssembly/Reference/Types/v128) value interpretations, for example `i32x4 4 8 12 16`. Each lane of the output pushed to the stack is the absolute value of the corresponding lane in the input.
+
+### Binary encoding
+
+| Instruction | Binary format  | Example text => binary          |
+| ----------- | -------------- | ------------------------------- |
+| `f32.abs`   | `0x8b`         | `f32.abs` => `0x8b`             |
+| `f64.abs`   | `0x99`         | `f64.abs` => `0x99`             |
+| `i8x16.abs` | `0xfd 96:u32`  | `i8x16.abs` => `0xfd 0x60`      |
+| `i16x8.abs` | `0xfd 128:u32` | `i16x8.abs` => `0xfd 0x80 0x01` |
+| `i32x4.abs` | `0xfd 160:u32` | `i32x4.abs` => `0xfd 0xa0 0x01` |
+| `i64x2.abs` | `0xfd 192:u32` | `i64x2.abs` => `0xfd 0xc0 0x01` |
+| `f32x4.abs` | `0xfd 224:u32` | `f32x4.abs` => `0xfd 0xe0 0x01` |
+| `f64x2.abs` | `0xfd 236:u32` | `f64x2.abs` => `0xfd 0xec 0x01` |
+
+## Examples
+
+### SIMD abs
+
+In this example, we demonstrate running the `abs` instruction on a SIMD value and outputting one of the resulting lane values.
+
+#### JavaScript
+
+In our script, we grab a reference to a {{htmlelement("p")}} element that we will output our result to, then define an object for import into Wasm containing a single function that writes a value to the output `<p>`. We then compile and instantiate our Wasm module using the [`WebAssembly.instantiateStreaming()`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/instantiateStreaming_static) method, importing the object in the process.
+
+```html hidden live-sample___simd_abs
+<p></p>
+```
 
-;; absolute
-f32.abs
+```js live-sample___simd_abs
+const outputElem = document.querySelector("p");
 
-;; the top item on the stack will now be 2
+const obj = {
+  output(val) {
+    outputElem.textContent += val;
+  },
+};
+
+WebAssembly.instantiateStreaming(fetch("{%wasm-url%}"), {
+  obj,
+});
 ```
 
-| Instruction | Binary opcode |
-| ----------- | ------------- |
-| `f32.abs`   | `0x8b`        |
-| `f64.abs`   | `0x99`        |
+#### Wasm
+
+In our Wasm module, we first import the JavaScript `output()` function, making sure to declare that it has an `i32` parameter. We then declare a SIMD `i32x4` value, then run `i32x4.abs`. Finally we extract the value stored in lane `3` of the output SIMD value using the [`extract_lane`](/en-US/docs/WebAssembly/Reference/SIMD/extract/extract_lane) instruction, and output it to the DOM by calling the imported `output()` function.
+
+```wat live-sample___simd_abs
+(module
+  ;; Import output function
+  (import "obj" "output" (func $output (param i32)))
+
+  (func $main
+    ;; load two SIMD values onto the stack
+    v128.const i32x4 -9 -10 -11 -12
+
+    i32x4.abs
+    i32x4.extract_lane 3 ;; Extract a value from the result
+
+    call $output
+  )
+
+  (start $main)
+)
+```
+
+#### Result
+
+The output is as follows:
+
+{{embedlivesample("simd_abs", "100%", 100)}}
+
+The result is `12`, because the value stored in lane `3` of the input value is `-12`, as we are outputting the absolute equivalent.

files/en-us/webassembly/reference/numeric/add/index.md

@@ -6,7 +6,7 @@ page-type: webassembly-instruction
 sidebar: webassemblysidebar
 ---
 
-The **`add`** instructions are used for adding up two numbers, similar to the **`+`** operator in other languages.
+The **`add`** instruction is used for adding up two numbers, similar to the **`+`** operator in other languages.
 
 {{InteractiveExample("Wat Demo: add", "tabbed-taller")}}
 
@@ -32,20 +32,114 @@ await WebAssembly.instantiateStreaming(fetch(url), { console });
 
 ## Syntax
 
-```wat
-;; load two numbers onto the stack
-i32.const 10
-i32.const 3
+```plain
+value_type.add
+```
+
+- `value_type`
+  - : The type of value the instruction is being run on. The following types support `add`:
+    - `i32`
+    - `i64`
+    - `f32`
+    - `f64`
+    - [`v128`](/en-US/docs/WebAssembly/Reference/Types/v128) interpretations:
+      - `i8x16`
+      - `i16x8`
+      - `i32x4`
+      - `i64x2`
+      - `f32x4`
+      - `f64x2`
+- `add`
+  - : The `add` instruction. Must always be included after the `value_type` and a period (`.`).
+
+### Type
+
+```plain
+[input1, input2] -> [output]
+```
+
+- `input1`
+  - : The first value to be added.
+- `input2`
+  - : The second value to be added.
+- `output`
+  - : The sum of the two input values.
+
+For a non-SIMD `add`, these will be basic numeric values such as `3` or `3.5`.
+
+For a [SIMD](/en-US/docs/WebAssembly/Reference/SIMD) `add`, these will be [`v128`](/en-US/docs/WebAssembly/Reference/Types/v128) value interpretations, for example `f32x4 0x9 0xa 0xb 0xc`. Each lane of the output pushed to the stack is the addition of the corresponding lanes in the input values.
+
+### Binary encoding
+
+| Instruction | Binary format  | Example text => binary          |
+| ----------- | -------------- | ------------------------------- |
+| `i32.add`   | `0x6a`         | `i32.add` => `0x6a`             |
+| `i64.add`   | `0x7c`         | `i64.add` => `0x7c`             |
+| `f32.add`   | `0x92`         | `f32.add` => `0x92`             |
+| `f64.add`   | `0xa0`         | `f64.add` => `0xa0`             |
+| `i8x16.add` | `0xfd 110:u32` | `i8x16.add` => `0xfd 0x6e`      |
+| `i16x8.add` | `0xfd 142:u32` | `i16x8.add` => `0xfd 0x8e 0x01` |
+| `i32x4.add` | `0xfd 174:u32` | `i32x4.add` => `0xfd 0xae 0x01` |
+| `i64x2.add` | `0xfd 206:u32` | `i64x2.add` => `0xfd 0xce 0x01` |
+| `f32x4.add` | `0xfd 228:u32` | `f32x4.add` => `0xfd 0xe4 0x01` |
+| `f64x2.add` | `0xfd 240:u32` | `f64x2.add` => `0xfd 0xf0 0x01` |
+
+## Examples
+
+### SIMD addition
+
+In this example, we demonstrate adding two SIMD values together and outputting one of the lane values.
+
+#### JavaScript
+
+In our script, we grab a reference to a {{htmlelement("p")}} element that we will output our result to, then define an object for import into Wasm containing a single function that writes a value to the output `<p>`. We then compile and instantiate our Wasm module using the [`WebAssembly.instantiateStreaming()`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/instantiateStreaming_static) method, importing the object in the process.
+
+```html hidden live-sample___simd_add
+<p></p>
+```
 
-;; add up both numbers
-i32.add
+```js live-sample___simd_add
+const outputElem = document.querySelector("p");
 
-;; the top item on the stack will now be 13  (10 + 3 = 13)
+const obj = {
+  output(val) {
+    outputElem.textContent += val;
+  },
+};
+
+WebAssembly.instantiateStreaming(fetch("{%wasm-url%}"), {
+  obj,
+});
 ```
 
-| Instruction | Binary opcode |
-| ----------- | ------------- |
-| `i32.add`   | `0x6a`        |
-| `i64.add`   | `0x7c`        |
-| `f32.add`   | `0x92`        |
-| `f64.add`   | `0xa0`        |
+#### Wasm
+
+In our Wasm module, we first import the JavaScript `output()` function, making sure to declare that it has an `i32` parameter. We then declare two SIMD `i32x4` values, then add them together using `i32x4.add`. Finally we extract the value stored in lane `3` of the sum of the addition using the [`extract_lane`](/en-US/docs/WebAssembly/Reference/SIMD/extract/extract_lane) instruction, and output it to the DOM by calling the imported `output()` function.
+
+```wat live-sample___simd_add
+(module
+  ;; Import output function
+  (import "obj" "output" (func $output (param i32)))
+
+  (func $main
+    ;; load two SIMD values onto the stack
+    v128.const i32x4 9 10 11 12
+    v128.const i32x4 9 10 11 12
+
+    i32x4.add ;; add the two values
+    i32x4.extract_lane 3 ;; Extract a value from the result
+
+    call $output
+  )
+
+  (start $main)
+)
+```
+
+#### Result
+
+The output is as follows:
+
+{{embedlivesample("simd_add", "100%", 100)}}
+
+The result is `24`, because the value stored in lane `3` of each of the input values is `12`. Once added together, the output value's lane `3` will contain the value `24`.