doc/guides/nics/af_packet.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 AF_PACKET Poll Mode Driver
   5 ==========================
   6
   7 The AF_PACKET socket in Linux allows an application to receive and send raw
   8 packets. This Linux-specific PMD driver binds to an AF_PACKET socket and allows
   9 a DPDK application to send and receive raw packets through the Kernel.
  10
  11 In order to improve Rx and Tx performance this implementation makes use of
  12 PACKET_MMAP, which provides a mmap'ed ring buffer, shared between user space
  13 and kernel, that's used to send and receive packets. This helps reducing system
  14 calls and the copies needed between user space and Kernel.
  15
  16 The PACKET_FANOUT_HASH behavior of AF_PACKET is used for frame reception.
  17
  18 Options and inherent limitations
  19 --------------------------------
  20
  21 The following options can be provided to set up an af_packet port in DPDK.
  22 Some of these, in turn, will be used to configure the PACKET_MMAP settings.
  23
  24 *   ``iface`` - name of the Kernel interface to attach to (required);
  25 *   ``qpairs`` - number of Rx and Tx queues (optional, default 1);
  26 *   ``qdisc_bypass`` - set PACKET_QDISC_BYPASS option in AF_PACKET (optional,
  27     disabled by default);
  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
  33 Because this implementation is based on PACKET_MMAP, and PACKET_MMAP has its
  34 own pre-requisites, it should be noted that the inner workings of PACKET_MMAP
  35 should be carefully considered before modifying some of these options (namely,
  36 ``blocksz``, ``framesz`` and ``framecnt`` above).
  37
  38 As an example, if one changes ``framesz`` to be 1024B, it is expected that
  39 ``blocksz`` is set to at least 1024B as well (although 2048B in this case would
  40 allow two "frames" per "block").
  41
  42 This restriction happens because PACKET_MMAP expects each single "frame" to fit
  43 inside of a "block". And although multiple "frames" can fit inside of a single
  44 "block", a "frame" may not span across two "blocks".
  45
  46 For the full details behind PACKET_MMAP's structures and settings, consider
  47 reading the `PACKET_MMAP documentation in the Kernel
  48 <https://www.kernel.org/doc/Documentation/networking/packet_mmap.txt>`_.
  49
  50 Prerequisites
  51 -------------
  52
  53 This is a Linux-specific PMD, thus the following prerequisites apply:
  54
  55 *  A Linux Kernel;
  56 *  A Kernel bound interface to attach to (e.g. a tap interface).
  57
  58 Set up an af_packet interface
  59 -----------------------------
  60
  61 The following example will set up an af_packet interface in DPDK with the
  62 default options described above (blocksz=4096B, framesz=2048B and
  63 framecnt=512):
  64
  65 .. code-block:: console
  66
  67     --vdev=eth_af_packet0,iface=tap0,blocksz=4096,framesz=2048,framecnt=512,qpairs=1,qdisc_bypass=0