|author||Siobhan Butler <firstname.lastname@example.org>||2014-12-02 21:11:42 +0000|
|committer||Thomas Monjalon <email@example.com>||2014-12-05 17:27:08 +0100|
doc: add vhost library
As Vhost will be a library in DPDK 1.8, adding a new section to Programmer's Guide to describe its use. Signed-off-by: Siobhan Butler <firstname.lastname@example.org> Signed-off-by: Huawei Xie <email@example.com> Acked-by: Bernard Iremonger <firstname.lastname@example.org>
2 files changed, 102 insertions, 0 deletions
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index e0ac8f4..6652cb4 100644
@@ -106,6 +106,7 @@ Copyright © 2012-2014, Intel Corporation. All rights reserved.
diff --git a/doc/guides/prog_guide/vhost_lib.rst b/doc/guides/prog_guide/vhost_lib.rst
new file mode 100644
@@ -0,0 +1,101 @@
+.. BSD LICENSE
+ Copyright(c) 2010-2014 Intel Corporation. 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
+ * Neither the name of Intel Corporation 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.
+The vhost cuse (cuse: user space character device driver) library implements a
+vhost cuse driver. It also creates, manages and destroys vhost devices for
+corresponding virtio devices in the guest. Vhost supported vSwitch could register
+callbacks to this library, which will be called when a vhost device is activated
+or deactivated by guest virtual machine.
+Vhost API Overview
+* Vhost driver registration
+ rte_vhost_driver_register registers the vhost cuse driver into the system.
+ Character device file will be created in the /dev directory.
+ Character device name is specified as the parameter.
+* Vhost session start
+ rte_vhost_driver_session_start starts the vhost session loop.
+ Vhost cuse session is an infinite blocking loop.
+ Put the session in a dedicate DPDK thread.
+* Callback register
+ Vhost supported vSwitch could call rte_vhost_driver_callback_register to
+ register two callbacks, new_destory and destroy_device.
+ When virtio device is activated or deactivated by guest virtual machine,
+ the callback will be called, then vSwitch could put the device onto data
+ core or remove the device from data core.
+* Read/write packets from/to guest virtual machine
+ rte_vhost_enqueue_burst transmit host packets to guest.
+ rte_vhost_dequeue_burst receives packets from guest.
+* Feature enable/disable
+ Now one negotiate-able feature in vhost is merge-able.
+ vSwitch could enable/disable this feature for performance consideration.
+When vSwitch registers the vhost driver, it will register a cuse device driver
+into the system and creates a character device file. This cuse driver will
+receive vhost open/release/IOCTL message from QEMU simulator.
+When the open call is received, vhost driver will create a vhost device for the
+virtio device in the guest.
+When VHOST_SET_MEM_TABLE IOCTL is received, vhost searches the memory region
+to find the starting user space virtual address that maps the memory of guest
+virtual machine. Through this virtual address and the QEMU pid, vhost could
+find the file QEMU uses to map the guest memory. Vhost maps this file into its
+address space, in this way vhost could fully access the guest physical memory,
+which means vhost could access the shared virtio ring and the guest physical
+address specified in the entry of the ring.
+The guest virtual machine tells the vhost whether the virtio device is ready
+for processing or is de-activated through VHOST_SET_BACKEND message.
+The registered callback from vSwitch will be called.
+When the release call is released, vhost will destroy the device.
+Vhost supported vSwitch reference
+For how to support vhost in vSwitch, please refer to vhost example in the
+DPDK Sample Applications Guide.