doc/guides/prog_guide/bpf_lib.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 Berkeley Packet Filter Library
   5 ==============================
   6
   7 The DPDK provides an BPF library that gives the ability
   8 to load and execute Enhanced Berkeley Packet Filter (eBPF) bytecode within
   9 user-space dpdk application.
  10
  11 It supports basic set of features from eBPF spec.
  12 Please refer to the
  13 `eBPF spec <https://www.kernel.org/doc/Documentation/networking/filter.txt>`
  14 for more information.
  15 Also it introduces basic framework to load/unload BPF-based filters
  16 on eth devices (right now only via SW RX/TX callbacks).
  17
  18 The library API provides the following basic operations:
  19
  20 *  Create a new BPF execution context and load user provided eBPF code into it.
  21
  22 *   Destroy an BPF execution context and its runtime structures and free the associated memory.
  23
  24 *   Execute eBPF bytecode associated with provided input parameter.
  25
  26 *   Provide information about natively compiled code for given BPF context.
  27
  28 *   Load BPF program from the ELF file and install callback to execute it on given ethdev port/queue.
  29
  30 Packet data load instructions
  31 -----------------------------
  32
  33 DPDK supports two non-generic instructions: ``(BPF_ABS | size | BPF_LD)``
  34 and ``(BPF_IND | size | BPF_LD)`` which are used to access packet data.
  35 These instructions can only be used when execution context is a pointer to
  36 ``struct rte_mbuf`` and have seven implicit operands.
  37 Register ``R6`` is an implicit input that must contain pointer to ``rte_mbuf``.
  38 Register ``R0`` is an implicit output which contains the data fetched from the
  39 packet. Registers ``R1-R5`` are scratch registers
  40 and must not be used to store the data across these instructions.
  41 These instructions have implicit program exit condition as well. When
  42 eBPF program is trying to access the data beyond the packet boundary,
  43 the interpreter will abort the execution of the program. JIT compilers
  44 therefore must preserve this property. ``src_reg`` and ``imm32`` fields are
  45 explicit inputs to these instructions.
  46 For example, ``(BPF_IND | BPF_W | BPF_LD)`` means:
  47
  48 .. code-block:: c
  49
  50     uint32_t tmp;
  51     R0 = rte_pktmbuf_read((const struct rte_mbuf *)R6,  src_reg + imm32,
  52         sizeof(tmp), &tmp);
  53     if (R0 == NULL) return FAILED;
  54     R0 = ntohl(*(uint32_t *)R0);
  55
  56 and ``R1-R5`` were scratched.
  57
  58
  59 Not currently supported eBPF features
  60 -------------------------------------
  61
  62  - JIT support only available for X86_64 and arm64 platforms
  63  - cBPF
  64  - tail-pointer call
  65  - eBPF MAP
  66  - external function calls for 32-bit platforms