1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2018 Intel Corporation. 3 4AF_PACKET Poll Mode Driver 5========================== 6 7The AF_PACKET socket in Linux allows an application to receive and send raw 8packets. This Linux-specific PMD binds to an AF_PACKET socket and allows 9a DPDK application to send and receive raw packets through the Kernel. 10 11In order to improve Rx and Tx performance this implementation makes use of 12PACKET_MMAP, which provides a mmapped ring buffer, shared between user space 13and kernel, that's used to send and receive packets. This helps reducing system 14calls and the copies needed between user space and Kernel. 15 16Options and inherent limitations 17-------------------------------- 18 19The following options can be provided to set up an af_packet port in DPDK. 20Some of these, in turn, will be used to configure the PACKET_MMAP settings. 21 22* ``iface`` - name of the Kernel interface to attach to (required); 23* ``qpairs`` - number of Rx and Tx queues (optional, default 1); 24* ``qdisc_bypass`` - set PACKET_QDISC_BYPASS option in AF_PACKET (optional, 25 disabled by default); 26* ``fanout_mode`` - set fanout algorithm. 27 Possible choices: hash, lb, cpu, rollover, rnd, qm (optional, default hash); 28* ``blocksz`` - PACKET_MMAP block size (optional, default 4096); 29* ``framesz`` - PACKET_MMAP frame size (optional, default 2048B; Note: multiple 30 of 16B); 31* ``framecnt`` - PACKET_MMAP frame count (optional, default 512). 32 33For details regarding ``fanout_mode`` argument, you can consult the 34`PACKET_FANOUT documentation <https://www.man7.org/linux/man-pages/man7/packet.7.html>`_. 35 36As an example, when ``fanout_mode=cpu`` is selected, the PACKET_FANOUT_CPU mode 37will be set on the sockets, so that on frame reception, 38the socket will be selected based on the CPU on which the packet arrived. 39 40Only one ``fanout_mode`` can be chosen. 41If left unspecified, the default is to use the ``PACKET_FANOUT_HASH`` behavior 42of AF_PACKET for frame reception. 43 44Because this implementation is based on PACKET_MMAP, and PACKET_MMAP has its 45own pre-requisites, it should be noted that the inner workings of PACKET_MMAP 46should be carefully considered before modifying some of these options (namely, 47``blocksz``, ``framesz`` and ``framecnt`` above). 48 49As an example, if one changes ``framesz`` to be 1024B, it is expected that 50``blocksz`` is set to at least 1024B as well (although 2048B in this case would 51allow two "frames" per "block"). 52 53This restriction happens because PACKET_MMAP expects each single "frame" to fit 54inside of a "block". And although multiple "frames" can fit inside of a single 55"block", a "frame" may not span across two "blocks". 56 57For the full details behind PACKET_MMAP's structures and settings, consider 58reading the `PACKET_MMAP documentation in the Kernel 59<https://www.kernel.org/doc/Documentation/networking/packet_mmap.txt>`_. 60 61Prerequisites 62------------- 63 64This is a Linux-specific PMD, thus the following prerequisites apply: 65 66* A Linux Kernel; 67* A Kernel bound interface to attach to (e.g. a tap interface). 68 69Set up an af_packet interface 70----------------------------- 71 72The following example will set up an af_packet interface in DPDK with the 73default options described above (blocksz=4096B, framesz=2048B and 74framecnt=512): 75 76.. code-block:: console 77 78 --vdev=eth_af_packet0,iface=tap0,blocksz=4096,framesz=2048,framecnt=512,qpairs=1,qdisc_bypass=0,fanout_mode=hash 79 80Features and Limitations 81------------------------ 82 83* The PMD will re-insert the VLAN tag transparently to the packet if the kernel 84 strips it, as long as the ``RTE_ETH_RX_OFFLOAD_VLAN_STRIP`` is not enabled by the 85 application. 86* The PMD will add the kernel packet timestamp with nanoseconds resolution and 87 UNIX origo, i.e. time since 1-JAN-1970 UTC, if ``RTE_ETH_RX_OFFLOAD_TIMESTAMP`` is enabled. 88