1.. contents:: 2.. sectnum:: 3 4========================== 5Linux implementation notes 6========================== 7 8This document provides more details specific to the Linux kernel implementation of the eBPF instruction set. 9 10Byte swap instructions 11====================== 12 13``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively. 14 15Jump instructions 16================= 17 18``BPF_CALL | BPF_X | BPF_JMP`` (0x8d), ``callx dst``, performs an indirect 19call of a BPF function whose address is held in the ``dst`` register. The 20``src``, ``offset`` and ``imm`` fields are reserved and must be zero. 21 22The address of a BPF function gets into a register in one of two ways: 23 24* it is loaded by a 64-bit immediate instruction with ``src`` = 25 ``BPF_PSEUDO_FUNC``; 26* it is read, with a 64-bit load, from a frozen read-only array map, that no 27 other program uses, that holds its read-only data: tables of functions, 28 structures of operations, vtables, where pointers to functions may be mixed 29 with other data. In the map a pointer to a function is the offset in bytes 30 of its first instruction in the program, and that is how the verifier 31 recognizes it. It is replaced with the address of the function when 32 the program is loaded. The program reads it from there, which requires 33 ``CAP_PERFMON``. 34 35In both cases only static functions can be referenced. Therefore all functions 36that can be called indirectly are known to the verifier before it starts to 37analyze the program, and ``callx`` is verified as a direct call of every 38function that ``dst`` may point to at that instruction. The same rules apply: 39the calls can not be recursive, and the depth of the call chain and its 40combined stack size are limited. 41 42Calling helper or kernel functions through a register, indirect calls of global 43functions, and tail calls in functions that are called via ``callx`` are not 44supported. ``callx`` requires the BPF JIT. 45 46Maps 47==== 48 49Linux only supports the 'map_val(map)' operation on array maps with a single element. 50 51Linux uses an fd_array to store maps associated with a BPF program. Thus, 52map_by_idx(imm) uses the fd at that index in the array. 53 54Variables 55========= 56 57The following 64-bit immediate instruction specifies that a variable address, 58which corresponds to some integer stored in the 'imm' field, should be loaded: 59 60========================= ====== === ========================================= =========== ============== 61opcode construction opcode src pseudocode imm type dst type 62========================= ====== === ========================================= =========== ============== 63BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = var_addr(imm) variable id data pointer 64========================= ====== === ========================================= =========== ============== 65 66On Linux, this integer is a BTF ID. 67 68Legacy BPF Packet access instructions 69===================================== 70 71As mentioned in the `ISA standard documentation 72<instruction-set.html#legacy-bpf-packet-access-instructions>`_, 73Linux has special eBPF instructions for access to packet data that have been 74carried over from classic BPF to retain the performance of legacy socket 75filters running in the eBPF interpreter. 76 77The instructions come in two forms: ``BPF_ABS | <size> | BPF_LD`` and 78``BPF_IND | <size> | BPF_LD``. 79 80These instructions are used to access packet data and can only be used when 81the program context is a pointer to a networking packet. ``BPF_ABS`` 82accesses packet data at an absolute offset specified by the immediate data 83and ``BPF_IND`` access packet data at an offset that includes the value of 84a register in addition to the immediate data. 85 86These instructions have seven implicit operands: 87 88* Register R6 is an implicit input that must contain a pointer to a 89 struct sk_buff. 90* Register R0 is an implicit output which contains the data fetched from 91 the packet. 92* Registers R1-R5 are scratch registers that are clobbered by the 93 instruction. 94 95These instructions have an implicit program exit condition as well. If an 96eBPF program attempts access data beyond the packet boundary, the 97program execution will be aborted. 98 99``BPF_ABS | BPF_W | BPF_LD`` (0x20) means:: 100 101 R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + imm)) 102 103where ``ntohl()`` converts a 32-bit value from network byte order to host byte order. 104 105``BPF_IND | BPF_W | BPF_LD`` (0x40) means:: 106 107 R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + src + imm)) 108