src/plugins/af_xdp/af_xdp_doc.rst

   1 AF_XDP device driver
   2 ====================
   3
   4 This driver relies on Linux AF_XDP socket to rx/tx Ethernet packets.
   5
   6 Maturity level
   7 --------------
   8
   9 Under development: it should work, but has not been thoroughly tested.
  10
  11 Features
  12 --------
  13
  14 -  copy and zero-copy mode
  15 -  multiqueue
  16 -  API
  17 -  custom eBPF program
  18 -  polling, interrupt and adaptive mode
  19
  20 Known limitations
  21 -----------------
  22
  23 MTU
  24 ~~~
  25
  26 Because of AF_XDP restrictions, the MTU is limited to below PAGE_SIZE
  27 (4096-bytes on most systems) minus 256-bytes, and they are additional
  28 limitations depending upon specific Linux device drivers. As a rule of
  29 thumb, a MTU of 3000-bytes or less should be safe.
  30
  31 Number of buffers
  32 ~~~~~~~~~~~~~~~~~
  33
  34 Furthermore, upon UMEM creation, the kernel allocates a
  35 physically-contiguous structure, whose size is proportional to the
  36 number of 4KB pages contained in the UMEM. That allocation might fail
  37 when the number of buffers allocated by VPP is too high. That number can
  38 be controlled with the ``buffers { buffers-per-numa }`` configuration
  39 option. Finally, note that because of this limitation, this plugin is
  40 unlikely to be compatible with the use of 1GB hugepages.
  41
  42 Interrupt mode
  43 ~~~~~~~~~~~~~~
  44
  45 Interrupt and adaptive mode are supported but is limited by default to
  46 single threaded (no worker) configurations because of a kernel
  47 limitation prior to 5.6. You can bypass the limitation at interface
  48 creation time by adding the ``no-syscall-lock`` parameter, but you must
  49 be sure that your kernel can support it, otherwise you will experience
  50 double-frees. See
  51 https://lore.kernel.org/bpf/BYAPR11MB365382C5DB1E5FCC53242609C1549@BYAPR11MB3653.namprd11.prod.outlook.com/
  52 for more details.
  53
  54 Mellanox
  55 ~~~~~~~~
  56
  57 When setting the number of queues on Mellanox NIC with ``ethtool -L``,
  58 you must use twice the amount of configured queues: it looks like the
  59 Linux driver will create separate RX queues and TX queues (but all
  60 queues can be used for both RX and TX, the NIC will just not sent any
  61 packet on “pure” TX queues. Confused? So I am.). For example if you set
  62 ``combined 2`` you will effectively have to create 4 rx queues in AF_XDP
  63 if you want to be sure to receive all packets.
  64
  65 Requirements
  66 ------------
  67
  68 This drivers supports Linux kernel 5.4 and later. Kernels older than 5.4
  69 are missing unaligned buffers support.
  70
  71 The Linux kernel interface must be up and have enough queues before
  72 creating the VPP AF_XDP interface, otherwise Linux will deny creating
  73 the AF_XDP socket. The AF_XDP interface will claim NIC RX queue starting
  74 from 0, up to the requested number of RX queues (only 1 by default). It
  75 means all packets destined to NIC RX queue ``[0, num_rx_queues[`` will
  76 be received by the AF_XDP interface, and only them. Depending on your
  77 configuration, there will usually be several RX queues (typically 1 per
  78 core) and packets are spread across queues by RSS. In order to receive
  79 consistent traffic, you **must** program the NIC dispatching
  80 accordingly. The simplest way to get all the packets is to specify
  81 ``num-rx-queues all`` to grab all available queues or to reconfigure the
  82 Linux kernel driver to use only ``num_rx_queues`` RX queues (i.e. all NIC
  83 queues will be associated with the AF_XDP socket):
  84
  85 ::
  86
  87    ~# ethtool -L <iface> combined <num_rx_queues>
  88
  89 Additionally, the VPP AF_XDP interface will use a MAC address generated
  90 at creation time instead of the Linux kernel interface MAC. As Linux
  91 kernel interface are not in promiscuous mode by default (see below) this
  92 will results in a useless configuration where the VPP AF_XDP interface
  93 only receives packets destined to the Linux kernel interface MAC just to
  94 drop them because the destination MAC does not match VPP AF_XDP
  95 interface MAC. If you want to use the Linux interface MAC for the VPP
  96 AF_XDP interface, you can change it afterwards in VPP:
  97
  98 ::
  99
 100    ~# vppctl set int mac address <iface> <mac>
 101
 102 Finally, if you wish to receive all packets and not only the packets
 103 destined to the Linux kernel interface MAC you need to set the Linux
 104 kernel interface in promiscuous mode:
 105
 106 ::
 107
 108    ~# ip link set dev <iface> promisc on
 109
 110 Security considerations
 111 -----------------------
 112
 113 When creating an AF_XDP interface, it will receive all packets arriving
 114 to the NIC RX queue ``[0, num_rx_queues[``. You need to configure the
 115 Linux kernel NIC driver properly to ensure that only intended packets
 116 will arrive in this queue. There is no way to filter the packets
 117 after-the-fact using e.g. netfilter or eBPF.
 118
 119 Quickstart
 120 ----------
 121
 122 1. Put the Linux kernel interface up and in promiscuous mode:
 123
 124 ::
 125
 126    ~# ip l set dev enp216s0f0 promisc on up
 127
 128 2. Create the AF_XDP interface:
 129
 130 ::
 131
 132    ~# vppctl create int af_xdp host-if enp216s0f0 num-rx-queues all
 133
 134 3. Use the interface as usual, e.g.:
 135
 136 ::
 137
 138    ~# vppctl set int ip addr enp216s0f0/0 1.1.1.1/24
 139    ~# vppctl set int st enp216s0f0/0 up
 140    ~# vppctl ping 1.1.1.100`
 141
 142 Custom eBPF XDP program
 143 -----------------------
 144
 145 This driver relies on libbpf and as such relies on the ``xsks_map`` eBPF
 146 map. The default behavior is to use the XDP program already attached to
 147 the interface if any, otherwise load the default one. You can request to
 148 load a custom XDP program with the ``prog`` option when creating the
 149 interface in VPP:
 150
 151 ::
 152
 153    ~# vppctl create int af_xdp host-if enp216s0f0 num-rx-queues 4 prog extras/bpf/af_xdp.bpf.o
 154
 155 In that case it will replace any previously attached program. A custom
 156 XDP program example is provided in ``extras/bpf/``.
 157
 158 Performance consideration
 159 -------------------------
 160
 161 AF_XDP relies on the Linux kernel NIC driver to rx/tx packets. To reach
 162 high-performance (10’s MPPS), the Linux kernel NIC driver must support
 163 zero-copy mode and its RX path must run on a dedicated core in the NUMA
 164 where the NIC is physically connected.