1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2010-2015 Intel Corporation.
4 Poll Mode Driver for Emulated Virtio NIC
5 ========================================
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.
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.
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".
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.
23 Virtio Implementation in DPDK
24 -----------------------------
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>`_.
30 As a PMD, virtio provides packet reception and transmission callbacks.
32 In Rx, packets described by the used descriptors in vring are available
33 for virtio to burst out.
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
40 Features and Limitations of virtio PMD
41 --------------------------------------
43 In this release, the virtio PMD driver provides the basic functionality of packet reception and transmission.
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.
48 * It supports multicast packets and promiscuous mode.
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.
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.
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.
66 * Virtio does not support runtime configuration.
68 * Virtio supports Link State interrupt.
70 * Virtio supports Rx interrupt (so far, only support 1:1 mapping for queue/interrupt).
72 * Virtio supports software vlan stripping and inserting.
74 * Virtio supports using port IO to get PCI resource when UIO module is not available.
76 * Virtio supports RSS Rx mode with 40B configurable hash key length, 128
77 configurable RETA entries and configurable hash types.
82 The following prerequisites apply:
84 * In the BIOS, turn VT-x and VT-d on
86 * Linux kernel with KVM module; vhost module loaded and ioeventfd supported.
87 Qemu standard backend without vhost support isn't tested, and probably isn't supported.
89 Virtio with kni vhost Back End
90 ------------------------------
92 This section demonstrates kni vhost back end example setup for Phy-VM Communication.
94 .. _figure_host_vm_comms:
96 .. figure:: img/host_vm_comms.*
98 Host2VM Communication Example Using kni vhost Back End
101 Host2VM communication example
103 #. Load the kni kernel module:
105 .. code-block:: console
109 Other basic DPDK preparations like hugepage enabling,
110 UIO port binding are not listed here.
111 Please refer to the *DPDK Getting Started Guide* for detailed instructions.
113 #. Launch the kni user application:
115 .. code-block:: console
117 <build_dir>/examples/dpdk-kni -l 0-3 -n 4 -- -p 0x1 -P --config="(0,1,3)"
119 This command generates one network device vEth0 for physical port.
120 If specify more physical ports, the generated network device will be vEth1, vEth2, and so on.
122 For each physical port, kni creates two user threads.
123 One thread loops to fetch packets from the physical NIC port into the kni receive queue.
124 The other user thread loops to send packets in the kni transmit queue.
126 For each physical port, kni also creates a kernel thread that retrieves packets from the kni receive queue,
127 place them onto kni's raw socket's queue and wake up the vhost kernel thread to exchange packets with the virtio virt queue.
129 For more details about kni, please refer to :ref:`kni`.
131 #. Enable the kni raw socket functionality for the specified physical NIC port,
132 get the generated file descriptor and set it in the qemu command line parameter.
133 Always remember to set ioeventfd_on and vhost_on.
137 .. code-block:: console
139 echo 1 > /sys/class/net/vEth0/sock_en
140 fd=`cat /sys/class/net/vEth0/sock_fd`
141 exec qemu-system-x86_64 -enable-kvm -cpu host \
142 -m 2048 -smp 4 -name dpdk-test1-vm1 \
143 -drive file=/data/DPDKVMS/dpdk-vm.img \
144 -netdev tap, fd=$fd,id=mynet_kni, script=no,vhost=on \
145 -device virtio-net-pci,netdev=mynet_kni,bus=pci.0,addr=0x3,ioeventfd=on \
148 In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns corresponds to a physical port,
149 which means received packets come from vEth0, and transmitted packets is sent to vEth0.
151 #. In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding application.
152 When the virtio port in guest bursts Rx, it is getting packets from the
153 raw socket's receive queue.
154 When the virtio port bursts Tx, it is sending packet to the tx_q.
156 .. code-block:: console
159 dpdk-hugepages.py --setup 1G
160 modprobe uio_pci_generic
161 ./usertools/dpdk-devbind.py -b uio_pci_generic 00:03.0
163 We use testpmd as the forwarding application in this example.
165 .. figure:: img/console.*
169 #. Use IXIA packet generator to inject a packet stream into the KNI physical port.
171 The packet reception and transmission flow path is:
173 IXIA packet generator->82599 PF->KNI Rx queue->KNI raw socket queue->Guest
174 VM virtio port 0 Rx burst->Guest VM virtio port 0 Tx burst-> KNI Tx queue
175 ->82599 PF-> IXIA packet generator
177 Virtio with qemu virtio Back End
178 --------------------------------
180 .. _figure_host_vm_comms_qemu:
182 .. figure:: img/host_vm_comms_qemu.*
184 Host2VM Communication Example Using qemu vhost Back End
187 .. code-block:: console
189 qemu-system-x86_64 -enable-kvm -cpu host -m 2048 -smp 2 -mem-path /dev/
190 hugepages -mem-prealloc
191 -drive file=/data/DPDKVMS/dpdk-vm1
192 -netdev tap,id=vm1_p1,ifname=tap0,script=no,vhost=on
193 -device virtio-net-pci,netdev=vm1_p1,bus=pci.0,addr=0x3,ioeventfd=on
194 -device pci-assign,host=04:10.1 \
196 In this example, the packet reception flow path is:
198 IXIA packet generator->82599 PF->Linux Bridge->TAP0's socket queue-> Guest
199 VM virtio port 0 Rx burst-> Guest VM 82599 VF port1 Tx burst-> IXIA packet
202 The packet transmission flow is:
204 IXIA packet generator-> Guest VM 82599 VF port1 Rx burst-> Guest VM virtio
205 port 0 Tx burst-> tap -> Linux Bridge->82599 PF-> IXIA packet generator
208 Virtio PMD Rx/Tx Callbacks
209 --------------------------
211 Virtio driver has 6 Rx callbacks and 3 Tx callbacks.
215 #. ``virtio_recv_pkts``:
216 Regular version without mergeable Rx buffer support for split virtqueue.
218 #. ``virtio_recv_mergeable_pkts``:
219 Regular version with mergeable Rx buffer support for split virtqueue.
221 #. ``virtio_recv_pkts_vec``:
222 Vector version without mergeable Rx buffer support, also fixes the available
223 ring indexes and uses vector instructions to optimize performance for split
226 #. ``virtio_recv_pkts_inorder``:
227 In-order version with mergeable and non-mergeable Rx buffer support
230 #. ``virtio_recv_pkts_packed``:
231 Regular and in-order version without mergeable Rx buffer support for
234 #. ``virtio_recv_mergeable_pkts_packed``:
235 Regular and in-order version with mergeable Rx buffer support for packed
240 #. ``virtio_xmit_pkts``:
241 Regular version for split virtqueue.
243 #. ``virtio_xmit_pkts_inorder``:
244 In-order version for split virtqueue.
246 #. ``virtio_xmit_pkts_packed``:
247 Regular and in-order version for packed virtqueue.
249 By default, the non-vector callbacks are used:
251 * For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts``
252 or ``virtio_recv_pkts_packed`` will be used, otherwise
253 ``virtio_recv_mergeable_pkts`` or ``virtio_recv_mergeable_pkts_packed``
256 * For Tx: ``virtio_xmit_pkts`` or ``virtio_xmit_pkts_packed`` will be used.
259 Vector callbacks will be used when:
261 * Mergeable Rx buffers is disabled.
263 The corresponding callbacks are:
265 * For Rx: ``virtio_recv_pkts_vec``.
267 There is no vector callbacks for packed virtqueue for now.
270 Example of using the vector version of the virtio poll mode driver in
273 dpdk-testpmd -l 0-2 -n 4 -- -i --rxq=1 --txq=1 --nb-cores=1
275 In-order callbacks only work on simulated virtio user vdev.
279 * For Rx: If in-order is enabled then ``virtio_recv_pkts_inorder`` is used.
281 * For Tx: If in-order is enabled then ``virtio_xmit_pkts_inorder`` is used.
283 For packed virtqueue, the default callbacks already support the
289 .. _virtio_interrupt_mode:
291 There are three kinds of interrupts from a virtio device over PCI bus: config
292 interrupt, Rx interrupts, and Tx interrupts. Config interrupt is used for
293 notification of device configuration changes, especially link status (lsc).
294 Interrupt mode is translated into Rx interrupts in the context of DPDK.
298 Virtio PMD already has support for receiving lsc from qemu when the link
299 status changes, especially when vhost user disconnects. However, it fails
300 to do that if the VM is created by qemu 2.6.2 or below, since the
301 capability to detect vhost user disconnection is introduced in qemu 2.7.0.
303 Prerequisites for Rx interrupts
304 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
306 To support Rx interrupts,
307 #. Check if guest kernel supports VFIO-NOIOMMU:
309 Linux started to support VFIO-NOIOMMU since 4.8.0. Make sure the guest
310 kernel is compiled with:
312 .. code-block:: console
314 CONFIG_VFIO_NOIOMMU=y
316 #. Properly set msix vectors when starting VM:
318 Enable multi-queue when starting VM, and specify msix vectors in qemu
319 cmdline. (N+1) is the minimum, and (2N+2) is mostly recommended.
321 .. code-block:: console
323 $(QEMU) ... -device virtio-net-pci,mq=on,vectors=2N+2 ...
325 #. In VM, insert vfio module in NOIOMMU mode:
327 .. code-block:: console
329 modprobe vfio enable_unsafe_noiommu_mode=1
332 #. In VM, bind the virtio device with vfio-pci:
334 .. code-block:: console
336 ./usertools/dpdk-devbind.py -b vfio-pci 00:03.0
341 Here we use l3fwd-power as an example to show how to get started.
345 .. code-block:: console
347 $ dpdk-l3fwd-power -l 0-1 -- -p 1 -P --config="(0,0,1)" \
348 --no-numa --parse-ptype
354 Below devargs are supported by the PCI virtio driver:
358 A virtio device could also be driven by vDPA (vhost data path acceleration)
359 driver, and works as a HW vhost backend. This argument is used to specify
360 a virtio device needs to work in vDPA mode.
361 (Default: 0 (disabled))
365 It is used to specify link speed of virtio device. Link speed is a part of
366 link status structure. It could be requested by application using
367 rte_eth_link_get_nowait function.
368 (Default: 0xffffffff (Unknown))
372 It is used to specify whether virtio device prefers to use vectorized path.
373 Afterwards, dependencies of vectorized path will be checked in path
375 (Default: 0 (disabled))
377 Below devargs are supported by the virtio-user vdev:
381 It is used to specify a path to connect to vhost backend.
385 It is used to specify the MAC address.
389 It is used to enable the control queue. (Default: 0 (disabled))
393 It is used to specify the queue size. (Default: 256)
397 It is used to specify the queue number. (Default: 1)
401 It is used to specify the host interface name for vhost-kernel
406 It is used to enable the server mode when using vhost-user backend.
407 (Default: 0 (disabled))
411 It is used to enable virtio device mergeable Rx buffer feature.
412 (Default: 1 (enabled))
416 It is used to enable virtio device in-order feature.
417 (Default: 1 (enabled))
421 It is used to enable virtio device packed virtqueue feature.
422 (Default: 0 (disabled))
426 It is used to specify link speed of virtio device. Link speed is a part of
427 link status structure. It could be requested by application using
428 rte_eth_link_get_nowait function.
429 (Default: 0xffffffff (Unknown))
433 It is used to specify whether virtio device prefers to use vectorized path.
434 Afterwards, dependencies of vectorized path will be checked in path
436 (Default: 0 (disabled))
438 Virtio paths Selection and Usage
439 --------------------------------
441 Logically virtio-PMD has 9 paths based on the combination of virtio features
442 (Rx mergeable, In-order, Packed virtqueue), below is an introduction of these
445 * `Rx mergeable <https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/
446 virtio-v1.1-cs01.html#x1-2140004>`_: With this feature negotiated, device
447 can receive large packets by combining individual descriptors.
448 * `In-order <https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/
449 virtio-v1.1-cs01.html#x1-690008>`_: Some devices always use descriptors
450 in the same order in which they have been made available, these
451 devices can offer the VIRTIO_F_IN_ORDER feature. With this feature negotiated,
452 driver will use descriptors in order.
453 * `Packed virtqueue <https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/
454 virtio-v1.1-cs01.html#x1-610007>`_: The structure of packed virtqueue is
455 different from split virtqueue, split virtqueue is composed of available ring,
456 used ring and descriptor table, while packed virtqueue is composed of descriptor
457 ring, driver event suppression and device event suppression. The idea behind
458 this is to improve performance by avoiding cache misses and make it easier
459 for hardware to implement.
461 Virtio paths Selection
462 ~~~~~~~~~~~~~~~~~~~~~~
464 If packed virtqueue is not negotiated, below split virtqueue paths will be selected
465 according to below configuration:
467 #. Split virtqueue mergeable path: If Rx mergeable is negotiated, in-order feature is
468 not negotiated, this path will be selected.
469 #. Split virtqueue non-mergeable path: If Rx mergeable and in-order feature are not
470 negotiated, also Rx offload(s) are requested, this path will be selected.
471 #. Split virtqueue in-order mergeable path: If Rx mergeable and in-order feature are
472 both negotiated, this path will be selected.
473 #. Split virtqueue in-order non-mergeable path: If in-order feature is negotiated and
474 Rx mergeable is not negotiated, this path will be selected.
475 #. Split virtqueue vectorized Rx path: If Rx mergeable is disabled and no Rx offload
476 requested, this path will be selected.
478 If packed virtqueue is negotiated, below packed virtqueue paths will be selected
479 according to below configuration:
481 #. Packed virtqueue mergeable path: If Rx mergeable is negotiated, in-order feature
482 is not negotiated, this path will be selected.
483 #. Packed virtqueue non-mergeable path: If Rx mergeable and in-order feature are not
484 negotiated, this path will be selected.
485 #. Packed virtqueue in-order mergeable path: If in-order and Rx mergeable feature are
486 both negotiated, this path will be selected.
487 #. Packed virtqueue in-order non-mergeable path: If in-order feature is negotiated and
488 Rx mergeable is not negotiated, this path will be selected.
489 #. Packed virtqueue vectorized Rx path: If building and running environment support
490 (AVX512 || NEON) && in-order feature is negotiated && Rx mergeable
491 is not negotiated && TCP_LRO Rx offloading is disabled && vectorized option enabled,
492 this path will be selected.
493 #. Packed virtqueue vectorized Tx path: If building and running environment support
494 (AVX512 || NEON) && in-order feature is negotiated && vectorized option enabled,
495 this path will be selected.
497 Rx/Tx callbacks of each Virtio path
498 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
500 Refer to above description, virtio path and corresponding Rx/Tx callbacks will
501 be selected automatically. Rx callbacks and Tx callbacks for each virtio path
502 are shown in below table:
504 .. table:: Virtio Paths and Callbacks
506 ============================================ ================================= ========================
507 Virtio paths Rx callbacks Tx callbacks
508 ============================================ ================================= ========================
509 Split virtqueue mergeable path virtio_recv_mergeable_pkts virtio_xmit_pkts
510 Split virtqueue non-mergeable path virtio_recv_pkts virtio_xmit_pkts
511 Split virtqueue in-order mergeable path virtio_recv_pkts_inorder virtio_xmit_pkts_inorder
512 Split virtqueue in-order non-mergeable path virtio_recv_pkts_inorder virtio_xmit_pkts_inorder
513 Split virtqueue vectorized Rx path virtio_recv_pkts_vec virtio_xmit_pkts
514 Packed virtqueue mergeable path virtio_recv_mergeable_pkts_packed virtio_xmit_pkts_packed
515 Packed virtqueue non-mergeable path virtio_recv_pkts_packed virtio_xmit_pkts_packed
516 Packed virtqueue in-order mergeable path virtio_recv_mergeable_pkts_packed virtio_xmit_pkts_packed
517 Packed virtqueue in-order non-mergeable path virtio_recv_pkts_packed virtio_xmit_pkts_packed
518 Packed virtqueue vectorized Rx path virtio_recv_pkts_packed_vec virtio_xmit_pkts_packed
519 Packed virtqueue vectorized Tx path virtio_recv_pkts_packed virtio_xmit_pkts_packed_vec
520 ============================================ ================================= ========================
522 Virtio paths Support Status from Release to Release
523 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
525 Virtio feature implementation:
527 * In-order feature is supported since DPDK 18.08 by adding new Rx/Tx callbacks
528 ``virtio_recv_pkts_inorder`` and ``virtio_xmit_pkts_inorder``.
529 * Packed virtqueue is supported since DPDK 19.02 by adding new Rx/Tx callbacks
530 ``virtio_recv_pkts_packed`` , ``virtio_recv_mergeable_pkts_packed`` and
531 ``virtio_xmit_pkts_packed``.
533 All virtio paths support status are shown in below table:
535 .. table:: Virtio Paths and Releases
537 ============================================ ============= ============= ============= =======
538 Virtio paths 16.11 ~ 18.05 18.08 ~ 18.11 19.02 ~ 19.11 20.05 ~
539 ============================================ ============= ============= ============= =======
540 Split virtqueue mergeable path Y Y Y Y
541 Split virtqueue non-mergeable path Y Y Y Y
542 Split virtqueue vectorized Rx path Y Y Y Y
543 Split virtqueue simple Tx path Y N N N
544 Split virtqueue in-order mergeable path Y Y Y
545 Split virtqueue in-order non-mergeable path Y Y Y
546 Packed virtqueue mergeable path Y Y
547 Packed virtqueue non-mergeable path Y Y
548 Packed virtqueue in-order mergeable path Y Y
549 Packed virtqueue in-order non-mergeable path Y Y
550 Packed virtqueue vectorized Rx path Y
551 Packed virtqueue vectorized Tx path Y
552 ============================================ ============= ============= ============= =======
557 * Qemu now supports three paths of split virtqueue: Split virtqueue mergeable path,
558 Split virtqueue non-mergeable path, Split virtqueue vectorized Rx path.
559 * Since qemu 4.2.0, Packed virtqueue mergeable path and Packed virtqueue non-mergeable
560 path can be supported.
565 If you meet performance drop or some other issues after upgrading the driver
566 or configuration, below steps can help you identify which path you selected and
569 #. Run vhost/virtio test case;
570 #. Run "perf top" and check virtio Rx/Tx callback names;
571 #. Identify which virtio path is selected refer to above table.