Documentation/bpf/linux-notes.rst

   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))