[1/1] bpf, docs: Specify twos complement as format for signed integers

Commit Message

Will Hawkins July 10, 2023, 9:58 p.m. UTC

In the documentation of the eBPF ISA it is unspecified how integers are
represented. Specify that twos complement is used.

Signed-off-by: Will Hawkins <[e-mail]>
---
 Documentation/bpf/instruction-set.rst | 5 +++++
 1 file changed, 5 insertions(+)

Comments

Alexei Starovoitov July 11, 2023, 3 a.m. UTC | #1

On Mon, Jul 10, 2023 at 2:58 PM Will Hawkins <[e-mail]> wrote:
>
> In the documentation of the eBPF ISA it is unspecified how integers are
> represented. Specify that twos complement is used.
>
> Signed-off-by: Will Hawkins <[e-mail]>
> ---
>  Documentation/bpf/instruction-set.rst | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
> index 751e657973f0..63dfcba5eb9a 100644
> --- a/Documentation/bpf/instruction-set.rst
> +++ b/Documentation/bpf/instruction-set.rst
> @@ -173,6 +173,11 @@ BPF_ARSH  0xc0   sign extending dst >>= (src & mask)
>  BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
>  ========  =====  ==========================================================
>
> +eBPF supports 32- and 64-bit signed and unsigned integers. It does
> +not support floating-point data types. All signed integers are represented in
> +twos-complement format where the sign bit is stored in the most-significant
> +bit.

Could you point to another ISA document (like x86, arm, ...) that
talks about signed and unsigned integers?

Will Hawkins July 11, 2023, 3:19 a.m. UTC | #2

On Mon, Jul 10, 2023 at 11:00 PM Alexei Starovoitov
<[e-mail]> wrote:
>
> On Mon, Jul 10, 2023 at 2:58 PM Will Hawkins <[e-mail]> wrote:
> >
> > In the documentation of the eBPF ISA it is unspecified how integers are
> > represented. Specify that twos complement is used.
> >
> > Signed-off-by: Will Hawkins <[e-mail]>
> > ---
> >  Documentation/bpf/instruction-set.rst | 5 +++++
> >  1 file changed, 5 insertions(+)
> >
> > diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
> > index 751e657973f0..63dfcba5eb9a 100644
> > --- a/Documentation/bpf/instruction-set.rst
> > +++ b/Documentation/bpf/instruction-set.rst
> > @@ -173,6 +173,11 @@ BPF_ARSH  0xc0   sign extending dst >>= (src & mask)
> >  BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
> >  ========  =====  ==========================================================
> >
> > +eBPF supports 32- and 64-bit signed and unsigned integers. It does
> > +not support floating-point data types. All signed integers are represented in
> > +twos-complement format where the sign bit is stored in the most-significant
> > +bit.
>
> Could you point to another ISA document (like x86, arm, ...) that
> talks about signed and unsigned integers?

Thank you for the reply. I hope that this change is useful. I proposed
this change to mimic the documentation of "Numeric Data Types" in
Volume 1, Chapter 4 of "Intel® 64 and IA-32 Architectures Software
Developer’s Manual" [1].

[1] https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html

Will Hawkins July 11, 2023, 3:24 a.m. UTC | #3

On Mon, Jul 10, 2023 at 11:19 PM Will Hawkins <[e-mail]> wrote:
>
> On Mon, Jul 10, 2023 at 11:00 PM Alexei Starovoitov
> <[e-mail]> wrote:
> >
> > On Mon, Jul 10, 2023 at 2:58 PM Will Hawkins <[e-mail]> wrote:
> > >
> > > In the documentation of the eBPF ISA it is unspecified how integers are
> > > represented. Specify that twos complement is used.
> > >
> > > Signed-off-by: Will Hawkins <[e-mail]>
> > > ---
> > >  Documentation/bpf/instruction-set.rst | 5 +++++
> > >  1 file changed, 5 insertions(+)
> > >
> > > diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
> > > index 751e657973f0..63dfcba5eb9a 100644
> > > --- a/Documentation/bpf/instruction-set.rst
> > > +++ b/Documentation/bpf/instruction-set.rst
> > > @@ -173,6 +173,11 @@ BPF_ARSH  0xc0   sign extending dst >>= (src & mask)
> > >  BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
> > >  ========  =====  ==========================================================
> > >
> > > +eBPF supports 32- and 64-bit signed and unsigned integers. It does
> > > +not support floating-point data types. All signed integers are represented in
> > > +twos-complement format where the sign bit is stored in the most-significant
> > > +bit.
> >
> > Could you point to another ISA document (like x86, arm, ...) that
> > talks about signed and unsigned integers?
>
> Thank you for the reply. I hope that this change is useful. I proposed
> this change to mimic the documentation of "Numeric Data Types" in
> Volume 1, Chapter 4 of "Intel® 64 and IA-32 Architectures Software
> Developer’s Manual" [1].
>
> [1] https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html

Perhaps you would prefer that this information goes (again) in a psABI
document? If so, that's great -- I am working on a strawman version of
one as we speak, in fact.

Whatever you think is best is great -- you are the expert I am just
trying to help!

Sincerely,
Will

Will Hawkins July 11, 2023, 3:28 a.m. UTC | #4

On Mon, Jul 10, 2023 at 11:24 PM Will Hawkins <[e-mail]> wrote:
>
> On Mon, Jul 10, 2023 at 11:19 PM Will Hawkins <[e-mail]> wrote:
> >
> > On Mon, Jul 10, 2023 at 11:00 PM Alexei Starovoitov
> > <[e-mail]> wrote:
> > >
> > > On Mon, Jul 10, 2023 at 2:58 PM Will Hawkins <[e-mail]> wrote:
> > > >
> > > > In the documentation of the eBPF ISA it is unspecified how integers are
> > > > represented. Specify that twos complement is used.
> > > >
> > > > Signed-off-by: Will Hawkins <[e-mail]>
> > > > ---
> > > >  Documentation/bpf/instruction-set.rst | 5 +++++
> > > >  1 file changed, 5 insertions(+)
> > > >
> > > > diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
> > > > index 751e657973f0..63dfcba5eb9a 100644
> > > > --- a/Documentation/bpf/instruction-set.rst
> > > > +++ b/Documentation/bpf/instruction-set.rst
> > > > @@ -173,6 +173,11 @@ BPF_ARSH  0xc0   sign extending dst >>= (src & mask)
> > > >  BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
> > > >  ========  =====  ==========================================================
> > > >
> > > > +eBPF supports 32- and 64-bit signed and unsigned integers. It does
> > > > +not support floating-point data types. All signed integers are represented in
> > > > +twos-complement format where the sign bit is stored in the most-significant
> > > > +bit.
> > >
> > > Could you point to another ISA document (like x86, arm, ...) that
> > > talks about signed and unsigned integers?
> >
> > Thank you for the reply. I hope that this change is useful. I proposed
> > this change to mimic the documentation of "Numeric Data Types" in
> > Volume 1, Chapter 4 of "Intel® 64 and IA-32 Architectures Software
> > Developer’s Manual" [1].
> >
> > [1] https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html

(Apologies for a string of responses)

The RISC-V ISA specifies integer representation [1].

[1] https://riscv.org/technical/specifications/

>
> Perhaps you would prefer that this information goes (again) in a psABI
> document? If so, that's great -- I am working on a strawman version of
> one as we speak, in fact.
>
> Whatever you think is best is great -- you are the expert I am just
> trying to help!
>
> Sincerely,
> Will

Alexei Starovoitov July 11, 2023, 4:46 a.m. UTC | #5

On Mon, Jul 10, 2023 at 8:19 PM Will Hawkins <[e-mail]> wrote:
>
> On Mon, Jul 10, 2023 at 11:00 PM Alexei Starovoitov
> <[e-mail]> wrote:
> >
> > On Mon, Jul 10, 2023 at 2:58 PM Will Hawkins <[e-mail]> wrote:
> > >
> > > In the documentation of the eBPF ISA it is unspecified how integers are
> > > represented. Specify that twos complement is used.
> > >
> > > Signed-off-by: Will Hawkins <[e-mail]>
> > > ---
> > >  Documentation/bpf/instruction-set.rst | 5 +++++
> > >  1 file changed, 5 insertions(+)
> > >
> > > diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
> > > index 751e657973f0..63dfcba5eb9a 100644
> > > --- a/Documentation/bpf/instruction-set.rst
> > > +++ b/Documentation/bpf/instruction-set.rst
> > > @@ -173,6 +173,11 @@ BPF_ARSH  0xc0   sign extending dst >>= (src & mask)
> > >  BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
> > >  ========  =====  ==========================================================
> > >
> > > +eBPF supports 32- and 64-bit signed and unsigned integers. It does
> > > +not support floating-point data types. All signed integers are represented in
> > > +twos-complement format where the sign bit is stored in the most-significant
> > > +bit.
> >
> > Could you point to another ISA document (like x86, arm, ...) that
> > talks about signed and unsigned integers?
>
> Thank you for the reply. I hope that this change is useful. I proposed
> this change to mimic the documentation of "Numeric Data Types" in
> Volume 1, Chapter 4 of "Intel® 64 and IA-32 Architectures Software
> Developer’s Manual" [1].
>
> [1] https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html

I see where you got the inspiration from.
It's a "software developer's manual". Not an ISA spec.
But, say, we adopt this form and proceed to create all 500 pages of it.

SDM has this to say about pointers:
"Pointers are addresses of locations in memory.
In non-64-bit modes, the architecture defines two types of pointers: a
near pointer and a far pointer. A near pointer is a 32-bit (or 16-bit)
offset (also called an effective address) within a segment. Near
pointers are used
for all memory references in a flat memory model or for references in
a segmented model where the identity of the segment being accessed is
implied."

BPF runs on 32-bit and 64-bit CPUs, so if we document signed vs unsigned
integers we'd have to say a few words about pointers, bitfields and strings
(just like Intel SDM). Pointers in BPF are clearly lacking docs.

Beyond Vol 1, Chapter 4 there are plenty of other chapters.
Should we have an equivalent for all of them?
I think it would be great to have something for all that,
but dropping a patch or two won't get us there.
It needs to be a full time commitment with SOW, roadmap, etc.
I doubt the kernel and/or IETF process can accommodate that.

Saying it differently. What is missing in instruction-set.rst
from making an IETF standard out of it?
Does it need a signed vs unsigned SDM-like paragraph?

Let's focus on converting instruction-set.rst into a standard
as fast as possible and tackle all nice-to-have later.

Will Hawkins July 11, 2023, 5:34 a.m. UTC | #6

On Tue, Jul 11, 2023 at 12:47 AM Alexei Starovoitov
<[e-mail]> wrote:
>
> On Mon, Jul 10, 2023 at 8:19 PM Will Hawkins <[e-mail]> wrote:
> >
> > On Mon, Jul 10, 2023 at 11:00 PM Alexei Starovoitov
> > <[e-mail]> wrote:
> > >
> > > On Mon, Jul 10, 2023 at 2:58 PM Will Hawkins <[e-mail]> wrote:
> > > >
> > > > In the documentation of the eBPF ISA it is unspecified how integers are
> > > > represented. Specify that twos complement is used.
> > > >
> > > > Signed-off-by: Will Hawkins <[e-mail]>
> > > > ---
> > > >  Documentation/bpf/instruction-set.rst | 5 +++++
> > > >  1 file changed, 5 insertions(+)
> > > >
> > > > diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
> > > > index 751e657973f0..63dfcba5eb9a 100644
> > > > --- a/Documentation/bpf/instruction-set.rst
> > > > +++ b/Documentation/bpf/instruction-set.rst
> > > > @@ -173,6 +173,11 @@ BPF_ARSH  0xc0   sign extending dst >>= (src & mask)
> > > >  BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
> > > >  ========  =====  ==========================================================
> > > >
> > > > +eBPF supports 32- and 64-bit signed and unsigned integers. It does
> > > > +not support floating-point data types. All signed integers are represented in
> > > > +twos-complement format where the sign bit is stored in the most-significant
> > > > +bit.
> > >
> > > Could you point to another ISA document (like x86, arm, ...) that
> > > talks about signed and unsigned integers?
> >
> > Thank you for the reply. I hope that this change is useful. I proposed
> > this change to mimic the documentation of "Numeric Data Types" in
> > Volume 1, Chapter 4 of "Intel® 64 and IA-32 Architectures Software
> > Developer’s Manual" [1].
> >
> > [1] https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html
>
> I see where you got the inspiration from.
> It's a "software developer's manual". Not an ISA spec.
> But, say, we adopt this form and proceed to create all 500 pages of it.

Though the RISC-V ISA does include information about the integer
representation, your point is well taken.

As I said in a previous message, I am working on setting up the
skeleton for a strawman for a psABI. I will devote my efforts there
where I hope that they can be more useful.

Will

>
> SDM has this to say about pointers:
> "Pointers are addresses of locations in memory.
> In non-64-bit modes, the architecture defines two types of pointers: a
> near pointer and a far pointer. A near pointer is a 32-bit (or 16-bit)
> offset (also called an effective address) within a segment. Near
> pointers are used
> for all memory references in a flat memory model or for references in
> a segmented model where the identity of the segment being accessed is
> implied."
>
> BPF runs on 32-bit and 64-bit CPUs, so if we document signed vs unsigned
> integers we'd have to say a few words about pointers, bitfields and strings
> (just like Intel SDM). Pointers in BPF are clearly lacking docs.
>
> Beyond Vol 1, Chapter 4 there are plenty of other chapters.
> Should we have an equivalent for all of them?
> I think it would be great to have something for all that,
> but dropping a patch or two won't get us there.
> It needs to be a full time commitment with SOW, roadmap, etc.
> I doubt the kernel and/or IETF process can accommodate that.
>
> Saying it differently. What is missing in instruction-set.rst
> from making an IETF standard out of it?
> Does it need a signed vs unsigned SDM-like paragraph?
>
> Let's focus on converting instruction-set.rst into a standard
> as fast as possible and tackle all nice-to-have later.

Jose E. Marchesi July 11, 2023, 2:04 p.m. UTC | #7

> On Mon, Jul 10, 2023 at 2:58 PM Will Hawkins <[e-mail]> wrote:
>>
>> In the documentation of the eBPF ISA it is unspecified how integers are
>> represented. Specify that twos complement is used.
>>
>> Signed-off-by: Will Hawkins <[e-mail]>
>> ---
>>  Documentation/bpf/instruction-set.rst | 5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
>> index 751e657973f0..63dfcba5eb9a 100644
>> --- a/Documentation/bpf/instruction-set.rst
>> +++ b/Documentation/bpf/instruction-set.rst
>> @@ -173,6 +173,11 @@ BPF_ARSH  0xc0   sign extending dst >>= (src & mask)
>>  BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
>>  ========  =====  ==========================================================
>>
>> +eBPF supports 32- and 64-bit signed and unsigned integers. It does
>> +not support floating-point data types. All signed integers are represented in
>> +twos-complement format where the sign bit is stored in the most-significant
>> +bit.
>
> Could you point to another ISA document (like x86, arm, ...) that
> talks about signed and unsigned integers?

AFAIK the only signedness encoding aspect that is always found in ISA
specifications and should be specified is how numerical immediates are
encoded in stored instructions.

But that has nothing to do with "data types".

Alexei Starovoitov July 11, 2023, 7:56 p.m. UTC | #8

On Tue, Jul 11, 2023 at 7:04 AM Jose E. Marchesi <[e-mail]> wrote:
>
>
> > On Mon, Jul 10, 2023 at 2:58 PM Will Hawkins <[e-mail]> wrote:
> >>
> >> In the documentation of the eBPF ISA it is unspecified how integers are
> >> represented. Specify that twos complement is used.
> >>
> >> Signed-off-by: Will Hawkins <[e-mail]>
> >> ---
> >>  Documentation/bpf/instruction-set.rst | 5 +++++
> >>  1 file changed, 5 insertions(+)
> >>
> >> diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
> >> index 751e657973f0..63dfcba5eb9a 100644
> >> --- a/Documentation/bpf/instruction-set.rst
> >> +++ b/Documentation/bpf/instruction-set.rst
> >> @@ -173,6 +173,11 @@ BPF_ARSH  0xc0   sign extending dst >>= (src & mask)
> >>  BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
> >>  ========  =====  ==========================================================
> >>
> >> +eBPF supports 32- and 64-bit signed and unsigned integers. It does
> >> +not support floating-point data types. All signed integers are represented in
> >> +twos-complement format where the sign bit is stored in the most-significant
> >> +bit.
> >
> > Could you point to another ISA document (like x86, arm, ...) that
> > talks about signed and unsigned integers?
>
> AFAIK the only signedness encoding aspect that is always found in ISA
> specifications and should be specified is how numerical immediates are
> encoded in stored instructions.
>
> But that has nothing to do with "data types".

+1 :)

Patch

diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
index 751e657973f0..63dfcba5eb9a 100644
--- a/Documentation/bpf/instruction-set.rst
+++ b/Documentation/bpf/instruction-set.rst
@@ -173,6 +173,11 @@  BPF_ARSH  0xc0   sign extending dst >>= (src & mask)
 BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
 ========  =====  ==========================================================
 
+eBPF supports 32- and 64-bit signed and unsigned integers. It does
+not support floating-point data types. All signed integers are represented in
+twos-complement format where the sign bit is stored in the most-significant
+bit.
+
 Underflow and overflow are allowed during arithmetic operations, meaning
 the 64-bit or 32-bit value will wrap. If eBPF program execution would
 result in division by zero, the destination register is instead set to zero.