Commit e546a119 authored by Will Hawkins's avatar Will Hawkins Committed by Martin KaFai Lau
Browse files

bpf, docs: Fix small typo and define semantics of sign extension 



Add additional precision on the semantics of the sign extension
operations in BPF. In addition, fix a very minor typo.

Signed-off-by: default avatarWill Hawkins <hawkinsw@obs.cr>
Acked-by: default avatarDavid Vernet <void@manifault.com>
Link: https://lore.kernel.org/r/20230808212503.197834-1-hawkinsw@obs.cr


Signed-off-by: default avatarMartin KaFai Lau <martin.lau@kernel.org>
parent eb62e6ae

Documentation/bpf/standardization/instruction-set.rst

+30 −9
Original line number Diff line number Diff line
@@ -76,6 +76,27 @@ Functions 
  format and returns the equivalent number with the same bit width but

  opposite endianness.





Definitions

-----------



.. glossary::



  Sign Extend

    To `sign extend an` ``X`` `-bit number, A, to a` ``Y`` `-bit number, B  ,` means to



    #. Copy all ``X`` bits from `A` to the lower ``X`` bits of `B`.

    #. Set the value of the remaining ``Y`` - ``X`` bits of `B` to the value of

       the  most-significant bit of `A`.



.. admonition:: Example



  Sign extend an 8-bit number ``A`` to a 16-bit number ``B`` on a big-endian platform:

  ::



    A:          10000110

    B: 11111111 10000110



Registers and calling convention

================================
@@ -234,7 +255,7 @@ BPF_SMOD 0x90 1 dst = (src != 0) ? (dst s% src) : dst 
BPF_XOR    0xa0   0        dst ^= src

BPF_MOV    0xb0   0        dst = src

BPF_MOVSX  0xb0   8/16/32  dst = (s8,s16,s32)src

BPF_ARSH   0xc0   0        sign extending dst >>= (src & mask)

BPF_ARSH   0xc0   0        :term:`sign extending<Sign Extend>` dst >>= (src & mask)

BPF_END    0xd0   0        byte swap operations (see `Byte swap instructions`_ below)

=========  =====  =======  ==========================================================
@@ -266,22 +287,22 @@ where '(u32)' indicates that the upper 32 bits are zeroed. 
Note that most instructions have instruction offset of 0. Only three instructions

(``BPF_SDIV``, ``BPF_SMOD``, ``BPF_MOVSX``) have a non-zero offset.



The devision and modulo operations support both unsigned and signed flavors.

The division and modulo operations support both unsigned and signed flavors.



For unsigned operations (``BPF_DIV`` and ``BPF_MOD``), for ``BPF_ALU``,

'imm' is interpreted as a 32-bit unsigned value. For ``BPF_ALU64``,

'imm' is first sign extended from 32 to 64 bits, and then interpreted as

a 64-bit unsigned value.

'imm' is first :term:`sign extended<Sign Extend>` from 32 to 64 bits, and then

interpreted as a 64-bit unsigned value.



For signed operations (``BPF_SDIV`` and ``BPF_SMOD``), for ``BPF_ALU``,

'imm' is interpreted as a 32-bit signed value. For ``BPF_ALU64``, 'imm'

is first sign extended from 32 to 64 bits, and then interpreted as a

64-bit signed value.

is first :term:`sign extended<Sign Extend>` from 32 to 64 bits, and then

interpreted as a 64-bit signed value.



The ``BPF_MOVSX`` instruction does a move operation with sign extension.

``BPF_ALU | BPF_MOVSX`` sign extends 8-bit and 16-bit operands into 32

``BPF_ALU | BPF_MOVSX`` :term:`sign extends<Sign Extend>` 8-bit and 16-bit operands into 32

bit operands, and zeroes the remaining upper 32 bits.

``BPF_ALU64 | BPF_MOVSX`` sign extends 8-bit, 16-bit, and 32-bit

``BPF_ALU64 | BPF_MOVSX`` :term:`sign extends<Sign Extend>` 8-bit, 16-bit, and 32-bit

operands into 64 bit operands.



Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31)
@@ -466,7 +487,7 @@ Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW`` and 
Sign-extension load operations

------------------------------



The ``BPF_MEMSX`` mode modifier is used to encode sign-extension load

The ``BPF_MEMSX`` mode modifier is used to encode :term:`sign-extension<Sign Extend>` load

instructions that transfer data between a register and memory.



``BPF_MEMSX | <size> | BPF_LDX`` means::