1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2015 Intel Corporation. 3 4Poll Mode Driver for Emulated Virtio NIC 5======================================== 6 7Virtio is a para-virtualization framework initiated by IBM, and supported by KVM hypervisor. 8In the Data Plane Development Kit (DPDK), 9we provide a virtio Poll Mode Driver (PMD) as a software solution, comparing to SRIOV hardware solution, 10for fast guest VM to guest VM communication and guest VM to host communication. 11 12Vhost is a kernel acceleration module for virtio qemu backend. 13The DPDK extends kni to support vhost raw socket interface, 14which enables vhost to directly read/ write packets from/to a physical port. 15With this enhancement, virtio could achieve quite promising performance. 16 17For basic qemu-KVM installation and other Intel EM poll mode driver in guest VM, 18please refer to Chapter "Driver for VM Emulated Devices". 19 20In this chapter, we will demonstrate usage of virtio PMD driver with two backends, 21standard qemu vhost back end and vhost kni back end. 22 23Virtio Implementation in DPDK 24----------------------------- 25 26For 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 30As a PMD, virtio provides packet reception and transmission callbacks. 31 32In Rx, packets described by the used descriptors in vring are available 33for virtio to burst out. 34 35In Tx, packets described by the used descriptors in vring are available 36for virtio to clean. Virtio will enqueue to be transmitted packets into 37vring, make them available to the device, and then notify the host back 38end if necessary. 39 40Features and Limitations of virtio PMD 41-------------------------------------- 42 43In 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 76Prerequisites 77------------- 78 79The 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 86Virtio with kni vhost Back End 87------------------------------ 88 89This 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 98Host2VM 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 <build_dir>/examples/dpdk-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 dpdk-hugepages.py --setup 1G 156 modprobe uio_pci_generic 157 ./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 173Virtio 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 192In 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 198The 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 204Virtio PMD Rx/Tx Callbacks 205-------------------------- 206 207Virtio driver has 6 Rx callbacks and 3 Tx callbacks. 208 209Rx 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 234Tx 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 245By 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 255Vector callbacks will be used when: 256 257* Mergeable Rx buffers is disabled. 258 259The corresponding callbacks are: 260 261* For Rx: ``virtio_recv_pkts_vec``. 262 263There is no vector callbacks for packed virtqueue for now. 264 265 266Example of using the vector version of the virtio poll mode driver in 267``testpmd``:: 268 269 dpdk-testpmd -l 0-2 -n 4 -- -i --rxq=1 --txq=1 --nb-cores=1 270 271In-order callbacks only work on simulated virtio user vdev. 272 273For 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 279For packed virtqueue, the default callbacks already support the 280in-order feature. 281 282Interrupt mode 283-------------- 284 285.. _virtio_interrupt_mode: 286 287There are three kinds of interrupts from a virtio device over PCI bus: config 288interrupt, Rx interrupts, and Tx interrupts. Config interrupt is used for 289notification of device configuration changes, especially link status (lsc). 290Interrupt 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 299Prerequisites for Rx interrupts 300~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 301 302To 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 ./usertools/dpdk-devbind.py -b vfio-pci 00:03.0 333 334Example 335~~~~~~~ 336 337Here we use l3fwd-power as an example to show how to get started. 338 339 Example: 340 341 .. code-block:: console 342 343 $ dpdk-l3fwd-power -l 0-1 -- -p 1 -P --config="(0,0,1)" \ 344 --no-numa --parse-ptype 345 346 347Virtio PMD arguments 348-------------------- 349 350Below 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#. ``speed``: 360 361 It is used to specify link speed of virtio device. Link speed is a part of 362 link status structure. It could be requested by application using 363 rte_eth_link_get_nowait function. 364 (Default: 0xffffffff (Unknown)) 365 366#. ``vectorized``: 367 368 It is used to specify whether virtio device prefers to use vectorized path. 369 Afterwards, dependencies of vectorized path will be checked in path 370 election. 371 (Default: 0 (disabled)) 372 373Below devargs are supported by the virtio-user vdev: 374 375#. ``path``: 376 377 It is used to specify a path to connect to vhost backend. 378 379#. ``mac``: 380 381 It is used to specify the MAC address. 382 383#. ``cq``: 384 385 It is used to enable the control queue. (Default: 0 (disabled)) 386 387#. ``queue_size``: 388 389 It is used to specify the queue size. (Default: 256) 390 391#. ``queues``: 392 393 It is used to specify the queue number. (Default: 1) 394 395#. ``iface``: 396 397 It is used to specify the host interface name for vhost-kernel 398 backend. 399 400#. ``server``: 401 402 It is used to enable the server mode when using vhost-user backend. 403 (Default: 0 (disabled)) 404 405#. ``mrg_rxbuf``: 406 407 It is used to enable virtio device mergeable Rx buffer feature. 408 (Default: 1 (enabled)) 409 410#. ``in_order``: 411 412 It is used to enable virtio device in-order feature. 413 (Default: 1 (enabled)) 414 415#. ``packed_vq``: 416 417 It is used to enable virtio device packed virtqueue feature. 418 (Default: 0 (disabled)) 419 420#. ``speed``: 421 422 It is used to specify link speed of virtio device. Link speed is a part of 423 link status structure. It could be requested by application using 424 rte_eth_link_get_nowait function. 425 (Default: 0xffffffff (Unknown)) 426 427#. ``vectorized``: 428 429 It is used to specify whether virtio device prefers to use vectorized path. 430 Afterwards, dependencies of vectorized path will be checked in path 431 election. 432 (Default: 0 (disabled)) 433 434Virtio paths Selection and Usage 435-------------------------------- 436 437Logically virtio-PMD has 9 paths based on the combination of virtio features 438(Rx mergeable, In-order, Packed virtqueue), below is an introduction of these 439features: 440 441* `Rx mergeable <https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/ 442 virtio-v1.1-cs01.html#x1-2140004>`_: With this feature negotiated, device 443 can receive large packets by combining individual descriptors. 444* `In-order <https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/ 445 virtio-v1.1-cs01.html#x1-690008>`_: Some devices always use descriptors 446 in the same order in which they have been made available, these 447 devices can offer the VIRTIO_F_IN_ORDER feature. With this feature negotiated, 448 driver will use descriptors in order. 449* `Packed virtqueue <https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/ 450 virtio-v1.1-cs01.html#x1-610007>`_: The structure of packed virtqueue is 451 different from split virtqueue, split virtqueue is composed of available ring, 452 used ring and descriptor table, while packed virtqueue is composed of descriptor 453 ring, driver event suppression and device event suppression. The idea behind 454 this is to improve performance by avoiding cache misses and make it easier 455 for hardware to implement. 456 457Virtio paths Selection 458~~~~~~~~~~~~~~~~~~~~~~ 459 460If packed virtqueue is not negotiated, below split virtqueue paths will be selected 461according to below configuration: 462 463#. Split virtqueue mergeable path: If Rx mergeable is negotiated, in-order feature is 464 not negotiated, this path will be selected. 465#. Split virtqueue non-mergeable path: If Rx mergeable and in-order feature are not 466 negotiated, also Rx offload(s) are requested, this path will be selected. 467#. Split virtqueue in-order mergeable path: If Rx mergeable and in-order feature are 468 both negotiated, this path will be selected. 469#. Split virtqueue in-order non-mergeable path: If in-order feature is negotiated and 470 Rx mergeable is not negotiated, this path will be selected. 471#. Split virtqueue vectorized Rx path: If Rx mergeable is disabled and no Rx offload 472 requested, this path will be selected. 473 474If packed virtqueue is negotiated, below packed virtqueue paths will be selected 475according to below configuration: 476 477#. Packed virtqueue mergeable path: If Rx mergeable is negotiated, in-order feature 478 is not negotiated, this path will be selected. 479#. Packed virtqueue non-mergeable path: If Rx mergeable and in-order feature are not 480 negotiated, this path will be selected. 481#. Packed virtqueue in-order mergeable path: If in-order and Rx mergeable feature are 482 both negotiated, this path will be selected. 483#. Packed virtqueue in-order non-mergeable path: If in-order feature is negotiated and 484 Rx mergeable is not negotiated, this path will be selected. 485#. Packed virtqueue vectorized Rx path: If building and running environment support 486 (AVX512 || NEON) && in-order feature is negotiated && Rx mergeable 487 is not negotiated && TCP_LRO Rx offloading is disabled && vectorized option enabled, 488 this path will be selected. 489#. Packed virtqueue vectorized Tx path: If building and running environment support 490 (AVX512 || NEON) && in-order feature is negotiated && vectorized option enabled, 491 this path will be selected. 492 493Rx/Tx callbacks of each Virtio path 494~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 495 496Refer to above description, virtio path and corresponding Rx/Tx callbacks will 497be selected automatically. Rx callbacks and Tx callbacks for each virtio path 498are shown in below table: 499 500.. table:: Virtio Paths and Callbacks 501 502 ============================================ ================================= ======================== 503 Virtio paths Rx callbacks Tx callbacks 504 ============================================ ================================= ======================== 505 Split virtqueue mergeable path virtio_recv_mergeable_pkts virtio_xmit_pkts 506 Split virtqueue non-mergeable path virtio_recv_pkts virtio_xmit_pkts 507 Split virtqueue in-order mergeable path virtio_recv_pkts_inorder virtio_xmit_pkts_inorder 508 Split virtqueue in-order non-mergeable path virtio_recv_pkts_inorder virtio_xmit_pkts_inorder 509 Split virtqueue vectorized Rx path virtio_recv_pkts_vec virtio_xmit_pkts 510 Packed virtqueue mergeable path virtio_recv_mergeable_pkts_packed virtio_xmit_pkts_packed 511 Packed virtqueue non-meregable path virtio_recv_pkts_packed virtio_xmit_pkts_packed 512 Packed virtqueue in-order mergeable path virtio_recv_mergeable_pkts_packed virtio_xmit_pkts_packed 513 Packed virtqueue in-order non-mergeable path virtio_recv_pkts_packed virtio_xmit_pkts_packed 514 Packed virtqueue vectorized Rx path virtio_recv_pkts_packed_vec virtio_xmit_pkts_packed 515 Packed virtqueue vectorized Tx path virtio_recv_pkts_packed virtio_xmit_pkts_packed_vec 516 ============================================ ================================= ======================== 517 518Virtio paths Support Status from Release to Release 519~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 520 521Virtio feature implementation: 522 523* In-order feature is supported since DPDK 18.08 by adding new Rx/Tx callbacks 524 ``virtio_recv_pkts_inorder`` and ``virtio_xmit_pkts_inorder``. 525* Packed virtqueue is supported since DPDK 19.02 by adding new Rx/Tx callbacks 526 ``virtio_recv_pkts_packed`` , ``virtio_recv_mergeable_pkts_packed`` and 527 ``virtio_xmit_pkts_packed``. 528 529All virtio paths support status are shown in below table: 530 531.. table:: Virtio Paths and Releases 532 533 ============================================ ============= ============= ============= ======= 534 Virtio paths 16.11 ~ 18.05 18.08 ~ 18.11 19.02 ~ 19.11 20.05 ~ 535 ============================================ ============= ============= ============= ======= 536 Split virtqueue mergeable path Y Y Y Y 537 Split virtqueue non-mergeable path Y Y Y Y 538 Split virtqueue vectorized Rx path Y Y Y Y 539 Split virtqueue simple Tx path Y N N N 540 Split virtqueue in-order mergeable path Y Y Y 541 Split virtqueue in-order non-mergeable path Y Y Y 542 Packed virtqueue mergeable path Y Y 543 Packed virtqueue non-mergeable path Y Y 544 Packed virtqueue in-order mergeable path Y Y 545 Packed virtqueue in-order non-mergeable path Y Y 546 Packed virtqueue vectorized Rx path Y 547 Packed virtqueue vectorized Tx path Y 548 ============================================ ============= ============= ============= ======= 549 550QEMU Support Status 551~~~~~~~~~~~~~~~~~~~ 552 553* Qemu now supports three paths of split virtqueue: Split virtqueue mergeable path, 554 Split virtqueue non-mergeable path, Split virtqueue vectorized Rx path. 555* Since qemu 4.2.0, Packed virtqueue mergeable path and Packed virtqueue non-mergeable 556 path can be supported. 557 558How to Debug 559~~~~~~~~~~~~ 560 561If you meet performance drop or some other issues after upgrading the driver 562or configuration, below steps can help you identify which path you selected and 563root cause faster. 564 565#. Run vhost/virtio test case; 566#. Run "perf top" and check virtio Rx/Tx callback names; 567#. Identify which virtio path is selected refer to above table. 568