net/af_xdp: support unaligned umem chunks
[dpdk.git] / doc / guides / nics / af_xdp.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2019 Intel Corporation.
3
4 AF_XDP Poll Mode Driver
5 ==========================
6
7 AF_XDP is an address family that is optimized for high performance
8 packet processing. AF_XDP sockets enable the possibility for XDP program to
9 redirect packets to a memory buffer in userspace.
10
11 For 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
15 This Linux-specific PMD driver creates the AF_XDP socket and binds it to a
16 specific netdev queue, it allows a DPDK application to send and receive raw
17 packets through the socket which would bypass the kernel network stack.
18 Current implementation only supports single queue, multi-queues feature will
19 be added later.
20
21 Note that MTU of AF_XDP PMD is limited due to XDP lacks support for
22 fragmentation.
23
24 AF_XDP PMD enables need_wakeup flag by default if it is supported. This
25 need_wakeup feature is used to support executing application and driver on the
26 same core efficiently. This feature not only has a large positive performance
27 impact for the one core case, but also does not degrade 2 core performance and
28 actually improves it for Tx heavy workloads.
29
30 Options
31 -------
32
33 The following options can be provided to set up an af_xdp port in DPDK.
34
35 *   ``iface`` - name of the Kernel interface to attach to (required);
36 *   ``start_queue`` - starting netdev queue id (optional, default 0);
37 *   ``queue_count`` - total netdev queue number (optional, default 1);
38
39 Prerequisites
40 -------------
41
42 This 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
52 Set up an af_xdp interface
53 -----------------------------
54
55 The following example will set up an af_xdp interface in DPDK:
56
57 .. code-block:: console
58
59     --vdev net_af_xdp,iface=ens786f1