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 | 82 +++++++++++++++++--
1 file changed, 74 insertions(+), 8 deletions(-)
Changelog:
v1 -> v2:
- Remove change to Sphinx version
- Address David's comments
- Address Dave's comments
v2 -> v3:
- Add information about sign-extending
v3 -> v4:
- Address David's helpful comments!
- Remove part 2 (re: sign extension)
diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index 655494ac7af6..25be958130dc 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -10,9 +10,71 @@ 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 expository,
+mnemonic functions when describing the semantics of instructions.
+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 the notation `SN` to specify
+a type's signedness (`S`) and bit width (`N`), respectively.
+
+.. table:: Meaning of signedness notation.
+
+ ==== =========
+ `S` Meaning
+ ==== =========
+ `u` unsigned
+ `s` signed
+ ==== =========
+
+.. table:: Meaning of bit-width notation.
+
+ ===== =========
+ `N` 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
================================
@@ -252,19 +314,23 @@ are supported: 16, 32 and 64.
Examples:
-``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means::
+``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means::
dst = htole16(dst)
+ dst = htole32(dst)
+ dst = htole64(dst)
-``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means::
+``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 16/32/64 means::
+ dst = htobe16(dst)
+ dst = htobe32(dst)
dst = htobe64(dst)
``BPF_ALU64 | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means::
- dst = bswap16 dst
- dst = bswap32 dst
- dst = bswap64 dst
+ dst = bswap16(dst)
+ dst = bswap32(dst)
+ dst = bswap64(dst)
Jump instructions
-----------------
--
2.41.0
