add vhost user documentation
fix some minor issues
Signed-off-by: Huawei Xie
---
doc/guides/sample_app_ug/vhost.rst | 123 -
1 file changed, 94 insertions(+), 29 deletions(-)
diff --git a/doc/guides/sample_app_ug/vhost.rst
b/doc/guides/sample_app_ug/vhost.rst
index fa53db6..4f28abd 100644
--- a/doc/guides/sample_app_ug/vhost.rst
+++ b/doc/guides/sample_app_ug/vhost.rst
@@ -45,7 +45,7 @@ Background
Virtio networking (virtio-net) was developed as the Linux* KVM
para-virtualized method for communicating network packets
between host and guest.
It was found that virtio-net performance was poor due to context switching and
packet copying between host, guest, and QEMU.
-The following figure shows the system architecture for a virtio- based
networking (virtio-net).
+The following figure shows the system architecture for a virtio-based
networking (virtio-net).
.. _figure_16:
@@ -89,20 +89,34 @@ Sample Code Overview
The DPDK vhost-net sample code demonstrates KVM (QEMU) offloading the
servicing of a Virtual Machine's (VM's)
virtio-net devices to a DPDK-based application in place of the kernel's
vhost-net module.
-The DPDK vhost-net sample code is a simple packet switching application with
the following features:
+The DPDK vhost-net sample code is based on vhost library. Vhost library is
developed for user space ethernet switch to
+easily integrate with vhost functionality.
+
+The vhost library implements the following features:
* Management of virtio-net device creation/destruction events.
-* Mapping of the VM's physical memory into the DPDK vhost-net sample code's
address space.
+* Mapping of the VM's physical memory into the DPDK vhost-net's address
space.
* Triggering/receiving notifications to/from VMs via eventfds.
* A virtio-net back-end implementation providing a subset of virtio-net
features.
+There are two vhost implementations in vhost library, vhost cuse and vhost
user. In vhost cuse, a character device driver is implemented to
+receive and process vhost requests through ioctl messages. In vhost user, a
socket server is created to received vhost requests through
+socket messages. Most of the messages share the same handler routine.
+
+.. note::
+**Any vhost cuse specific requirement in the following sections will be
emphasized**.
+
+Two impelmentations are turned on and off statically through configure file.
Only one implementation could be turned on. They don't co-exist in current
implementation.
+
+The vhost sample code application is a simple packet switching application
with the following feature:
+
* Packet switching between virtio-net devices and the network interface card,
including using VMDQs to reduce the switching that needs to be performed
in software.
-The following figure shows the architecture of the Vhost sample application.
+The following figure shows the architecture of the Vhost sample application
based on vhost-cuse.
.. _figure_18:
@@ -131,15 +145,19 @@ The example in this section have been validated with the
following distributions
* Fedora* 19
+* Fedora* 20
+
Prerequisites
-
This section lists prerequisite packages that must be installed.
-Installing Packages on the Host
-~~~
+Installing Packages on the Host(vhost cuse required)
+
-The vhost sample code uses the following packages; fuse, fuse-devel, and
kernel- modules-extra.
+The vhost cuse code uses the following packages; fuse, fuse-devel, and
kernel-modules-extra.
+The vhost user code don't rely on those modules as eventfds are already
installed into vhost process through
+unix domain socket.
#. Install Fuse Development Libraries and headers:
@@ -153,6 +171,11 @@ The vhost sample code uses the following packages; fuse,
fuse-devel, and kernel-
yum -y install kernel-modules-extra
+QEMU simulator
+~~
+
+For vhost user, qemu 2.2 is required.
+
Setting up the Execution Environment
@@ -202,7 +225,7 @@ In this section, we create a second hugetlbs mount point to
allocate hugepages f
.. code-block:: console
-echo 256 > /sys/kernel/mm/hugepages/hugepages-2048kB/ nr_hugepages
+echo 256 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
#. Mount hugetlbs at a separate mount point for 2 MB pages:
@@ -251,6 +274,8 @@ at the command line as follows.
Observe that in the example, "-device" and "-netdev" are repeated for two
virtio-net devices.
+For vhost cuse:
+
.. code-block:: console
user at target:~$ qemu-system-x86_64 ... \
@@ -259,15 +284,46 @@ at the command line as follows.
-netdev tap,id=hostnet2,vhost=on,vhostfd= \
-device virtio-net-pci, netdev=hostnet2,id=net1
+For vhost user:
+
+.. code-block:: console
+
+user at target:~$ qemu-system-x86_64 ... \
+-chardev socket,id=char1,path= \
+
