net/ixgbe: fix flow control mode setting
[dpdk.git] / doc / guides / nics / virtio.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2010-2015 Intel Corporation.
3
4 Poll Mode Driver for Emulated Virtio NIC
5 ========================================
6
7 Virtio is a para-virtualization framework initiated by IBM, and supported by KVM hypervisor.
8 In the Data Plane Development Kit (DPDK),
9 we provide a virtio Poll Mode Driver (PMD) as a software solution, comparing to SRIOV hardware solution,
10 for fast guest VM to guest VM communication and guest VM to host communication.
11
12 Vhost is a kernel acceleration module for virtio qemu backend.
13 The DPDK extends kni to support vhost raw socket interface,
14 which enables vhost to directly read/ write packets from/to a physical port.
15 With this enhancement, virtio could achieve quite promising performance.
16
17 For basic qemu-KVM installation and other Intel EM poll mode driver in guest VM,
18 please refer to Chapter "Driver for VM Emulated Devices".
19
20 In this chapter, we will demonstrate usage of virtio PMD driver with two backends,
21 standard qemu vhost back end and vhost kni back end.
22
23 Virtio Implementation in DPDK
24 -----------------------------
25
26 For details about the virtio spec, refer to the latest
27 `VIRTIO (Virtual I/O) Device Specification
28 <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio>`_.
29
30 As a PMD, virtio provides packet reception and transmission callbacks.
31
32 In Rx, packets described by the used descriptors in vring are available
33 for virtio to burst out.
34
35 In Tx, packets described by the used descriptors in vring are available
36 for virtio to clean. Virtio will enqueue to be transmitted packets into
37 vring, make them available to the device, and then notify the host back
38 end if necessary.
39
40 Features and Limitations of virtio PMD
41 --------------------------------------
42
43 In this release, the virtio PMD driver provides the basic functionality of packet reception and transmission.
44
45 *   It supports merge-able buffers per packet when receiving packets and scattered buffer per packet
46     when transmitting packets. The packet size supported is from 64 to 1518.
47
48 *   It supports multicast packets and promiscuous mode.
49
50 *   The descriptor number for the Rx/Tx queue is hard-coded to be 256 by qemu 2.7 and below.
51     If given a different descriptor number by the upper application,
52     the virtio PMD generates a warning and fall back to the hard-coded value.
53     Rx queue size can be configurable and up to 1024 since qemu 2.8 and above. Rx queue size is 256
54     by default. Tx queue size is still hard-coded to be 256.
55
56 *   Features of mac/vlan filter are supported, negotiation with vhost/backend are needed to support them.
57     When backend can't support vlan filter, virtio app on guest should not enable vlan filter in order
58     to make sure the virtio port is configured correctly. E.g. do not specify '--enable-hw-vlan' in testpmd
59     command line. Note that, mac/vlan filter is best effort: unwanted packets could still arrive.
60
61 *   "RTE_PKTMBUF_HEADROOM" should be defined
62     no less than "sizeof(struct virtio_net_hdr_mrg_rxbuf)", which is 12 bytes when mergeable or
63     "VIRTIO_F_VERSION_1" is set.
64     no less than "sizeof(struct virtio_net_hdr)", which is 10 bytes, when using non-mergeable.
65
66 *   Virtio does not support runtime configuration.
67
68 *   Virtio supports Link State interrupt.
69
70 *   Virtio supports Rx interrupt (so far, only support 1:1 mapping for queue/interrupt).
71
72 *   Virtio supports software vlan stripping and inserting.
73
74 *   Virtio supports using port IO to get PCI resource when uio/igb_uio module is not available.
75
76 Prerequisites
77 -------------
78
79 The following prerequisites apply:
80
81 *   In the BIOS, turn VT-x and VT-d on
82
83 *   Linux kernel with KVM module; vhost module loaded and ioeventfd supported.
84     Qemu standard backend without vhost support isn't tested, and probably isn't supported.
85
86 Virtio with kni vhost Back End
87 ------------------------------
88
89 This section demonstrates kni vhost back end example setup for Phy-VM Communication.
90
91 .. _figure_host_vm_comms:
92
93 .. figure:: img/host_vm_comms.*
94
95    Host2VM Communication Example Using kni vhost Back End
96
97
98 Host2VM communication example
99
100 #.  Load the kni kernel module:
101
102     .. code-block:: console
103
104         insmod rte_kni.ko
105
106     Other basic DPDK preparations like hugepage enabling, uio port binding are not listed here.
107     Please refer to the *DPDK Getting Started Guide* for detailed instructions.
108
109 #.  Launch the kni user application:
110
111     .. code-block:: console
112
113         examples/kni/build/app/kni -l 0-3 -n 4 -- -p 0x1 -P --config="(0,1,3)"
114
115     This command generates one network device vEth0 for physical port.
116     If specify more physical ports, the generated network device will be vEth1, vEth2, and so on.
117
118     For each physical port, kni creates two user threads.
119     One thread loops to fetch packets from the physical NIC port into the kni receive queue.
120     The other user thread loops to send packets in the kni transmit queue.
121
122     For each physical port, kni also creates a kernel thread that retrieves packets from the kni receive queue,
123     place them onto kni's raw socket's queue and wake up the vhost kernel thread to exchange packets with the virtio virt queue.
124
125     For more details about kni, please refer to :ref:`kni`.
126
127 #.  Enable the kni raw socket functionality for the specified physical NIC port,
128     get the generated file descriptor and set it in the qemu command line parameter.
129     Always remember to set ioeventfd_on and vhost_on.
130
131     Example:
132
133     .. code-block:: console
134
135         echo 1 > /sys/class/net/vEth0/sock_en
136         fd=`cat /sys/class/net/vEth0/sock_fd`
137         exec qemu-system-x86_64 -enable-kvm -cpu host \
138         -m 2048 -smp 4 -name dpdk-test1-vm1 \
139         -drive file=/data/DPDKVMS/dpdk-vm.img \
140         -netdev tap, fd=$fd,id=mynet_kni, script=no,vhost=on \
141         -device virtio-net-pci,netdev=mynet_kni,bus=pci.0,addr=0x3,ioeventfd=on \
142         -vnc:1 -daemonize
143
144     In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns corresponds to a physical port,
145     which means received packets come from vEth0, and transmitted packets is sent to vEth0.
146
147 #.  In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding application.
148     When the virtio port in guest bursts Rx, it is getting packets from the
149     raw socket's receive queue.
150     When the virtio port bursts Tx, it is sending packet to the tx_q.
151
152     .. code-block:: console
153
154         modprobe uio
155         echo 512 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
156         modprobe uio_pci_generic
157         python usertools/dpdk-devbind.py -b uio_pci_generic 00:03.0
158
159     We use testpmd as the forwarding application in this example.
160
161     .. figure:: img/console.*
162
163        Running testpmd
164
165 #.  Use IXIA packet generator to inject a packet stream into the KNI physical port.
166
167     The packet reception and transmission flow path is:
168
169     IXIA packet generator->82599 PF->KNI Rx queue->KNI raw socket queue->Guest
170     VM virtio port 0 Rx burst->Guest VM virtio port 0 Tx burst-> KNI Tx queue
171     ->82599 PF-> IXIA packet generator
172
173 Virtio with qemu virtio Back End
174 --------------------------------
175
176 .. _figure_host_vm_comms_qemu:
177
178 .. figure:: img/host_vm_comms_qemu.*
179
180    Host2VM Communication Example Using qemu vhost Back End
181
182
183 .. code-block:: console
184
185     qemu-system-x86_64 -enable-kvm -cpu host -m 2048 -smp 2 -mem-path /dev/
186     hugepages -mem-prealloc
187     -drive file=/data/DPDKVMS/dpdk-vm1
188     -netdev tap,id=vm1_p1,ifname=tap0,script=no,vhost=on
189     -device virtio-net-pci,netdev=vm1_p1,bus=pci.0,addr=0x3,ioeventfd=on
190     -device pci-assign,host=04:10.1 \
191
192 In this example, the packet reception flow path is:
193
194     IXIA packet generator->82599 PF->Linux Bridge->TAP0's socket queue-> Guest
195     VM virtio port 0 Rx burst-> Guest VM 82599 VF port1 Tx burst-> IXIA packet
196     generator
197
198 The packet transmission flow is:
199
200     IXIA packet generator-> Guest VM 82599 VF port1 Rx burst-> Guest VM virtio
201     port 0 Tx burst-> tap -> Linux Bridge->82599 PF-> IXIA packet generator
202
203
204 Virtio PMD Rx/Tx Callbacks
205 --------------------------
206
207 Virtio driver has 6 Rx callbacks and 3 Tx callbacks.
208
209 Rx callbacks:
210
211 #. ``virtio_recv_pkts``:
212    Regular version without mergeable Rx buffer support for split virtqueue.
213
214 #. ``virtio_recv_mergeable_pkts``:
215    Regular version with mergeable Rx buffer support for split virtqueue.
216
217 #. ``virtio_recv_pkts_vec``:
218    Vector version without mergeable Rx buffer support, also fixes the available
219    ring indexes and uses vector instructions to optimize performance for split
220    virtqueue.
221
222 #. ``virtio_recv_pkts_inorder``:
223    In-order version with mergeable and non-mergeable Rx buffer support
224    for split virtqueue.
225
226 #. ``virtio_recv_pkts_packed``:
227    Regular and in-order version without mergeable Rx buffer support for
228    packed virtqueue.
229
230 #. ``virtio_recv_mergeable_pkts_packed``:
231    Regular and in-order version with mergeable Rx buffer support for packed
232    virtqueue.
233
234 Tx callbacks:
235
236 #. ``virtio_xmit_pkts``:
237    Regular version for split virtqueue.
238
239 #. ``virtio_xmit_pkts_inorder``:
240    In-order version for split virtqueue.
241
242 #. ``virtio_xmit_pkts_packed``:
243    Regular and in-order version for packed virtqueue.
244
245 By default, the non-vector callbacks are used:
246
247 *   For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts``
248     or ``virtio_recv_pkts_packed`` will be used, otherwise
249     ``virtio_recv_mergeable_pkts`` or ``virtio_recv_mergeable_pkts_packed``
250     will be used.
251
252 *   For Tx: ``virtio_xmit_pkts`` or ``virtio_xmit_pkts_packed`` will be used.
253
254
255 Vector callbacks will be used when:
256
257 *   Mergeable Rx buffers is disabled.
258
259 The corresponding callbacks are:
260
261 *   For Rx: ``virtio_recv_pkts_vec``.
262
263 There is no vector callbacks for packed virtqueue for now.
264
265
266 Example of using the vector version of the virtio poll mode driver in
267 ``testpmd``::
268
269    testpmd -l 0-2 -n 4 -- -i --rxq=1 --txq=1 --nb-cores=1
270
271 In-order callbacks only work on simulated virtio user vdev.
272
273 For split virtqueue:
274
275 *   For Rx: If in-order is enabled then ``virtio_recv_pkts_inorder`` is used.
276
277 *   For Tx: If in-order is enabled then ``virtio_xmit_pkts_inorder`` is used.
278
279 For packed virtqueue, the default callbacks already support the
280 in-order feature.
281
282 Interrupt mode
283 --------------
284
285 .. _virtio_interrupt_mode:
286
287 There are three kinds of interrupts from a virtio device over PCI bus: config
288 interrupt, Rx interrupts, and Tx interrupts. Config interrupt is used for
289 notification of device configuration changes, especially link status (lsc).
290 Interrupt mode is translated into Rx interrupts in the context of DPDK.
291
292 .. Note::
293
294    Virtio PMD already has support for receiving lsc from qemu when the link
295    status changes, especially when vhost user disconnects. However, it fails
296    to do that if the VM is created by qemu 2.6.2 or below, since the
297    capability to detect vhost user disconnection is introduced in qemu 2.7.0.
298
299 Prerequisites for Rx interrupts
300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
301
302 To support Rx interrupts,
303 #. Check if guest kernel supports VFIO-NOIOMMU:
304
305     Linux started to support VFIO-NOIOMMU since 4.8.0. Make sure the guest
306     kernel is compiled with:
307
308     .. code-block:: console
309
310         CONFIG_VFIO_NOIOMMU=y
311
312 #. Properly set msix vectors when starting VM:
313
314     Enable multi-queue when starting VM, and specify msix vectors in qemu
315     cmdline. (N+1) is the minimum, and (2N+2) is mostly recommended.
316
317     .. code-block:: console
318
319         $(QEMU) ... -device virtio-net-pci,mq=on,vectors=2N+2 ...
320
321 #. In VM, insert vfio module in NOIOMMU mode:
322
323     .. code-block:: console
324
325         modprobe vfio enable_unsafe_noiommu_mode=1
326         modprobe vfio-pci
327
328 #. In VM, bind the virtio device with vfio-pci:
329
330     .. code-block:: console
331
332         python usertools/dpdk-devbind.py -b vfio-pci 00:03.0
333
334 Example
335 ~~~~~~~
336
337 Here we use l3fwd-power as an example to show how to get started.
338
339     Example:
340
341     .. code-block:: console
342
343         $ l3fwd-power -l 0-1 -- -p 1 -P --config="(0,0,1)" \
344                                                --no-numa --parse-ptype
345
346
347 Virtio PMD arguments
348 --------------------
349
350 Below devargs are supported by the PCI virtio driver:
351
352 #.  ``vdpa``:
353
354     A virtio device could also be driven by vDPA (vhost data path acceleration)
355     driver, and works as a HW vhost backend. This argument is used to specify
356     a virtio device needs to work in vDPA mode.
357     (Default: 0 (disabled))
358
359 Below devargs are supported by the virtio-user vdev:
360
361 #.  ``path``:
362
363     It is used to specify a path to connect to vhost backend.
364
365 #.  ``mac``:
366
367     It is used to specify the MAC address.
368
369 #.  ``cq``:
370
371     It is used to enable the control queue. (Default: 0 (disabled))
372
373 #.  ``queue_size``:
374
375     It is used to specify the queue size. (Default: 256)
376
377 #.  ``queues``:
378
379     It is used to specify the queue number. (Default: 1)
380
381 #.  ``iface``:
382
383     It is used to specify the host interface name for vhost-kernel
384     backend.
385
386 #.  ``server``:
387
388     It is used to enable the server mode when using vhost-user backend.
389     (Default: 0 (disabled))
390
391 #.  ``mrg_rxbuf``:
392
393     It is used to enable virtio device mergeable Rx buffer feature.
394     (Default: 1 (enabled))
395
396 #.  ``in_order``:
397
398     It is used to enable virtio device in-order feature.
399     (Default: 1 (enabled))
400
401 #.  ``packed_vq``:
402
403     It is used to enable virtio device packed virtqueue feature.
404     (Default: 0 (disabled))
405
406 Virtio paths Selection and Usage
407 --------------------------------
408
409 Logically virtio-PMD has 9 paths based on the combination of virtio features
410 (Rx mergeable, In-order, Packed virtqueue), below is an introduction of these
411 features:
412
413 *   `Rx mergeable <https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/
414     virtio-v1.1-cs01.html#x1-2140004>`_: With this feature negotiated, device
415     can receive large packets by combining individual descriptors.
416 *   `In-order <https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/
417     virtio-v1.1-cs01.html#x1-690008>`_: Some devices always use descriptors
418     in the same order in which they have been made available, these
419     devices can offer the VIRTIO_F_IN_ORDER feature. With this feature negotiated,
420     driver will use descriptors in order.
421 *   `Packed virtqueue <https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/
422     virtio-v1.1-cs01.html#x1-610007>`_: The structure of packed virtqueue is
423     different from split virtqueue, split virtqueue is composed of available ring,
424     used ring and descriptor table, while packed virtqueue is composed of descriptor
425     ring, driver event suppression and device event suppression. The idea behind
426     this is to improve performance by avoiding cache misses and make it easier
427     for hardware to implement.
428
429 Virtio paths Selection
430 ~~~~~~~~~~~~~~~~~~~~~~
431
432 If packed virtqueue is not negotiated, below split virtqueue paths will be selected
433 according to below configuration:
434
435 #. Split virtqueue mergeable path: If Rx mergeable is negotiated, in-order feature is
436    not negotiated, this path will be selected.
437 #. Split virtqueue non-mergeable path: If Rx mergeable and in-order feature are not
438    negotiated, also Rx offload(s) are requested, this path will be selected.
439 #. Split virtqueue in-order mergeable path: If Rx mergeable and in-order feature are
440    both negotiated, this path will be selected.
441 #. Split virtqueue in-order non-mergeable path: If in-order feature is negotiated and
442    Rx mergeable is not negotiated, this path will be selected.
443 #. Split virtqueue vectorized Rx path: If Rx mergeable is disabled and no Rx offload
444    requested, this path will be selected.
445
446 If packed virtqueue is negotiated, below packed virtqueue paths will be selected
447 according to below configuration:
448
449 #. Packed virtqueue mergeable path: If Rx mergeable is negotiated, in-order feature
450    is not negotiated, this path will be selected.
451 #. Packed virtqueue non-mergeable path: If Rx mergeable and in-order feature are not
452    negotiated, this path will be selected.
453 #. Packed virtqueue in-order mergeable path: If in-order and Rx mergeable feature are
454    both negotiated, this path will be selected.
455 #. Packed virtqueue in-order non-mergeable path: If in-order feature is negotiated and
456    Rx mergeable is not negotiated, this path will be selected.
457
458 Rx/Tx callbacks of each Virtio path
459 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
460
461 Refer to above description, virtio path and corresponding Rx/Tx callbacks will
462 be selected automatically. Rx callbacks and Tx callbacks for each virtio path
463 are shown in below table:
464
465 .. table:: Virtio Paths and Callbacks
466
467    ============================================ ================================= ========================
468                  Virtio paths                            Rx callbacks                   Tx callbacks
469    ============================================ ================================= ========================
470    Split virtqueue mergeable path               virtio_recv_mergeable_pkts        virtio_xmit_pkts
471    Split virtqueue non-mergeable path           virtio_recv_pkts                  virtio_xmit_pkts
472    Split virtqueue in-order mergeable path      virtio_recv_pkts_inorder          virtio_xmit_pkts_inorder
473    Split virtqueue in-order non-mergeable path  virtio_recv_pkts_inorder          virtio_xmit_pkts_inorder
474    Split virtqueue vectorized Rx path           virtio_recv_pkts_vec              virtio_xmit_pkts
475    Packed virtqueue mergeable path              virtio_recv_mergeable_pkts_packed virtio_xmit_pkts_packed
476    Packed virtqueue non-meregable path          virtio_recv_pkts_packed           virtio_xmit_pkts_packed
477    Packed virtqueue in-order mergeable path     virtio_recv_mergeable_pkts_packed virtio_xmit_pkts_packed
478    Packed virtqueue in-order non-mergeable path virtio_recv_pkts_packed           virtio_xmit_pkts_packed
479    ============================================ ================================= ========================
480
481 Virtio paths Support Status from Release to Release
482 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
483
484 Virtio feature implementation:
485
486 *   In-order feature is supported since DPDK 18.08 by adding new Rx/Tx callbacks
487     ``virtio_recv_pkts_inorder`` and ``virtio_xmit_pkts_inorder``.
488 *   Packed virtqueue is supported since DPDK 19.02 by adding new Rx/Tx callbacks
489     ``virtio_recv_pkts_packed`` , ``virtio_recv_mergeable_pkts_packed`` and
490     ``virtio_xmit_pkts_packed``.
491
492 All virtio paths support status are shown in below table:
493
494 .. table:: Virtio Paths and Releases
495
496    ============================================ ============= ============= =============
497                   Virtio paths                  16.11 ~ 18.05 18.08 ~ 18.11 19.02 ~ 19.11
498    ============================================ ============= ============= =============
499    Split virtqueue mergeable path                     Y             Y             Y
500    Split virtqueue non-mergeable path                 Y             Y             Y
501    Split virtqueue vectorized Rx path                 Y             Y             Y
502    Split virtqueue simple Tx path                     Y             N             N
503    Split virtqueue in-order mergeable path                          Y             Y
504    Split virtqueue in-order non-mergeable path                      Y             Y
505    Packed virtqueue mergeable path                                                Y
506    Packed virtqueue non-mergeable path                                            Y
507    Packed virtqueue in-order mergeable path                                       Y
508    Packed virtqueue in-order non-mergeable path                                   Y
509    ============================================ ============= ============= =============
510
511 QEMU Support Status
512 ~~~~~~~~~~~~~~~~~~~
513
514 *   Qemu now supports three paths of split virtqueue: Split virtqueue mergeable path,
515     Split virtqueue non-mergeable path, Split virtqueue vectorized Rx path.
516 *   Since qemu 4.2.0, Packed virtqueue mergeable path and Packed virtqueue non-mergeable
517     path can be supported.
518
519 How to Debug
520 ~~~~~~~~~~~~
521
522 If you meet performance drop or some other issues after upgrading the driver
523 or configuration, below steps can help you identify which path you selected and
524 root cause faster.
525
526 #. Run vhost/virtio test case;
527 #. Run "perf top" and check virtio Rx/Tx callback names;
528 #. Identify which virtio path is selected refer to above table.