[ceph.git] / ceph / src / spdk / dpdk / doc / guides / nics / vhost.rst

..  BSD LICENSE
    Copyright(c) 2016 IGEL Co., Ltd.. All rights reserved.
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
    * Neither the name of IGEL Co., Ltd. nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Poll Mode Driver that wraps vhost library
=========================================

This PMD is a thin wrapper of the DPDK vhost library.
The user can handle virtqueues as one of normal DPDK port.

Vhost Implementation in DPDK
----------------------------

Please refer to Chapter "Vhost Library" of *DPDK Programmer's Guide* to know detail of vhost.

Features and Limitations of vhost PMD
-------------------------------------

Currently, the vhost PMD provides the basic functionality of packet reception, transmission and event handling.

*   It has multiple queues support.

*   It supports ``RTE_ETH_EVENT_INTR_LSC`` and ``RTE_ETH_EVENT_QUEUE_STATE`` events.

*   It supports Port Hotplug functionality.

*   Don't need to stop RX/TX, when the user wants to stop a guest or a virtio-net driver on guest.

Vhost PMD arguments
-------------------

The user can specify below arguments in `--vdev` option.

#.  ``iface``:

    It is used to specify a path to connect to a QEMU virtio-net device.

#.  ``queues``:

    It is used to specify the number of queues virtio-net device has.
    (Default: 1)

#.  ``iommu-support``:

    It is used to enable iommu support in vhost library.
    (Default: 0 (disabled))

#.  ``postcopy-support``:

    It is used to enable postcopy live-migration support in vhost library.
    (Default: 0 (disabled))

Vhost PMD event handling
------------------------

This section describes how to handle vhost PMD events.

The user can register an event callback handler with ``rte_eth_dev_callback_register()``.
The registered callback handler will be invoked with one of below event types.

#.  ``RTE_ETH_EVENT_INTR_LSC``:

    It means link status of the port was changed.

#.  ``RTE_ETH_EVENT_QUEUE_STATE``:

    It means some of queue statuses were changed. Call ``rte_eth_vhost_get_queue_event()`` in the callback handler.
    Because changing multiple statuses may occur only one event, call the function repeatedly as long as it doesn't return negative value.

Vhost PMD with testpmd application
----------------------------------

This section demonstrates vhost PMD with testpmd DPDK sample application.

#.  Launch the testpmd with vhost PMD:

    .. code-block:: console

        ./testpmd -l 0-3 -n 4 --vdev 'net_vhost0,iface=/tmp/sock0,queues=1' -- -i

    Other basic DPDK preparations like hugepage enabling here.
    Please refer to the *DPDK Getting Started Guide* for detailed instructions.

#.  Launch the QEMU:

    .. code-block:: console

       qemu-system-x86_64 <snip>
                   -chardev socket,id=chr0,path=/tmp/sock0 \
                   -netdev vhost-user,id=net0,chardev=chr0,vhostforce,queues=1 \
                   -device virtio-net-pci,netdev=net0

    This command attaches one virtio-net device to QEMU guest.
    After initialization processes between QEMU and DPDK vhost library are done, status of the port will be linked up.
Commit	Line	Data
7c673cae FG	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
	31	Poll Mode Driver that wraps vhost library
	32	=========================================
	33
	34	This PMD is a thin wrapper of the DPDK vhost library.
	35	The user can handle virtqueues as one of normal DPDK port.
	36
	37	Vhost Implementation in DPDK
	38	----------------------------
	39
	40	Please refer to Chapter "Vhost Library" of DPDK Programmer's Guide to know detail of vhost.
	41
	42	Features and Limitations of vhost PMD
	43	-------------------------------------
	44
	45	Currently, 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
	55	Vhost PMD arguments
	56	-------------------
	57
	58	The 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
11fdf7f2 TL	69	#. ``iommu-support``:
	70
	71	It is used to enable iommu support in vhost library.
	72	(Default: 0 (disabled))
	73
9f95a23c TL	74	#. ``postcopy-support``:
	75
	76	It is used to enable postcopy live-migration support in vhost library.
	77	(Default: 0 (disabled))
	78
7c673cae FG	79	Vhost PMD event handling
	80	------------------------
	81
	82	This section describes how to handle vhost PMD events.
	83
	84	The user can register an event callback handler with ``rte_eth_dev_callback_register()``.
	85	The registered callback handler will be invoked with one of below event types.
	86
	87	#. ``RTE_ETH_EVENT_INTR_LSC``:
	88
	89	It means link status of the port was changed.
	90
	91	#. ``RTE_ETH_EVENT_QUEUE_STATE``:
	92
	93	It means some of queue statuses were changed. Call ``rte_eth_vhost_get_queue_event()`` in the callback handler.
	94	Because changing multiple statuses may occur only one event, call the function repeatedly as long as it doesn't return negative value.
	95
	96	Vhost PMD with testpmd application
	97	----------------------------------
	98
	99	This section demonstrates vhost PMD with testpmd DPDK sample application.
	100
	101	#. Launch the testpmd with vhost PMD:
	102
	103	.. code-block:: console
	104
11fdf7f2	105	./testpmd -l 0-3 -n 4 --vdev 'net_vhost0,iface=/tmp/sock0,queues=1' -- -i
7c673cae FG	106
	107	Other basic DPDK preparations like hugepage enabling here.
	108	Please refer to the DPDK Getting Started Guide for detailed instructions.
	109
	110	#. Launch the QEMU:
	111
	112	.. code-block:: console
	113
	114	qemu-system-x86_64 <snip>
	115	-chardev socket,id=chr0,path=/tmp/sock0 \
	116	-netdev vhost-user,id=net0,chardev=chr0,vhostforce,queues=1 \
	117	-device virtio-net-pci,netdev=net0
	118
	119	This command attaches one virtio-net device to QEMU guest.
	120	After initialization processes between QEMU and DPDK vhost library are done, status of the port will be linked up.