1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2019-2020 Intel Corporation. 3 4AF_XDP Poll Mode Driver 5========================== 6 7AF_XDP is an address family that is optimized for high performance 8packet processing. AF_XDP sockets enable the possibility for XDP program to 9redirect packets to a memory buffer in userspace. 10 11For the full details behind AF_XDP socket, you can refer to 12`AF_XDP documentation in the Kernel 13<https://www.kernel.org/doc/Documentation/networking/af_xdp.rst>`_. 14 15This Linux-specific PMD driver creates the AF_XDP socket and binds it to a 16specific netdev queue, it allows a DPDK application to send and receive raw 17packets through the socket which would bypass the kernel network stack. 18Current implementation only supports single queue, multi-queues feature will 19be added later. 20 21AF_XDP PMD enables need_wakeup flag by default if it is supported. This 22need_wakeup feature is used to support executing application and driver on the 23same core efficiently. This feature not only has a large positive performance 24impact for the one core case, but also does not degrade 2 core performance and 25actually improves it for Tx heavy workloads. 26 27Options 28------- 29 30The following options can be provided to set up an af_xdp port in DPDK. 31 32* ``iface`` - name of the Kernel interface to attach to (required); 33* ``start_queue`` - starting netdev queue id (optional, default 0); 34* ``queue_count`` - total netdev queue number (optional, default 1); 35* ``shared_umem`` - PMD will attempt to share UMEM with others (optional, 36 default 0); 37* ``xdp_prog`` - path to custom xdp program (optional, default none); 38 39Prerequisites 40------------- 41 42This is a Linux-specific PMD, thus the following prerequisites apply: 43 44* A Linux Kernel (version > v4.18) with XDP sockets configuration enabled; 45* libbpf (within kernel version > v5.1-rc4) with latest af_xdp support installed, 46 User can install libbpf via `make install_lib` && `make install_headers` in 47 <kernel src tree>/tools/lib/bpf; 48* A Kernel bound interface to attach to; 49* For need_wakeup feature, it requires kernel version later than v5.3-rc1; 50* For PMD zero copy, it requires kernel version later than v5.4-rc1; 51* For shared_umem, it requires kernel version v5.10 or later and libbpf version 52 v0.2.0 or later. 53* For 32-bit OS, a kernel with version 5.4 or later is required. 54 55Set up an af_xdp interface 56----------------------------- 57 58The following example will set up an af_xdp interface in DPDK: 59 60.. code-block:: console 61 62 --vdev net_af_xdp,iface=ens786f1 63 64Limitations 65----------- 66 67- **MTU** 68 69 The MTU of the AF_XDP PMD is limited due to the XDP requirement of one packet 70 per page. In the PMD we report the maximum MTU for zero copy to be equal 71 to the page size less the frame overhead introduced by AF_XDP (XDP HR = 256) 72 and DPDK (frame headroom = 320). With a 4K page size this works out at 3520. 73 However in practice this value may be even smaller, due to differences between 74 the supported RX buffer sizes of the underlying kernel netdev driver. 75 76 For example, the largest RX buffer size supported by the underlying kernel driver 77 which is less than the page size (4096B) may be 3072B. In this case, the maximum 78 MTU value will be at most 3072, but likely even smaller than this, once relevant 79 headers are accounted for eg. Ethernet and VLAN. 80 81 To determine the actual maximum MTU value of the interface you are using with the 82 AF_XDP PMD, consult the documentation for the kernel driver. 83 84 Note: The AF_XDP PMD will fail to initialise if an MTU which violates the driver's 85 conditions as above is set prior to launching the application. 86 87- **Shared UMEM** 88 89 The sharing of UMEM is only supported for AF_XDP sockets with unique contexts. 90 The context refers to the netdev,qid tuple. 91 92 The following combination will fail: 93 94 .. code-block:: console 95 96 --vdev net_af_xdp0,iface=ens786f1,shared_umem=1 \ 97 --vdev net_af_xdp1,iface=ens786f1,shared_umem=1 \ 98 99 Either of the following however is permitted since either the netdev or qid differs 100 between the two vdevs: 101 102 .. code-block:: console 103 104 --vdev net_af_xdp0,iface=ens786f1,shared_umem=1 \ 105 --vdev net_af_xdp1,iface=ens786f1,start_queue=1,shared_umem=1 \ 106 107 .. code-block:: console 108 109 --vdev net_af_xdp0,iface=ens786f1,shared_umem=1 \ 110 --vdev net_af_xdp1,iface=ens786f2,shared_umem=1 \