* more eBPF instruction set documentation improvements
@ 2022-01-03 18:35 Christoph Hellwig
2022-01-03 18:35 ` [PATCH 1/6] bpf, docs: Add a setion to explain the basic instruction encoding Christoph Hellwig
` (6 more replies)
0 siblings, 7 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
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.
Diffstat:
instruction-set.rst | 156 ++++++++++++++++++++++++++++++----------------------
1 file changed, 91 insertions(+), 65 deletions(-)
^ permalink raw reply [flat|nested] 8+ messages in thread
* [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
end of thread, other threads:[~2022-01-05 21:14 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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 ` [PATCH 3/6] bpf, docs: Document the opcode classes Christoph Hellwig
2022-01-03 18:35 ` [PATCH 4/6] bpf, docs: Fully document the ALU opcodes Christoph Hellwig
2022-01-03 18:35 ` [PATCH 5/6] bpf, docs: Fully document the JMP opcodes 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
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.