summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSiobhan Butler <siobhan.a.butler@intel.com>2014-12-02 21:11:42 +0000
committerThomas Monjalon <thomas.monjalon@6wind.com>2014-12-05 17:27:08 +0100
commit0ee5e7fb93aefe9bccb6a9c331cfe27c14bc7ec6 (patch)
treeec09b91b49e0808da67b5a0132e2a82686ca383c
parent60643134c1c16386ecc737edcd66d16c9df16859 (diff)
downloaddpdk-0ee5e7fb93aefe9bccb6a9c331cfe27c14bc7ec6.zip
dpdk-0ee5e7fb93aefe9bccb6a9c331cfe27c14bc7ec6.tar.gz
dpdk-0ee5e7fb93aefe9bccb6a9c331cfe27c14bc7ec6.tar.xz
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 <siobhan.a.butler@intel.com> Signed-off-by: Huawei Xie <huawei.xie@intel.com> Acked-by: Bernard Iremonger <bernard.iremonger@intel.com>
-rw-r--r--doc/guides/prog_guide/index.rst1
-rw-r--r--doc/guides/prog_guide/vhost_lib.rst101
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
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -106,6 +106,7 @@ Copyright © 2012-2014, Intel Corporation. All rights reserved.
power_man
packet_classif_access_ctrl
packet_framework
+ vhost_lib
source_org
dev_kit_build_system
dev_kit_root_make_help
diff --git a/doc/guides/prog_guide/vhost_lib.rst b/doc/guides/prog_guide/vhost_lib.rst
new file mode 100644
index 0000000..0b6eda7
--- /dev/null
+++ b/doc/guides/prog_guide/vhost_lib.rst
@@ -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
+ distribution.
+ * 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.
+
+Vhost Library
+=============
+
+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.
+
+Vhost Implementation
+--------------------
+
+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.