Re: [PATCH v3 2/2] bpf, doc: Improve MOV/MOVSX documentation and add examples

[Vineet Gupta <vineet.gupta@linux.dev>]

On 4/4/26 20:33, Alexei Starovoitov wrote:
> On Fri, Apr 3, 2026 at 9:41 AM Vineet Gupta <vineet.gupta@linux.dev> wrote:
>>   - Add missing form {MOV, K, ALU}.
>>
>>   - Add some assembly (pseudo-C) snippets.
>>
>>   - Rearrange: MOV content comes before MOVSX.
>>
>>   - MOVSX content itself rearranged: canonical sign extension variant
>>     for {8,16,32}-> 64 moved ahead of the special variant which only
>>     sign extends to 32 and zeroes out the upper bits.
>>
>>   - Remove the hyphen '-' in "sign-extension" to make grep hit all
>>     instances with one pattern.
>>
>> Signed-off-by: Vineet Gupta <vineet.gupta@linux.dev>
>> ---
>> Changes since v2:
>>   - Fixed RST markup for asm example "w5 = w9"
>>   - Added asm example "w5 = (s8)w9" for {MOVSX, X, ALU}
>> ---
>>   .../bpf/standardization/instruction-set.rst   | 49 +++++++++++++++----
>>   1 file changed, 39 insertions(+), 10 deletions(-)
>>
>> diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
>> index 96181565906f..863a0cc22a75 100644
>> --- a/Documentation/bpf/standardization/instruction-set.rst
>> +++ b/Documentation/bpf/standardization/instruction-set.rst
>> @@ -414,25 +414,54 @@ etc. This specification requires that signed modulo MUST use truncated division
>>
>>      a % n = a - n * trunc(a / n)
>>
>> -The ``MOVSX`` instruction does a move operation with sign extension.
>> -``{MOVSX, X, ALU}`` :term:`sign extends<Sign Extend>` 8-bit and 16-bit operands into
>> -32-bit operands, and zeroes the remaining upper 32 bits.
>> -``{MOVSX, X, ALU64}`` :term:`sign extends<Sign Extend>` 8-bit, 16-bit, and 32-bit
>> -operands into 64-bit operands.  Unlike other arithmetic instructions,
>> -``MOVSX`` is only defined for register source operands (``X``).
>> +For move operations, the ``MOV`` instruction has a few different forms.
>> +
>> +``{MOV, X, ALU64}`` means::
>> +
>> +  dst = src
>> +
>> +e.g. ``r1 = r2``
>>
>>   ``{MOV, K, ALU64}`` means::
>>
>>     dst = (s64)imm
>>
>> -``{MOV, X, ALU}`` means::
>> +e.g. ``r1 = -4``
>> +     ``r5 = 9282009``
>> +
>> +``{MOV, K, ALU}`` means::
>> +
>> +  dst = (u32)imm
>> +
>> +e.g. ``w1 = -4``
>> +     ``w5 = 7302004``
>> +
>> +``{MOV, X, ALU}`` has zero extension semantics (upper 32 bits are zeroed)::
>>
>>     dst = (u32)src
>>
>> +e.g. ``w5 = w9``
>> +
>> +The ``MOVSX`` instruction does a move operation with sign extension and has
>> +a couple of forms.
>> +
>> +``{MOVSX, X, ALU64}`` :term:`sign extends<Sign Extend>` 8-bit, 16-bit, and 32-bit
>> +operands into 64-bit operands.
>> +
>> +e.g. ``r1 = (s8)r2``
>> +
>> +The ``{MOVSX, X, ALU}`` form has slightly different semantics: it
>> +:term:`sign extends<Sign Extend>` 8-bit and 16-bit operands into
>> +32-bit operands, and zeroes the remaining upper 32 bits (similar to ``MOV``).
> This reads too conversational. This is a spec. It's supposed to be dry.

Perhaps there is some extra commentary in this part which can be toned down.

But I think the actual asm examples are warranted for, considering this 
is an ISA doc. Just capturing the abstract operations doesn't give the 
full picture, specially since this is considered single source of truth 
for the ISA.

e.g. consider dst = (u32)(s32)(s8)src
I tried to feed this to assemblers, but neither llvm/gnu can grok it 
since the actual insn is WN = (s8)wM

> Overall I'm not sure it's an improvement.
> Only (MOV, K, ALU) worth adding.
> Please cc David Vernet in the future patches and bpf @ ietf.
>
> I feel that both patches are wiki or faq material than IETF spec.

Thx,
-Vineet