1.. BSD LICENSE 2 Copyright(c) 2010-2016 Intel Corporation. All rights reserved. 3 All rights reserved. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions 7 are met: 8 9 * Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 * Redistributions in binary form must reproduce the above copyright 12 notice, this list of conditions and the following disclaimer in 13 the documentation and/or other materials provided with the 14 distribution. 15 * Neither the name of Intel Corporation nor the names of its 16 contributors may be used to endorse or promote products derived 17 from this software without specific prior written permission. 18 19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31Vhost Library 32============= 33 34The vhost library implements a user space virtio net server allowing the user 35to manipulate the virtio ring directly. In another words, it allows the user 36to fetch/put packets from/to the VM virtio net device. To achieve this, a 37vhost library should be able to: 38 39* Access the guest memory: 40 41 For QEMU, this is done by using the ``-object memory-backend-file,share=on,...`` 42 option. Which means QEMU will create a file to serve as the guest RAM. 43 The ``share=on`` option allows another process to map that file, which 44 means it can access the guest RAM. 45 46* Know all the necessary information about the vring: 47 48 Information such as where the available ring is stored. Vhost defines some 49 messages to tell the backend all the information it needs to know how to 50 manipulate the vring. 51 52Currently, there are two ways to pass these messages and as a result there are 53two Vhost implementations in DPDK: *vhost-cuse* (where the character devices 54are in user space) and *vhost-user*. 55 56Vhost-cuse creates a user space character device and hook to a function ioctl, 57so that all ioctl commands that are sent from the frontend (QEMU) will be 58captured and handled. 59 60Vhost-user creates a Unix domain socket file through which messages are 61passed. 62 63.. Note:: 64 65 Since DPDK v2.2, the majority of the development effort has gone into 66 enhancing vhost-user, such as multiple queue, live migration, and 67 reconnect. Thus, it is strongly advised to use vhost-user instead of 68 vhost-cuse. 69 70 71Vhost API Overview 72------------------ 73 74The following is an overview of the Vhost API functions: 75 76* ``rte_vhost_driver_register(path, flags)`` 77 78 This function registers a vhost driver into the system. For vhost-cuse, a 79 ``/dev/path`` character device file will be created. For vhost-user server 80 mode, a Unix domain socket file ``path`` will be created. 81 82 Currently supported flags are (these are valid for vhost-user only): 83 84 - ``RTE_VHOST_USER_CLIENT`` 85 86 DPDK vhost-user will act as the client when this flag is given. See below 87 for an explanation. 88 89 - ``RTE_VHOST_USER_NO_RECONNECT`` 90 91 When DPDK vhost-user acts as the client it will keep trying to reconnect 92 to the server (QEMU) until it succeeds. This is useful in two cases: 93 94 * When QEMU is not started yet. 95 * When QEMU restarts (for example due to a guest OS reboot). 96 97 This reconnect option is enabled by default. However, it can be turned off 98 by setting this flag. 99 100 - ``RTE_VHOST_USER_DEQUEUE_ZERO_COPY`` 101 102 Dequeue zero copy will be enabled when this flag is set. It is disabled by 103 default. 104 105 There are some truths (including limitations) you might want to know while 106 setting this flag: 107 108 * zero copy is not good for small packets (typically for packet size below 109 512). 110 111 * zero copy is really good for VM2VM case. For iperf between two VMs, the 112 boost could be above 70% (when TSO is enableld). 113 114 * for VM2NIC case, the ``nb_tx_desc`` has to be small enough: <= 64 if virtio 115 indirect feature is not enabled and <= 128 if it is enabled. 116 117 The is because when dequeue zero copy is enabled, guest Tx used vring will 118 be updated only when corresponding mbuf is freed. Thus, the nb_tx_desc 119 has to be small enough so that the PMD driver will run out of available 120 Tx descriptors and free mbufs timely. Otherwise, guest Tx vring would be 121 starved. 122 123 * Guest memory should be backended with huge pages to achieve better 124 performance. Using 1G page size is the best. 125 126 When dequeue zero copy is enabled, the guest phys address and host phys 127 address mapping has to be established. Using non-huge pages means far 128 more page segments. To make it simple, DPDK vhost does a linear search 129 of those segments, thus the fewer the segments, the quicker we will get 130 the mapping. NOTE: we may speed it by using tree searching in future. 131 132* ``rte_vhost_driver_session_start()`` 133 134 This function starts the vhost session loop to handle vhost messages. It 135 starts an infinite loop, therefore it should be called in a dedicated 136 thread. 137 138* ``rte_vhost_driver_callback_register(virtio_net_device_ops)`` 139 140 This function registers a set of callbacks, to let DPDK applications take 141 the appropriate action when some events happen. The following events are 142 currently supported: 143 144 * ``new_device(int vid)`` 145 146 This callback is invoked when a virtio net device becomes ready. ``vid`` 147 is the virtio net device ID. 148 149 * ``destroy_device(int vid)`` 150 151 This callback is invoked when a virtio net device shuts down (or when the 152 vhost connection is broken). 153 154 * ``vring_state_changed(int vid, uint16_t queue_id, int enable)`` 155 156 This callback is invoked when a specific queue's state is changed, for 157 example to enabled or disabled. 158 159* ``rte_vhost_enqueue_burst(vid, queue_id, pkts, count)`` 160 161 Transmits (enqueues) ``count`` packets from host to guest. 162 163* ``rte_vhost_dequeue_burst(vid, queue_id, mbuf_pool, pkts, count)`` 164 165 Receives (dequeues) ``count`` packets from guest, and stored them at ``pkts``. 166 167* ``rte_vhost_feature_disable/rte_vhost_feature_enable(feature_mask)`` 168 169 This function disables/enables some features. For example, it can be used to 170 disable mergeable buffers and TSO features, which both are enabled by 171 default. 172 173 174Vhost Implementations 175--------------------- 176 177Vhost-cuse implementation 178~~~~~~~~~~~~~~~~~~~~~~~~~ 179 180When vSwitch registers the vhost driver, it will register a cuse device driver 181into the system and creates a character device file. This cuse driver will 182receive vhost open/release/IOCTL messages from the QEMU simulator. 183 184When the open call is received, the vhost driver will create a vhost device 185for the virtio device in the guest. 186 187When the ``VHOST_SET_MEM_TABLE`` ioctl is received, vhost searches the memory 188region to find the starting user space virtual address that maps the memory of 189the guest virtual machine. Through this virtual address and the QEMU pid, 190vhost can find the file QEMU uses to map the guest memory. Vhost maps this 191file into its address space, in this way vhost can fully access the guest 192physical memory, which means vhost could access the shared virtio ring and the 193guest physical address specified in the entry of the ring. 194 195The guest virtual machine tells the vhost whether the virtio device is ready 196for processing or is de-activated through the ``VHOST_NET_SET_BACKEND`` 197message. The registered callback from vSwitch will be called. 198 199When the release call is made, vhost will destroy the device. 200 201Vhost-user implementation 202~~~~~~~~~~~~~~~~~~~~~~~~~ 203 204Vhost-user uses Unix domain sockets for passing messages. This means the DPDK 205vhost-user implementation has two options: 206 207* DPDK vhost-user acts as the server. 208 209 DPDK will create a Unix domain socket server file and listen for 210 connections from the frontend. 211 212 Note, this is the default mode, and the only mode before DPDK v16.07. 213 214 215* DPDK vhost-user acts as the client. 216 217 Unlike the server mode, this mode doesn't create the socket file; 218 it just tries to connect to the server (which responses to create the 219 file instead). 220 221 When the DPDK vhost-user application restarts, DPDK vhost-user will try to 222 connect to the server again. This is how the "reconnect" feature works. 223 224 .. Note:: 225 * The "reconnect" feature requires **QEMU v2.7** (or above). 226 227 * The vhost supported features must be exactly the same before and 228 after the restart. For example, if TSO is disabled and then enabled, 229 nothing will work and issues undefined might happen. 230 231No matter which mode is used, once a connection is established, DPDK 232vhost-user will start receiving and processing vhost messages from QEMU. 233 234For messages with a file descriptor, the file descriptor can be used directly 235in the vhost process as it is already installed by the Unix domain socket. 236 237The supported vhost messages are: 238 239* ``VHOST_SET_MEM_TABLE`` 240* ``VHOST_SET_VRING_KICK`` 241* ``VHOST_SET_VRING_CALL`` 242* ``VHOST_SET_LOG_FD`` 243* ``VHOST_SET_VRING_ERR`` 244 245For ``VHOST_SET_MEM_TABLE`` message, QEMU will send information for each 246memory region and its file descriptor in the ancillary data of the message. 247The file descriptor is used to map that region. 248 249There is no ``VHOST_NET_SET_BACKEND`` message as in vhost-cuse to signal 250whether the virtio device is ready or stopped. Instead, 251``VHOST_SET_VRING_KICK`` is used as the signal to put the vhost device into 252the data plane, and ``VHOST_GET_VRING_BASE`` is used as the signal to remove 253the vhost device from the data plane. 254 255When the socket connection is closed, vhost will destroy the device. 256 257Vhost supported vSwitch reference 258--------------------------------- 259 260For more vhost details and how to support vhost in vSwitch, please refer to 261the vhost example in the DPDK Sample Applications Guide. 262