Editorial review: Document the Wasm wide arithmetic proposal - #45320
Editorial review: Document the Wasm wide arithmetic proposal#45320chrisdavidmills wants to merge 3 commits into
Conversation
github-actions
Bot
added
Content:wasm
Preview URLs (9 pages)
External URLs (1)URL:
(comment last updated: 2026-08-27 11:00:02) |
github-actions
Bot
added
the
Content:Firefox
chrisdavidmills
changed the title
bvisness
left a comment
bvisness
left a comment
There was a problem hiding this comment.
I don't see any factual issues here, just some stylistic questions / thoughts.
| ### Operand stack | ||
|
|
||
| ```plain | ||
| [input1:i64 input2:i64 input3:i64 input4:i64] -> [output1:i64 output2:i64] |
There was a problem hiding this comment.
nit: Maybe we could call these left_low, left_high, right_low, and right_high or something? Same story for the results.
There was a problem hiding this comment.
This makes sense.
I've gone for low_input, high_input, low_output, high_output,
and low_left_input, low_right_input, etc.
|
|
||
| ## Description | ||
|
|
||
| The `add128` instruction provides a mechanism by which two 128-bit integers — represented by four `i64` values — can be added together, with the result represented by two `i64` values. This so-called wide arithmetic is useful in any situation where larger-than-64-bit numbers are being used in source languages with Wasm as a compile target, for example cryptographic algorithms. |
There was a problem hiding this comment.
"so-called wide arithmetic" threw me a little bit lol, it feels a bit mocking, like there are air quotes around it.
More seriously, while this description is correct, I feel the main benefit is not just "support for larger numbers" per se, but the fact that engines can generate more efficient machine code for these operations than is possible with the existing wasm i64 arithmetic operations.
There was a problem hiding this comment.
Heh, I need to stop sounding sarcastic about Wasm. I honestly don't have anything against it.
I've updated that wording to "Such operations are termed wide arithmetic, which is useful..."
Then I've added a sentence to cover your other point:
More importantly, it also allows engines to generate more efficient machine code for these operations than is possible with
i64arithmetic operations.
Super, thanks for the review, @bvisness. |
chrisdavidmills
changed the title
|
This pull request has merge conflicts that must be resolved before it can be merged. |
| <!-- #### Removals --> | ||
|
|
||
| <!-- ### WebAssembly --> | ||
| ### WebAssembly |
There was a problem hiding this comment.
FYI @chrisdavidmills I always split out the FF release note into it's own PR because the review cycles are different.
If you do this in one PR you will likely get conflicts unless you are all finished and reviewed very quickly.
There was a problem hiding this comment.
FWIW, the suggested release note in bugzilla is "Firefox now supports the WebAssembly Wide Arithmetic proposal, which adds 128-bit arithmetic instructions for better performance on some workloads.". Is it worth mentioning the "better performance" thing?
| - [`mul_wide_u`](/en-US/docs/WebAssembly/Reference/Numeric/mul_wide_u) | ||
| - : Multiply two unsigned 64-bit integers to produce an unsigned 128-bit result represented by two 64-bit integers. | ||
| - [`sub128`](/en-US/docs/WebAssembly/Reference/Numeric/sub128) | ||
| - : Subtract one 128-bit integer — represented by two 64-bit integers — from another, to produce a 128-bit result represented by two 64-bit integers. |
There was a problem hiding this comment.
Inconsistent
| - : Subtract one 128-bit integer — represented by two 64-bit integers — from another, to produce a 128-bit result represented by two 64-bit integers. | |
| - : Subtract one 128-bit integer, represented by two 64-bit integers, from another, to produce a 128-bit result represented by two 64-bit integers. |
| {{InteractiveExample("Wat Demo: add128", "tabbed-taller")}} | ||
|
|
||
| ```wat interactive-example | ||
| (module |
There was a problem hiding this comment.
Output is
Error: WebAssembly.instantiateStreaming(): Compiling function #1:"main" failed: Invalid opcode 0xfc13 (enable with --experimental-wasm-wide_arithmetic) @+77
Assume you are getting this addressed?
| ## Description | ||
|
|
||
| The `add128` instruction adds two 128-bit integers — represented by four `i64` values — together to produce a 128-bit result represented by two `i64` values. Such operations are termed **wide arithmetic**, which is useful in any situation where larger-than-64-bit numbers are being used in source languages with Wasm as a compile target, for example cryptographic algorithms. | ||
|
|
||
| More importantly, it also allows engines to generate more efficient machine code for these operations than is possible with `i64` arithmetic operations. |
There was a problem hiding this comment.
I'm not sure about this section adds much and it feels a bit like marketing/non-specific to this method. Its a pity this isn't here: https://pr45320.review.mdn.allizom.net/en-US/docs/WebAssembly/Reference/Numeric#wide_arithmetic.
Consider this, which at least makes it a bit more clearly separates the things that are common to all, and roll out everywhere.
| ## Description | |
| The `add128` instruction adds two 128-bit integers — represented by four `i64` values — together to produce a 128-bit result represented by two `i64` values. Such operations are termed **wide arithmetic**, which is useful in any situation where larger-than-64-bit numbers are being used in source languages with Wasm as a compile target, for example cryptographic algorithms. | |
| More importantly, it also allows engines to generate more efficient machine code for these operations than is possible with `i64` arithmetic operations. | |
| ## Description | |
| The `add128` instruction adds two 128-bit integers — represented by four `i64` values — together to produce a 128-bit result represented by two `i64` values. | |
| This is one of the **wide arithmetic** operations, which are useful in situations where larger-than-64-bit numbers are being used in source languages with Wasm as a compile target. One such example is cryptographic algorithms. | |
| These methods allow engines to generate more efficient machine code for these operations than is possible with `i64` arithmetic operations. |
hamishwillee
left a comment
hamishwillee
left a comment
There was a problem hiding this comment.
@chrisdavidmills I've scanned this an added a few comments.
The /mdn-pr review skill came up with the following.
Some of these are valid - for example "Missing comma before, and ambiguous attachment of, "for example cryptographic algorithms"; sentence also runs ~33 words" is part of the problem I tried to address in https://github.com/mdn/content/pull/45320/changes#r3899579426
Details
Detailed per-file review of changed lines
files/en-us/webassembly/reference/numeric/mul_wide_u/index.md
| Line | Issue | Severity | Suggestion |
|---|---|---|---|
| 41 | "i64.mul_wide_u" defined as "The i64.mul_wide_u instruction" — restates the term, no new information |
bug | Drop the bullet, or give it real content the way extend8_s's equivalent bullet does |
| 50-56 | low_input/high_input implies a low/high split of one value (correct for add128/sub128); per spec this instruction takes two independent 64-bit multiplicands ("left-hand-side"/"right-hand-side" argument), so the naming misleads the reader |
bug | Rename to e.g. left_input/right_input, or the page's original input1/input2 |
| 70 | Missing comma before, and ambiguous attachment of, "for example cryptographic algorithms"; sentence also runs ~33 words | style | See suggestion block below |
| 70 | "multiplies two unsigned i64 values to produce..." drops "together" that the parallel sentence in mul_wide_s (same slot) has |
minor | "multiplies two unsigned i64 values together to produce..." |
| 84-86 | See also order (add128, sub128, mul_wide_s) isn't alphabetical, unlike add128's and sub128's own See-also lists in this PR |
minor | Reorder: add128, mul_wide_s, sub128 |
| 12-27 | Interactive WAT demo likely fails the same way as add128's (see below) — same runtime, same newly-added 0xfc 0x16 opcode, not independently reproduced here |
bug | Confirm the demo runtime supports the new opcode before merge |
files/en-us/webassembly/reference/numeric/mul_wide_s/index.md
| Line | Issue | Severity | Suggestion |
|---|---|---|---|
| 41 | "i64.mul_wide_s" defined as "The i64.mul_wide_s instruction" — restates the term, no new information |
bug | Drop the bullet, or give it real content the way extend8_s's equivalent bullet does |
| 50-56 | low_input/high_input implies a low/high split of one value; the spec's two "left-hand-side"/"right-hand-side" arguments are independent 64-bit multiplicands. The reviewer only asked to rename the outputs to output_low/output_high; the author's fix commit also renamed the inputs, which was neither requested nor correct |
bug | Rename to e.g. left_input/right_input, or the page's original input1/input2 |
| 70 | Missing comma before, and ambiguous attachment of, "for example cryptographic algorithms"; sentence also runs ~33 words | style | See suggestion block below |
| 84-86 | See also order (add128, sub128, mul_wide_u) isn't alphabetical, unlike add128's and sub128's own See-also lists |
minor | Reorder: add128, mul_wide_u, sub128 |
| 12-27 | Interactive WAT demo likely fails the same way as add128's (see below) — same runtime, same newly-added 0xfc 0x15 opcode, not independently reproduced here |
bug | Confirm the demo runtime supports the new opcode before merge |
files/en-us/webassembly/reference/numeric/add128/index.md
| Line | Issue | Severity | Suggestion |
|---|---|---|---|
| 10 | Intro sets off "represented by four 64-bit integers" with commas, but the Description (line 76) sets off the identical construction with em dashes — internally inconsistent, and unlike sub128, which uses em dashes in both spots |
style | Match line 76's em-dash style (or vice versa) |
| 43 | "i64.add128" defined as "The i64.add128 instruction" — restates the term, no new information |
bug | Drop the bullet, or give it real content the way extend8_s's equivalent bullet does |
| 76 | Missing comma before, and ambiguous attachment of, "for example cryptographic algorithms"; sentence also runs ~33 words | style | See suggestion block below |
| 12-29 | Interactive WAT demo fails: reviewer-reported Invalid opcode 0xfc13 (enable with --experimental-wasm-wide_arithmetic), matching this page's own Binary encoding table (0xfc 0x13 for i64.add128); comment is still unresolved |
bug | Confirm the interactive-example runtime supports the new opcode before merge; resolve the open thread |
files/en-us/webassembly/reference/numeric/sub128/index.md
| Line | Issue | Severity | Suggestion |
|---|---|---|---|
| 43 | "i64.sub128" defined as "The i64.sub128 instruction" — restates the term, no new information |
bug | Drop the bullet, or give it real content the way extend8_s's equivalent bullet does |
| 76 | Missing comma before, and ambiguous attachment of, "for example cryptographic algorithms"; sentence also runs ~33 words | style | See suggestion block below |
| 12-29 | Interactive WAT demo likely fails the same way as add128's (see above) — same runtime, same newly-added 0xfc 0x14 opcode, not independently reproduced here |
bug | Confirm the demo runtime supports the new opcode before merge |
files/en-us/mozilla/firefox/releases/155/index.md
| Line | Issue | Severity | Suggestion |
|---|---|---|---|
| 73 | "128-bit integer additions, multiplications, and subtractions" groups multiplication with addition/subtraction as if it also operates on 128-bit integers; mul_wide_s/mul_wide_u actually multiply two 64-bit integers to produce a 128-bit result. Contradicts this PR's own numeric/index.md (lines 64 & 70: "Multiply two ... 64-bit integers...") |
bug | "...which allows 128-bit integer addition and subtraction, and 64-bit-to-128-bit multiplication, to be represented in Wasm." |
| 73 | Passive voice ("has been implemented ... to be represented") breaks with every sibling bullet in this file, which uses active voice ("now implements", "now support") | style | "Firefox 155 implements the Wide arithmetic proposal, allowing 128-bit integer addition and subtraction, and 64-bit-to-128-bit multiplication, in Wasm." |
files/en-us/webassembly/reference/numeric/index.md
| Line | Issue | Severity | Suggestion |
|---|---|---|---|
| 70 | sub128's bullet uses em dashes for "represented by two 64-bit integers"; add128's bullet (line 64) uses commas for the identical construction. A reviewer already flagged this as "Inconsistent" in an unresolved comment on this line, suggesting the comma form — not yet applied |
style | Apply the reviewer's suggested rewrite so both bullets match |
Suggestion block — add128:76, sub128:76, mul_wide_s:70, mul_wide_u:70.
All four pages share the sentence "...Such operations are termed wide arithmetic, which is useful in any situation where larger-than-64-bit numbers are being used in source languages with Wasm as a compile target, for example cryptographic algorithms." Split it and fix the attachment:
Such operations are termed wide arithmetic. Wide arithmetic is useful whenever a source language that targets Wasm needs numbers larger than 64 bits — for example, in cryptographic algorithms.
(For mul_wide_u, combine with the "together" fix above: "...multiplies two unsigned i64 values together to produce...")
Pre-existing issues on lines this PR didn't change.
4 participants
Description
Firefox 155 adds support for the Wasm wide arithmetic proposal; see https://bugzilla.mozilla.org/show_bug.cgi?id=2062374.
The proposal adds four new Wasm instructions:
add128sub128mul_wide_smul_wide_uThis PR adds reference pages for the new instructions.
Motivation
Additional details
Related issues and pull requests
Fixes #45174