114b8f0bbSKonstantin Ananyev.. SPDX-License-Identifier: BSD-3-Clause 214b8f0bbSKonstantin Ananyev Copyright(c) 2018 Intel Corporation. 314b8f0bbSKonstantin Ananyev 414b8f0bbSKonstantin AnanyevBerkeley Packet Filter Library 514b8f0bbSKonstantin Ananyev============================== 614b8f0bbSKonstantin Ananyev 714b8f0bbSKonstantin AnanyevThe DPDK provides an BPF library that gives the ability 814b8f0bbSKonstantin Ananyevto load and execute Enhanced Berkeley Packet Filter (eBPF) bytecode within 914b8f0bbSKonstantin Ananyevuser-space dpdk application. 1014b8f0bbSKonstantin Ananyev 1114b8f0bbSKonstantin AnanyevIt supports basic set of features from eBPF spec. 1214b8f0bbSKonstantin AnanyevPlease refer to the 1314b8f0bbSKonstantin Ananyev`eBPF spec <https://www.kernel.org/doc/Documentation/networking/filter.txt>` 1414b8f0bbSKonstantin Ananyevfor more information. 1514b8f0bbSKonstantin AnanyevAlso it introduces basic framework to load/unload BPF-based filters 1614b8f0bbSKonstantin Ananyevon eth devices (right now only via SW RX/TX callbacks). 1714b8f0bbSKonstantin Ananyev 1814b8f0bbSKonstantin AnanyevThe library API provides the following basic operations: 1914b8f0bbSKonstantin Ananyev 2014b8f0bbSKonstantin Ananyev* Create a new BPF execution context and load user provided eBPF code into it. 2114b8f0bbSKonstantin Ananyev 2214b8f0bbSKonstantin Ananyev* Destroy an BPF execution context and its runtime structures and free the associated memory. 2314b8f0bbSKonstantin Ananyev 2414b8f0bbSKonstantin Ananyev* Execute eBPF bytecode associated with provided input parameter. 2514b8f0bbSKonstantin Ananyev 2614b8f0bbSKonstantin Ananyev* Provide information about natively compiled code for given BPF context. 2714b8f0bbSKonstantin Ananyev 2814b8f0bbSKonstantin Ananyev* Load BPF program from the ELF file and install callback to execute it on given ethdev port/queue. 2914b8f0bbSKonstantin Ananyev 30*b901d928SKonstantin AnanyevPacket data load instructions 31*b901d928SKonstantin Ananyev----------------------------- 32*b901d928SKonstantin Ananyev 33*b901d928SKonstantin AnanyevDPDK supports two non-generic instructions: ``(BPF_ABS | size | BPF_LD)`` 34*b901d928SKonstantin Ananyevand ``(BPF_IND | size | BPF_LD)`` which are used to access packet data. 35*b901d928SKonstantin AnanyevThese instructions can only be used when execution context is a pointer to 36*b901d928SKonstantin Ananyev``struct rte_mbuf`` and have seven implicit operands. 37*b901d928SKonstantin AnanyevRegister ``R6`` is an implicit input that must contain pointer to ``rte_mbuf``. 38*b901d928SKonstantin AnanyevRegister ``R0`` is an implicit output which contains the data fetched from the 39*b901d928SKonstantin Ananyevpacket. Registers ``R1-R5`` are scratch registers 40*b901d928SKonstantin Ananyevand must not be used to store the data across these instructions. 41*b901d928SKonstantin AnanyevThese instructions have implicit program exit condition as well. When 42*b901d928SKonstantin AnanyeveBPF program is trying to access the data beyond the packet boundary, 43*b901d928SKonstantin Ananyevthe interpreter will abort the execution of the program. JIT compilers 44*b901d928SKonstantin Ananyevtherefore must preserve this property. ``src_reg`` and ``imm32`` fields are 45*b901d928SKonstantin Ananyevexplicit inputs to these instructions. 46*b901d928SKonstantin AnanyevFor example, ``(BPF_IND | BPF_W | BPF_LD)`` means: 47*b901d928SKonstantin Ananyev 48*b901d928SKonstantin Ananyev.. code-block:: c 49*b901d928SKonstantin Ananyev 50*b901d928SKonstantin Ananyev uint32_t tmp; 51*b901d928SKonstantin Ananyev R0 = rte_pktmbuf_read((const struct rte_mbuf *)R6, src_reg + imm32, 52*b901d928SKonstantin Ananyev sizeof(tmp), &tmp); 53*b901d928SKonstantin Ananyev if (R0 == NULL) return FAILED; 54*b901d928SKonstantin Ananyev R0 = ntohl(*(uint32_t *)R0); 55*b901d928SKonstantin Ananyev 56*b901d928SKonstantin Ananyevand ``R1-R5`` were scratched. 57*b901d928SKonstantin Ananyev 58*b901d928SKonstantin Ananyev 5914b8f0bbSKonstantin AnanyevNot currently supported eBPF features 6014b8f0bbSKonstantin Ananyev------------------------------------- 6114b8f0bbSKonstantin Ananyev 626861c010SJerin Jacob - JIT support only available for X86_64 and arm64 platforms 6314b8f0bbSKonstantin Ananyev - cBPF 6414b8f0bbSKonstantin Ananyev - tail-pointer call 6514b8f0bbSKonstantin Ananyev - eBPF MAP 6614b8f0bbSKonstantin Ananyev - external function calls for 32-bit platforms 67