1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2016 IGEL Co., Ltd. 3 4Poll Mode Driver that wraps vhost library 5========================================= 6 7This PMD is a thin wrapper of the DPDK vhost library. 8The user can handle virtqueues as one of normal DPDK port. 9 10Vhost Implementation in DPDK 11---------------------------- 12 13Please refer to Chapter "Vhost Library" of *DPDK Programmer's Guide* to know detail of vhost. 14 15Features and Limitations of vhost PMD 16------------------------------------- 17 18Currently, the vhost PMD provides the basic functionality of packet reception, transmission and event handling. 19 20* It has multiple queues support. 21 22* It supports ``RTE_ETH_EVENT_INTR_LSC`` and ``RTE_ETH_EVENT_QUEUE_STATE`` events. 23 24* It supports Port Hotplug functionality. 25 26* Don't need to stop RX/TX, when the user wants to stop a guest or a virtio-net driver on guest. 27 28Runtime Configuration 29--------------------- 30 31The user can specify below arguments in `--vdev` option. 32 33#. ``iface``: 34 35 It is used to specify a path to connect to a QEMU virtio-net device. 36 37#. ``queues``: 38 39 It is used to specify the number of queues virtio-net device has. 40 (Default: 1) 41 42#. ``iommu-support``: 43 44 It is used to enable iommu support in vhost library. 45 (Default: 0 (disabled)) 46 47#. ``postcopy-support``: 48 49 It is used to enable postcopy live-migration support in vhost library. 50 (Default: 0 (disabled)) 51 52#. ``tso``: 53 54 It is used to enable tso support in vhost library. 55 (Default: 0 (disabled)) 56 57#. ``linear-buffer``: 58 59 It is used to enable linear buffer support in vhost library. 60 (Default: 0 (disabled)) 61 62#. ``ext-buffer``: 63 64 It is used to enable external buffer support in vhost library. 65 (Default: 0 (disabled)) 66 67#. ``legacy-ol-flags``: 68 69 It is used to restore legacy behavior for offloading that was not 70 compliant with offloading API. 71 (Default: 0 (disabled)) 72 73Vhost PMD event handling 74------------------------ 75 76This section describes how to handle vhost PMD events. 77 78The user can register an event callback handler with ``rte_eth_dev_callback_register()``. 79The registered callback handler will be invoked with one of below event types. 80 81#. ``RTE_ETH_EVENT_INTR_LSC``: 82 83 It means link status of the port was changed. 84 85#. ``RTE_ETH_EVENT_QUEUE_STATE``: 86 87 It means some of queue statuses were changed. Call ``rte_eth_vhost_get_queue_event()`` in the callback handler. 88 Because changing multiple statuses may occur only one event, call the function repeatedly as long as it doesn't return negative value. 89 90Vhost PMD with testpmd application 91---------------------------------- 92 93This section demonstrates vhost PMD with testpmd DPDK sample application. 94 95#. Launch the testpmd with vhost PMD: 96 97 .. code-block:: console 98 99 ./dpdk-testpmd -l 0-3 -n 4 --vdev 'net_vhost0,iface=/tmp/sock0,queues=1' -- -i 100 101 Other basic DPDK preparations like hugepage enabling here. 102 Please refer to the *DPDK Getting Started Guide* for detailed instructions. 103 104#. Launch the QEMU: 105 106 .. code-block:: console 107 108 qemu-system-x86_64 <snip> 109 -chardev socket,id=chr0,path=/tmp/sock0 \ 110 -netdev vhost-user,id=net0,chardev=chr0,vhostforce,queues=1 \ 111 -device virtio-net-pci,netdev=net0 112 113 This command attaches one virtio-net device to QEMU guest. 114 After initialization processes between QEMU and DPDK vhost library are done, status of the port will be linked up. 115