* [PATCH 1/6] bpf, docs: Add a setion to explain the basic instruction encoding
2022-01-03 18:35 more eBPF instruction set documentation improvements Christoph Hellwig
@ 2022-01-03 18:35 ` Christoph Hellwig
2022-01-03 18:35 ` [PATCH 2/6] bpf, docs: Add subsections for ALU and JMP instructions Christoph Hellwig
` (5 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Christoph Hellwig @ 2022-01-03 18:35 UTC (permalink / raw)
To: Jonathan Corbet, Alexei Starovoitov, Daniel Borkmann, Andrii Nakryiko
Cc: Martin KaFai Lau, Song Liu, Yonghong Song, John Fastabend,
KP Singh, linux-doc, netdev, bpf
The eBPF instruction set document does not currently document the basic
instruction encoding. Add a section to do that.
Signed-off-by: Christoph Hellwig <hch@lst.de>
---
Documentation/bpf/instruction-set.rst | 16 +++++++++++++++-
1 file changed, 15 insertions(+), 1 deletion(-)
diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
index 1af51143ff9f6..80f42984b5942 100644
--- a/Documentation/bpf/instruction-set.rst
+++ b/Documentation/bpf/instruction-set.rst
@@ -19,8 +19,22 @@ The eBPF calling convention is defined as:
R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if
necessary across calls.
+Instruction encoding
+====================
+
+eBPF uses 64-bit instructions with the following encoding:
+
+ ============= ======= =============== ==================== ============
+ 32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB)
+ ============= ======= =============== ==================== ============
+ immediate offset source register destination register opcode
+ ============= ======= =============== ==================== ============
+
+Note that most instructions do not use all of the fields.
+Unused fields shall be cleared to zero.
+
Instruction classes
-===================
+-------------------
The three LSB bits of the 'opcode' field store the instruction class:
--
2.30.2
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH 2/6] bpf, docs: Add subsections for ALU and JMP instructions
2022-01-03 18:35 more eBPF instruction set documentation improvements Christoph Hellwig
2022-01-03 18:35 ` [PATCH 1/6] bpf, docs: Add a setion to explain the basic instruction encoding Christoph Hellwig
@ 2022-01-03 18:35 ` Christoph Hellwig
2022-01-03 18:35 ` [PATCH 3/6] bpf, docs: Document the opcode classes Christoph Hellwig
` (4 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Christoph Hellwig @ 2022-01-03 18:35 UTC (permalink / raw)
To: Jonathan Corbet, Alexei Starovoitov, Daniel Borkmann, Andrii Nakryiko
Cc: Martin KaFai Lau, Song Liu, Yonghong Song, John Fastabend,
KP Singh, linux-doc, netdev, bpf
Add a little more stucture to the ALU/JMP documentation with sections and
improve the example text.
Signed-off-by: Christoph Hellwig <hch@lst.de>
---
Documentation/bpf/instruction-set.rst | 52 ++++++++++++++++-----------
1 file changed, 32 insertions(+), 20 deletions(-)
diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
index 80f42984b5942..03bf3c6c55771 100644
--- a/Documentation/bpf/instruction-set.rst
+++ b/Documentation/bpf/instruction-set.rst
@@ -74,7 +74,13 @@ The 4th bit encodes the source operand:
The four MSB bits store the operation code.
-For class BPF_ALU or BPF_ALU64:
+
+Arithmetic instructions
+-----------------------
+
+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
@@ -95,7 +101,29 @@ For class BPF_ALU or BPF_ALU64:
BPF_END 0xd0 endianness conversion
======== ===== =========================
-For class BPF_JMP or BPF_JMP32:
+BPF_ADD | BPF_X | BPF_ALU means::
+
+ dst_reg = (u32) dst_reg + (u32) src_reg;
+
+BPF_ADD | BPF_X | BPF_ALU64 means::
+
+ dst_reg = dst_reg + src_reg
+
+BPF_XOR | BPF_K | BPF_ALU means::
+
+ src_reg = (u32) src_reg ^ (u32) imm32
+
+BPF_XOR | BPF_K | BPF_ALU64 means::
+
+ src_reg = src_reg ^ imm32
+
+
+Jump instructions
+-----------------
+
+BPF_JMP32 uses 32-bit wide operands while BPF_JMP uses 64-bit wide operands for
+otherwise identical operations.
+The code field encodes the operation as below:
======== ===== =========================
code value description
@@ -116,24 +144,8 @@ For class BPF_JMP or BPF_JMP32:
BPF_JSLE 0xd0 signed '<='
======== ===== =========================
-So BPF_ADD | BPF_X | BPF_ALU means::
-
- dst_reg = (u32) dst_reg + (u32) src_reg;
-
-Similarly, BPF_XOR | BPF_K | BPF_ALU means::
-
- src_reg = (u32) src_reg ^ (u32) imm32
-
-eBPF is using BPF_MOV | BPF_X | BPF_ALU to represent A = B moves. BPF_ALU64
-is used to mean exactly the same operations as BPF_ALU, but with 64-bit wide
-operands instead. So BPF_ADD | BPF_X | BPF_ALU64 means 64-bit addition, i.e.::
-
- dst_reg = dst_reg + src_reg
-
-BPF_JMP | BPF_EXIT means function exit only. The eBPF program needs to store
-the return value into register R0 before doing a BPF_EXIT. Class 6 is used as
-BPF_JMP32 to mean exactly the same operations as BPF_JMP, but with 32-bit wide
-operands for the comparisons instead.
+The eBPF program needs to store the return value into register R0 before doing a
+BPF_EXIT.
Load and store instructions
--
2.30.2
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH 3/6] bpf, docs: Document the opcode classes
2022-01-03 18:35 more eBPF instruction set documentation improvements Christoph Hellwig
2022-01-03 18:35 ` [PATCH 1/6] bpf, docs: Add a setion to explain the basic instruction encoding Christoph Hellwig
2022-01-03 18:35 ` [PATCH 2/6] bpf, docs: Add subsections for ALU and JMP instructions Christoph Hellwig
@ 2022-01-03 18:35 ` Christoph Hellwig
2022-01-03 18:35 ` [PATCH 4/6] bpf, docs: Fully document the ALU opcodes Christoph Hellwig
` (3 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Christoph Hellwig @ 2022-01-03 18:35 UTC (permalink / raw)
To: Jonathan Corbet, Alexei Starovoitov, Daniel Borkmann, Andrii Nakryiko
Cc: Martin KaFai Lau, Song Liu, Yonghong Song, John Fastabend,
KP Singh, linux-doc, netdev, bpf
Add a description for each opcode class.
Signed-off-by: Christoph Hellwig <hch@lst.de>
---
Documentation/bpf/instruction-set.rst | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
index 03bf3c6c55771..2987cbb07f7f6 100644
--- a/Documentation/bpf/instruction-set.rst
+++ b/Documentation/bpf/instruction-set.rst
@@ -38,18 +38,18 @@ Instruction classes
The three LSB bits of the 'opcode' field store the instruction class:
- ========= =====
- class value
- ========= =====
- BPF_LD 0x00
- BPF_LDX 0x01
- BPF_ST 0x02
- BPF_STX 0x03
- BPF_ALU 0x04
- BPF_JMP 0x05
- BPF_JMP32 0x06
- BPF_ALU64 0x07
- ========= =====
+ ========= ===== ===============================
+ class value description
+ ========= ===== ===============================
+ BPF_LD 0x00 non-standard load operations
+ BPF_LDX 0x01 load into register operations
+ BPF_ST 0x02 store from immediate operations
+ BPF_STX 0x03 store from register operations
+ BPF_ALU 0x04 32-bit arithmetic operations
+ BPF_JMP 0x05 64-bit jump operations
+ BPF_JMP32 0x06 32-bit jump operations
+ BPF_ALU64 0x07 64-bit arithmetic operations
+ ========= ===== ===============================
Arithmetic and jump instructions
================================
--
2.30.2
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH 4/6] bpf, docs: Fully document the ALU opcodes
2022-01-03 18:35 more eBPF instruction set documentation improvements Christoph Hellwig
` (2 preceding siblings ...)
2022-01-03 18:35 ` [PATCH 3/6] bpf, docs: Document the opcode classes Christoph Hellwig
@ 2022-01-03 18:35 ` Christoph Hellwig
2022-01-03 18:35 ` [PATCH 5/6] bpf, docs: Fully document the JMP opcodes Christoph Hellwig
` (2 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Christoph Hellwig @ 2022-01-03 18:35 UTC (permalink / raw)
To: Jonathan Corbet, Alexei Starovoitov, Daniel Borkmann, Andrii Nakryiko
Cc: Martin KaFai Lau, Song Liu, Yonghong Song, John Fastabend,
KP Singh, linux-doc, netdev, bpf
Add pseudo-code to document all the different BPF_ALU / BPF_ALU64
opcodes.
Signed-off-by: Christoph Hellwig <hch@lst.de>
---
Documentation/bpf/instruction-set.rst | 30 +++++++++++++--------------
1 file changed, 15 insertions(+), 15 deletions(-)
diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
index 2987cbb07f7f6..efba4d1931853 100644
--- a/Documentation/bpf/instruction-set.rst
+++ b/Documentation/bpf/instruction-set.rst
@@ -82,24 +82,24 @@ 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
- BPF_SUB 0x10
- BPF_MUL 0x20
- BPF_DIV 0x30
- BPF_OR 0x40
- BPF_AND 0x50
- BPF_LSH 0x60
- BPF_RSH 0x70
- BPF_NEG 0x80
- BPF_MOD 0x90
- BPF_XOR 0xa0
- BPF_MOV 0xb0 mov reg to reg
+ ======== ===== ==========================
+ BPF_ADD 0x00 dst += src
+ BPF_SUB 0x10 dst -= src
+ BPF_MUL 0x20 dst \*= src
+ BPF_DIV 0x30 dst /= src
+ BPF_OR 0x40 dst \|= src
+ BPF_AND 0x50 dst &= src
+ BPF_LSH 0x60 dst <<= src
+ BPF_RSH 0x70 dst >>= src
+ BPF_NEG 0x80 dst = ~src
+ BPF_MOD 0x90 dst %= src
+ BPF_XOR 0xa0 dst ^= src
+ BPF_MOV 0xb0 dst = src
BPF_ARSH 0xc0 sign extending shift right
BPF_END 0xd0 endianness conversion
- ======== ===== =========================
+ ======== ===== ==========================
BPF_ADD | BPF_X | BPF_ALU means::
--
2.30.2
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH 5/6] bpf, docs: Fully document the JMP opcodes
2022-01-03 18:35 more eBPF instruction set documentation improvements Christoph Hellwig
` (3 preceding siblings ...)
2022-01-03 18:35 ` [PATCH 4/6] bpf, docs: Fully document the ALU opcodes Christoph Hellwig
@ 2022-01-03 18:35 ` Christoph Hellwig
2022-01-03 18:35 ` [PATCH 6/6] bpf, docs: Fully document the JMP mode modifiers Christoph Hellwig
2022-01-05 21:14 ` more eBPF instruction set documentation improvements Alexei Starovoitov
6 siblings, 0 replies; 8+ messages in thread
From: Christoph Hellwig @ 2022-01-03 18:35 UTC (permalink / raw)
To: Jonathan Corbet, Alexei Starovoitov, Daniel Borkmann, Andrii Nakryiko
Cc: Martin KaFai Lau, Song Liu, Yonghong Song, John Fastabend,
KP Singh, linux-doc, netdev, bpf
Add pseudo-code to document all the different BPF_JMP / BPF_JMP64
opcodes.
Signed-off-by: Christoph Hellwig <hch@lst.de>
---
Documentation/bpf/instruction-set.rst | 34 +++++++++++++--------------
1 file changed, 17 insertions(+), 17 deletions(-)
diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
index efba4d1931853..88e8d6a9195cd 100644
--- a/Documentation/bpf/instruction-set.rst
+++ b/Documentation/bpf/instruction-set.rst
@@ -125,24 +125,24 @@ BPF_JMP32 uses 32-bit wide operands while BPF_JMP uses 64-bit wide operands for
otherwise identical operations.
The code field encodes the operation as below:
- ======== ===== =========================
- code value description
- ======== ===== =========================
- BPF_JA 0x00 BPF_JMP only
- BPF_JEQ 0x10
- BPF_JGT 0x20
- BPF_JGE 0x30
- BPF_JSET 0x40
- BPF_JNE 0x50 jump '!='
- BPF_JSGT 0x60 signed '>'
- BPF_JSGE 0x70 signed '>='
+ ======== ===== ========================= ============
+ code value description notes
+ ======== ===== ========================= ============
+ BPF_JA 0x00 PC += off BPF_JMP only
+ BPF_JEQ 0x10 PC += off if dst == src
+ BPF_JGT 0x20 PC += off if dst > src unsigned
+ BPF_JGE 0x30 PC += off if dst >= src unsigned
+ BPF_JSET 0x40 PC += off if dst & src
+ BPF_JNE 0x50 PC += off if dst != src
+ BPF_JSGT 0x60 PC += off if dst > src signed
+ BPF_JSGE 0x70 PC += off if dst >= src signed
BPF_CALL 0x80 function call
- BPF_EXIT 0x90 function return
- BPF_JLT 0xa0 unsigned '<'
- BPF_JLE 0xb0 unsigned '<='
- BPF_JSLT 0xc0 signed '<'
- BPF_JSLE 0xd0 signed '<='
- ======== ===== =========================
+ BPF_EXIT 0x90 function / program return BPF_JMP only
+ BPF_JLT 0xa0 PC += off if dst < src unsigned
+ BPF_JLE 0xb0 PC += off if dst <= src unsigned
+ BPF_JSLT 0xc0 PC += off if dst < src signed
+ BPF_JSLE 0xd0 PC += off if dst <= src signed
+ ======== ===== ========================= ============
The eBPF program needs to store the return value into register R0 before doing a
BPF_EXIT.
--
2.30.2
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH 6/6] bpf, docs: Fully document the JMP mode modifiers
2022-01-03 18:35 more eBPF instruction set documentation improvements Christoph Hellwig
` (4 preceding siblings ...)
2022-01-03 18:35 ` [PATCH 5/6] bpf, docs: Fully document the JMP opcodes Christoph Hellwig
@ 2022-01-03 18:35 ` Christoph Hellwig
2022-01-05 21:14 ` more eBPF instruction set documentation improvements Alexei Starovoitov
6 siblings, 0 replies; 8+ messages in thread
From: Christoph Hellwig @ 2022-01-03 18:35 UTC (permalink / raw)
To: Jonathan Corbet, Alexei Starovoitov, Daniel Borkmann, Andrii Nakryiko
Cc: Martin KaFai Lau, Song Liu, Yonghong Song, John Fastabend,
KP Singh, linux-doc, netdev, bpf
Add a description for all the modifiers.
Signed-off-by: Christoph Hellwig <hch@lst.de>
---
Documentation/bpf/instruction-set.rst | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
index 88e8d6a9195cd..3704836fe6df6 100644
--- a/Documentation/bpf/instruction-set.rst
+++ b/Documentation/bpf/instruction-set.rst
@@ -173,15 +173,15 @@ The size modifier is one of:
The mode modifier is one of:
- ============= ===== =====================
+ ============= ===== ====================================
mode modifier value description
- ============= ===== =====================
+ ============= ===== ====================================
BPF_IMM 0x00 used for 64-bit mov
- BPF_ABS 0x20
- BPF_IND 0x40
- BPF_MEM 0x60
+ BPF_ABS 0x20 legacy BPF packet access
+ BPF_IND 0x40 legacy BPF packet access
+ BPF_MEM 0x60 all normal load and store operations
BPF_ATOMIC 0xc0 atomic operations
- ============= ===== =====================
+ ============= ===== ====================================
BPF_MEM | <size> | BPF_STX means::
--
2.30.2
^ permalink raw reply related [flat|nested] 8+ messages in thread* Re: more eBPF instruction set documentation improvements
2022-01-03 18:35 more eBPF instruction set documentation improvements Christoph Hellwig
` (5 preceding siblings ...)
2022-01-03 18:35 ` [PATCH 6/6] bpf, docs: Fully document the JMP mode modifiers Christoph Hellwig
@ 2022-01-05 21:14 ` Alexei Starovoitov
6 siblings, 0 replies; 8+ messages in thread
From: Alexei Starovoitov @ 2022-01-05 21:14 UTC (permalink / raw)
To: Christoph Hellwig
Cc: Jonathan Corbet, Alexei Starovoitov, Daniel Borkmann,
Andrii Nakryiko, Martin KaFai Lau, Song Liu, Yonghong Song,
John Fastabend, KP Singh, linux-doc, netdev, bpf
On Mon, Jan 03, 2022 at 07:35:50PM +0100, Christoph Hellwig wrote:
> Hi all,
>
> this series adds further improves the eBPF instruction set documentation.
> Mostly it adds descriptions to the various tables as requested by
> Alexei, but there are a few other minor tidyups as well.
Applied, Thanks
^ permalink raw reply [flat|nested] 8+ messages in thread