doc/guides/nics/vhost.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2016 IGEL Co., Ltd.
   3
   4 Poll Mode Driver that wraps vhost library
   5 =========================================
   6
   7 This PMD is a thin wrapper of the DPDK vhost library.
   8 The user can handle virtqueues as one of normal DPDK port.
   9
  10 Vhost Implementation in DPDK
  11 ----------------------------
  12
  13 Please refer to Chapter "Vhost Library" of *DPDK Programmer's Guide* to know detail of vhost.
  14
  15 Features and Limitations of vhost PMD
  16 -------------------------------------
  17
  18 Currently, 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
  28 Vhost PMD arguments
  29 -------------------
  30
  31 The 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 Vhost PMD event handling
  68 ------------------------
  69
  70 This section describes how to handle vhost PMD events.
  71
  72 The user can register an event callback handler with ``rte_eth_dev_callback_register()``.
  73 The 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
  84 Vhost PMD with testpmd application
  85 ----------------------------------
  86
  87 This 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.