BPF documentation improvements
Subsystems (3)
v3 cover BPF documentation improvements
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(-)
Signature · 1 line
2.53.0
PATCH v3 1/2 bpf, doc: Clarify Pseudo-C notation and w vs r register usage
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.
---
No changes since v2
--- .../bpf/standardization/instruction-set.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-)
Documentation/bpf/standardization/instruction-set.rst +11 -3
@@ -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 ===== ===== ======= ===================================================================================
Signature · 1 line
2.53.0
Re: [PATCH v3 1/2] bpf, doc: Clarify Pseudo-C notation and w vs r register usage
Quoted 21 lines · 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 <[email protected]>---
No changes since v2--- .../bpf/standardization/instruction-set.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-)Documentation/bpf/standardization/instruction-set.rst +0
-0@@ -315,13 +315,21 @@ For arithmetic and jump instructions (``ALU``, ``ALU64``, ``JMP`` and Arithmetic instructions -----------------------
Documentation/bpf/standardization/instruction-set.rst For arithmetic and jump instructions (``ALU``, ``ALU64``, ``JMP`` and · line 324
Quoted 10 lines
Documentation/bpf/standardization/instruction-set.rst +4
-3-``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.
Documentation/bpf/standardization/instruction-set.rst For arithmetic and jump instructions (``ALU``, ``ALU64``, ``JMP`` and · line 331
Quoted 7 lines
Documentation/bpf/standardization/instruction-set.rst +6
-0+.. 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.
PATCH v3 2/2 bpf, doc: Improve MOV/MOVSX documentation and add examples
In reply to 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.
---
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(-)
Documentation/bpf/standardization/instruction-set.rst +39 -10
@@ -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::
Signature · 1 line
2.53.0
Re: [PATCH v3 2/2] bpf, doc: Improve MOV/MOVSX documentation and add examples
Quoted 67 lines · 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 <[email protected]>---
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(-)Documentation/bpf/standardization/instruction-set.rst +21
-7@@ -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
Documentation/bpf/standardization/instruction-set.rst etc. This specification requires that signed modulo MUST use truncated division · line 455
Quoted 10 lines
Documentation/bpf/standardization/instruction-set.rst +10
-0+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
Quoted 64 lines · Alexei Starovoitov
Quoted 63 lines · 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 <[email protected]>---
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(-)Documentation/bpf/standardization/instruction-set.rst +18
-7@@ -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
Quoted 14 lines
Documentation/bpf/standardization/instruction-set.rst etc. This specification requires that signed modulo MUST use truncated division · line 455
Quoted 13 lines
Documentation/bpf/standardization/instruction-set.rst +13
-0+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
Quoted 5 lines
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