[PATCH 0/1] Formalize type notation and function semantics in ISA standard

[PATCH 0/1] Formalize type notation and function semantics in ISA standard

[Will Hawkins]

Based on a conversation with Alexei, here is an attempt at condensing
all the definitions of helper functions and type shorthands in a single
place.

I hope that this is helpful!
Will


Will Hawkins (1):
  bpf, docs: Formalize type notation and function semantics in ISA
    standard

 .../bpf/standardization/instruction-set.rst   | 65 ++++++++++++++++++-
 Documentation/sphinx/requirements.txt         |  2 +-
 2 files changed, 63 insertions(+), 4 deletions(-)

-- 
2.40.1

[Bpf] [PATCH 0/1] Formalize type notation and function semantics in ISA standard

[Will Hawkins]

Based on a conversation with Alexei, here is an attempt at condensing
all the definitions of helper functions and type shorthands in a single
place.

I hope that this is helpful!
Will


Will Hawkins (1):
  bpf, docs: Formalize type notation and function semantics in ISA
    standard

 .../bpf/standardization/instruction-set.rst   | 65 ++++++++++++++++++-
 Documentation/sphinx/requirements.txt         |  2 +-
 2 files changed, 63 insertions(+), 4 deletions(-)

-- 
2.40.1

-- 
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf

[PATCH 1/1] bpf, docs: Formalize type notation and function semantics in ISA standard

[Will Hawkins]

Give a single place where the shorthand for types are defined and the
semantics of helper functions are described.

Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
---
 .../bpf/standardization/instruction-set.rst   | 65 ++++++++++++++++++-
 Documentation/sphinx/requirements.txt         |  2 +-
 2 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index fb8154cedd84..97378388e20b 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -10,9 +10,68 @@ This document specifies version 1.0 of the eBPF instruction set.
 Documentation conventions
 =========================
 
-For brevity, this document uses the type notion "u64", "u32", etc.
-to mean an unsigned integer whose width is the specified number of bits,
-and "s32", etc. to mean a signed integer of the specified number of bits.
+For brevity and consistency, this document refers to families
+of types using a shorthand syntax and refers to several helper
+functions when explaining the semantics of opcodes. The range
+of valid values for those types and the semantics of those functions
+are defined in the following subsections.
+
+Types
+-----
+This document refers to integer types with a notation of the form `SX`
+that succinctly defines whether their values are signed or unsigned
+numbers and the bit widths:
+
+=== =======
+`S` Meaning
+=== =======
+`u` unsigned
+`s` signed
+=== =======
+
+===== =========
+`X`   Bit width
+===== =========
+`8`   8 bits
+`16`  16 bits
+`32`  32 bits
+`64`  64 bits
+`128` 128 bits
+===== =========
+
+For example, `u32` is a type whose valid values are all the 32-bit unsigned
+numbers and `s16` is a types whose valid values are all the 16-bit signed
+numbers.
+
+Functions
+---------
+* `htobe16`: Takes an unsigned 16-bit number in host-endian format and
+  returns the equivalent number as an unsigned 16-bit number in big-endian
+  format.
+* `htobe32`: Takes an unsigned 32-bit number in host-endian format and
+  returns the equivalent number as an unsigned 32-bit number in big-endian
+  format.
+* `htobe64`: Takes an unsigned 64-bit number in host-endian format and
+  returns the equivalent number as an unsigned 64-bit number in big-endian
+  format.
+* `htole16`: Takes an unsigned 16-bit number in host-endian format and
+  returns the equivalent number as an unsigned 16-bit number in little-endian
+  format.
+* `htole32`: Takes an unsigned 32-bit number in host-endian format and
+  returns the equivalent number as an unsigned 32-bit number in little-endian
+  format.
+* `htole64`: Takes an unsigned 64-bit number in host-endian format and
+  returns the equivalent number as an unsigned 64-bit number in little-endian
+  format.
+* `bswap16`: Takes an unsigned 16-bit number in either big- or little-endian
+  format and returns the equivalent number with the same bit width but
+  opposite endianness.
+* `bswap32`: Takes an unsigned 32-bit number in either big- or little-endian
+  format and returns the equivalent number with the same bit width but
+  opposite endianness.
+* `bswap64`: Takes an unsigned 64-bit number in either big- or little-endian
+  format and returns the equivalent number with the same bit width but
+  opposite endianness.
 
 Registers and calling convention
 ================================
diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 335b53df35e2..9479c5c2e338 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,3 +1,3 @@
 # jinja2>=3.1 is not compatible with Sphinx<4.0
 jinja2<3.1
-Sphinx==2.4.4
+Sphinx==7.1.1
-- 
2.40.1

[Bpf] [PATCH 1/1] bpf, docs: Formalize type notation and function semantics in ISA standard

[Will Hawkins]

Give a single place where the shorthand for types are defined and the
semantics of helper functions are described.

Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
---
 .../bpf/standardization/instruction-set.rst   | 65 ++++++++++++++++++-
 Documentation/sphinx/requirements.txt         |  2 +-
 2 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index fb8154cedd84..97378388e20b 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -10,9 +10,68 @@ This document specifies version 1.0 of the eBPF instruction set.
 Documentation conventions
 =========================
 
-For brevity, this document uses the type notion "u64", "u32", etc.
-to mean an unsigned integer whose width is the specified number of bits,
-and "s32", etc. to mean a signed integer of the specified number of bits.
+For brevity and consistency, this document refers to families
+of types using a shorthand syntax and refers to several helper
+functions when explaining the semantics of opcodes. The range
+of valid values for those types and the semantics of those functions
+are defined in the following subsections.
+
+Types
+-----
+This document refers to integer types with a notation of the form `SX`
+that succinctly defines whether their values are signed or unsigned
+numbers and the bit widths:
+
+=== =======
+`S` Meaning
+=== =======
+`u` unsigned
+`s` signed
+=== =======
+
+===== =========
+`X`   Bit width
+===== =========
+`8`   8 bits
+`16`  16 bits
+`32`  32 bits
+`64`  64 bits
+`128` 128 bits
+===== =========
+
+For example, `u32` is a type whose valid values are all the 32-bit unsigned
+numbers and `s16` is a types whose valid values are all the 16-bit signed
+numbers.
+
+Functions
+---------
+* `htobe16`: Takes an unsigned 16-bit number in host-endian format and
+  returns the equivalent number as an unsigned 16-bit number in big-endian
+  format.
+* `htobe32`: Takes an unsigned 32-bit number in host-endian format and
+  returns the equivalent number as an unsigned 32-bit number in big-endian
+  format.
+* `htobe64`: Takes an unsigned 64-bit number in host-endian format and
+  returns the equivalent number as an unsigned 64-bit number in big-endian
+  format.
+* `htole16`: Takes an unsigned 16-bit number in host-endian format and
+  returns the equivalent number as an unsigned 16-bit number in little-endian
+  format.
+* `htole32`: Takes an unsigned 32-bit number in host-endian format and
+  returns the equivalent number as an unsigned 32-bit number in little-endian
+  format.
+* `htole64`: Takes an unsigned 64-bit number in host-endian format and
+  returns the equivalent number as an unsigned 64-bit number in little-endian
+  format.
+* `bswap16`: Takes an unsigned 16-bit number in either big- or little-endian
+  format and returns the equivalent number with the same bit width but
+  opposite endianness.
+* `bswap32`: Takes an unsigned 32-bit number in either big- or little-endian
+  format and returns the equivalent number with the same bit width but
+  opposite endianness.
+* `bswap64`: Takes an unsigned 64-bit number in either big- or little-endian
+  format and returns the equivalent number with the same bit width but
+  opposite endianness.
 
 Registers and calling convention
 ================================
diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 335b53df35e2..9479c5c2e338 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,3 +1,3 @@
 # jinja2>=3.1 is not compatible with Sphinx<4.0
 jinja2<3.1
-Sphinx==2.4.4
+Sphinx==7.1.1
-- 
2.40.1

-- 
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf

Re: [Bpf] [PATCH 1/1] bpf, docs: Formalize type notation and function semantics in ISA standard

[David Vernet]

On Sat, Jul 29, 2023 at 11:51:56PM -0400, Will Hawkins wrote:
> Give a single place where the shorthand for types are defined and the
> semantics of helper functions are described.
> 
> Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
> ---
>  .../bpf/standardization/instruction-set.rst   | 65 ++++++++++++++++++-
>  Documentation/sphinx/requirements.txt         |  2 +-
>  2 files changed, 63 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> index fb8154cedd84..97378388e20b 100644
> --- a/Documentation/bpf/standardization/instruction-set.rst
> +++ b/Documentation/bpf/standardization/instruction-set.rst
> @@ -10,9 +10,68 @@ This document specifies version 1.0 of the eBPF instruction set.
>  Documentation conventions
>  =========================
>  
> -For brevity, this document uses the type notion "u64", "u32", etc.
> -to mean an unsigned integer whose width is the specified number of bits,
> -and "s32", etc. to mean a signed integer of the specified number of bits.
> +For brevity and consistency, this document refers to families
> +of types using a shorthand syntax and refers to several helper
> +functions when explaining the semantics of opcodes. The range

nit: Can we use a different term than "helper functions" here, just
because it's an overloaded term for BPF. Maybe "shorthand functions" or
"mnemonic functions"? Or just "functions"?

> +of valid values for those types and the semantics of those functions
> +are defined in the following subsections.
> +
> +Types
> +-----
> +This document refers to integer types with a notation of the form `SX`

I suggest replacing `SX` with `Sn`, as `SX` is short for sign-extension
in several instructions.

> +that succinctly defines whether their values are signed or unsigned
> +numbers and the bit widths:
> +
> +=== =======
> +`S` Meaning
> +=== =======
> +`u` unsigned
> +`s` signed
> +=== =======
> +
> +===== =========
> +`X`   Bit width
> +===== =========
> +`8`   8 bits
> +`16`  16 bits
> +`32`  32 bits
> +`64`  64 bits
> +`128` 128 bits
> +===== =========
> +
> +For example, `u32` is a type whose valid values are all the 32-bit unsigned
> +numbers and `s16` is a types whose valid values are all the 16-bit signed
> +numbers.
> +
> +Functions
> +---------
> +* `htobe16`: Takes an unsigned 16-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 16-bit number in big-endian
> +  format.
> +* `htobe32`: Takes an unsigned 32-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 32-bit number in big-endian
> +  format.
> +* `htobe64`: Takes an unsigned 64-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 64-bit number in big-endian
> +  format.
> +* `htole16`: Takes an unsigned 16-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 16-bit number in little-endian
> +  format.
> +* `htole32`: Takes an unsigned 32-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 32-bit number in little-endian
> +  format.
> +* `htole64`: Takes an unsigned 64-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 64-bit number in little-endian
> +  format.

Hmm, some of these functions aren't actually used elsewhere in the
document. Maybe update the hto{b,l}eN examples later in the Byte swap
instructions section to match bswapN where all widths are illustrated in
the example?

> +* `bswap16`: Takes an unsigned 16-bit number in either big- or little-endian
> +  format and returns the equivalent number with the same bit width but
> +  opposite endianness.
> +* `bswap32`: Takes an unsigned 32-bit number in either big- or little-endian
> +  format and returns the equivalent number with the same bit width but
> +  opposite endianness.
> +* `bswap64`: Takes an unsigned 64-bit number in either big- or little-endian
> +  format and returns the equivalent number with the same bit width but
> +  opposite endianness.
>  
>  Registers and calling convention
>  ================================
> diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
> index 335b53df35e2..9479c5c2e338 100644
> --- a/Documentation/sphinx/requirements.txt
> +++ b/Documentation/sphinx/requirements.txt
> @@ -1,3 +1,3 @@
>  # jinja2>=3.1 is not compatible with Sphinx<4.0
>  jinja2<3.1
> -Sphinx==2.4.4
> +Sphinx==7.1.1

I don't think we can unilaterally update the whole kernel docs tree to
require a new version of Sphinx like this. Could you please clarify why
you needed to update it? Was it for the tables or something?

> -- 
> 2.40.1
> 
> -- 
> Bpf mailing list
> Bpf@ietf.org
> https://www.ietf.org/mailman/listinfo/bpf

Re: [Bpf] [PATCH 1/1] bpf, docs: Formalize type notation and function semantics in ISA standard

[David Vernet]

On Sat, Jul 29, 2023 at 11:51:56PM -0400, Will Hawkins wrote:
> Give a single place where the shorthand for types are defined and the
> semantics of helper functions are described.
> 
> Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
> ---
>  .../bpf/standardization/instruction-set.rst   | 65 ++++++++++++++++++-
>  Documentation/sphinx/requirements.txt         |  2 +-
>  2 files changed, 63 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> index fb8154cedd84..97378388e20b 100644
> --- a/Documentation/bpf/standardization/instruction-set.rst
> +++ b/Documentation/bpf/standardization/instruction-set.rst
> @@ -10,9 +10,68 @@ This document specifies version 1.0 of the eBPF instruction set.
>  Documentation conventions
>  =========================
>  
> -For brevity, this document uses the type notion "u64", "u32", etc.
> -to mean an unsigned integer whose width is the specified number of bits,
> -and "s32", etc. to mean a signed integer of the specified number of bits.
> +For brevity and consistency, this document refers to families
> +of types using a shorthand syntax and refers to several helper
> +functions when explaining the semantics of opcodes. The range

nit: Can we use a different term than "helper functions" here, just
because it's an overloaded term for BPF. Maybe "shorthand functions" or
"mnemonic functions"? Or just "functions"?

> +of valid values for those types and the semantics of those functions
> +are defined in the following subsections.
> +
> +Types
> +-----
> +This document refers to integer types with a notation of the form `SX`

I suggest replacing `SX` with `Sn`, as `SX` is short for sign-extension
in several instructions.

> +that succinctly defines whether their values are signed or unsigned
> +numbers and the bit widths:
> +
> +=== =======
> +`S` Meaning
> +=== =======
> +`u` unsigned
> +`s` signed
> +=== =======
> +
> +===== =========
> +`X`   Bit width
> +===== =========
> +`8`   8 bits
> +`16`  16 bits
> +`32`  32 bits
> +`64`  64 bits
> +`128` 128 bits
> +===== =========
> +
> +For example, `u32` is a type whose valid values are all the 32-bit unsigned
> +numbers and `s16` is a types whose valid values are all the 16-bit signed
> +numbers.
> +
> +Functions
> +---------
> +* `htobe16`: Takes an unsigned 16-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 16-bit number in big-endian
> +  format.
> +* `htobe32`: Takes an unsigned 32-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 32-bit number in big-endian
> +  format.
> +* `htobe64`: Takes an unsigned 64-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 64-bit number in big-endian
> +  format.
> +* `htole16`: Takes an unsigned 16-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 16-bit number in little-endian
> +  format.
> +* `htole32`: Takes an unsigned 32-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 32-bit number in little-endian
> +  format.
> +* `htole64`: Takes an unsigned 64-bit number in host-endian format and
> +  returns the equivalent number as an unsigned 64-bit number in little-endian
> +  format.

Hmm, some of these functions aren't actually used elsewhere in the
document. Maybe update the hto{b,l}eN examples later in the Byte swap
instructions section to match bswapN where all widths are illustrated in
the example?

> +* `bswap16`: Takes an unsigned 16-bit number in either big- or little-endian
> +  format and returns the equivalent number with the same bit width but
> +  opposite endianness.
> +* `bswap32`: Takes an unsigned 32-bit number in either big- or little-endian
> +  format and returns the equivalent number with the same bit width but
> +  opposite endianness.
> +* `bswap64`: Takes an unsigned 64-bit number in either big- or little-endian
> +  format and returns the equivalent number with the same bit width but
> +  opposite endianness.
>  
>  Registers and calling convention
>  ================================
> diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
> index 335b53df35e2..9479c5c2e338 100644
> --- a/Documentation/sphinx/requirements.txt
> +++ b/Documentation/sphinx/requirements.txt
> @@ -1,3 +1,3 @@
>  # jinja2>=3.1 is not compatible with Sphinx<4.0
>  jinja2<3.1
> -Sphinx==2.4.4
> +Sphinx==7.1.1

I don't think we can unilaterally update the whole kernel docs tree to
require a new version of Sphinx like this. Could you please clarify why
you needed to update it? Was it for the tables or something?

> -- 
> 2.40.1
> 
> -- 
> Bpf mailing list
> Bpf@ietf.org
> https://www.ietf.org/mailman/listinfo/bpf

-- 
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf

Re: [Bpf] [PATCH 1/1] bpf, docs: Formalize type notation and function semantics in ISA standard

[Will Hawkins]

Thank you for the feedback! Responses inline.

On Tue, Aug 1, 2023 at 3:35 PM David Vernet <void@manifault.com> wrote:
>
> On Sat, Jul 29, 2023 at 11:51:56PM -0400, Will Hawkins wrote:
> > Give a single place where the shorthand for types are defined and the
> > semantics of helper functions are described.
> >
> > Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
> > ---
> >  .../bpf/standardization/instruction-set.rst   | 65 ++++++++++++++++++-
> >  Documentation/sphinx/requirements.txt         |  2 +-
> >  2 files changed, 63 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> > index fb8154cedd84..97378388e20b 100644
> > --- a/Documentation/bpf/standardization/instruction-set.rst
> > +++ b/Documentation/bpf/standardization/instruction-set.rst
> > @@ -10,9 +10,68 @@ This document specifies version 1.0 of the eBPF instruction set.
> >  Documentation conventions
> >  =========================
> >
> > -For brevity, this document uses the type notion "u64", "u32", etc.
> > -to mean an unsigned integer whose width is the specified number of bits,
> > -and "s32", etc. to mean a signed integer of the specified number of bits.
> > +For brevity and consistency, this document refers to families
> > +of types using a shorthand syntax and refers to several helper
> > +functions when explaining the semantics of opcodes. The range
>
> nit: Can we use a different term than "helper functions" here, just
> because it's an overloaded term for BPF. Maybe "shorthand functions" or
> "mnemonic functions"? Or just "functions"?

Great idea. I like the term mnemonic functions (given that we talk
about mnemonics with opcodes). I will go with that unless there is
additional guidance.

>
> > +of valid values for those types and the semantics of those functions
> > +are defined in the following subsections.
> > +
> > +Types
> > +-----
> > +This document refers to integer types with a notation of the form `SX`
>
> I suggest replacing `SX` with `Sn`, as `SX` is short for sign-extension
> in several instructions.

Good point! Will do!

>
> > +that succinctly defines whether their values are signed or unsigned
> > +numbers and the bit widths:
> > +
> > +=== =======
> > +`S` Meaning
> > +=== =======
> > +`u` unsigned
> > +`s` signed
> > +=== =======
> > +
> > +===== =========
> > +`X`   Bit width
> > +===== =========
> > +`8`   8 bits
> > +`16`  16 bits
> > +`32`  32 bits
> > +`64`  64 bits
> > +`128` 128 bits
> > +===== =========
> > +
> > +For example, `u32` is a type whose valid values are all the 32-bit unsigned
> > +numbers and `s16` is a types whose valid values are all the 16-bit signed
> > +numbers.
> > +
> > +Functions
> > +---------
> > +* `htobe16`: Takes an unsigned 16-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 16-bit number in big-endian
> > +  format.
> > +* `htobe32`: Takes an unsigned 32-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 32-bit number in big-endian
> > +  format.
> > +* `htobe64`: Takes an unsigned 64-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 64-bit number in big-endian
> > +  format.
> > +* `htole16`: Takes an unsigned 16-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 16-bit number in little-endian
> > +  format.
> > +* `htole32`: Takes an unsigned 32-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 32-bit number in little-endian
> > +  format.
> > +* `htole64`: Takes an unsigned 64-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 64-bit number in little-endian
> > +  format.
>
> Hmm, some of these functions aren't actually used elsewhere in the
> document. Maybe update the hto{b,l}eN examples later in the Byte swap
> instructions section to match bswapN where all widths are illustrated in
> the example?
>

Another great point. Will do!


> > +* `bswap16`: Takes an unsigned 16-bit number in either big- or little-endian
> > +  format and returns the equivalent number with the same bit width but
> > +  opposite endianness.
> > +* `bswap32`: Takes an unsigned 32-bit number in either big- or little-endian
> > +  format and returns the equivalent number with the same bit width but
> > +  opposite endianness.
> > +* `bswap64`: Takes an unsigned 64-bit number in either big- or little-endian
> > +  format and returns the equivalent number with the same bit width but
> > +  opposite endianness.
> >
> >  Registers and calling convention
> >  ================================
> > diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
> > index 335b53df35e2..9479c5c2e338 100644
> > --- a/Documentation/sphinx/requirements.txt
> > +++ b/Documentation/sphinx/requirements.txt
> > @@ -1,3 +1,3 @@
> >  # jinja2>=3.1 is not compatible with Sphinx<4.0
> >  jinja2<3.1
> > -Sphinx==2.4.4
> > +Sphinx==7.1.1
>
> I don't think we can unilaterally update the whole kernel docs tree to
> require a new version of Sphinx like this. Could you please clarify why
> you needed to update it? Was it for the tables or something?

An absolute git typo on my part. I will remove in v2.

Thanks again for the feedback!
Will


>
> > --
> > 2.40.1
> >
> > --
> > Bpf mailing list
> > Bpf@ietf.org
> > https://www.ietf.org/mailman/listinfo/bpf

Re: [Bpf] [PATCH 1/1] bpf, docs: Formalize type notation and function semantics in ISA standard

[Will Hawkins]

Thank you for the feedback! Responses inline.

On Tue, Aug 1, 2023 at 3:35 PM David Vernet <void@manifault.com> wrote:
>
> On Sat, Jul 29, 2023 at 11:51:56PM -0400, Will Hawkins wrote:
> > Give a single place where the shorthand for types are defined and the
> > semantics of helper functions are described.
> >
> > Signed-off-by: Will Hawkins <hawkinsw@obs.cr>
> > ---
> >  .../bpf/standardization/instruction-set.rst   | 65 ++++++++++++++++++-
> >  Documentation/sphinx/requirements.txt         |  2 +-
> >  2 files changed, 63 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> > index fb8154cedd84..97378388e20b 100644
> > --- a/Documentation/bpf/standardization/instruction-set.rst
> > +++ b/Documentation/bpf/standardization/instruction-set.rst
> > @@ -10,9 +10,68 @@ This document specifies version 1.0 of the eBPF instruction set.
> >  Documentation conventions
> >  =========================
> >
> > -For brevity, this document uses the type notion "u64", "u32", etc.
> > -to mean an unsigned integer whose width is the specified number of bits,
> > -and "s32", etc. to mean a signed integer of the specified number of bits.
> > +For brevity and consistency, this document refers to families
> > +of types using a shorthand syntax and refers to several helper
> > +functions when explaining the semantics of opcodes. The range
>
> nit: Can we use a different term than "helper functions" here, just
> because it's an overloaded term for BPF. Maybe "shorthand functions" or
> "mnemonic functions"? Or just "functions"?

Great idea. I like the term mnemonic functions (given that we talk
about mnemonics with opcodes). I will go with that unless there is
additional guidance.

>
> > +of valid values for those types and the semantics of those functions
> > +are defined in the following subsections.
> > +
> > +Types
> > +-----
> > +This document refers to integer types with a notation of the form `SX`
>
> I suggest replacing `SX` with `Sn`, as `SX` is short for sign-extension
> in several instructions.

Good point! Will do!

>
> > +that succinctly defines whether their values are signed or unsigned
> > +numbers and the bit widths:
> > +
> > +=== =======
> > +`S` Meaning
> > +=== =======
> > +`u` unsigned
> > +`s` signed
> > +=== =======
> > +
> > +===== =========
> > +`X`   Bit width
> > +===== =========
> > +`8`   8 bits
> > +`16`  16 bits
> > +`32`  32 bits
> > +`64`  64 bits
> > +`128` 128 bits
> > +===== =========
> > +
> > +For example, `u32` is a type whose valid values are all the 32-bit unsigned
> > +numbers and `s16` is a types whose valid values are all the 16-bit signed
> > +numbers.
> > +
> > +Functions
> > +---------
> > +* `htobe16`: Takes an unsigned 16-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 16-bit number in big-endian
> > +  format.
> > +* `htobe32`: Takes an unsigned 32-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 32-bit number in big-endian
> > +  format.
> > +* `htobe64`: Takes an unsigned 64-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 64-bit number in big-endian
> > +  format.
> > +* `htole16`: Takes an unsigned 16-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 16-bit number in little-endian
> > +  format.
> > +* `htole32`: Takes an unsigned 32-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 32-bit number in little-endian
> > +  format.
> > +* `htole64`: Takes an unsigned 64-bit number in host-endian format and
> > +  returns the equivalent number as an unsigned 64-bit number in little-endian
> > +  format.
>
> Hmm, some of these functions aren't actually used elsewhere in the
> document. Maybe update the hto{b,l}eN examples later in the Byte swap
> instructions section to match bswapN where all widths are illustrated in
> the example?
>

Another great point. Will do!


> > +* `bswap16`: Takes an unsigned 16-bit number in either big- or little-endian
> > +  format and returns the equivalent number with the same bit width but
> > +  opposite endianness.
> > +* `bswap32`: Takes an unsigned 32-bit number in either big- or little-endian
> > +  format and returns the equivalent number with the same bit width but
> > +  opposite endianness.
> > +* `bswap64`: Takes an unsigned 64-bit number in either big- or little-endian
> > +  format and returns the equivalent number with the same bit width but
> > +  opposite endianness.
> >
> >  Registers and calling convention
> >  ================================
> > diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
> > index 335b53df35e2..9479c5c2e338 100644
> > --- a/Documentation/sphinx/requirements.txt
> > +++ b/Documentation/sphinx/requirements.txt
> > @@ -1,3 +1,3 @@
> >  # jinja2>=3.1 is not compatible with Sphinx<4.0
> >  jinja2<3.1
> > -Sphinx==2.4.4
> > +Sphinx==7.1.1
>
> I don't think we can unilaterally update the whole kernel docs tree to
> require a new version of Sphinx like this. Could you please clarify why
> you needed to update it? Was it for the tables or something?

An absolute git typo on my part. I will remove in v2.

Thanks again for the feedback!
Will


>
> > --
> > 2.40.1
> >
> > --
> > Bpf mailing list
> > Bpf@ietf.org
> > https://www.ietf.org/mailman/listinfo/bpf

-- 
Bpf mailing list
Bpf@ietf.org
https://www.ietf.org/mailman/listinfo/bpf