Documentation/networking/af_xdp.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======
   4 AF_XDP
   5 ======
   6
   7 Overview
   8 ========
   9
  10 AF_XDP is an address family that is optimized for high performance
  11 packet processing.
  12
  13 This document assumes that the reader is familiar with BPF and XDP. If
  14 not, the Cilium project has an excellent reference guide at
  15 http://cilium.readthedocs.io/en/latest/bpf/.
  16
  17 Using the XDP_REDIRECT action from an XDP program, the program can
  18 redirect ingress frames to other XDP enabled netdevs, using the
  19 bpf_redirect_map() function. AF_XDP sockets enable the possibility for
  20 XDP programs to redirect frames to a memory buffer in a user-space
  21 application.
  22
  23 An AF_XDP socket (XSK) is created with the normal socket()
  24 syscall. Associated with each XSK are two rings: the RX ring and the
  25 TX ring. A socket can receive packets on the RX ring and it can send
  26 packets on the TX ring. These rings are registered and sized with the
  27 setsockopts XDP_RX_RING and XDP_TX_RING, respectively. It is mandatory
  28 to have at least one of these rings for each socket. An RX or TX
  29 descriptor ring points to a data buffer in a memory area called a
  30 UMEM. RX and TX can share the same UMEM so that a packet does not have
  31 to be copied between RX and TX. Moreover, if a packet needs to be kept
  32 for a while due to a possible retransmit, the descriptor that points
  33 to that packet can be changed to point to another and reused right
  34 away. This again avoids copying data.
  35
  36 The UMEM consists of a number of equally sized chunks. A descriptor in
  37 one of the rings references a frame by referencing its addr. The addr
  38 is simply an offset within the entire UMEM region. The user space
  39 allocates memory for this UMEM using whatever means it feels is most
  40 appropriate (malloc, mmap, huge pages, etc). This memory area is then
  41 registered with the kernel using the new setsockopt XDP_UMEM_REG. The
  42 UMEM also has two rings: the FILL ring and the COMPLETION ring. The
  43 fill ring is used by the application to send down addr for the kernel
  44 to fill in with RX packet data. References to these frames will then
  45 appear in the RX ring once each packet has been received. The
  46 completion ring, on the other hand, contains frame addr that the
  47 kernel has transmitted completely and can now be used again by user
  48 space, for either TX or RX. Thus, the frame addrs appearing in the
  49 completion ring are addrs that were previously transmitted using the
  50 TX ring. In summary, the RX and FILL rings are used for the RX path
  51 and the TX and COMPLETION rings are used for the TX path.
  52
  53 The socket is then finally bound with a bind() call to a device and a
  54 specific queue id on that device, and it is not until bind is
  55 completed that traffic starts to flow.
  56
  57 The UMEM can be shared between processes, if desired. If a process
  58 wants to do this, it simply skips the registration of the UMEM and its
  59 corresponding two rings, sets the XDP_SHARED_UMEM flag in the bind
  60 call and submits the XSK of the process it would like to share UMEM
  61 with as well as its own newly created XSK socket. The new process will
  62 then receive frame addr references in its own RX ring that point to
  63 this shared UMEM. Note that since the ring structures are
  64 single-consumer / single-producer (for performance reasons), the new
  65 process has to create its own socket with associated RX and TX rings,
  66 since it cannot share this with the other process. This is also the
  67 reason that there is only one set of FILL and COMPLETION rings per
  68 UMEM. It is the responsibility of a single process to handle the UMEM.
  69
  70 How is then packets distributed from an XDP program to the XSKs? There
  71 is a BPF map called XSKMAP (or BPF_MAP_TYPE_XSKMAP in full). The
  72 user-space application can place an XSK at an arbitrary place in this
  73 map. The XDP program can then redirect a packet to a specific index in
  74 this map and at this point XDP validates that the XSK in that map was
  75 indeed bound to that device and ring number. If not, the packet is
  76 dropped. If the map is empty at that index, the packet is also
  77 dropped. This also means that it is currently mandatory to have an XDP
  78 program loaded (and one XSK in the XSKMAP) to be able to get any
  79 traffic to user space through the XSK.
  80
  81 AF_XDP can operate in two different modes: XDP_SKB and XDP_DRV. If the
  82 driver does not have support for XDP, or XDP_SKB is explicitly chosen
  83 when loading the XDP program, XDP_SKB mode is employed that uses SKBs
  84 together with the generic XDP support and copies out the data to user
  85 space. A fallback mode that works for any network device. On the other
  86 hand, if the driver has support for XDP, it will be used by the AF_XDP
  87 code to provide better performance, but there is still a copy of the
  88 data into user space.
  89
  90 Concepts
  91 ========
  92
  93 In order to use an AF_XDP socket, a number of associated objects need
  94 to be setup.
  95
  96 Jonathan Corbet has also written an excellent article on LWN,
  97 "Accelerating networking with AF_XDP". It can be found at
  98 https://lwn.net/Articles/750845/.
  99
 100 UMEM
 101 ----
 102
 103 UMEM is a region of virtual contiguous memory, divided into
 104 equal-sized frames. An UMEM is associated to a netdev and a specific
 105 queue id of that netdev. It is created and configured (chunk size,
 106 headroom, start address and size) by using the XDP_UMEM_REG setsockopt
 107 system call. A UMEM is bound to a netdev and queue id, via the bind()
 108 system call.
 109
 110 An AF_XDP is socket linked to a single UMEM, but one UMEM can have
 111 multiple AF_XDP sockets. To share an UMEM created via one socket A,
 112 the next socket B can do this by setting the XDP_SHARED_UMEM flag in
 113 struct sockaddr_xdp member sxdp_flags, and passing the file descriptor
 114 of A to struct sockaddr_xdp member sxdp_shared_umem_fd.
 115
 116 The UMEM has two single-producer/single-consumer rings, that are used
 117 to transfer ownership of UMEM frames between the kernel and the
 118 user-space application.
 119
 120 Rings
 121 -----
 122
 123 There are a four different kind of rings: Fill, Completion, RX and
 124 TX. All rings are single-producer/single-consumer, so the user-space
 125 application need explicit synchronization of multiple
 126 processes/threads are reading/writing to them.
 127
 128 The UMEM uses two rings: Fill and Completion. Each socket associated
 129 with the UMEM must have an RX queue, TX queue or both. Say, that there
 130 is a setup with four sockets (all doing TX and RX). Then there will be
 131 one Fill ring, one Completion ring, four TX rings and four RX rings.
 132
 133 The rings are head(producer)/tail(consumer) based rings. A producer
 134 writes the data ring at the index pointed out by struct xdp_ring
 135 producer member, and increasing the producer index. A consumer reads
 136 the data ring at the index pointed out by struct xdp_ring consumer
 137 member, and increasing the consumer index.
 138
 139 The rings are configured and created via the _RING setsockopt system
 140 calls and mmapped to user-space using the appropriate offset to mmap()
 141 (XDP_PGOFF_RX_RING, XDP_PGOFF_TX_RING, XDP_UMEM_PGOFF_FILL_RING and
 142 XDP_UMEM_PGOFF_COMPLETION_RING).
 143
 144 The size of the rings need to be of size power of two.
 145
 146 UMEM Fill Ring
 147 ~~~~~~~~~~~~~~
 148
 149 The Fill ring is used to transfer ownership of UMEM frames from
 150 user-space to kernel-space. The UMEM addrs are passed in the ring. As
 151 an example, if the UMEM is 64k and each chunk is 4k, then the UMEM has
 152 16 chunks and can pass addrs between 0 and 64k.
 153
 154 Frames passed to the kernel are used for the ingress path (RX rings).
 155
 156 The user application produces UMEM addrs to this ring. Note that, if
 157 running the application with aligned chunk mode, the kernel will mask
 158 the incoming addr.  E.g. for a chunk size of 2k, the log2(2048) LSB of
 159 the addr will be masked off, meaning that 2048, 2050 and 3000 refers
 160 to the same chunk. If the user application is run in the unaligned
 161 chunks mode, then the incoming addr will be left untouched.
 162
 163
 164 UMEM Completion Ring
 165 ~~~~~~~~~~~~~~~~~~~~
 166
 167 The Completion Ring is used transfer ownership of UMEM frames from
 168 kernel-space to user-space. Just like the Fill ring, UMEM indicies are
 169 used.
 170
 171 Frames passed from the kernel to user-space are frames that has been
 172 sent (TX ring) and can be used by user-space again.
 173
 174 The user application consumes UMEM addrs from this ring.
 175
 176
 177 RX Ring
 178 ~~~~~~~
 179
 180 The RX ring is the receiving side of a socket. Each entry in the ring
 181 is a struct xdp_desc descriptor. The descriptor contains UMEM offset
 182 (addr) and the length of the data (len).
 183
 184 If no frames have been passed to kernel via the Fill ring, no
 185 descriptors will (or can) appear on the RX ring.
 186
 187 The user application consumes struct xdp_desc descriptors from this
 188 ring.
 189
 190 TX Ring
 191 ~~~~~~~
 192
 193 The TX ring is used to send frames. The struct xdp_desc descriptor is
 194 filled (index, length and offset) and passed into the ring.
 195
 196 To start the transfer a sendmsg() system call is required. This might
 197 be relaxed in the future.
 198
 199 The user application produces struct xdp_desc descriptors to this
 200 ring.
 201
 202 XSKMAP / BPF_MAP_TYPE_XSKMAP
 203 ----------------------------
 204
 205 On XDP side there is a BPF map type BPF_MAP_TYPE_XSKMAP (XSKMAP) that
 206 is used in conjunction with bpf_redirect_map() to pass the ingress
 207 frame to a socket.
 208
 209 The user application inserts the socket into the map, via the bpf()
 210 system call.
 211
 212 Note that if an XDP program tries to redirect to a socket that does
 213 not match the queue configuration and netdev, the frame will be
 214 dropped. E.g. an AF_XDP socket is bound to netdev eth0 and
 215 queue 17. Only the XDP program executing for eth0 and queue 17 will
 216 successfully pass data to the socket. Please refer to the sample
 217 application (samples/bpf/) in for an example.
 218
 219 Usage
 220 =====
 221
 222 In order to use AF_XDP sockets there are two parts needed. The
 223 user-space application and the XDP program. For a complete setup and
 224 usage example, please refer to the sample application. The user-space
 225 side is xdpsock_user.c and the XDP side is part of libbpf.
 226
 227 The XDP code sample included in tools/lib/bpf/xsk.c is the following::
 228
 229    SEC("xdp_sock") int xdp_sock_prog(struct xdp_md *ctx)
 230    {
 231        int index = ctx->rx_queue_index;
 232
 233        // A set entry here means that the correspnding queue_id
 234        // has an active AF_XDP socket bound to it.
 235        if (bpf_map_lookup_elem(&xsks_map, &index))
 236            return bpf_redirect_map(&xsks_map, index, 0);
 237
 238        return XDP_PASS;
 239    }
 240
 241 Naive ring dequeue and enqueue could look like this::
 242
 243     // struct xdp_rxtx_ring {
 244     //  __u32 *producer;
 245     //  __u32 *consumer;
 246     //  struct xdp_desc *desc;
 247     // };
 248
 249     // struct xdp_umem_ring {
 250     //  __u32 *producer;
 251     //  __u32 *consumer;
 252     //  __u64 *desc;
 253     // };
 254
 255     // typedef struct xdp_rxtx_ring RING;
 256     // typedef struct xdp_umem_ring RING;
 257
 258     // typedef struct xdp_desc RING_TYPE;
 259     // typedef __u64 RING_TYPE;
 260
 261     int dequeue_one(RING *ring, RING_TYPE *item)
 262     {
 263         __u32 entries = *ring->producer - *ring->consumer;
 264
 265         if (entries == 0)
 266             return -1;
 267
 268         // read-barrier!
 269
 270         *item = ring->desc[*ring->consumer & (RING_SIZE - 1)];
 271         (*ring->consumer)++;
 272         return 0;
 273     }
 274
 275     int enqueue_one(RING *ring, const RING_TYPE *item)
 276     {
 277         u32 free_entries = RING_SIZE - (*ring->producer - *ring->consumer);
 278
 279         if (free_entries == 0)
 280             return -1;
 281
 282         ring->desc[*ring->producer & (RING_SIZE - 1)] = *item;
 283
 284         // write-barrier!
 285
 286         (*ring->producer)++;
 287         return 0;
 288     }
 289
 290
 291 For a more optimized version, please refer to the sample application.
 292
 293 Sample application
 294 ==================
 295
 296 There is a xdpsock benchmarking/test application included that
 297 demonstrates how to use AF_XDP sockets with both private and shared
 298 UMEMs. Say that you would like your UDP traffic from port 4242 to end
 299 up in queue 16, that we will enable AF_XDP on. Here, we use ethtool
 300 for this::
 301
 302       ethtool -N p3p2 rx-flow-hash udp4 fn
 303       ethtool -N p3p2 flow-type udp4 src-port 4242 dst-port 4242 \
 304           action 16
 305
 306 Running the rxdrop benchmark in XDP_DRV mode can then be done
 307 using::
 308
 309       samples/bpf/xdpsock -i p3p2 -q 16 -r -N
 310
 311 For XDP_SKB mode, use the switch "-S" instead of "-N" and all options
 312 can be displayed with "-h", as usual.
 313
 314 FAQ
 315 =======
 316
 317 Q: I am not seeing any traffic on the socket. What am I doing wrong?
 318
 319 A: When a netdev of a physical NIC is initialized, Linux usually
 320    allocates one Rx and Tx queue pair per core. So on a 8 core system,
 321    queue ids 0 to 7 will be allocated, one per core. In the AF_XDP
 322    bind call or the xsk_socket__create libbpf function call, you
 323    specify a specific queue id to bind to and it is only the traffic
 324    towards that queue you are going to get on you socket. So in the
 325    example above, if you bind to queue 0, you are NOT going to get any
 326    traffic that is distributed to queues 1 through 7. If you are
 327    lucky, you will see the traffic, but usually it will end up on one
 328    of the queues you have not bound to.
 329
 330    There are a number of ways to solve the problem of getting the
 331    traffic you want to the queue id you bound to. If you want to see
 332    all the traffic, you can force the netdev to only have 1 queue, queue
 333    id 0, and then bind to queue 0. You can use ethtool to do this::
 334
 335      sudo ethtool -L <interface> combined 1
 336
 337    If you want to only see part of the traffic, you can program the
 338    NIC through ethtool to filter out your traffic to a single queue id
 339    that you can bind your XDP socket to. Here is one example in which
 340    UDP traffic to and from port 4242 are sent to queue 2::
 341
 342      sudo ethtool -N <interface> rx-flow-hash udp4 fn
 343      sudo ethtool -N <interface> flow-type udp4 src-port 4242 dst-port \
 344      4242 action 2
 345
 346    A number of other ways are possible all up to the capabilitites of
 347    the NIC you have.
 348
 349 Credits
 350 =======
 351
 352 - Björn Töpel (AF_XDP core)
 353 - Magnus Karlsson (AF_XDP core)
 354 - Alexander Duyck
 355 - Alexei Starovoitov
 356 - Daniel Borkmann
 357 - Jesper Dangaard Brouer
 358 - John Fastabend
 359 - Jonathan Corbet (LWN coverage)
 360 - Michael S. Tsirkin
 361 - Qi Z Zhang
 362 - Willem de Bruijn