| 1 | .. contents:: |
| 2 | .. sectnum:: |
| 3 | |
| 4 | ========================== |
| 5 | Linux implementation notes |
| 6 | ========================== |
| 7 | |
| 8 | This document provides more details specific to the Linux kernel implementation of the eBPF instruction set. |
| 9 | |
| 10 | Byte 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 | |
| 15 | Jump instructions |
| 16 | ================= |
| 17 | |
| 18 | ``BPF_CALL | BPF_X | BPF_JMP`` (0x8d), where the helper function |
| 19 | integer would be read from a specified register, is not currently supported |
| 20 | by the verifier. Any programs with this instruction will fail to load |
| 21 | until such support is added. |
| 22 | |
| 23 | Maps |
| 24 | ==== |
| 25 | |
| 26 | Linux only supports the 'map_val(map)' operation on array maps with a single element. |
| 27 | |
| 28 | Linux uses an fd_array to store maps associated with a BPF program. Thus, |
| 29 | map_by_idx(imm) uses the fd at that index in the array. |
| 30 | |
| 31 | Variables |
| 32 | ========= |
| 33 | |
| 34 | The following 64-bit immediate instruction specifies that a variable address, |
| 35 | which corresponds to some integer stored in the 'imm' field, should be loaded: |
| 36 | |
| 37 | ========================= ====== === ========================================= =========== ============== |
| 38 | opcode construction opcode src pseudocode imm type dst type |
| 39 | ========================= ====== === ========================================= =========== ============== |
| 40 | BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = var_addr(imm) variable id data pointer |
| 41 | ========================= ====== === ========================================= =========== ============== |
| 42 | |
| 43 | On Linux, this integer is a BTF ID. |
| 44 | |
| 45 | Legacy BPF Packet access instructions |
| 46 | ===================================== |
| 47 | |
| 48 | As mentioned in the `ISA standard documentation <instruction-set.rst#legacy-bpf-packet-access-instructions>`_, |
| 49 | Linux has special eBPF instructions for access to packet data that have been |
| 50 | carried over from classic BPF to retain the performance of legacy socket |
| 51 | filters running in the eBPF interpreter. |
| 52 | |
| 53 | The instructions come in two forms: ``BPF_ABS | <size> | BPF_LD`` and |
| 54 | ``BPF_IND | <size> | BPF_LD``. |
| 55 | |
| 56 | These instructions are used to access packet data and can only be used when |
| 57 | the program context is a pointer to a networking packet. ``BPF_ABS`` |
| 58 | accesses packet data at an absolute offset specified by the immediate data |
| 59 | and ``BPF_IND`` access packet data at an offset that includes the value of |
| 60 | a register in addition to the immediate data. |
| 61 | |
| 62 | These instructions have seven implicit operands: |
| 63 | |
| 64 | * Register R6 is an implicit input that must contain a pointer to a |
| 65 | struct sk_buff. |
| 66 | * Register R0 is an implicit output which contains the data fetched from |
| 67 | the packet. |
| 68 | * Registers R1-R5 are scratch registers that are clobbered by the |
| 69 | instruction. |
| 70 | |
| 71 | These instructions have an implicit program exit condition as well. If an |
| 72 | eBPF program attempts access data beyond the packet boundary, the |
| 73 | program execution will be aborted. |
| 74 | |
| 75 | ``BPF_ABS | BPF_W | BPF_LD`` (0x20) means:: |
| 76 | |
| 77 | R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + imm)) |
| 78 | |
| 79 | where ``ntohl()`` converts a 32-bit value from network byte order to host byte order. |
| 80 | |
| 81 | ``BPF_IND | BPF_W | BPF_LD`` (0x40) means:: |
| 82 | |
| 83 | R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + src + imm)) |