From: Yonghong Song <yhs@fb.com>
To: <bpf@vger.kernel.org>
Cc: Alexei Starovoitov <ast@kernel.org>,
Andrii Nakryiko <andrii@kernel.org>,
Daniel Borkmann <daniel@iogearbox.net>,
Fangrui Song <maskray@google.com>, <kernel-team@fb.com>
Subject: [PATCH bpf-next v2 15/15] docs/bpf: Add documentation for new instructions
Date: Wed, 12 Jul 2023 23:08:47 -0700 [thread overview]
Message-ID: <20230713060847.397969-1-yhs@fb.com> (raw)
In-Reply-To: <20230713060718.388258-1-yhs@fb.com>
Add documentation in instruction-set.rst for new instruction encoding
and their corresponding operations. Also removed the question
related to 'no BPF_SDIV' in bpf_design_QA.rst since we have
BPF_SDIV insn now.
Signed-off-by: Yonghong Song <yhs@fb.com>
---
Documentation/bpf/bpf_design_QA.rst | 5 -
.../bpf/standardization/instruction-set.rst | 100 ++++++++++++------
2 files changed, 66 insertions(+), 39 deletions(-)
diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
index 38372a956d65..eb19c945f4d5 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -140,11 +140,6 @@ A: Because if we picked one-to-one relationship to x64 it would have made
it more complicated to support on arm64 and other archs. Also it
needs div-by-zero runtime check.
-Q: Why there is no BPF_SDIV for signed divide operation?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A: Because it would be rarely used. llvm errors in such case and
-prints a suggestion to use unsigned divide instead.
-
Q: Why BPF has implicit prologue and epilogue?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A: Because architectures like sparc have register windows and in general
diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index 751e657973f0..367f426d09a1 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -154,24 +154,27 @@ otherwise identical operations.
The 'code' field encodes the operation as below, where 'src' and 'dst' refer
to the values of the source and destination registers, respectively.
-======== ===== ==========================================================
-code value description
-======== ===== ==========================================================
-BPF_ADD 0x00 dst += src
-BPF_SUB 0x10 dst -= src
-BPF_MUL 0x20 dst \*= src
-BPF_DIV 0x30 dst = (src != 0) ? (dst / src) : 0
-BPF_OR 0x40 dst \|= src
-BPF_AND 0x50 dst &= src
-BPF_LSH 0x60 dst <<= (src & mask)
-BPF_RSH 0x70 dst >>= (src & mask)
-BPF_NEG 0x80 dst = -src
-BPF_MOD 0x90 dst = (src != 0) ? (dst % src) : dst
-BPF_XOR 0xa0 dst ^= src
-BPF_MOV 0xb0 dst = src
-BPF_ARSH 0xc0 sign extending dst >>= (src & mask)
-BPF_END 0xd0 byte swap operations (see `Byte swap instructions`_ below)
-======== ===== ==========================================================
+======== ===== ============ ==========================================================
+code value offset value description
+======== ===== ============ ==========================================================
+BPF_ADD 0x00 0 dst += src
+BPF_SUB 0x10 0 dst -= src
+BPF_MUL 0x20 0 dst \*= src
+BPF_DIV 0x30 0 dst = (src != 0) ? (dst / src) : 0
+BPF_SDIV 0x30 1 dst = (src != 0) ? (dst s/ src) : 0
+BPF_OR 0x40 0 dst \|= src
+BPF_AND 0x50 0 dst &= src
+BPF_LSH 0x60 0 dst <<= (src & mask)
+BPF_RSH 0x70 0 dst >>= (src & mask)
+BPF_NEG 0x80 0 dst = -src
+BPF_MOD 0x90 0 dst = (src != 0) ? (dst % src) : dst
+BPF_SMOD 0x90 1 dst = (src != 0) ? (dst s% src) : dst
+BPF_XOR 0xa0 0 dst ^= src
+BPF_MOV 0xb0 0 dst = src
+BPF_MOVSX 0xb0 8/16/32 dst = (s8,16,s32)src
+BPF_ARSH 0xc0 0 sign extending dst >>= (src & mask)
+BPF_END 0xd0 0 byte swap operations (see `Byte swap instructions`_ below)
+======== ===== ============ ==========================================================
Underflow and overflow are allowed during arithmetic operations, meaning
the 64-bit or 32-bit value will wrap. If eBPF program execution would
@@ -198,11 +201,19 @@ where '(u32)' indicates that the upper 32 bits are zeroed.
dst = dst ^ imm32
-Also note that the division and modulo operations are unsigned. Thus, for
-``BPF_ALU``, 'imm' is first interpreted as an unsigned 32-bit value, whereas
-for ``BPF_ALU64``, 'imm' is first sign extended to 64 bits and the result
-interpreted as an unsigned 64-bit value. There are no instructions for
-signed division or modulo.
+Note that most instructions have instruction offset of 0. But three instructions
+(BPF_SDIV, BPF_SMOD, BPF_MOVSX) have non-zero offset.
+
+The devision and modulo operations support both unsigned and signed flavors.
+For unsigned operation (BPF_DIV and BPF_MOD), for ``BPF_ALU``, 'imm' is first
+interpreted as an unsigned 32-bit value, whereas for ``BPF_ALU64``, 'imm' is
+first sign extended to 64 bits and the result interpreted as an unsigned 64-bit
+value. For signed operation (BPF_SDIV and BPF_SMOD), for both ``BPF_ALU`` and
+``BPF_ALU64``, 'imm' is interpreted as a signed value.
+
+Instruction BPF_MOVSX does move operation with sign extension. For ``BPF_ALU``
+mode, 8-bit and 16-bit sign extensions to 32-bit are supported. For ``BPF_ALU64``,
+8-bit, 16-bit and 32-bit sign extenstions to 64-bit are supported.
Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31)
for 32-bit operations.
@@ -210,21 +221,23 @@ for 32-bit operations.
Byte swap instructions
~~~~~~~~~~~~~~~~~~~~~~
-The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit
-'code' field of ``BPF_END``.
+The byte swap instructions use instruction classes of ``BPF_ALU`` and ``BPF_ALU64``
+and a 4-bit 'code' field of ``BPF_END``.
The byte swap 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 select what byte
-order the operation convert from or to:
+For ``BPF_ALU``, the 1-bit source operand field in the opcode is used to select what byte
+order the operation convert from or to. For ``BPF_ALU64``, the 1-bit source operand
+field in the opcode is not used.
-========= ===== =================================================
-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
-========= ===== =================================================
+========= ========= ===== =================================================
+class source value description
+========= ========= ===== =================================================
+BPF_ALU BPF_TO_LE 0x00 convert between host byte order and little endian
+BPF_ALU BPF_TO_BE 0x08 convert between host byte order and big endian
+BPF_ALU64 BPF_TO_LE 0x00 do byte swap unconditionally
+========= ========= ===== =================================================
The 'imm' field encodes the width of the swap operations. The following widths
are supported: 16, 32 and 64.
@@ -239,6 +252,10 @@ Examples:
dst = htobe64(dst)
+``BPF_ALU64 | BPF_TO_LE | BPF_END`` with imm = 16 means::
+
+ dst = bswap16(dst)
+
Jump instructions
-----------------
@@ -249,7 +266,8 @@ The 'code' field encodes the operation as below:
======== ===== === =========================================== =========================================
code value src description notes
======== ===== === =========================================== =========================================
-BPF_JA 0x0 0x0 PC += offset BPF_JMP only
+BPF_JA 0x0 0x0 PC += offset BPF_JMP class
+BPF_JA 0x0 0x0 PC += imm BPF_JMP32 class
BPF_JEQ 0x1 any PC += offset if dst == src
BPF_JGT 0x2 any PC += offset if dst > src unsigned
BPF_JGE 0x3 any PC += offset if dst >= src unsigned
@@ -278,6 +296,10 @@ Example:
where 's>=' indicates a signed '>=' comparison.
+Note there are two flavors of BPF_JA instrions. BPF_JMP class permits 16-bit jump offset while
+BPF_JMP32 permits 32-bit jump offset. A >16bit conditional jmp can be converted to a <16bit
+conditional jmp plus a 32-bit unconditional jump.
+
Helper functions
~~~~~~~~~~~~~~~~
@@ -320,6 +342,7 @@ The mode modifier is one of:
BPF_ABS 0x20 legacy BPF packet access (absolute) `Legacy BPF Packet access instructions`_
BPF_IND 0x40 legacy BPF packet access (indirect) `Legacy BPF Packet access instructions`_
BPF_MEM 0x60 regular load and store operations `Regular load and store operations`_
+ BPF_MEMSX 0x80 sign-extension load operations `Sign-extension load operations`_
BPF_ATOMIC 0xc0 atomic operations `Atomic operations`_
============= ===== ==================================== =============
@@ -354,6 +377,15 @@ instructions that transfer data between a register and memory.
Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``.
+The ``BPF_MEMSX`` mode modifier is used to encode sign-extension load
+instructions that transfer data between a register and memory.
+
+``BPF_MEMSX | <size> | BPF_LDX`` means::
+
+ dst = *(sign-extension size *) (src + offset)
+
+Where size is one of: ``BPF_B``, ``BPF_H`` or ``BPF_W``.
+
Atomic operations
-----------------
--
2.34.1
next prev parent reply other threads:[~2023-07-13 6:09 UTC|newest]
Thread overview: 54+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-07-13 6:07 [PATCH bpf-next v2 00/15] bpf: Support new insns from cpu v4 Yonghong Song
2023-07-13 6:07 ` [PATCH bpf-next v2 01/15] bpf: Support new sign-extension load insns Yonghong Song
2023-07-14 18:13 ` Alexei Starovoitov
2023-07-14 23:22 ` Yonghong Song
2023-07-17 1:39 ` Eduard Zingerman
2023-07-19 0:15 ` Eduard Zingerman
2023-07-19 2:28 ` Yonghong Song
2023-07-13 6:07 ` [PATCH bpf-next v2 02/15] bpf: Fix sign-extension ctx member accesses Yonghong Song
2023-07-17 1:40 ` Eduard Zingerman
2023-07-19 0:40 ` Yonghong Song
2023-07-13 6:07 ` [PATCH bpf-next v2 03/15] bpf: Support new sign-extension mov insns Yonghong Song
2023-07-17 1:41 ` Eduard Zingerman
2023-07-19 1:17 ` Yonghong Song
2023-07-19 12:53 ` Eduard Zingerman
2023-07-19 15:59 ` Fangrui Song
2023-07-19 16:57 ` Eduard Zingerman
2023-07-13 6:07 ` [PATCH bpf-next v2 04/15] bpf: Support new unconditional bswap instruction Yonghong Song
2023-07-17 1:42 ` Eduard Zingerman
2023-07-19 1:22 ` Yonghong Song
2023-07-13 6:07 ` [PATCH bpf-next v2 05/15] bpf: Support new signed div/mod instructions Yonghong Song
2023-07-18 23:00 ` Eduard Zingerman
2023-07-19 2:30 ` Yonghong Song
2023-07-19 2:44 ` Alexei Starovoitov
2023-07-19 6:57 ` Yonghong Song
2023-07-13 6:07 ` [PATCH bpf-next v2 06/15] bpf: Fix jit blinding with new sdiv/smov insns Yonghong Song
2023-07-13 6:07 ` [PATCH bpf-next v2 07/15] bpf: Support new 32bit offset jmp instruction Yonghong Song
2023-07-13 6:08 ` [PATCH bpf-next v2 08/15] selftests/bpf: Add a cpuv4 test runner for cpu=v4 testing Yonghong Song
2023-07-13 6:18 ` Fangrui Song
2023-07-13 6:25 ` Yonghong Song
2023-07-13 6:08 ` [PATCH bpf-next v2 09/15] selftests/bpf: Add unit tests for new sign-extension load insns Yonghong Song
2023-07-18 23:06 ` Eduard Zingerman
2023-07-13 6:08 ` [PATCH bpf-next v2 10/15] selftests/bpf: Add unit tests for new sign-extension mov insns Yonghong Song
2023-07-13 6:08 ` [PATCH bpf-next v2 11/15] selftests/bpf: Add unit tests for new bswap insns Yonghong Song
2023-07-13 6:08 ` [PATCH bpf-next v2 12/15] selftests/bpf: Add unit tests for new sdiv/smod insns Yonghong Song
2023-07-18 23:10 ` Eduard Zingerman
2023-07-13 6:08 ` [PATCH bpf-next v2 13/15] selftests/bpf: Add unit tests for new gotol insn Yonghong Song
2023-07-13 6:08 ` [PATCH bpf-next v2 14/15] selftests/bpf: Test ldsx with more complex cases Yonghong Song
2023-07-13 6:08 ` Yonghong Song [this message]
2023-07-14 18:28 ` [PATCH bpf-next v2 15/15] docs/bpf: Add documentation for new instructions Alexei Starovoitov
2023-07-14 23:26 ` Yonghong Song
2023-07-14 23:33 ` Dave Thaler
2023-07-14 23:33 ` [Bpf] " Dave Thaler
2023-07-15 0:23 ` Alexei Starovoitov
2023-07-15 0:23 ` [Bpf] " Alexei Starovoitov
2023-07-14 23:34 ` Dave Thaler
2023-07-14 23:34 ` [Bpf] " Dave Thaler
2023-07-17 1:39 ` [PATCH bpf-next v2 00/15] bpf: Support new insns from cpu v4 Eduard Zingerman
2023-07-17 16:56 ` Alexei Starovoitov
2023-07-17 17:04 ` Eduard Zingerman
2023-07-17 21:52 ` Yonghong Song
2023-07-21 14:56 ` Jose E. Marchesi
2023-07-24 0:17 ` Jose E. Marchesi
2023-07-24 1:04 ` Jose E. Marchesi
2023-07-24 2:35 ` Yonghong Song
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230713060847.397969-1-yhs@fb.com \
--to=yhs@fb.com \
--cc=andrii@kernel.org \
--cc=ast@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=daniel@iogearbox.net \
--cc=kernel-team@fb.com \
--cc=maskray@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.