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