| Message ID | 20230730035156.2728106-2-hawkinsw@obs.cr (mailing list archive) |
|---|---|
| State | Changes Requested |
| Delegated to: | BPF |
| Headers | show |
| Series | Formalize type notation and function semantics in ISA standard | expand |
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
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
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
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(-)