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 28Vhost PMD arguments 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 67Vhost PMD event handling 68------------------------ 69 70This section describes how to handle vhost PMD events. 71 72The user can register an event callback handler with ``rte_eth_dev_callback_register()``. 73The registered callback handler will be invoked with one of below event types. 74 75#. ``RTE_ETH_EVENT_INTR_LSC``: 76 77 It means link status of the port was changed. 78 79#. ``RTE_ETH_EVENT_QUEUE_STATE``: 80 81 It means some of queue statuses were changed. Call ``rte_eth_vhost_get_queue_event()`` in the callback handler. 82 Because changing multiple statuses may occur only one event, call the function repeatedly as long as it doesn't return negative value. 83 84Vhost PMD with testpmd application 85---------------------------------- 86 87This section demonstrates vhost PMD with testpmd DPDK sample application. 88 89#. Launch the testpmd with vhost PMD: 90 91 .. code-block:: console 92 93 ./dpdk-testpmd -l 0-3 -n 4 --vdev 'net_vhost0,iface=/tmp/sock0,queues=1' -- -i 94 95 Other basic DPDK preparations like hugepage enabling here. 96 Please refer to the *DPDK Getting Started Guide* for detailed instructions. 97 98#. Launch the QEMU: 99 100 .. code-block:: console 101 102 qemu-system-x86_64 <snip> 103 -chardev socket,id=chr0,path=/tmp/sock0 \ 104 -netdev vhost-user,id=net0,chardev=chr0,vhostforce,queues=1 \ 105 -device virtio-net-pci,netdev=net0 106 107 This command attaches one virtio-net device to QEMU guest. 108 After initialization processes between QEMU and DPDK vhost library are done, status of the port will be linked up. 109