Document Wasm SIMD arithmetic instructions by chrisdavidmills · Pull Request #43583 · mdn/content

chrisdavidmills · 2026-03-26T11:55:34Z

Description

This PR adds reference docs for WebAssembly SIMD arithmetic instructions (and possibly some more bitwise ones too).

Note: I've updated the general shl page to cover SIMD and non-SIMD values. I've also deleted the previously published SIMD-specific shl page and redirected it to the general one.

Motivation

Additional details

Related issues and pull requests

github-actions · 2026-03-26T11:57:19Z

Preview URLs (60 pages)

Flaws (4)

Note! 56 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/WebAssembly/Reference/Numeric/add
Title: add: Wasm text instruction
Flaw count: 1

macros:
- Macro ? produces link /en-US/docs/WebAssembly/Reference/SIMD/Arithmetic which is ill cased

URL: /en-US/docs/WebAssembly/Reference/Numeric/promote_32
Title: promote_32: Wasm text instruction
Flaw count: 1

macros:
- Macro ? produces link /en-US/docs/WebAssembly/Reference/SIMD/Arithmetic which is ill cased

URL: /en-US/docs/WebAssembly/Reference/Numeric/trunc_f32_u
Title: trunc_f32_u: Wasm text instruction
Flaw count: 1

macros:
- Macro ? produces link /en-US/docs/WebAssembly/Reference/SIMD/Arithmetic which is ill cased

URL: /en-US/docs/WebAssembly/Reference/SIMD/arithmetic/min_s
Title: min_s: Wasm SIMD arithmetic instruction
Flaw count: 1

macros:
- Macro ? produces link /en-US/docs/WebAssembly/Reference/SIMD/Arithmetic which is ill cased

(comment last updated: 2026-04-10 16:37:30)

ge_s, ge_u, gt_s, gt_u, le_s, le_u, lt_s, lt_u all showed f32/f64 prefixes in the example column (e.g. `f32.ge_s`) which don't exist.

108 and 109 are both < 128 so they encode as single LEB128 bytes. The examples incorrectly showed a trailing 0x01 byte.

f32.div and f64.div showed 0x92/0xa0 (the add opcodes). f64x2.div showed 0xf0 0x01 (f64x2.add). Correct values are 0x95, 0xa3, and 0xf3 0x01 respectively.

i32.const and i64.const had spurious extra bytes; 2 and 1 are single LEB128 bytes so no extra byte is needed. f32.const 2.5 had an extra trailing 0x40 byte; 2.5 in f32 little-endian is 4 bytes. Also align the SIMD description example to use i32x4 consistently with the binary table.

The Wasm code uses i16x8 but the prose described it as i8x16.

The prose described the lane type as i8x16 but the code uses i16x8. Also switched to extract_lane_u since the page demonstrates unsigned shift-right.

ceil and floor only apply to f32x4 and f64x2. Using i32x4 with float literal values was incorrect.

The original described it as operating on "each byte" and "bit 7", which is only accurate for i8x16. Updated to say "each lane" and clarified the threshold values for wider types in the note.

The spec defines ixN.all_true as checking that each lane is non-zero, not each bit. A lane value of 1 passes (non-zero lane) even though most bits within it are 0.

Those pages don't exist yet; plain text avoids publishing dead links.

hamishwillee · 2026-04-10T00:19:26Z

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

+- `output`
+  - : The output value.
+
+For a non-SIMD `abs`, the `input` and `output` will be basic numeric values such as `-3.5` or `3.5`.


This reads as though the output can be -3.5.

Fair point. I've removed the negative value in my next commit.

hamishwillee · 2026-04-10T00:28:04Z

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

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


Any reason you chose "in our" rather than "in the following", "in the", or "in this"? Feels inconsistent/odd.

No reason at all. I don't think this is a big enough issue to worry about. It feels slightly more conversational than usual, but otherwise OK.

hamishwillee · 2026-04-10T00:31:55Z

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

+
+For a non-SIMD `abs`, the `input` and `output` will be basic numeric values such as `-3.5` or `3.5`.
+
+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`.


Ditto. So for a SIMD all the values will be made absolute after the instruction?

Yes. I changed this one to all positive values too.

hamishwillee · 2026-04-10T00:35:49Z

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

+
+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`.


I think you need to say what numbers are added in the SIMD case since there are multiple lanes in the input and the description is "is used for adding up two numbers".
Also in this case, where does the value "go"? Is it written into the v128 value or onto the stack?

Ah, this is answered by the example. I think it is "For SIMD this adds two v128 values of the same interpretation type, returning another v128 on the stack where each lane is the addition of the corresponding lanes in the original blah blha.

It isn't clear if they have to be the same type of data, though I would assume so.

We should capture all this here.

And similar for all the other instructions

Some of this is a bit too obvious for the target audience. For example, if the "Type" section shows an output, you know that a value is pushed onto the stack as a result.

However, I think it is useful to explicitly describe the nature of each output in the case of SIMD versions of the instructions. I've gone through and added a descriptive sentence for each one, for example:

For a SIMD add, these will be 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.

hamishwillee · 2026-04-10T00:42:11Z

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

+
+For a non-SIMD `and`, these will be basic numeric values such as `14` or `3`.
+
+For a [SIMD](/en-US/docs/WebAssembly/Reference/SIMD) `and`, these will be [`v128`](/en-US/docs/WebAssembly/Reference/Types/v128) value interpretations, for example `i32x4 9 4 -16 100`.


As above https://github.com/mdn/content/pull/43583/changes#r3061408253 we need to make it clear if the types are the same and that the comparison is by corresponding lane, returning a new value to the stack of the same type.

I've added an explanation, as per above. The types will always be the same in Wasm.

hamishwillee · 2026-04-10T00:42:59Z

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

YOu changed this in all the other cases to instruction/is

Good catch; changed.

hamishwillee

It is all very consistent. I haven't got the energy or time to review every case, so I have read a few carefully and added a few points for discussion.

hamishwillee · 2026-04-10T00:52:09Z

files/en-us/webassembly/reference/simd/arithmetic/min_u/index.md

+- `input2`
+  - : The second input value.
+- `output`
+  - : The output value. A new `v128` of the same type as the inputs, with each lane set to the greater of that lane index's value on the two inputs.


Suggested change

- : The output value. A new `v128` of the same type as the inputs, with each lane set to the greater of that lane index's value on the two inputs.

- : The output value. A new `v128` of the same type as the inputs, with each lane set to the lower of that lane index's value on the two inputs.

This was a claude check ^^^

Here is the rest of the comments:

simd/bitwise/index.md — wrong URL for any_true

any_true

any_true links to the andnot page. Should be .../bitwise/any_true.

Grammar errors

simd/index.md — "This instructions"

▎ "This instructions in this section are SIMD-specific."

Should be: "The instructions in this section are SIMD-specific."

simd/bitwise/any_true/index.md — article before v128

▎ "tests whether an v128 input value contains any non-zero bits."

Should be: "tests whether a v128 input value..." (v is a consonant sound).

simd/bitwise/all_true/index.md — type section says input1 but signature has [input]

### Type [input] -> [output] - `input1` - : The input `v128` value interpretation.

The parameter name is input1 but the type signature uses input. Should be consistent — either input1/input2 pattern
(if that's the convention, but all_true only takes one input) or just input. This is the same pattern issue as
bitmask.

simd/bitwise/bitmask/index.md — same input1 vs [input] inconsistency

The type signature shows [input] -> [output] but the parameter description uses input1.

Spelling errors

simd/bitwise/bitmask/index.md — "equivent"

▎ "The example's output value is 4096, which is the decimal equivent of the above binary pattern."

Should be: "equivalent"

simd/bitwise/bitmask/index.md — duplicate word "means means"

▎ "while an MSB of 0 means means the value is less than 128."

Should be: "while an MSB of 0 means the value is less than 128."

Wrong section heading (content accuracy)

simd/arithmetic/index.md — ## Comparison heading is misleading

The section under ## Comparison lists max_s, max_u, min_s, min_u — these are arithmetic min/max instructions, not comparison instructions (comparisons return booleans). A heading like ## Min/Max would be more accurate.

OK, cool, I've corrected all the ones that were not already fixed by @eqrion's PR.

SIMD arithmetic fixes

github-actions · 2026-04-10T11:28:28Z

This pull request has merge conflicts that must be resolved before it can be merged.

eqrion · 2026-04-10T15:18:25Z

Just commenting that I did a quick technical review of this as well. It's a lot so I didn't look at everything. I added some commits that Chris merged on to his branch.

Document Wasm SIMD arithmetic instructions

874b015

chrisdavidmills requested a review from a team as a code owner March 26, 2026 11:55

chrisdavidmills requested review from hamishwillee and removed request for a team March 26, 2026 11:55

github-actions bot added the Content:wasm WebAssembly docs label Mar 26, 2026

chrisdavidmills marked this pull request as draft March 26, 2026 11:55

github-actions bot added the size/m [PR only] 51-500 LoC changed label Mar 26, 2026

Add more SIMD information to numeric values

9c44291

github-actions bot added size/xl [PR only] >1000 LoC changed and removed size/m [PR only] 51-500 LoC changed labels Mar 26, 2026

chrisdavidmills added 3 commits April 1, 2026 09:08

Merge branch 'main' into wasm-simd-3

b4185e3

Arithmetic instruction progress

1543148

More bitwise/arithmetic progress

527741b

github-actions bot added the Content:Meta Content in the meta docs label Apr 3, 2026

chrisdavidmills added 2 commits April 6, 2026 18:50

Add v128 logic instructions

e48fa06

correct arithmetic casin

5f07945

chrisdavidmills marked this pull request as ready for review April 7, 2026 12:19

chrisdavidmills requested a review from a team as a code owner April 7, 2026 12:19

chrisdavidmills requested review from dipikabh and removed request for a team April 7, 2026 12:19

eqrion added 9 commits April 8, 2026 17:30

Fix i32/i64 type prefix in integer comparison binary examples

7cd395b

ge_s, ge_u, gt_s, gt_u, le_s, le_u, lt_s, lt_u all showed f32/f64 prefixes in the example column (e.g. `f32.ge_s`) which don't exist.

Fix i8x16.shr_s and i8x16.shr_u binary encoding examples

2d214a3

108 and 109 are both < 128 so they encode as single LEB128 bytes. The examples incorrectly showed a trailing 0x01 byte.

Fix 00x0 typo in load64_lane binary encoding example

dc4c126

Fix div binary encoding examples

9c7c2ba

f32.div and f64.div showed 0x92/0xa0 (the add opcodes). f64x2.div showed 0xf0 0x01 (f64x2.add). Correct values are 0x95, 0xa3, and 0xf3 0x01 respectively.

Fix shr_s example description: i8x16 -> i16x8

a87d6bd

The Wasm code uses i16x8 but the prose described it as i8x16.

Fix shr_u example: i8x16 -> i16x8, extract_lane_s -> extract_lane_u

e6b5e23

The prose described the lane type as i8x16 but the code uses i16x8. Also switched to extract_lane_u since the page demonstrates unsigned shift-right.

Fix ceil/floor SIMD example type: i32x4 -> f32x4

62d90ff

ceil and floor only apply to f32x4 and f64x2. Using i32x4 with float literal values was incorrect.

Fix bitmask description to be accurate for all lane types

c550058

The original described it as operating on "each byte" and "bit 7", which is only accurate for i8x16. Updated to say "each lane" and clarified the threshold values for wider types in the note.

eqrion added 3 commits April 8, 2026 17:33

Fix all_true description: "all bits" -> "all lanes"

9752a16

The spec defines ixN.all_true as checking that each lane is non-zero, not each bit. A lane value of 1 passes (non-zero lane) even though most bits within it are 0.

Fix gt_u link in numeric index pointing to gt_s

d5f36ff

Remove placeholder (#) links for add_sat_s/add_sat_u

0faa6c1

Those pages don't exist yet; plain text avoids publishing dead links.

hamishwillee reviewed Apr 10, 2026

View reviewed changes

Merge pull request #14 from eqrion/simd-review

d4615dc

SIMD arithmetic fixes

github-actions bot added the merge conflicts 🚧 [PR only] label Apr 10, 2026

Merge branch 'main' into wasm-simd-3

486d716

github-actions bot removed the merge conflicts 🚧 [PR only] label Apr 10, 2026

Remove empty links for now

6af370a

chrisdavidmills added 2 commits April 10, 2026 17:21

Add explanations of what the output SIMD values contain.

e5b03d0

More fixes from Hamish review

e993159

chrisdavidmills requested review from hamishwillee and removed request for dipikabh April 10, 2026 16:37


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


		For a non-SIMD `abs`, the `input` and `output` will be basic numeric values such as `-3.5` or `3.5`.

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


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


		For a non-SIMD `and`, these will be basic numeric values such as `14` or `3`.

		For a [SIMD](/en-US/docs/WebAssembly/Reference/SIMD) `and`, these will be [`v128`](/en-US/docs/WebAssembly/Reference/Types/v128) value interpretations, for example `i32x4 9 4 -16 100`.

	- : The output value. A new `v128` of the same type as the inputs, with each lane set to the greater of that lane index's value on the two inputs.
	- : The output value. A new `v128` of the same type as the inputs, with each lane set to the lower of that lane index's value on the two inputs.

Conversation

chrisdavidmills commented Mar 26, 2026

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Apr 10, 2026

Uh oh!

eqrion commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Mar 26, 2026 •

edited

Loading

hamishwillee Apr 10, 2026 •

edited

Loading