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>

diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index e0ac8f4..6652cb4 100644 (file)
--- 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 (file)
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.