Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/3974/?format=api
{ "id": 3974, "url": "http://patches.dpdk.org/api/patches/3974/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/1426090907-18746-1-git-send-email-huawei.xie@intel.com/", "project": { "id": 1, "url": "http://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<1426090907-18746-1-git-send-email-huawei.xie@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/1426090907-18746-1-git-send-email-huawei.xie@intel.com", "date": "2015-03-11T16:21:47", "name": "[dpdk-dev] vhost example doc update", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": true, "hash": "82f8c4dda91ba48b37d010fc0555ec926cd88fd1", "submitter": { "id": 16, "url": "http://patches.dpdk.org/api/people/16/?format=api", "name": "Huawei Xie", "email": "huawei.xie@intel.com" }, "delegate": null, "mbox": "http://patches.dpdk.org/project/dpdk/patch/1426090907-18746-1-git-send-email-huawei.xie@intel.com/mbox/", "series": [], "comments": "http://patches.dpdk.org/api/patches/3974/comments/", "check": "pending", "checks": "http://patches.dpdk.org/api/patches/3974/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@dpdk.org", "Delivered-To": "patchwork@dpdk.org", "Received": [ "from [92.243.14.124] (localhost [IPv6:::1])\n\tby dpdk.org (Postfix) with ESMTP id 11F939A94;\n\tWed, 11 Mar 2015 17:21:58 +0100 (CET)", "from mga11.intel.com (mga11.intel.com [192.55.52.93])\n\tby dpdk.org (Postfix) with ESMTP id C94739A91\n\tfor <dev@dpdk.org>; Wed, 11 Mar 2015 17:21:55 +0100 (CET)", "from fmsmga002.fm.intel.com ([10.253.24.26])\n\tby fmsmga102.fm.intel.com with ESMTP; 11 Mar 2015 09:21:55 -0700", "from shvmail01.sh.intel.com ([10.239.29.42])\n\tby fmsmga002.fm.intel.com with ESMTP; 11 Mar 2015 09:21:54 -0700", "from shecgisg003.sh.intel.com (shecgisg003.sh.intel.com\n\t[10.239.29.90])\n\tby shvmail01.sh.intel.com with ESMTP id t2BGLpx9015083;\n\tThu, 12 Mar 2015 00:21:52 +0800", "from shecgisg003.sh.intel.com (localhost [127.0.0.1])\n\tby shecgisg003.sh.intel.com (8.13.6/8.13.6/SuSE Linux 0.8) with ESMTP\n\tid t2BGLnLV018781; Thu, 12 Mar 2015 00:21:51 +0800", "(from hxie5@localhost)\n\tby shecgisg003.sh.intel.com (8.13.6/8.13.6/Submit) id t2BGLn2I018777; \n\tThu, 12 Mar 2015 00:21:49 +0800" ], "X-ExtLoop1": "1", "X-IronPort-AV": "E=Sophos;i=\"5.11,382,1422950400\"; d=\"scan'208\";a=\"690561867\"", "From": "Huawei Xie <huawei.xie@intel.com>", "To": "dev@dpdk.org", "Date": "Thu, 12 Mar 2015 00:21:47 +0800", "Message-Id": "<1426090907-18746-1-git-send-email-huawei.xie@intel.com>", "X-Mailer": "git-send-email 1.7.4.1", "Subject": "[dpdk-dev] [PATCH] vhost example doc update", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "patches and discussions about DPDK <dev.dpdk.org>", "List-Unsubscribe": "<http://dpdk.org/ml/options/dev>,\n\t<mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://dpdk.org/ml/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<http://dpdk.org/ml/listinfo/dev>,\n\t<mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "add vhost user documentation\nfix some minor issues\n\nSigned-off-by: Huawei Xie <huawei.xie@intel.com>\n---\n doc/guides/sample_app_ug/vhost.rst | 123 ++++++++++++++++++++++++++++---------\n 1 file changed, 94 insertions(+), 29 deletions(-)", "diff": "diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst\nindex fa53db6..4f28abd 100644\n--- a/doc/guides/sample_app_ug/vhost.rst\n+++ b/doc/guides/sample_app_ug/vhost.rst\n@@ -45,7 +45,7 @@ Background\n Virtio networking (virtio-net) was developed as the Linux* KVM para-virtualized method for communicating network packets\n between host and guest.\n It was found that virtio-net performance was poor due to context switching and packet copying between host, guest, and QEMU.\n-The following figure shows the system architecture for a virtio- based networking (virtio-net).\n+The following figure shows the system architecture for a virtio-based networking (virtio-net).\n \n .. _figure_16:\n \n@@ -89,20 +89,34 @@ Sample Code Overview\n The DPDK vhost-net sample code demonstrates KVM (QEMU) offloading the servicing of a Virtual Machine's (VM's)\n virtio-net devices to a DPDK-based application in place of the kernel's vhost-net module.\n \n-The DPDK vhost-net sample code is a simple packet switching application with the following features:\n+The DPDK vhost-net sample code is based on vhost library. Vhost library is developed for user space ethernet switch to\n+easily integrate with vhost functionality.\n+\n+The vhost library implements the following features:\n \n * Management of virtio-net device creation/destruction events.\n \n-* Mapping of the VM's physical memory into the DPDK vhost-net sample code's address space.\n+* Mapping of the VM's physical memory into the DPDK vhost-net's address space.\n \n * Triggering/receiving notifications to/from VMs via eventfds.\n \n * A virtio-net back-end implementation providing a subset of virtio-net features.\n \n+There are two vhost implementations in vhost library, vhost cuse and vhost user. In vhost cuse, a character device driver is implemented to\n+receive and process vhost requests through ioctl messages. In vhost user, a socket server is created to received vhost requests through\n+socket messages. Most of the messages share the same handler routine.\n+\n+.. note::\n+ **Any vhost cuse specific requirement in the following sections will be emphasized**.\n+\n+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.\n+\n+The vhost sample code application is a simple packet switching application with the following feature:\n+\n * Packet switching between virtio-net devices and the network interface card,\n including using VMDQs to reduce the switching that needs to be performed in software.\n \n-The following figure shows the architecture of the Vhost sample application.\n+The following figure shows the architecture of the Vhost sample application based on vhost-cuse.\n \n .. _figure_18:\n \n@@ -131,15 +145,19 @@ The example in this section have been validated with the following distributions\n \n * Fedora* 19\n \n+* Fedora* 20\n+\n Prerequisites\n -------------\n \n This section lists prerequisite packages that must be installed.\n \n-Installing Packages on the Host\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+Installing Packages on the Host(vhost cuse required)\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n-The vhost sample code uses the following packages; fuse, fuse-devel, and kernel- modules-extra.\n+The vhost cuse code uses the following packages; fuse, fuse-devel, and kernel-modules-extra.\n+The vhost user code don't rely on those modules as eventfds are already installed into vhost process through\n+unix domain socket.\n \n #. Install Fuse Development Libraries and headers:\n \n@@ -153,6 +171,11 @@ The vhost sample code uses the following packages; fuse, fuse-devel, and kernel-\n \n yum -y install kernel-modules-extra\n \n+QEMU simulator\n+~~~~~~~~~~~~~~\n+\n+For vhost user, qemu 2.2 is required.\n+\n Setting up the Execution Environment\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n@@ -202,7 +225,7 @@ In this section, we create a second hugetlbs mount point to allocate hugepages f\n \n .. code-block:: console\n \n- echo 256 > /sys/kernel/mm/hugepages/hugepages-2048kB/ nr_hugepages\n+ echo 256 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages\n \n #. Mount hugetlbs at a separate mount point for 2 MB pages:\n \n@@ -251,6 +274,8 @@ at the command line as follows.\n \n Observe that in the example, \"-device\" and \"-netdev\" are repeated for two virtio-net devices.\n \n+For vhost cuse:\n+\n .. code-block:: console\n \n user@target:~$ qemu-system-x86_64 ... \\\n@@ -259,15 +284,46 @@ at the command line as follows.\n -netdev tap,id=hostnet2,vhost=on,vhostfd=<open fd> \\\n -device virtio-net-pci, netdev=hostnet2,id=net1\n \n+For vhost user:\n+\n+.. code-block:: console\n+\n+ user@target:~$ qemu-system-x86_64 ... \\\n+ -chardev socket,id=char1,path=<sock_path> \\\n+ -netdev type=vhost-user,id=hostnet1,chardev=char1 \\\n+ -device virtio-net-pci,netdev=hostnet1,id=net1 \\\n+ -chardev socket,id=char2,path=<sock_path> \\\n+ -netdev type=vhost-user,id=hostnet2,chardev=char2 \\\n+ -device virtio-net-pci,netdev=hostnet2,id=net2\n+\n+sock_path is the path for the socket file created by vhost.\n \n Compiling the Sample Code\n -------------------------\n+#. Compile vhost lib:\n+\n+ To enable vhost, turn on vhost library in the configure file config/common_linuxapp.\n+\n+ .. code-block:: console\n+\n+ CONFIG_RTE_LIBRTE_VHOST=n\n+\n+ vhost user is turned on by default in the lib/librte_vhost/Makefile.\n+ To enable vhost cuse, uncomment vhost cuse and comment vhost user manually. In future, a configure will be created for switch between two implementations.\n+\n+ .. code-block:: console\n+\n+ SRCS-$(CONFIG_RTE_LIBRTE_VHOST) += vhost_cuse/vhost-net-cdev.c vhost_cuse/virtio-net-cdev.c vhost_cuse/eventfd_copy.c\n+ #SRCS-$(CONFIG_RTE_LIBRTE_VHOST) += vhost_user/vhost-net-user.c vhost_user/virtio-net-user.c vhost_user/fd_man.c\n+\n+ After vhost is enabled and the implementation is selected, build the vhost library.\n \n #. Go to the examples directory:\n \n .. code-block:: console\n \n- export RTE_SDK=/path/to/rte_sdk cd ${RTE_SDK}/examples/vhost-net\n+ export RTE_SDK=/path/to/rte_sdk\n+ cd ${RTE_SDK}/examples/vhost\n \n #. Set the target (a default target is used if not specified). For example:\n \n@@ -309,13 +365,13 @@ Compiling the Sample Code\n cd ${RTE_SDK}/examples/vhost\n make\n \n-#. Go to the eventfd_link directory:\n+#. Go to the eventfd_link directory(vhost cuse required):\n \n .. code-block:: console\n \n- cd ${RTE_SDK}/examples/vhost-net/eventfd_link\n+ cd ${RTE_SDK}/lib/librte_vhost/eventfd_link\n \n-#. Build the eventfd_link kernel module:\n+#. Build the eventfd_link kernel module(vhost cuse required):\n \n .. code-block:: console\n \n@@ -324,20 +380,20 @@ Compiling the Sample Code\n Running the Sample Code\n -----------------------\n \n-#. Install the cuse kernel module:\n+#. Install the cuse kernel module(vhost cuse required):\n \n .. code-block:: console\n \n modprobe cuse\n \n-#. Go to the eventfd_link directory:\n+#. Go to the eventfd_link directory(vhost cuse required):\n \n .. code-block:: console\n \n export RTE_SDK=/path/to/rte_sdk\n- cd ${RTE_SDK}/examples/vhost-net/eventfd_link\n+ cd ${RTE_SDK}/lib/librte_vhost/eventfd_link\n \n-#. Install the eventfd_link module:\n+#. Install the eventfd_link module(vhost cuse required):\n \n .. code-block:: console\n \n@@ -348,14 +404,22 @@ Running the Sample Code\n .. code-block:: console\n \n export RTE_SDK=/path/to/rte_sdk\n- cd ${RTE_SDK}/examples/vhost-net\n+ cd ${RTE_SDK}/examples/vhost\n \n #. Run the vhost-switch sample code:\n \n+ vhost cuse:\n+\n .. code-block:: console\n \n user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- -p 0x1 --dev-basename usvhost --dev-index 1\n \n+ vhost user: a socket file named usvhost will be created under current directory. Use its path as the socket path in guest's qemu commandline.\n+\n+ .. code-block:: console\n+\n+ user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- -p 0x1 --dev-basename usvhost\n+\n .. note::\n \n Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs.\n@@ -364,7 +428,7 @@ Parameters\n ~~~~~~~~~~\n \n **Basename and Index.**\n-The DPDK vhost-net sample code uses a Linux* character device to communicate with QEMU.\n+vhost cuse uses a Linux* character device to communicate with QEMU.\n The basename and the index are used to generate the character devices name.\n \n /dev/<basename>-<index>\n@@ -477,15 +541,15 @@ QEMU must be executed with specific parameters to:\n \n .. code-block:: console\n \n- user@target:~$ qemu-system-x86_64 ... -device virtio-net-pci, netdev=hostnet1,id=net1 ...\n+ user@target:~$ qemu-system-x86_64 ... -device virtio-net-pci,netdev=hostnet1,id=net1 ...\n \n * Ensure the guest's virtio-net network adapter is configured with offloads disabled.\n \n .. code-block:: console\n \n- user@target:~$ qemu-system-x86_64 ... -device virtio-net-pci, netdev=hostnet1,id=net1,csum=off,gso=off,guest_tso4=off,guest_ tso6=off,guest_ecn=off\n+ user@target:~$ qemu-system-x86_64 ... -device virtio-net-pci,netdev=hostnet1,id=net1,csum=off,gso=off,guest_tso4=off,guest_tso6=off,guest_ecn=off\n \n-* Redirect QEMU to communicate with the DPDK vhost-net sample code in place of the vhost-net kernel module.\n+* Redirect QEMU to communicate with the DPDK vhost-net sample code in place of the vhost-net kernel module(vhost cuse).\n \n .. code-block:: console\n \n@@ -502,8 +566,8 @@ QEMU must be executed with specific parameters to:\n The QEMU wrapper (qemu-wrap.py) is a Python script designed to automate the QEMU configuration described above.\n It also facilitates integration with libvirt, although the script may also be used standalone without libvirt.\n \n-Redirecting QEMU to vhost-net Sample Code\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+Redirecting QEMU to vhost-net Sample Code(vhost cuse)\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n To redirect QEMU to the vhost-net sample code implementation of the vhost-net API,\n an open file descriptor must be passed to QEMU running as a child process.\n@@ -516,7 +580,7 @@ an open file descriptor must be passed to QEMU running as a child process.\n \n .. note::\n \n- This process is automated in the QEMU wrapper script discussed in Section 22.7.3.\n+ This process is automated in the QEMU wrapper script discussed in Section 24.7.3.\n \n Mapping the Virtual Machine's Memory\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n@@ -533,7 +597,8 @@ In this case, the path passed to the guest should be that of the 1 GB page huget\n \n .. note::\n \n- This process is automated in the QEMU wrapper script discussed in Section 22.7.3.\n+ This process is automated in the QEMU wrapper script discussed in Section 24.7.3.\n+ The following two sections only applies to vhost cuse. For vhost-user, please make corresponding changes to qemu-wrapper script and guest XML file.\n \n QEMU Wrapper Script\n ~~~~~~~~~~~~~~~~~~~\n@@ -562,8 +627,8 @@ which will become the following call to QEMU:\n .. code-block:: console\n \n /usr/local/bin/qemu-system-x86_64 -machine pc-i440fx-1.4,accel=kvm,usb=off -cpu SandyBridge -smp 4,sockets=4,cores=1,threads=1\n- -netdev tap,id=hostnet1,vhost=on,vhostfd=<open fd> -device virtio-net- pci,netdev=hostnet1,id=net1,\n- csum=off,gso=off,guest_tso4=off,gu est_tso6=off,guest_ecn=off -hda <disk img> -m 4096 -mem-path /dev/hugepages -mem-prealloc\n+ -netdev tap,id=hostnet1,vhost=on,vhostfd=<open fd> -device virtio-net-pci,netdev=hostnet1,id=net1,\n+ csum=off,gso=off,guest_tso4=off,guest_tso6=off,guest_ecn=off -hda <disk img> -m 4096 -mem-path /dev/hugepages -mem-prealloc\n \n Libvirt Integration\n ~~~~~~~~~~~~~~~~~~~\n@@ -630,7 +695,7 @@ To call the QEMU wrapper automatically from libvirt, the following configuration\n \n emul_path = \"/usr/local/bin/qemu-system-x86_64\"\n \n- * Configure the \"us_vhost_path\" variable to point to the DPDK vhost- net sample code's character devices name.\n+ * Configure the \"us_vhost_path\" variable to point to the DPDK vhost-net sample code's character devices name.\n DPDK vhost-net sample code's character device will be in the format \"/dev/<basename>-<index>\".\n \n .. code-block:: xml\n@@ -650,7 +715,7 @@ The number of free hugepages can be checked as follows:\n \n .. code-block:: console\n \n- user@target:cat /sys/kernel/mm/hugepages/hugepages-<pagesize> / nr_hugepages\n+ user@target:cat /sys/kernel/mm/hugepages/hugepages-<pagesize>/nr_hugepages\n \n The command above indicates how many hugepages are free to support QEMU's allocation request.\n \n", "prefixes": [ "dpdk-dev" ] }