Remove or update the overview?

[valadaptive]

It seems the overview has not been updated since October 2023, and differs significantly from the actual ratified specification.

However, it is a lot easier to read than the ratified specification, and is prominently linked in the README, so many people treat it as a source of truth.

I think the overview should preferably be removed entirely, or else updated to match the actual ratified semantics. If neither of those options work, a big, hard-to-miss disclaimer should be added to the overview stating that does not describe the current official semantics that made it into the actual WebAssembly 3.0 spec.

[ppenzin]

differs significantly from the actual ratified specification.

I believe you either need to describe what those differences are or if the issue is only about the signedness of the relaxed swizzle indices then update the description to reflect that. Significant differences without an explanation between overview and the ratified document would be somewhat problematic, as the spec was developed using the Overview.md (just like original SIMD and flexible-vectors) and then the official doc was written with the intent to describe the same thing.

On the signedness - I was going to respond on the review, but this is definitely a better place - I can't seem to find a trail on why the change was made, and that might or might not be an issue, will follow up in the next SIMD sync.

It is probably somewhat unadvised to count me as "many people" 😄

[valadaptive]

Let's see:

• For the relaxed swizzle operation, the pseudocode in the overview is actually correct, but the accompanying prose is incorrect/vague.

• According to the overview's pseudocode, the unsigned relaxed_trunc is allowed to return UINT32_MAX if the input is NaN or out-of-range (which matches x86's VCVTPS2UDQ). The official spec just says that the operation can choose between returning the proper saturated value or 𝐑. As far as I can tell, it does not define what 𝐑 means anywhere.

• Similarly, the overview says that the signed relaxed_trunc can return INT32_MIN if the input is NaN (which matches CVTPS2DQ¹). The official spec again says it can return 𝐑, whatever that is.

• The relaxed_madd and relaxed_nmadd operations in the overview seem to match the spec.

• The prose for the relaxed_laneselect operations in the overview simply state that "the result is implementation defined" if all the bits within each lane are not identical. The pseudocode is more specific, and lays out that implementations can choose between a bit-select (like ARM) and checking the top bit of each lane (like x86).

• The prose for relaxed_min and relaxed_max is similarly vague, stating only "If either values is NaN, or the values are -0.0 and +0.0, the return value is implementation-defined.". I can't really tell whether the pseudocode matches the spec here with regards to signed zero. The spec uses this bespoke syntax with plus-or-minus symbols and a flipped minus-or-plus symbol.

  I think the distinct permitted behaviors here can be enumerated as follows:

  1. x86's MINPS/MAXPS/etc. These behave like a < b ? a : b and a > b ? a : b. That is, they return the second operand if either is NaN or both are signed zero.
  2. WebAssembly's fpmin and fpmax. These behave like b < a ? b : a and b > a ? b : a. That is, exactly like MINPS and MAXPS but with the operands flipped. It's not clear to me why both need to be allowed, since it should be trivial to just flip the operands.
  3. IEEE754-2019's minimum and maximum, as implemented in ARM's fmin and fmax. These treat -0.0 as less than +0.0, and return NaN if either operand is NaN.
  4. IEEE754-2019's minimumNumber and maximumNumber, as implemented in ARM's fminnm and fmaxnm. These treat -0.0 as less than +0.0, but only return NaN if both operands are NaN, and will otherwise prefer returning the non-NaN operand. I believe these are the only ones implemented in hardware on RISC-V.

  It's unclear to me whether the semantics are "choose between exactly one of those versions at runtime".

  Also, Rust's documentation of these intrinsics was incorrect; it stated that they could only behave like WebAssembly's fmin/fmax or fpmin/fpmax, excluding behaviors 1 and 4 in the list above. I'm not sure where that mistake came from, but it may be worth clarifying that in the overview.

• I'm not very familiar with q15mulr_s or the integer dot product ops, but the overview's pseudocode seems to match the spec here. The prose for the relaxed integer dot product is vague, stating only "that lane's result is implementation defined", without enumerating which implementation-defined results are allowed.

So, I guess the pseudocode is correct here. The prose is vague (verging on misleading), and could do with some clarification and probably some copy-editing as well.

Footnotes

1. There's an Intel documentation bug here. Intel's manual, and hence all the online instruction references, say that CVTPS2DQ returns (2**32)-1, or the all-ones bit pattern. In actuality, it returns 2**(32 - 1), or 0x80000000, which is in fact INT32_MIN. ↩