From bbaf1ff06af49e856501024abbe161d96c1f0d66 Mon Sep 17 00:00:00 2001 From: Fangrui Song Date: Sat, 24 Jun 2023 00:18:56 +0000 Subject: bpf: Replace deprecated -target with --target= for Clang The -target option has been deprecated since clang 3.4 in 2013. Therefore, use the preferred --target=bpf form instead. This also matches how we use --target= in scripts/Makefile.clang. Signed-off-by: Fangrui Song Signed-off-by: Daniel Borkmann Acked-by: Yonghong Song Acked-by: Quentin Monnet Link: https://github.com/llvm/llvm-project/commit/274b6f0c87a6a1798de0a68135afc7f95def6277 Link: https://lore.kernel.org/bpf/20230624001856.1903733-1-maskray@google.com --- Documentation/bpf/bpf_devel_QA.rst | 10 +++++----- Documentation/bpf/btf.rst | 4 ++-- Documentation/bpf/llvm_reloc.rst | 6 +++--- 3 files changed, 10 insertions(+), 10 deletions(-) (limited to 'Documentation') diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst index 609b71f5747d..de27e1620821 100644 --- a/Documentation/bpf/bpf_devel_QA.rst +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -635,12 +635,12 @@ test coverage. Q: clang flag for target bpf? ----------------------------- -Q: In some cases clang flag ``-target bpf`` is used but in other cases the +Q: In some cases clang flag ``--target=bpf`` is used but in other cases the default clang target, which matches the underlying architecture, is used. What is the difference and when I should use which? A: Although LLVM IR generation and optimization try to stay architecture -independent, ``-target `` still has some impact on generated code: +independent, ``--target=`` still has some impact on generated code: - BPF program may recursively include header file(s) with file scope inline assembly codes. The default target can handle this well, @@ -658,7 +658,7 @@ independent, ``-target `` still has some impact on generated code: The clang option ``-fno-jump-tables`` can be used to disable switch table generation. -- For clang ``-target bpf``, it is guaranteed that pointer or long / +- For clang ``--target=bpf``, it is guaranteed that pointer or long / unsigned long types will always have a width of 64 bit, no matter whether underlying clang binary or default target (or kernel) is 32 bit. However, when native clang target is used, then it will @@ -668,7 +668,7 @@ independent, ``-target `` still has some impact on generated code: while the BPF LLVM back end still operates in 64 bit. The native target is mostly needed in tracing for the case of walking ``pt_regs`` or other kernel structures where CPU's register width matters. - Otherwise, ``clang -target bpf`` is generally recommended. + Otherwise, ``clang --target=bpf`` is generally recommended. You should use default target when: @@ -685,7 +685,7 @@ when: into these structures is verified by the BPF verifier and may result in verification failures if the native architecture is not aligned with the BPF architecture, e.g. 64-bit. An example of this is - BPF_PROG_TYPE_SK_MSG require ``-target bpf`` + BPF_PROG_TYPE_SK_MSG require ``--target=bpf`` .. Links diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst index 7cd7c5415a99..f32db1f44ae9 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -990,7 +990,7 @@ format.:: } g2; int main() { return 0; } int test() { return 0; } - -bash-4.4$ clang -c -g -O2 -target bpf t2.c + -bash-4.4$ clang -c -g -O2 --target=bpf t2.c -bash-4.4$ readelf -S t2.o ...... [ 8] .BTF PROGBITS 0000000000000000 00000247 @@ -1000,7 +1000,7 @@ format.:: [10] .rel.BTF.ext REL 0000000000000000 000007e0 0000000000000040 0000000000000010 16 9 8 ...... - -bash-4.4$ clang -S -g -O2 -target bpf t2.c + -bash-4.4$ clang -S -g -O2 --target=bpf t2.c -bash-4.4$ cat t2.s ...... .section .BTF,"",@progbits diff --git a/Documentation/bpf/llvm_reloc.rst b/Documentation/bpf/llvm_reloc.rst index e4a777a6a3a2..450e6403fe3d 100644 --- a/Documentation/bpf/llvm_reloc.rst +++ b/Documentation/bpf/llvm_reloc.rst @@ -28,7 +28,7 @@ For example, for the following code:: return g1 + g2 + l1 + l2; } -Compiled with ``clang -target bpf -O2 -c test.c``, the following is +Compiled with ``clang --target=bpf -O2 -c test.c``, the following is the code with ``llvm-objdump -dr test.o``:: 0: 18 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 r1 = 0 ll @@ -157,7 +157,7 @@ and ``call`` instructions. For example:: return gfunc(a, b) + lfunc(a, b) + global; } -Compiled with ``clang -target bpf -O2 -c test.c``, we will have +Compiled with ``clang --target=bpf -O2 -c test.c``, we will have following code with `llvm-objdump -dr test.o``:: Disassembly of section .text: @@ -203,7 +203,7 @@ The following is an example to show how R_BPF_64_ABS64 could be generated:: int global() { return 0; } struct t { void *g; } gbl = { global }; -Compiled with ``clang -target bpf -O2 -g -c test.c``, we will see a +Compiled with ``clang --target=bpf -O2 -g -c test.c``, we will see a relocation below in ``.data`` section with command ``llvm-readelf -r test.o``:: -- cgit v1.2.3 From 85b0c6d4905ec21cd22cb18da701aa02278ccc4c Mon Sep 17 00:00:00 2001 From: Dave Thaler Date: Tue, 27 Jun 2023 21:39:12 +0000 Subject: bpf, docs: Fix definition of BPF_NEG operation Instruction is an arithmetic negative, not a bitwise inverse. Signed-off-by: Dave Thaler Signed-off-by: Daniel Borkmann Acked-by: David Vernet Link: https://lore.kernel.org/bpf/20230627213912.951-1-dthaler1968@googlemail.com --- Documentation/bpf/instruction-set.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 6644842cd3ea..751e657973f0 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -165,7 +165,7 @@ 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_NEG 0x80 dst = -src BPF_MOD 0x90 dst = (src != 0) ? (dst % src) : dst BPF_XOR 0xa0 dst ^= src BPF_MOV 0xb0 dst = src -- cgit v1.2.3 From 4d496be9ca05d22dbbbba78368ac4bb05bcc67f2 Mon Sep 17 00:00:00 2001 From: David Vernet Date: Mon, 10 Jul 2023 13:30:27 -0500 Subject: bpf,docs: Create new standardization subdirectory The BPF standardization effort is actively underway with the IETF. As described in the BPF Working Group (WG) charter in [0], there are a number of proposed documents, some informational and some proposed standards, that will be drafted as part of the standardization effort. [0]: https://datatracker.ietf.org/wg/bpf/about/ Though the specific documents that will formally be standardized will exist as Internet Drafts (I-D) and WG documents in the BPF WG datatracker page, the source of truth from where those documents will be generated will reside in the kernel documentation tree (originating in the bpf-next tree). Because these documents will be used to generate the I-D and WG documents which will be standardized with the IETF, they are a bit special as far as kernel-tree documentation goes: - They will be dual licensed with LGPL-2.1 OR BSD-2-Clause - IETF I-D and WG documents (the documents which will actually be standardized) will be auto-generated from these documents. In order to keep things clearly organized in the BPF documentation tree, and to make it abundantly clear where standards-related documentation needs to go, we should move standards-relevant documents into a separate standardization/ subdirectory. Signed-off-by: David Vernet Link: https://lore.kernel.org/r/20230710183027.15132-1-void@manifault.com Signed-off-by: Alexei Starovoitov --- Documentation/bpf/index.rst | 3 +- Documentation/bpf/instruction-set.rst | 478 --------------------- Documentation/bpf/linux-notes.rst | 83 ---- Documentation/bpf/standardization/index.rst | 18 + .../bpf/standardization/instruction-set.rst | 478 +++++++++++++++++++++ Documentation/bpf/standardization/linux-notes.rst | 84 ++++ MAINTAINERS | 2 +- 7 files changed, 582 insertions(+), 564 deletions(-) delete mode 100644 Documentation/bpf/instruction-set.rst delete mode 100644 Documentation/bpf/linux-notes.rst create mode 100644 Documentation/bpf/standardization/index.rst create mode 100644 Documentation/bpf/standardization/instruction-set.rst create mode 100644 Documentation/bpf/standardization/linux-notes.rst (limited to 'Documentation') diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index dbb39e8f9889..1ff177b89d66 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -12,9 +12,9 @@ that goes into great technical depth about the BPF Architecture. .. toctree:: :maxdepth: 1 - instruction-set verifier libbpf/index + standardization/index btf faq syscall_api @@ -29,7 +29,6 @@ that goes into great technical depth about the BPF Architecture. bpf_licensing test_debug clang-notes - linux-notes other redirect diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst deleted file mode 100644 index 751e657973f0..000000000000 --- a/Documentation/bpf/instruction-set.rst +++ /dev/null @@ -1,478 +0,0 @@ -.. contents:: -.. sectnum:: - -======================================== -eBPF Instruction Set Specification, v1.0 -======================================== - -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. - -Registers and calling convention -================================ - -eBPF has 10 general purpose registers and a read-only frame pointer register, -all of which are 64-bits wide. - -The eBPF calling convention is defined as: - -* R0: return value from function calls, and exit value for eBPF programs -* R1 - R5: arguments for function calls -* R6 - R9: callee saved registers that function calls will preserve -* R10: read-only frame pointer to access stack - -R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if -necessary across calls. - -Instruction 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 (i.e., - constant) value after the basic instruction for a total of 128 bits. - -The fields conforming an encoded basic instruction are stored in the -following order:: - - opcode:8 src_reg:4 dst_reg:4 offset:16 imm:32 // In little-endian BPF. - opcode:8 dst_reg:4 src_reg:4 offset:16 imm:32 // In big-endian BPF. - -**imm** - signed integer immediate value - -**offset** - signed integer offset used with pointer arithmetic - -**src_reg** - the source register number (0-10), except where otherwise specified - (`64-bit immediate instructions`_ reuse this field for other purposes) - -**dst_reg** - destination register number (0-10) - -**opcode** - operation to perform - -Note that the contents of multi-byte fields ('imm' and 'offset') are -stored using big-endian byte ordering in big-endian BPF and -little-endian byte ordering in little-endian BPF. - -For example:: - - opcode offset imm assembly - src_reg dst_reg - 07 0 1 00 00 44 33 22 11 r1 += 0x11223344 // little - dst_reg src_reg - 07 1 0 00 00 11 22 33 44 r1 += 0x11223344 // big - -Note that most instructions do not use all of the fields. -Unused fields shall be cleared to zero. - -As discussed below in `64-bit immediate instructions`_, a 64-bit immediate -instruction uses a 64-bit immediate value that is constructed as follows. -The 64 bits following the basic instruction contain a pseudo instruction -using the same format but with opcode, dst_reg, src_reg, and offset all set to zero, -and imm containing the high 32 bits of the immediate value. - -This is depicted in the following figure:: - - basic_instruction - .-----------------------------. - | | - code:8 regs:8 offset:16 imm:32 unused:32 imm:32 - | | - '--------------' - pseudo instruction - -Thus the 64-bit immediate value is constructed as follows: - - imm64 = (next_imm << 32) | imm - -where 'next_imm' refers to the imm value of the pseudo instruction -following the basic instruction. The unused bytes in the pseudo -instruction are reserved and shall be cleared to zero. - -Instruction classes -------------------- - -The three LSB bits of the 'opcode' field store the instruction class: - -========= ===== =============================== =================================== -class value description reference -========= ===== =============================== =================================== -BPF_LD 0x00 non-standard load operations `Load and store instructions`_ -BPF_LDX 0x01 load into register operations `Load and store instructions`_ -BPF_ST 0x02 store from immediate operations `Load and store instructions`_ -BPF_STX 0x03 store from register operations `Load and store instructions`_ -BPF_ALU 0x04 32-bit arithmetic operations `Arithmetic and jump instructions`_ -BPF_JMP 0x05 64-bit jump operations `Arithmetic and jump instructions`_ -BPF_JMP32 0x06 32-bit jump operations `Arithmetic and jump instructions`_ -BPF_ALU64 0x07 64-bit arithmetic operations `Arithmetic and jump instructions`_ -========= ===== =============================== =================================== - -Arithmetic and jump instructions -================================ - -For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` and -``BPF_JMP32``), the 8-bit 'opcode' field is divided into three parts: - -============== ====== ================= -4 bits (MSB) 1 bit 3 bits (LSB) -============== ====== ================= -code source instruction class -============== ====== ================= - -**code** - the operation code, whose meaning varies by instruction class - -**source** - the source operand location, which unless otherwise specified is one of: - - ====== ===== ============================================== - source value description - ====== ===== ============================================== - BPF_K 0x00 use 32-bit 'imm' value as source operand - BPF_X 0x08 use 'src_reg' register value as source operand - ====== ===== ============================================== - -**instruction class** - the instruction class (see `Instruction classes`_) - -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, 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) -======== ===== ========================================================== - -Underflow and overflow are allowed during arithmetic operations, meaning -the 64-bit or 32-bit value will wrap. If eBPF program execution would -result in division by zero, the destination register is instead set to zero. -If execution would result in modulo by zero, for ``BPF_ALU64`` the value of -the destination register is unchanged whereas for ``BPF_ALU`` the upper -32 bits of the destination register are zeroed. - -``BPF_ADD | BPF_X | BPF_ALU`` means:: - - dst = (u32) ((u32) dst + (u32) src) - -where '(u32)' indicates that the upper 32 bits are zeroed. - -``BPF_ADD | BPF_X | BPF_ALU64`` means:: - - dst = dst + src - -``BPF_XOR | BPF_K | BPF_ALU`` means:: - - dst = (u32) dst ^ (u32) imm32 - -``BPF_XOR | BPF_K | BPF_ALU64`` means:: - - 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. - -Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31) -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 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: - -========= ===== ================================================= -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 = htole16(dst) - -``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means:: - - dst = htobe64(dst) - -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 src description notes -======== ===== === =========================================== ========================================= -BPF_JA 0x0 0x0 PC += offset BPF_JMP only -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 -BPF_JSET 0x4 any PC += offset if dst & src -BPF_JNE 0x5 any PC += offset if dst != src -BPF_JSGT 0x6 any PC += offset if dst > src signed -BPF_JSGE 0x7 any PC += offset if dst >= src signed -BPF_CALL 0x8 0x0 call helper function by address see `Helper functions`_ -BPF_CALL 0x8 0x1 call PC += offset see `Program-local functions`_ -BPF_CALL 0x8 0x2 call helper function by BTF ID see `Helper functions`_ -BPF_EXIT 0x9 0x0 return BPF_JMP only -BPF_JLT 0xa any PC += offset if dst < src unsigned -BPF_JLE 0xb any PC += offset if dst <= src unsigned -BPF_JSLT 0xc any PC += offset if dst < src signed -BPF_JSLE 0xd any PC += offset if dst <= src signed -======== ===== === =========================================== ========================================= - -The eBPF program needs to store the return value into register R0 before doing a -``BPF_EXIT``. - -Example: - -``BPF_JSGE | BPF_X | BPF_JMP32`` (0x7e) means:: - - if (s32)dst s>= (s32)src goto +offset - -where 's>=' indicates a signed '>=' comparison. - -Helper functions -~~~~~~~~~~~~~~~~ - -Helper functions are a concept whereby BPF programs can call into a -set of function calls exposed by the underlying platform. - -Historically, each helper function was identified by an address -encoded in the imm field. The available helper functions may differ -for each program type, but address values are unique across all program types. - -Platforms that support the BPF Type Format (BTF) support identifying -a helper function by a BTF ID encoded in the imm field, where the BTF ID -identifies the helper name and type. - -Program-local functions -~~~~~~~~~~~~~~~~~~~~~~~ -Program-local functions are functions exposed by the same BPF program as the -caller, and are referenced by offset from the call instruction, similar to -``BPF_JA``. A ``BPF_EXIT`` within the program-local function will return to -the caller. - -Load and store instructions -=========================== - -For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the -8-bit 'opcode' field is divided as: - -============ ====== ================= -3 bits (MSB) 2 bits 3 bits (LSB) -============ ====== ================= -mode size instruction class -============ ====== ================= - -The mode modifier is one of: - - ============= ===== ==================================== ============= - mode modifier value description reference - ============= ===== ==================================== ============= - BPF_IMM 0x00 64-bit immediate instructions `64-bit immediate instructions`_ - 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_ATOMIC 0xc0 atomic operations `Atomic operations`_ - ============= ===== ==================================== ============= - -The size modifier is one of: - - ============= ===== ===================== - size modifier value description - ============= ===== ===================== - BPF_W 0x00 word (4 bytes) - BPF_H 0x08 half word (2 bytes) - BPF_B 0x10 byte - BPF_DW 0x18 double word (8 bytes) - ============= ===== ===================== - -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 | | BPF_STX`` means:: - - *(size *) (dst + offset) = src - -``BPF_MEM | | BPF_ST`` means:: - - *(size *) (dst + offset) = imm32 - -``BPF_MEM | | BPF_LDX`` means:: - - dst = *(size *) (src + offset) - -Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``. - -Atomic operations ------------------ - -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. - -All atomic operations supported by eBPF are encoded as store operations -that use the ``BPF_ATOMIC`` mode modifier as follows: - -* ``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. - -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: - -======== ===== =========== -imm value description -======== ===== =========== -BPF_ADD 0x00 atomic add -BPF_OR 0x40 atomic or -BPF_AND 0x50 atomic and -BPF_XOR 0xa0 atomic xor -======== ===== =========== - - -``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means:: - - *(u32 *)(dst + offset) += src - -``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means:: - - *(u64 *)(dst + offset) += src - -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`` with the value that -was in memory before it was modified. - -The ``BPF_XCHG`` operation atomically exchanges ``src`` with the value -addressed by ``dst + offset``. - -The ``BPF_CMPXCHG`` operation atomically compares the value addressed by -``dst + offset`` with ``R0``. If they match, the value addressed by -``dst + offset`` is replaced with ``src``. In either case, the -value that was at ``dst + offset`` before the operation is zero-extended -and loaded back to ``R0``. - -64-bit immediate instructions ------------------------------ - -Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction -encoding defined in `Instruction encoding`_, and use the 'src' field of the -basic instruction to hold an opcode subtype. - -The following table defines a set of ``BPF_IMM | BPF_DW | BPF_LD`` instructions -with opcode subtypes in the 'src' field, using new terms such as "map" -defined further below: - -========================= ====== === ========================================= =========== ============== -opcode construction opcode src pseudocode imm type dst type -========================= ====== === ========================================= =========== ============== -BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = imm64 integer integer -BPF_IMM | BPF_DW | BPF_LD 0x18 0x1 dst = map_by_fd(imm) map fd map -BPF_IMM | BPF_DW | BPF_LD 0x18 0x2 dst = map_val(map_by_fd(imm)) + next_imm map fd data pointer -BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = var_addr(imm) variable id data pointer -BPF_IMM | BPF_DW | BPF_LD 0x18 0x4 dst = code_addr(imm) integer code pointer -BPF_IMM | BPF_DW | BPF_LD 0x18 0x5 dst = map_by_idx(imm) map index map -BPF_IMM | BPF_DW | BPF_LD 0x18 0x6 dst = map_val(map_by_idx(imm)) + next_imm map index data pointer -========================= ====== === ========================================= =========== ============== - -where - -* map_by_fd(imm) means to convert a 32-bit file descriptor into an address of a map (see `Maps`_) -* map_by_idx(imm) means to convert a 32-bit index into an address of a map -* map_val(map) gets the address of the first value in a given map -* var_addr(imm) gets the address of a platform variable (see `Platform Variables`_) with a given id -* code_addr(imm) gets the address of the instruction at a specified relative offset in number of (64-bit) instructions -* the 'imm type' can be used by disassemblers for display -* the 'dst type' can be used for verification and JIT compilation purposes - -Maps -~~~~ - -Maps are shared memory regions accessible by eBPF programs on some platforms. -A map can have various semantics as defined in a separate document, and may or -may not have a single contiguous memory region, but the 'map_val(map)' is -currently only defined for maps that do have a single contiguous memory region. - -Each map can have a file descriptor (fd) if supported by the platform, where -'map_by_fd(imm)' means to get the map with the specified file descriptor. Each -BPF program can also be defined to use a set of maps associated with the -program at load time, and 'map_by_idx(imm)' means to get the map with the given -index in the set associated with the BPF program containing the instruction. - -Platform Variables -~~~~~~~~~~~~~~~~~~ - -Platform variables are memory regions, identified by integer ids, exposed by -the runtime and accessible by BPF programs on some platforms. The -'var_addr(imm)' operation means to get the address of the memory region -identified by the given id. - -Legacy BPF Packet access instructions -------------------------------------- - -eBPF previously introduced special instructions for access to packet data that were -carried over from classic BPF. However, these instructions are -deprecated and should no longer be used. diff --git a/Documentation/bpf/linux-notes.rst b/Documentation/bpf/linux-notes.rst deleted file mode 100644 index 508d009d3bed..000000000000 --- a/Documentation/bpf/linux-notes.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. contents:: -.. sectnum:: - -========================== -Linux implementation notes -========================== - -This document provides more details specific to the Linux kernel implementation of the eBPF instruction set. - -Byte swap instructions -====================== - -``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively. - -Jump instructions -================= - -``BPF_CALL | BPF_X | BPF_JMP`` (0x8d), where the helper function -integer would be read from a specified register, is not currently supported -by the verifier. Any programs with this instruction will fail to load -until such support is added. - -Maps -==== - -Linux only supports the 'map_val(map)' operation on array maps with a single element. - -Linux uses an fd_array to store maps associated with a BPF program. Thus, -map_by_idx(imm) uses the fd at that index in the array. - -Variables -========= - -The following 64-bit immediate instruction specifies that a variable address, -which corresponds to some integer stored in the 'imm' field, should be loaded: - -========================= ====== === ========================================= =========== ============== -opcode construction opcode src pseudocode imm type dst type -========================= ====== === ========================================= =========== ============== -BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = var_addr(imm) variable id data pointer -========================= ====== === ========================================= =========== ============== - -On Linux, this integer is a BTF ID. - -Legacy BPF Packet access instructions -===================================== - -As mentioned in the `ISA standard documentation `_, -Linux has special eBPF 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. - -The instructions come in two forms: ``BPF_ABS | | BPF_LD`` and -``BPF_IND | | BPF_LD``. - -These instructions are used to access packet data and can only be used when -the program context is a pointer to a 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. - -These instructions have seven implicit operands: - -* Register R6 is an implicit input that must contain a 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 by the - instruction. - -These instructions have an implicit program exit condition as well. If an -eBPF program attempts access data beyond the packet boundary, the -program execution will be aborted. - -``BPF_ABS | BPF_W | BPF_LD`` (0x20) means:: - - R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + imm)) - -where ``ntohl()`` converts a 32-bit value from network byte order to host byte order. - -``BPF_IND | BPF_W | BPF_LD`` (0x40) means:: - - R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + src + imm)) diff --git a/Documentation/bpf/standardization/index.rst b/Documentation/bpf/standardization/index.rst new file mode 100644 index 000000000000..09c6ba055fd7 --- /dev/null +++ b/Documentation/bpf/standardization/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) + +=================== +BPF Standardization +=================== + +This directory contains documents that are being iterated on as part of the BPF +standardization effort with the IETF. See the `IETF BPF Working Group`_ page +for the working group charter, documents, and more. + +.. toctree:: + :maxdepth: 1 + + instruction-set + linux-notes + +.. Links: +.. _IETF BPF Working Group: https://datatracker.ietf.org/wg/bpf/about/ diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst new file mode 100644 index 000000000000..751e657973f0 --- /dev/null +++ b/Documentation/bpf/standardization/instruction-set.rst @@ -0,0 +1,478 @@ +.. contents:: +.. sectnum:: + +======================================== +eBPF Instruction Set Specification, v1.0 +======================================== + +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. + +Registers and calling convention +================================ + +eBPF has 10 general purpose registers and a read-only frame pointer register, +all of which are 64-bits wide. + +The eBPF calling convention is defined as: + +* R0: return value from function calls, and exit value for eBPF programs +* R1 - R5: arguments for function calls +* R6 - R9: callee saved registers that function calls will preserve +* R10: read-only frame pointer to access stack + +R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if +necessary across calls. + +Instruction 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 (i.e., + constant) value after the basic instruction for a total of 128 bits. + +The fields conforming an encoded basic instruction are stored in the +following order:: + + opcode:8 src_reg:4 dst_reg:4 offset:16 imm:32 // In little-endian BPF. + opcode:8 dst_reg:4 src_reg:4 offset:16 imm:32 // In big-endian BPF. + +**imm** + signed integer immediate value + +**offset** + signed integer offset used with pointer arithmetic + +**src_reg** + the source register number (0-10), except where otherwise specified + (`64-bit immediate instructions`_ reuse this field for other purposes) + +**dst_reg** + destination register number (0-10) + +**opcode** + operation to perform + +Note that the contents of multi-byte fields ('imm' and 'offset') are +stored using big-endian byte ordering in big-endian BPF and +little-endian byte ordering in little-endian BPF. + +For example:: + + opcode offset imm assembly + src_reg dst_reg + 07 0 1 00 00 44 33 22 11 r1 += 0x11223344 // little + dst_reg src_reg + 07 1 0 00 00 11 22 33 44 r1 += 0x11223344 // big + +Note that most instructions do not use all of the fields. +Unused fields shall be cleared to zero. + +As discussed below in `64-bit immediate instructions`_, a 64-bit immediate +instruction uses a 64-bit immediate value that is constructed as follows. +The 64 bits following the basic instruction contain a pseudo instruction +using the same format but with opcode, dst_reg, src_reg, and offset all set to zero, +and imm containing the high 32 bits of the immediate value. + +This is depicted in the following figure:: + + basic_instruction + .-----------------------------. + | | + code:8 regs:8 offset:16 imm:32 unused:32 imm:32 + | | + '--------------' + pseudo instruction + +Thus the 64-bit immediate value is constructed as follows: + + imm64 = (next_imm << 32) | imm + +where 'next_imm' refers to the imm value of the pseudo instruction +following the basic instruction. The unused bytes in the pseudo +instruction are reserved and shall be cleared to zero. + +Instruction classes +------------------- + +The three LSB bits of the 'opcode' field store the instruction class: + +========= ===== =============================== =================================== +class value description reference +========= ===== =============================== =================================== +BPF_LD 0x00 non-standard load operations `Load and store instructions`_ +BPF_LDX 0x01 load into register operations `Load and store instructions`_ +BPF_ST 0x02 store from immediate operations `Load and store instructions`_ +BPF_STX 0x03 store from register operations `Load and store instructions`_ +BPF_ALU 0x04 32-bit arithmetic operations `Arithmetic and jump instructions`_ +BPF_JMP 0x05 64-bit jump operations `Arithmetic and jump instructions`_ +BPF_JMP32 0x06 32-bit jump operations `Arithmetic and jump instructions`_ +BPF_ALU64 0x07 64-bit arithmetic operations `Arithmetic and jump instructions`_ +========= ===== =============================== =================================== + +Arithmetic and jump instructions +================================ + +For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` and +``BPF_JMP32``), the 8-bit 'opcode' field is divided into three parts: + +============== ====== ================= +4 bits (MSB) 1 bit 3 bits (LSB) +============== ====== ================= +code source instruction class +============== ====== ================= + +**code** + the operation code, whose meaning varies by instruction class + +**source** + the source operand location, which unless otherwise specified is one of: + + ====== ===== ============================================== + source value description + ====== ===== ============================================== + BPF_K 0x00 use 32-bit 'imm' value as source operand + BPF_X 0x08 use 'src_reg' register value as source operand + ====== ===== ============================================== + +**instruction class** + the instruction class (see `Instruction classes`_) + +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, 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) +======== ===== ========================================================== + +Underflow and overflow are allowed during arithmetic operations, meaning +the 64-bit or 32-bit value will wrap. If eBPF program execution would +result in division by zero, the destination register is instead set to zero. +If execution would result in modulo by zero, for ``BPF_ALU64`` the value of +the destination register is unchanged whereas for ``BPF_ALU`` the upper +32 bits of the destination register are zeroed. + +``BPF_ADD | BPF_X | BPF_ALU`` means:: + + dst = (u32) ((u32) dst + (u32) src) + +where '(u32)' indicates that the upper 32 bits are zeroed. + +``BPF_ADD | BPF_X | BPF_ALU64`` means:: + + dst = dst + src + +``BPF_XOR | BPF_K | BPF_ALU`` means:: + + dst = (u32) dst ^ (u32) imm32 + +``BPF_XOR | BPF_K | BPF_ALU64`` means:: + + 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. + +Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31) +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 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: + +========= ===== ================================================= +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 = htole16(dst) + +``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means:: + + dst = htobe64(dst) + +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 src description notes +======== ===== === =========================================== ========================================= +BPF_JA 0x0 0x0 PC += offset BPF_JMP only +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 +BPF_JSET 0x4 any PC += offset if dst & src +BPF_JNE 0x5 any PC += offset if dst != src +BPF_JSGT 0x6 any PC += offset if dst > src signed +BPF_JSGE 0x7 any PC += offset if dst >= src signed +BPF_CALL 0x8 0x0 call helper function by address see `Helper functions`_ +BPF_CALL 0x8 0x1 call PC += offset see `Program-local functions`_ +BPF_CALL 0x8 0x2 call helper function by BTF ID see `Helper functions`_ +BPF_EXIT 0x9 0x0 return BPF_JMP only +BPF_JLT 0xa any PC += offset if dst < src unsigned +BPF_JLE 0xb any PC += offset if dst <= src unsigned +BPF_JSLT 0xc any PC += offset if dst < src signed +BPF_JSLE 0xd any PC += offset if dst <= src signed +======== ===== === =========================================== ========================================= + +The eBPF program needs to store the return value into register R0 before doing a +``BPF_EXIT``. + +Example: + +``BPF_JSGE | BPF_X | BPF_JMP32`` (0x7e) means:: + + if (s32)dst s>= (s32)src goto +offset + +where 's>=' indicates a signed '>=' comparison. + +Helper functions +~~~~~~~~~~~~~~~~ + +Helper functions are a concept whereby BPF programs can call into a +set of function calls exposed by the underlying platform. + +Historically, each helper function was identified by an address +encoded in the imm field. The available helper functions may differ +for each program type, but address values are unique across all program types. + +Platforms that support the BPF Type Format (BTF) support identifying +a helper function by a BTF ID encoded in the imm field, where the BTF ID +identifies the helper name and type. + +Program-local functions +~~~~~~~~~~~~~~~~~~~~~~~ +Program-local functions are functions exposed by the same BPF program as the +caller, and are referenced by offset from the call instruction, similar to +``BPF_JA``. A ``BPF_EXIT`` within the program-local function will return to +the caller. + +Load and store instructions +=========================== + +For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the +8-bit 'opcode' field is divided as: + +============ ====== ================= +3 bits (MSB) 2 bits 3 bits (LSB) +============ ====== ================= +mode size instruction class +============ ====== ================= + +The mode modifier is one of: + + ============= ===== ==================================== ============= + mode modifier value description reference + ============= ===== ==================================== ============= + BPF_IMM 0x00 64-bit immediate instructions `64-bit immediate instructions`_ + 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_ATOMIC 0xc0 atomic operations `Atomic operations`_ + ============= ===== ==================================== ============= + +The size modifier is one of: + + ============= ===== ===================== + size modifier value description + ============= ===== ===================== + BPF_W 0x00 word (4 bytes) + BPF_H 0x08 half word (2 bytes) + BPF_B 0x10 byte + BPF_DW 0x18 double word (8 bytes) + ============= ===== ===================== + +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 | | BPF_STX`` means:: + + *(size *) (dst + offset) = src + +``BPF_MEM | | BPF_ST`` means:: + + *(size *) (dst + offset) = imm32 + +``BPF_MEM | | BPF_LDX`` means:: + + dst = *(size *) (src + offset) + +Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``. + +Atomic operations +----------------- + +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. + +All atomic operations supported by eBPF are encoded as store operations +that use the ``BPF_ATOMIC`` mode modifier as follows: + +* ``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. + +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: + +======== ===== =========== +imm value description +======== ===== =========== +BPF_ADD 0x00 atomic add +BPF_OR 0x40 atomic or +BPF_AND 0x50 atomic and +BPF_XOR 0xa0 atomic xor +======== ===== =========== + + +``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means:: + + *(u32 *)(dst + offset) += src + +``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means:: + + *(u64 *)(dst + offset) += src + +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`` with the value that +was in memory before it was modified. + +The ``BPF_XCHG`` operation atomically exchanges ``src`` with the value +addressed by ``dst + offset``. + +The ``BPF_CMPXCHG`` operation atomically compares the value addressed by +``dst + offset`` with ``R0``. If they match, the value addressed by +``dst + offset`` is replaced with ``src``. In either case, the +value that was at ``dst + offset`` before the operation is zero-extended +and loaded back to ``R0``. + +64-bit immediate instructions +----------------------------- + +Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction +encoding defined in `Instruction encoding`_, and use the 'src' field of the +basic instruction to hold an opcode subtype. + +The following table defines a set of ``BPF_IMM | BPF_DW | BPF_LD`` instructions +with opcode subtypes in the 'src' field, using new terms such as "map" +defined further below: + +========================= ====== === ========================================= =========== ============== +opcode construction opcode src pseudocode imm type dst type +========================= ====== === ========================================= =========== ============== +BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = imm64 integer integer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x1 dst = map_by_fd(imm) map fd map +BPF_IMM | BPF_DW | BPF_LD 0x18 0x2 dst = map_val(map_by_fd(imm)) + next_imm map fd data pointer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = var_addr(imm) variable id data pointer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x4 dst = code_addr(imm) integer code pointer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x5 dst = map_by_idx(imm) map index map +BPF_IMM | BPF_DW | BPF_LD 0x18 0x6 dst = map_val(map_by_idx(imm)) + next_imm map index data pointer +========================= ====== === ========================================= =========== ============== + +where + +* map_by_fd(imm) means to convert a 32-bit file descriptor into an address of a map (see `Maps`_) +* map_by_idx(imm) means to convert a 32-bit index into an address of a map +* map_val(map) gets the address of the first value in a given map +* var_addr(imm) gets the address of a platform variable (see `Platform Variables`_) with a given id +* code_addr(imm) gets the address of the instruction at a specified relative offset in number of (64-bit) instructions +* the 'imm type' can be used by disassemblers for display +* the 'dst type' can be used for verification and JIT compilation purposes + +Maps +~~~~ + +Maps are shared memory regions accessible by eBPF programs on some platforms. +A map can have various semantics as defined in a separate document, and may or +may not have a single contiguous memory region, but the 'map_val(map)' is +currently only defined for maps that do have a single contiguous memory region. + +Each map can have a file descriptor (fd) if supported by the platform, where +'map_by_fd(imm)' means to get the map with the specified file descriptor. Each +BPF program can also be defined to use a set of maps associated with the +program at load time, and 'map_by_idx(imm)' means to get the map with the given +index in the set associated with the BPF program containing the instruction. + +Platform Variables +~~~~~~~~~~~~~~~~~~ + +Platform variables are memory regions, identified by integer ids, exposed by +the runtime and accessible by BPF programs on some platforms. The +'var_addr(imm)' operation means to get the address of the memory region +identified by the given id. + +Legacy BPF Packet access instructions +------------------------------------- + +eBPF previously introduced special instructions for access to packet data that were +carried over from classic BPF. However, these instructions are +deprecated and should no longer be used. diff --git a/Documentation/bpf/standardization/linux-notes.rst b/Documentation/bpf/standardization/linux-notes.rst new file mode 100644 index 000000000000..00d2693de025 --- /dev/null +++ b/Documentation/bpf/standardization/linux-notes.rst @@ -0,0 +1,84 @@ +.. contents:: +.. sectnum:: + +========================== +Linux implementation notes +========================== + +This document provides more details specific to the Linux kernel implementation of the eBPF instruction set. + +Byte swap instructions +====================== + +``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively. + +Jump instructions +================= + +``BPF_CALL | BPF_X | BPF_JMP`` (0x8d), where the helper function +integer would be read from a specified register, is not currently supported +by the verifier. Any programs with this instruction will fail to load +until such support is added. + +Maps +==== + +Linux only supports the 'map_val(map)' operation on array maps with a single element. + +Linux uses an fd_array to store maps associated with a BPF program. Thus, +map_by_idx(imm) uses the fd at that index in the array. + +Variables +========= + +The following 64-bit immediate instruction specifies that a variable address, +which corresponds to some integer stored in the 'imm' field, should be loaded: + +========================= ====== === ========================================= =========== ============== +opcode construction opcode src pseudocode imm type dst type +========================= ====== === ========================================= =========== ============== +BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = var_addr(imm) variable id data pointer +========================= ====== === ========================================= =========== ============== + +On Linux, this integer is a BTF ID. + +Legacy BPF Packet access instructions +===================================== + +As mentioned in the `ISA standard documentation +`_, +Linux has special eBPF 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. + +The instructions come in two forms: ``BPF_ABS | | BPF_LD`` and +``BPF_IND | | BPF_LD``. + +These instructions are used to access packet data and can only be used when +the program context is a pointer to a 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. + +These instructions have seven implicit operands: + +* Register R6 is an implicit input that must contain a 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 by the + instruction. + +These instructions have an implicit program exit condition as well. If an +eBPF program attempts access data beyond the packet boundary, the +program execution will be aborted. + +``BPF_ABS | BPF_W | BPF_LD`` (0x20) means:: + + R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + imm)) + +where ``ntohl()`` converts a 32-bit value from network byte order to host byte order. + +``BPF_IND | BPF_W | BPF_LD`` (0x40) means:: + + R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + src + imm)) diff --git a/MAINTAINERS b/MAINTAINERS index acbe54087d1c..99d8dc9b2850 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3746,7 +3746,7 @@ R: David Vernet L: bpf@vger.kernel.org L: bpf@ietf.org S: Maintained -F: Documentation/bpf/instruction-set.rst +F: Documentation/bpf/standardization/ BPF [GENERAL] (Safe Dynamic Programs and Tools) M: Alexei Starovoitov -- cgit v1.2.3