Skip to contentSkip to conversation

event more eBPF instruction set documentation improvements

PATCH Applied Christoph Hellwig 3 participants 10 messages Jan 31, 2022 – Feb 3, 2022

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

Hi all,

this series adds further improves the eBPF instruction set documentation. It documents the byte swap instructions and polishes up the load and store section.

Diffstat:

 instruction-set.rst |  215 ++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 151 insertions(+), 64 deletions(-)
#1 lore raw

PATCH 1/5 bpf, docs: Document the byte swapping instructions

Add a section to document the byte swapping instructions.

---
 Documentation/bpf/instruction-set.rst | 44 ++++++++++++++++++++++++---
 1 file changed, 40 insertions(+), 4 deletions(-)
Documentation/bpf/instruction-set.rst +40 -4
index 3704836fe6df6..87f6ad62633a5 100644
@@ -82,9 +82,9 @@ BPF_ALU uses 32-bit wide operands while BPF_ALU64 uses 64-bit wide operands for
 otherwise identical operations.
 The code field encodes the operation as below:
 
-  ========  =====  ==========================
+  ========  =====  =================================================
   code      value  description
-  ========  =====  ==========================
+  ========  =====  =================================================
   BPF_ADD   0x00   dst += src
   BPF_SUB   0x10   dst -= src
   BPF_MUL   0x20   dst \*= src
@@ -98,8 +98,8 @@ The code field encodes the operation as below:
   BPF_XOR   0xa0   dst ^= src
   BPF_MOV   0xb0   dst = src
   BPF_ARSH  0xc0   sign extending shift right
-  BPF_END   0xd0   endianness conversion
-  ========  =====  ==========================
+  BPF_END   0xd0   byte swap operations (see separate section below)
+  ========  =====  =================================================
 
 BPF_ADD | BPF_X | BPF_ALU means::
 
@@ -118,6 +118,42 @@ BPF_XOR | BPF_K | BPF_ALU64 means::
   src_reg = src_reg ^ imm32
 
 
+Byte swap instructions
+----------------------
+
+The byte swap instructions use an instruction class of ``BFP_ALU`` and a 4-bit
+code field of ``BPF_END``.
+
+The byte swap instructions instructions operate on the destination register
+only and do not use a separate source register or immediate value.
+
+The 1-bit source operand field in the opcode is used to to select what byte
+order the operation convert from or to:
+
+  =========  =====  =================================================
+  source     value  description
+  =========  =====  =================================================
+  BPF_TO_LE  0x00   convert between host byte order and little endian
+  BPF_TO_BE  0x08   convert between host byte order and big endian
+  =========  =====  =================================================
+
+The imm field encodes the width of the swap operations.  The following widths
+are supported: 16, 32 and 64.
+
+Examples:
+
+``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means::
+
+  dst_reg = htole16(dst_reg)
+
+``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means::
+
+  dst_reg = htobe64(dst_reg)
+
+``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and
+``BPF_TO_LE`` respetively.
+
+
 Jump instructions
 -----------------
 
Signature · 1 line
2.30.2
#2 lore raw

Re: [PATCH 1/5] bpf, docs: Document the byte swapping instructions

This series was applied to bpf/bpf-next.git (master) by Alexei Starovoitov <[email protected]>:

Hello:

This series was applied to bpf/bpf-next.git (master) by Alexei Starovoitov <[email protected]>:

Quoted 6 lines · On Mon, 31 Jan 2022 19:36:34 +0100 you wrote:

Add a section to document the byte swapping instructions.

---
 Documentation/bpf/instruction-set.rst | 44 ++++++++++++++++++++++++---
 1 file changed, 40 insertions(+), 4 deletions(-)

Here is the summary with links:
- [1/5] bpf, docs: Document the byte swapping instructions

    https://git.kernel.org/bpf/bpf-next/c/dd33fb571f5c
  - [2/5] bpf, docs: Better document the regular load and store instructions
    https://git.kernel.org/bpf/bpf-next/c/63d8c242b9a5
  - [3/5] bpf, docs: Better document the legacy packet access instruction
    https://git.kernel.org/bpf/bpf-next/c/15175336270a
  - [4/5] bpf, docs: Better document the extended instruction format
    https://git.kernel.org/bpf/bpf-next/c/5ca15b8a939f
  - [5/5] bpf, docs: Better document the atomic instructions
    https://git.kernel.org/bpf/bpf-next/c/594d32348556

You are awesome, thank you!

Signature · 2 lines
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html
#3 lore raw

PATCH 2/5 bpf, docs: Better document the regular load and store instructions

In reply to Christoph Hellwig

Add a separate section and a little intro blurb for the regular load and store instructions.

---
 Documentation/bpf/instruction-set.rst | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)
Documentation/bpf/instruction-set.rst +12 -5
index 87f6ad62633a5..03da885301722 100644
@@ -215,23 +215,30 @@ The mode modifier is one of:
   BPF_IMM        0x00   used for 64-bit mov
   BPF_ABS        0x20   legacy BPF packet access
   BPF_IND        0x40   legacy BPF packet access
-  BPF_MEM        0x60   all normal load and store operations
+  BPF_MEM        0x60   regular load and store operations
   BPF_ATOMIC     0xc0   atomic operations
   =============  =====  ====================================
 
-BPF_MEM | <size> | BPF_STX means::
+
+Regular load and store operations
+---------------------------------
+
+The ``BPF_MEM`` mode modifier is used to encode regular load and store
+instructions that transfer data between a register and memory.
+
+``BPF_MEM | <size> | BPF_STX`` means::
 
   *(size *) (dst_reg + off) = src_reg
 
-BPF_MEM | <size> | BPF_ST means::
+``BPF_MEM | <size> | BPF_ST`` means::
 
   *(size *) (dst_reg + off) = imm32
 
-BPF_MEM | <size> | BPF_LDX means::
+``BPF_MEM | <size> | BPF_LDX`` means::
 
   dst_reg = *(size *) (src_reg + off)
 
-Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW.
+Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``.
 
 Atomic operations
 -----------------
Signature · 1 line
2.30.2
#4 lore raw

PATCH 3/5 bpf, docs: Better document the legacy packet access instruction

In reply to Christoph Hellwig

Use consistent terminology and structured RST elements to better document these two oddball instructions.

---
 Documentation/bpf/instruction-set.rst | 54 ++++++++++++++++-----------
 1 file changed, 32 insertions(+), 22 deletions(-)
Documentation/bpf/instruction-set.rst +32 -22
index 03da885301722..b3c2621216c97 100644
@@ -213,8 +213,8 @@ The mode modifier is one of:
   mode modifier  value  description
   =============  =====  ====================================
   BPF_IMM        0x00   used for 64-bit mov
-  BPF_ABS        0x20   legacy BPF packet access
-  BPF_IND        0x40   legacy BPF packet access
+  BPF_ABS        0x20   legacy BPF packet access (absolute)
+  BPF_IND        0x40   legacy BPF packet access (indirect)
   BPF_MEM        0x60   regular load and store operations
   BPF_ATOMIC     0xc0   atomic operations
   =============  =====  ====================================
@@ -294,29 +294,39 @@ eBPF has one 16-byte instruction: ``BPF_LD | BPF_DW | BPF_IMM`` which consists
 of two consecutive ``struct bpf_insn`` 8-byte blocks and interpreted as single
 instruction that loads 64-bit immediate value into a dst_reg.
 
-Packet access instructions
---------------------------
+Legacy BPF Packet access instructions
+-------------------------------------
 
-eBPF has two non-generic instructions: (BPF_ABS | <size> | BPF_LD) and
-(BPF_IND | <size> | BPF_LD) which are used to access packet data.
+eBPF has special instructions for access to packet data that have been
+carried over from classic BPF to retain the performance of legacy socket
+filters running in the eBPF interpreter.
 
-They had to be carried over from classic BPF to have strong performance of
-socket filters running in eBPF interpreter. These instructions can only
-be used when interpreter context is a pointer to ``struct sk_buff`` and
-have seven implicit operands. Register R6 is an implicit input that must
-contain pointer to sk_buff. Register R0 is an implicit output which contains
-the data fetched from the packet. Registers R1-R5 are scratch registers
-and must not be used to store the data across BPF_ABS | BPF_LD or
-BPF_IND | BPF_LD instructions.
+The instructions come in two forms: ``BPF_ABS | <size> | BPF_LD`` and
+``BPF_IND | <size> | BPF_LD``.
 
-These instructions have implicit program exit condition as well. When
-eBPF program is trying to access the data beyond the packet boundary,
-the interpreter will abort the execution of the program. JIT compilers
-therefore must preserve this property. src_reg and imm32 fields are
-explicit inputs to these instructions.
+These instructions are used to access packet data and can only be used when
+the interpreter context is a pointer to networking packet.  ``BPF_ABS``
+accesses packet data at an absolute offset specified by the immediate data
+and ``BPF_IND`` access packet data at an offset that includes the value of
+a register in addition to the immediate data.
 
-For example, BPF_IND | BPF_W | BPF_LD means::
+These instructions have seven implicit operands:
 
-  R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + src_reg + imm32))
+ * Register R6 is an implicit input that must contain pointer to a
+   struct sk_buff.
+ * Register R0 is an implicit output which contains the data fetched from
+   the packet.
+ * Registers R1-R5 are scratch registers that are clobbered after a call to
+   ``BPF_ABS | BPF_LD`` or ``BPF_IND`` | BPF_LD instructions.
+
+These instructions have an implicit program exit condition as well. When an
+eBPF program is trying to access the data beyond the packet boundary, the
+interpreter will abort the execution of the program.
+
+``BPF_ABS | BPF_W | BPF_LD`` means::
 
-and R1 - R5 are clobbered.
+  R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + imm32))
+
+``BPF_IND | BPF_W | BPF_LD`` means::
+
+  R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + src_reg + imm32))
Signature · 1 line
2.30.2
#5 lore raw

Re: [PATCH 3/5] bpf, docs: Better document the legacy packet access instruction

Quoted 2 lines · Christoph Hellwig
Documentation/bpf/instruction-set.rst +2 -0
+These instructions are used to access packet data and can only be used when
+the interpreter context is a pointer to networking packet.  ``BPF_ABS``

...

Documentation/bpf/instruction-set.rst eBPF has one 16-byte instruction: ``BPF_LD | BPF_DW | BPF_IMM`` which consists · line 324

Quoted 3 lines
Documentation/bpf/instruction-set.rst +3 -0
+These instructions have an implicit program exit condition as well. When an
+eBPF program is trying to access the data beyond the packet boundary, the
+interpreter will abort the execution of the program.

These two places make it sound like it's interpreter only behavior. I've reworded it like:
-the interpreter context is a pointer to networking packet. ``BPF_ABS`` +the program context is a pointer to networking packet. ``BPF_ABS``

-interpreter will abort the execution of the program. +program execution will be aborted.

and pushed to bpf-next with the rest of patches.

#6 lore raw

Re: [PATCH 3/5] bpf, docs: Better document the legacy packet access instruction

Quoted 9 lines · Alexei Starovoitov

These two places make it sound like it's interpreter only behavior. I've reworded it like:

(quoted diff) +2 -2
-the interpreter context is a pointer to networking packet.  ``BPF_ABS``
+the program context is a pointer to networking packet.  ``BPF_ABS``
 
-interpreter will abort the execution of the program.
+program execution will be aborted.

and pushed to bpf-next with the rest of patches.

The interpreter thing is actually unchanged from the old text, but I totally agree with your fixup. Thanks!

#7 lore raw

Re: [PATCH 3/5] bpf, docs: Better document the legacy packet access instruction

Quoted 7 lines · Christoph Hellwig
Quoted 5 lines · Alexei Starovoitov

These two places make it sound like it's interpreter only behavior. I've reworded it like:

(quoted diff) +1 -1
-the interpreter context is a pointer to networking packet.  ``BPF_ABS``
+the program context is a pointer to networking packet.  ``BPF_ABS``
Quoted 7 lines
Quoted 4 lines
(quoted diff) +1 -1
-interpreter will abort the execution of the program.
+program execution will be aborted.

and pushed to bpf-next with the rest of patches.

The interpreter thing is actually unchanged from the old text, but I totally agree with your fixup. Thanks!

The old doc had:
"the interpreter will abort the execution of the program. JIT compilers therefore must preserve this property."

Since the latter sentence is now gone the former got ambiguous.

#8 lore raw

PATCH 4/5 bpf, docs: Better document the extended instruction format

In reply to Christoph Hellwig

In addition to the normal 64-bit instruction encoding, eBPF also has a single instruction that uses a second 64-bit bits for a second immediate value. Instead of only documenting this format deep down in the document mention it in the instruction encoding section.

---
 Documentation/bpf/instruction-set.rst | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)
Documentation/bpf/instruction-set.rst +19 -7
index b3c2621216c97..048aea0952a2e 100644
@@ -22,7 +22,13 @@ necessary across calls.
 Instruction encoding
 ====================
 
-eBPF uses 64-bit instructions with the following encoding:
+eBPF has two instruction encodings:
+
+ * the basic instruction encoding, which uses 64 bits to encode an instruction
+ * the wide instruction encoding, which appends a second 64-bit immediate value
+   (imm64) after the basic instruction for a total of 128 bits.
+
+The basic instruction encoding looks as follows:
 
  =============  =======  ===============  ====================  ============
  32 bits (MSB)  16 bits  4 bits           4 bits                8 bits (LSB)
@@ -212,7 +218,7 @@ The mode modifier is one of:
   =============  =====  ====================================
   mode modifier  value  description
   =============  =====  ====================================
-  BPF_IMM        0x00   used for 64-bit mov
+  BPF_IMM        0x00   64-bit immediate instructions
   BPF_ABS        0x20   legacy BPF packet access (absolute)
   BPF_IND        0x40   legacy BPF packet access (indirect)
   BPF_MEM        0x60   regular load and store operations
@@ -287,12 +293,18 @@ You may encounter ``BPF_XADD`` - this is a legacy name for ``BPF_ATOMIC``,
 referring to the exclusive-add operation encoded when the immediate field is
 zero.
 
-16-byte instructions
---------------------
+64-bit immediate instructions
+-----------------------------
+
+Instructions with the ``BPF_IMM`` mode modifier use the wide instruction
+encoding for an extra imm64 value.
+
+There is currently only one such instruction.
+
+``BPF_LD | BPF_DW | BPF_IMM`` means::
+
+  dst_reg = imm64
 
-eBPF has one 16-byte instruction: ``BPF_LD | BPF_DW | BPF_IMM`` which consists
-of two consecutive ``struct bpf_insn`` 8-byte blocks and interpreted as single
-instruction that loads 64-bit immediate value into a dst_reg.
 
 Legacy BPF Packet access instructions
 -------------------------------------
Signature · 1 line
2.30.2
#9 lore raw

PATCH 5/5 bpf, docs: Better document the atomic instructions

In reply to Christoph Hellwig

Use proper tables and RST markup to document the atomic instructions in a structured way.

---
 Documentation/bpf/instruction-set.rst | 76 +++++++++++++++++----------
 1 file changed, 49 insertions(+), 27 deletions(-)
Documentation/bpf/instruction-set.rst +49 -27
index 048aea0952a2e..4e79a77febd43 100644
@@ -249,39 +249,65 @@ Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``.
 Atomic operations
 -----------------
 
-eBPF includes atomic operations, which use the immediate field for extra
-encoding::
+Atomic operations are operations that operate on memory and can not be
+interrupted or corrupted by other access to the same memory region
+by other eBPF programs or means outside of this specification.
 
-   .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_W  | BPF_STX: lock xadd *(u32 *)(dst_reg + off16) += src_reg
-   .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_DW | BPF_STX: lock xadd *(u64 *)(dst_reg + off16) += src_reg
+All atomic operations supported by eBPF are encoded as store operations
+that use the ``BPF_ATOMIC`` mode modifier as follows:
 
-The basic atomic operations supported are::
+  * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations
+  * ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations
+  * 8-bit and 16-bit wide atomic operations are not supported.
 
-    BPF_ADD
-    BPF_AND
-    BPF_OR
-    BPF_XOR
+The imm field is used to encode the actual atomic operation.
+Simple atomic operation use a subset of the values defined to encode
+arithmetic operations in the imm field to encode the atomic operation:
 
-Each having equivalent semantics with the ``BPF_ADD`` example, that is: the
-memory location addresed by ``dst_reg + off`` is atomically modified, with
-``src_reg`` as the other operand. If the ``BPF_FETCH`` flag is set in the
-immediate, then these operations also overwrite ``src_reg`` with the
-value that was in memory before it was modified.
+  ========  =====  ===========
+  imm       value  description
+  ========  =====  ===========
+  BPF_ADD   0x00   atomic add
+  BPF_OR    0x40   atomic or
+  BPF_AND   0x50   atomic and
+  BPF_XOR   0xa0   atomic xor
+  ========  =====  ===========
 
-The more special operations are::
 
-    BPF_XCHG
+``BPF_ATOMIC | BPF_W  | BPF_STX`` with imm = BPF_ADD means::
 
-This atomically exchanges ``src_reg`` with the value addressed by ``dst_reg +
-off``. ::
+  *(u32 *)(dst_reg + off16) += src_reg
 
-    BPF_CMPXCHG
+``BPF_ATOMIC | BPF_DW | BPF_STX`` with imm = BPF ADD means::
 
-This atomically compares the value addressed by ``dst_reg + off`` with
-``R0``. If they match it is replaced with ``src_reg``. In either case, the
-value that was there before is zero-extended and loaded back to ``R0``.
+  *(u64 *)(dst_reg + off16) += src_reg
 
-Note that 1 and 2 byte atomic operations are not supported.
+``BPF_XADD`` is a deprecated name for ``BPF_ATOMIC | BPF_ADD``.
+
+In addition to the simple atomic operations, there also is a modifier and
+two complex atomic operations:
+
+  ===========  ================  ===========================
+  imm          value             description
+  ===========  ================  ===========================
+  BPF_FETCH    0x01              modifier: return old value
+  BPF_XCHG     0xe0 | BPF_FETCH  atomic exchange
+  BPF_CMPXCHG  0xf0 | BPF_FETCH  atomic compare and exchange
+  ===========  ================  ===========================
+
+The ``BPF_FETCH`` modifier is optional for simple atomic operations, and
+always set for the complex atomic operations.  If the ``BPF_FETCH`` flag
+is set, then the operation also overwrites ``src_reg`` with the value that
+was in memory before it was modified.
+
+The ``BPF_XCHG`` operation atomically exchanges ``src_reg`` with the value
+addressed by ``dst_reg + off``.
+
+The ``BPF_CMPXCHG`` operation atomically compares the value addressed by
+``dst_reg + off`` with ``R0``. If they match, the value addressed by
+``dst_reg + off`` is replaced with ``src_reg``. In either case, the
+value that was at ``dst_reg + off`` before the operation is zero-extended
+and loaded back to ``R0``.
 
 Clang can generate atomic instructions by default when ``-mcpu=v3`` is
 enabled. If a lower version for ``-mcpu`` is set, the only atomic instruction
@@ -289,10 +315,6 @@ Clang can generate is ``BPF_ADD`` *without* ``BPF_FETCH``. If you need to enable
 the atomics features, while keeping a lower ``-mcpu`` version, you can use
 ``-Xclang -target-feature -Xclang +alu32``.
 
-You may encounter ``BPF_XADD`` - this is a legacy name for ``BPF_ATOMIC``,
-referring to the exclusive-add operation encoded when the immediate field is
-zero.
-
 64-bit immediate instructions
 -----------------------------
 
Signature · 1 line
2.30.2