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@xxxxxx>
> ---
> .../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@xxxxxxxx
> https://www.ietf.org/mailman/listinfo/bpf
