On Thu, 21 Apr 2022 04:23:22 GMT, Jie Fu <ji...@openjdk.org> wrote:
>> Hi all,
>>
>> The Current Vector API doc for `LSHR` is
>>
>> Produce a>>>(n&(ESIZE*8-1)). Integral only.
>>
>>
>> This is misleading which may lead to bugs for Java developers.
>> This is because for negative byte/short elements, the results computed by
>> `LSHR` will be different from that of `>>>`.
>> For more details, please see
>> https://github.com/openjdk/jdk/pull/8276#issue-1206391831 .
>>
>> After the patch, the doc for `LSHR` is
>>
>> Produce zero-extended right shift of a by (n&(ESIZE*8-1)) bits. Integral
>> only.
>>
>>
>> Thanks.
>> Best regards,
>> Jie
>
> Jie Fu has updated the pull request with a new target base due to a merge or
> a rebase. The incremental webrev excludes the unrelated changes brought in by
> the merge/rebase. The pull request contains three additional commits since
> the last revision:
>
> - Address review comments
> - Merge branch 'master' into JDK-8284992
> - 8284992: Fix misleading Vector API doc for LSHR operator
After talking with John here's what we think is a better approach than what I
originally had in mind:
1. In the class doc of `VectorOperators` add a definition for `EMASK` occurring
after the definition for `ESIZE`:
* <li>{@code EMASK} — the bit mask of the operand type, where {@code
EMASK=(1<<ESIZE*8)-1}
2. Change `LSHR` to be:
/** Produce {@code (a&EMASK)>>>(n&(ESIZE*8-1))}. Integral only. */
That more clearly gets across operating in the correct domain for sub-word
operand types, which was the original intention (e.g. the right shift value).
-------------
PR: https://git.openjdk.java.net/jdk/pull/8291
