| Message ID | 20230805030921.52035-2-hawkinsw@obs.cr (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | BPF |
| Headers | show |
| Series | [v3,1/2] bpf, docs: Formalize type notation and function semantics in ISA standard | expand |
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
On Sat, Aug 5, 2023 at 10:18 AM David Vernet <void@manifault.com> wrote: > > 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. Agree -- sorry for adding it to this set. It was contingent on the first going on so that there was not a merge conflict so I just added it here. In v3 of the patch I will make the change!! > > - 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? Absolutely! Sorry that I missed them! > > Thanks, > David
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
Signed-off-by: Will Hawkins <hawkinsw@obs.cr> --- .../bpf/standardization/instruction-set.rst | 31 ++++++++++++++++--- 1 file changed, 26 insertions(+), 5 deletions(-)