Re: [Bpf] [PATCH v3 2/2] bpf, docs: Fix small typo and define semantics of sign extension

[David Vernet <void@manifault.com>]

On Fri, Aug 04, 2023 at 11:09:19PM -0400, Will Hawkins wrote:
> Signed-off-by: Will Hawkins <hawkinsw@obs.cr>

Hi Will,

Given that this is a separate patch, it should also have its own commit
summary as it would be merged as a separate commit to the kernel.

- David

> ---
>  .../bpf/standardization/instruction-set.rst   | 31 ++++++++++++++++---
>  1 file changed, 26 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> index fe296f35e5a7..6f3b34ef7b7c 100644
> --- a/Documentation/bpf/standardization/instruction-set.rst
> +++ b/Documentation/bpf/standardization/instruction-set.rst
> @@ -73,6 +73,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
>  ================================
>  
> @@ -263,17 +284,17 @@ 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

There are some other places where we say e.g. "sign extend", "sign
extending", etc. Can we link those places to your handy new section as
well, please?

Thanks,
David