summaryrefslogtreecommitdiff
path: root/Documentation/bpf
diff options
context:
space:
mode:
authorWill Hawkins <hawkinsw@obs.cr>2023-08-07 17:06:48 +0300
committerMartin KaFai Lau <martin.lau@kernel.org>2023-08-08 01:13:26 +0300
commit2369e52657d371c58da0b826f8b87f01611cfc59 (patch)
treeeab83b7e56738d67342a4128344f3e628301b4b0 /Documentation/bpf
parent1e8e2efb34023c5113ec679eae3c59ae2cd57b13 (diff)
downloadlinux-2369e52657d371c58da0b826f8b87f01611cfc59.tar.xz
bpf, docs: Formalize type notation and function semantics in ISA standard
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> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/r/20230807140651.122484-1-hawkinsw@obs.cr Signed-off-by: Martin KaFai Lau <martin.lau@kernel.org>
Diffstat (limited to 'Documentation/bpf')
-rw-r--r--Documentation/bpf/standardization/instruction-set.rst82
1 files changed, 74 insertions, 8 deletions
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
-----------------