[PATCH v3 0/2] BPF documentation improvements

[PATCH v3 0/2] BPF documentation improvements

[Vineet Gupta]

Hi,

A couple of patches for documentation as I start to hack on gcc-bpf backend.
Changes since v2 captured in individual patches.

Thx,
-Vineet

Vineet Gupta (2):
  bpf, doc: Clarify Pseudo-C notation and w vs r register usage
  bpf, doc: Improve MOV/MOVSX documentation and add examples

 .../bpf/standardization/instruction-set.rst   | 63 +++++++++++++++----
 1 file changed, 50 insertions(+), 13 deletions(-)

-- 
2.53.0

[PATCH v3 1/2] bpf, doc: Clarify Pseudo-C notation and w vs r register usage

[Vineet Gupta]

As a newcomer to BPF ecosystem I was confused with Pseudo-C being the
actual assembly. And while it's obvious now that w and r forms represent
32-bit and 64-bit regs respectively, it's better to call this out in
documentation explicitly and make it more newbie-proof.

Signed-off-by: Vineet Gupta <vineet.gupta@linux.dev>
---
No changes since v2
---
 .../bpf/standardization/instruction-set.rst        | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index 39c74611752b..96181565906f 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -315,13 +315,21 @@ For arithmetic and jump instructions (``ALU``, ``ALU64``, ``JMP`` and
 Arithmetic instructions
 -----------------------
 
-``ALU`` uses 32-bit wide operands while ``ALU64`` uses 64-bit wide operands for
-otherwise identical operations. ``ALU64`` instructions belong to the
+``ALU`` uses 32-bit wide operands ('w' registers in assembly) while
+``ALU64`` uses 64-bit wide operands ('r' registers) for otherwise
+identical operations. ``ALU64`` instructions belong to the
 base64 conformance group unless noted otherwise.
-The 'code' field encodes the operation as below, where 'src' refers to the
+The 'code' field encodes the operation as below, where 'src' refers to
 the source operand and 'dst' refers to the value of the destination
 register.
 
+.. note:: BPF ISA is unique as it uses "Pseudo-C" notation for the assembly
+          instructions. In the table below, the column "name" specifies the
+          encoding names. Assembly instructions (as generated by compilers)
+          are specified in the description column for some cases. Description
+          of ``DIV/SDIV``, ``MOD/SMOD`` includes additional semantic logic,
+          not actual assembly.
+
 .. table:: Arithmetic instructions
 
   =====  =====  =======  ===================================================================================
-- 
2.53.0

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

[Vineet Gupta]

 - 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``).
+
 ``{MOVSX, X, ALU}`` with 'offset' 8 means::
 
   dst = (u32)(s32)(s8)src
 
+e.g. ``w5 = (s8)w9``
+
+Unlike other arithmetic instructions,
+``MOVSX`` is only defined for register source operands (``X``).
 
 The ``NEG`` instruction is only defined when the source bit is clear
 (``K``).
@@ -605,7 +634,7 @@ For load and store instructions (``LD``, ``LDX``, ``ST``, and ``STX``), the
     ABS            1      legacy BPF packet access (absolute)   `Legacy BPF Packet access instructions`_
     IND            2      legacy BPF packet access (indirect)   `Legacy BPF Packet access instructions`_
     MEM            3      regular load and store operations     `Regular load and store operations`_
-    MEMSX          4      sign-extension load operations        `Sign-extension load operations`_
+    MEMSX          4      sign extension load operations        `Sign extension load operations`_
     ATOMIC         6      atomic operations                     `Atomic operations`_
     =============  =====  ====================================  =============
 
@@ -649,10 +678,10 @@ instructions that transfer data between a register and memory.
 Where '<size>' is one of: ``B``, ``H``, ``W``, or ``DW``, and
 'unsigned size' is one of: u8, u16, u32, or u64.
 
-Sign-extension load operations
+Sign extension load operations
 ------------------------------
 
-The ``MEMSX`` mode modifier is used to encode :term:`sign-extension<Sign Extend>` load
+The ``MEMSX`` mode modifier is used to encode :term:`sign extension<Sign Extend>` load
 instructions that transfer data between a register and memory.
 
 ``{MEMSX, <size>, LDX}`` means::
-- 
2.53.0

Re: [PATCH v3 1/2] bpf, doc: Clarify Pseudo-C notation and w vs r register usage

[Alexei Starovoitov]

On Fri, Apr 3, 2026 at 9:41 AM Vineet Gupta <vineet.gupta@linux.dev> wrote:
>
> As a newcomer to BPF ecosystem I was confused with Pseudo-C being the
> actual assembly. And while it's obvious now that w and r forms represent
> 32-bit and 64-bit regs respectively, it's better to call this out in
> documentation explicitly and make it more newbie-proof.
>
> Signed-off-by: Vineet Gupta <vineet.gupta@linux.dev>
> ---
> No changes since v2
> ---
>  .../bpf/standardization/instruction-set.rst        | 14 +++++++++++---
>  1 file changed, 11 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> index 39c74611752b..96181565906f 100644
> --- a/Documentation/bpf/standardization/instruction-set.rst
> +++ b/Documentation/bpf/standardization/instruction-set.rst
> @@ -315,13 +315,21 @@ For arithmetic and jump instructions (``ALU``, ``ALU64``, ``JMP`` and
>  Arithmetic instructions
>  -----------------------
>
> -``ALU`` uses 32-bit wide operands while ``ALU64`` uses 64-bit wide operands for
> -otherwise identical operations. ``ALU64`` instructions belong to the
> +``ALU`` uses 32-bit wide operands ('w' registers in assembly) while
> +``ALU64`` uses 64-bit wide operands ('r' registers) for otherwise
> +identical operations. ``ALU64`` instructions belong to the
>  base64 conformance group unless noted otherwise.
> -The 'code' field encodes the operation as below, where 'src' refers to the
> +The 'code' field encodes the operation as below, where 'src' refers to
>  the source operand and 'dst' refers to the value of the destination
>  register.

This is fine.

>
> +.. note:: BPF ISA is unique as it uses "Pseudo-C" notation for the assembly
> +          instructions. In the table below, the column "name" specifies the
> +          encoding names. Assembly instructions (as generated by compilers)
> +          are specified in the description column for some cases. Description
> +          of ``DIV/SDIV``, ``MOD/SMOD`` includes additional semantic logic,
> +          not actual assembly.

but I don't understand the point of this paragraph.
It reads quite subjective and doesn't really explain anything.
With or without it the document is still the same.

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

[Alexei Starovoitov]

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

pw-bot: cr

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

[Vineet Gupta]

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

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

[Vineet Gupta]

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

-- 
Bpf mailing list -- bpf@ietf.org
To unsubscribe send an email to bpf-leave@ietf.org