[PATCH] doc: Update doc for vhost sample

[PATCH] doc: Update doc for vhost sample

[Ouyang Changchun]

Add some contents for vhost sample.

Signed-off-by: Changchun Ouyang <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
 doc/guides/sample_app_ug/vhost.rst | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst
index fa53db6..756838c 100644
--- a/doc/guides/sample_app_ug/vhost.rst
+++ b/doc/guides/sample_app_ug/vhost.rst
@@ -654,6 +654,35 @@ The number of free hugepages can be checked as follows:
 
 The command above indicates how many hugepages are free to support QEMU's allocation request.
 
+**Can user space VHOST work properly with the guest with 2M sized hug pages?**
+
+Yes, it can. The guest may have 2M or 1G sized huge pages file, the user space VHOST can work properly in both cases.
+
+**Can user space VHOST work with QEMU without '-mem-prealloc' option?**
+The current implementation work properly only when the guest memory is pre-allocated, so you are required to use the
+correct QEMU version(e.g. 1.6) which supports '-mem-prealloc'; And the option '-mem-prealloc' is required to be specified
+explicitly in QEMU command line.
+
+**Can user space VHOST work with QEMU version without shared memory mapping?**
+No, it can't, shared memory mapping is mandatory for user space VHOST to work properly with guest as user space VHOST
+need access the shared memory from guest to receive and transmit packets. You are required to make sure the QEMU version
+support shared memory mapping.
+
+**When using libvirt "virsh create" the qemu-wrap.py spawns a new process to run "qemu-kvm". This impacts the behavior
+of the "virsh destroy" which kills the process running "qemu-wrap.py" without actually destroying the VM (leaves the
+"qemu-kvm" process running).**
+This patch can fix this issue: http://dpdk.org/ml/archives/dev/2014-June/003607.html
+
+**On Ubuntu environment, QEMU fail to start a new guest normally with user space VHOST due to hug pages can't be
+allocated for the new guest.**
+The solution for this issue could be adding "-boot c" into QEMU command line to make sure the huge pages are allocated
+properly and then the guest startup normally. You may use "cat /proc/meminfo" to check if there is any change in value
+of HugePages_Total and HugePages_Free after the guest startup.
+
+**Why I get this logging message: "eventfd_link: module verification failed: signature and/or required key missing - tainting kernel"?**
+You can ignore the above logging message. The message occurs due to the new module eventfd_link is not a standard
+module of Linux, but it is necessary for user space VHOST current implementation(CUSE-based) to communicate with guest.
+
 Running DPDK in the Virtual Machine
 -----------------------------------
 
-- 
1.8.4.2

[PATCH v2] doc: Update doc for vhost sample

[Ouyang Changchun]

Add some contents for vhost sample.

Signed-off-by: Changchun Ouyang <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---

Change in v2:
  -- Refine its format to fit well with other parts.

 doc/guides/sample_app_ug/vhost.rst | 52 +++++++++++++++++++++++++++++++++-----
 1 file changed, 45 insertions(+), 7 deletions(-)

diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst
index fa53db6..76997da 100644
--- a/doc/guides/sample_app_ug/vhost.rst
+++ b/doc/guides/sample_app_ug/vhost.rst
@@ -640,19 +640,57 @@ To call the QEMU wrapper automatically from libvirt, the following configuration
 Common Issues
 ~~~~~~~~~~~~~
 
-**QEMU failing to allocate memory on hugetlbfs.**
+*   QEMU failing to allocate memory on hugetlbfs:
 
-file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
+    file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
 
-When running QEMU the above error implies that it has failed to allocate memory for the Virtual Machine on the hugetlbfs.
-This is typically due to insufficient hugepages being free to support the allocation request.
-The number of free hugepages can be checked as follows:
+    When running QEMU the above error implies that it has failed to allocate memory for the Virtual Machine on
+    the hugetlbfs. This is typically due to insufficient hugepages being free to support the allocation request.
+    The number of free hugepages can be checked as follows:
 
-.. code-block:: console
+    .. code-block:: console
 
     user@target:cat /sys/kernel/mm/hugepages/hugepages-<pagesize> / nr_hugepages
 
-The command above indicates how many hugepages are free to support QEMU's allocation request.
+    The command above indicates how many hugepages are free to support QEMU's allocation request.
+
+*   User space VHOST work properly with the guest with 2M sized hug pages:
+
+    The guest may have 2M or 1G sized huge pages file, the user space VHOST can work properly in both cases.
+
+*   User space VHOST will not work with QEMU without '-mem-prealloc' option:
+
+    The current implementation work properly only when the guest memory is pre-allocated, so it is required to
+    use the correct QEMU version(e.g. 1.6) which supports '-mem-prealloc'; The option '-mem-prealloc' must be
+    specified explicitly in QEMU command line.
+
+*   User space VHOST will not work with QEMU version without shared memory mapping:
+
+    As shared memory mapping is mandatory for user space VHOST to work properly with the guest as user space VHOST
+    needs access the shared memory from the guest to receive and transmit packets. It is important to make sure
+    the QEMU version used supports shared memory mapping.
+
+*   Using libvirt "virsh create" the qemu-wrap.py spawns a new process to run "qemu-kvm". This impacts the behavior
+    of the "virsh destroy" which kills the process running "qemu-wrap.py" without actually destroying the VM (leaves
+    the "qemu-kvm" process running):
+
+    This following patch can fix this issue:
+        http://dpdk.org/ml/archives/dev/2014-June/003607.html
+
+*   In Ubuntu environment, QEMU fail to start a new guest normally with user space VHOST due to hug pages can't be
+    allocated for the new guest.*
+
+    The solution for this issue could be adding "-boot c" into QEMU command line to make sure the huge pages are
+    allocated properly and then the guest will startup normally.
+
+    Use "cat /proc/meminfo" to check if there is any change in value of HugePages_Total and HugePages_Free after the
+    guest startup.
+
+*   Logging message: "eventfd_link: module verification failed: signature and/or required key missing - tainting kernel"*
+
+    Ignore the above logging message. The message occurs due to the new module eventfd_link, which is not a standard
+    module of Linux, but it is necessary for user space VHOST current implementation(CUSE-based) to communicate with
+    the guest.
 
 Running DPDK in the Virtual Machine
 -----------------------------------
-- 
1.8.4.2

[PATCH v3] Update doc for vhost sample

[John McNamara]

V3: Fix for code indentation issue preventing PDF build.

Ouyang Changchun (1):
  doc: Update doc for vhost sample

 doc/guides/sample_app_ug/vhost.rst | 55 ++++++++++++++++++++++++++++++++------
 1 file changed, 47 insertions(+), 8 deletions(-)

-- 
1.8.1.4

[PATCH v3] doc: Update doc for vhost sample

[John McNamara]

From: Ouyang Changchun <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

Add some documentation updates for vhost sample app.

Signed-off-by: Changchun Ouyang <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
Signed-off-by: John McNamara <john.mcnamara-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
 doc/guides/sample_app_ug/vhost.rst | 55 ++++++++++++++++++++++++++++++++------
 1 file changed, 47 insertions(+), 8 deletions(-)

diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst
index 4a6d434..7254578 100644
--- a/doc/guides/sample_app_ug/vhost.rst
+++ b/doc/guides/sample_app_ug/vhost.rst
@@ -1,3 +1,4 @@
+
 ..  BSD LICENSE
     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
     All rights reserved.
@@ -640,19 +641,57 @@ To call the QEMU wrapper automatically from libvirt, the following configuration
 Common Issues
 ~~~~~~~~~~~~~
 
-**QEMU failing to allocate memory on hugetlbfs.**
+*   QEMU failing to allocate memory on hugetlbfs::
 
-file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
+       file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
 
-When running QEMU the above error implies that it has failed to allocate memory for the Virtual Machine on the hugetlbfs.
-This is typically due to insufficient hugepages being free to support the allocation request.
-The number of free hugepages can be checked as follows:
+    When running QEMU the above error implies that it has failed to allocate memory for the Virtual Machine on
+    the hugetlbfs. This is typically due to insufficient hugepages being free to support the allocation request.
+    The number of free hugepages can be checked as follows:
 
-.. code-block:: console
+    .. code-block:: console
+
+        user@target:cat /sys/kernel/mm/hugepages/hugepages-<pagesize> / nr_hugepages
+
+    The command above indicates how many hugepages are free to support QEMU's allocation request.
+
+*   User space VHOST work properly with the guest with 2M sized hug pages:
+
+    The guest may have 2M or 1G sized huge pages file, the user space VHOST can work properly in both cases.
+
+*   User space VHOST will not work with QEMU without '-mem-prealloc' option:
+
+    The current implementation work properly only when the guest memory is pre-allocated, so it is required to
+    use the correct QEMU version(e.g. 1.6) which supports '-mem-prealloc'; The option '-mem-prealloc' must be
+    specified explicitly in QEMU command line.
+
+*   User space VHOST will not work with QEMU version without shared memory mapping:
+
+    As shared memory mapping is mandatory for user space VHOST to work properly with the guest as user space VHOST
+    needs access the shared memory from the guest to receive and transmit packets. It is important to make sure
+    the QEMU version used supports shared memory mapping.
+
+*   Using libvirt "virsh create" the qemu-wrap.py spawns a new process to run "qemu-kvm". This impacts the behavior
+    of the "virsh destroy" which kills the process running "qemu-wrap.py" without actually destroying the VM (leaves
+    the "qemu-kvm" process running):
+
+    This following patch can fix this issue:
+        http://dpdk.org/ml/archives/dev/2014-June/003607.html
+
+*   In Ubuntu environment, QEMU fail to start a new guest normally with user space VHOST due to hug pages can't be
+    allocated for the new guest.*
+
+    The solution for this issue could be adding "-boot c" into QEMU command line to make sure the huge pages are
+    allocated properly and then the guest will startup normally.
+
+    Use "cat /proc/meminfo" to check if there is any change in value of HugePages_Total and HugePages_Free after the
+    guest startup.
 
-    user@target:cat /sys/kernel/mm/hugepages/hugepages-<pagesize> / nr_hugepages
+*   Logging message: "eventfd_link: module verification failed: signature and/or required key missing - tainting kernel"*
 
-The command above indicates how many hugepages are free to support QEMU's allocation request.
+    Ignore the above logging message. The message occurs due to the new module eventfd_link, which is not a standard
+    module of Linux, but it is necessary for user space VHOST current implementation(CUSE-based) to communicate with
+    the guest.
 
 Running DPDK in the Virtual Machine
 -----------------------------------
-- 
1.8.1.4

[PATCH v4] doc: Update doc for vhost sample

[John McNamara]

From: Ouyang Changchun <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

Added some documentation on common issues for the vhost sample app
and how to resolve them.

Signed-off-by: Changchun Ouyang <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
Signed-off-by: John McNamara <john.mcnamara-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
 doc/guides/sample_app_ug/vhost.rst | 58 ++++++++++++++++++++++++++++++++------
 1 file changed, 50 insertions(+), 8 deletions(-)

diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst
index 4a6d434..7e333cf 100644
--- a/doc/guides/sample_app_ug/vhost.rst
+++ b/doc/guides/sample_app_ug/vhost.rst
@@ -1,3 +1,4 @@
+
 ..  BSD LICENSE
     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
     All rights reserved.
@@ -640,19 +641,60 @@ To call the QEMU wrapper automatically from libvirt, the following configuration
 Common Issues
 ~~~~~~~~~~~~~
 
-**QEMU failing to allocate memory on hugetlbfs.**
+*   QEMU failing to allocate memory on hugetlbfs, with an error like the following::
 
-file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
+       file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
 
-When running QEMU the above error implies that it has failed to allocate memory for the Virtual Machine on the hugetlbfs.
-This is typically due to insufficient hugepages being free to support the allocation request.
-The number of free hugepages can be checked as follows:
+    When running QEMU the above error indicates that it has failed to allocate memory for the Virtual Machine on
+    the hugetlbfs. This is typically due to insufficient hugepages being free to support the allocation request.
+    The number of free hugepages can be checked as follows:
 
-.. code-block:: console
+    .. code-block:: console
+
+        cat /sys/kernel/mm/hugepages/hugepages-<pagesize>/nr_hugepages
+
+    The command above indicates how many hugepages are free to support QEMU's allocation request.
+
+*   User space VHOST when the guest has 2MB sized huge pages:
+
+    The guest may have 2MB or 1GB sized huge pages. The user space VHOST should work properly in both cases.
+
+*   User space VHOST will not work with QEMU without the ``-mem-prealloc`` option:
+
+    The current implementation works properly only when the guest memory is pre-allocated, so it is required to
+    use a QEMU version (e.g. 1.6) which supports ``-mem-prealloc``. The ``-mem-prealloc`` option must be
+    specified explicitly in the QEMU command line.
+
+*   User space VHOST will not work with a QEMU version without shared memory mapping:
+
+    As shared memory mapping is mandatory for user space VHOST to work properly with the guest, user space VHOST
+    needs access to the shared memory from the guest to receive and transmit packets. It is important to make sure
+    the QEMU version supports shared memory mapping.
+
+*   Issues with ``virsh destroy`` not destroying the VM:
+
+    Using libvirt ``virsh create`` the ``qemu-wrap.py`` spawns a new process to run ``qemu-kvm``. This impacts the behavior
+    of ``virsh destroy`` which kills the process running ``qemu-wrap.py`` without actually destroying the VM (it leaves
+    the ``qemu-kvm`` process running):
+
+    This following patch should fix this issue:
+        http://dpdk.org/ml/archives/dev/2014-June/003607.html
+
+*   In an Ubuntu environment, QEMU fails to start a new guest normally with user space VHOST due to not being able
+    to allocate huge pages for the new guest:
+
+    The solution for this issue is to add ``-boot c`` into the QEMU command line to make sure the huge pages are
+    allocated properly and then the guest should start normally.
+
+    Use ``cat /proc/meminfo`` to check if there is any changes in the value of ``HugePages_Total`` and ``HugePages_Free``
+    after the guest startup.
+
+*   Log message: ``eventfd_link: module verification failed: signature and/or required key missing - tainting kernel``:
 
-    user@target:cat /sys/kernel/mm/hugepages/hugepages-<pagesize> / nr_hugepages
+    This log message may be ignored. The message occurs due to the kernel module ``eventfd_link``, which is not a standard
+    Linux module but which is necessary for the user space VHOST current implementation (CUSE-based) to communicate with
+    the guest.
 
-The command above indicates how many hugepages are free to support QEMU's allocation request.
 
 Running DPDK in the Virtual Machine
 -----------------------------------
-- 
V4: Fixed typos and syntax.
V3: Fixed indentation issue that prevented PDFs from building.


1.8.1.4

Re: [PATCH v4] doc: Update doc for vhost sample

[Butler, Siobhan A]

> From: dev [mailto:dev-bounces-VfR2kkLFssw@public.gmane.org] On Behalf Of John McNamara
> Sent: Friday, March 27, 2015 1:20 PM
> To: dev-VfR2kkLFssw@public.gmane.org
> Subject: [dpdk-dev] [PATCH v4] doc: Update doc for vhost sample
> 
> From: Ouyang Changchun <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> 
> Added some documentation on common issues for the vhost sample app
> and how to resolve them.
> 
> Signed-off-by: Changchun Ouyang <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> Signed-off-by: John McNamara <john.mcnamara-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> ---
>  doc/guides/sample_app_ug/vhost.rst | 58
> ++++++++++++++++++++++++++++++++------
>  1 file changed, 50 insertions(+), 8 deletions(-)
> 
> diff --git a/doc/guides/sample_app_ug/vhost.rst
> b/doc/guides/sample_app_ug/vhost.rst
> index 4a6d434..7e333cf 100644
> --- a/doc/guides/sample_app_ug/vhost.rst
> +++ b/doc/guides/sample_app_ug/vhost.rst
> @@ -1,3 +1,4 @@
> +
>  ..  BSD LICENSE
>      Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
>      All rights reserved.
> @@ -640,19 +641,60 @@ To call the QEMU wrapper automatically from
> libvirt, the following configuration  Common Issues  ~~~~~~~~~~~~~
> 
> -**QEMU failing to allocate memory on hugetlbfs.**
> +*   QEMU failing to allocate memory on hugetlbfs, with an error like the
> following::
> 
> -file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
> +       file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
> 
> -When running QEMU the above error implies that it has failed to allocate
> memory for the Virtual Machine on the hugetlbfs.
> -This is typically due to insufficient hugepages being free to support the
> allocation request.
> -The number of free hugepages can be checked as follows:
> +    When running QEMU the above error indicates that it has failed to
> allocate memory for the Virtual Machine on
> +    the hugetlbfs. This is typically due to insufficient hugepages being free to
> support the allocation request.
> +    The number of free hugepages can be checked as follows:
> 
> -.. code-block:: console
> +    .. code-block:: console
> +
> +        cat /sys/kernel/mm/hugepages/hugepages-<pagesize>/nr_hugepages
> +
> +    The command above indicates how many hugepages are free to support
> QEMU's allocation request.
> +
> +*   User space VHOST when the guest has 2MB sized huge pages:
> +
> +    The guest may have 2MB or 1GB sized huge pages. The user space VHOST
> should work properly in both cases.
> +
> +*   User space VHOST will not work with QEMU without the ``-mem-
> prealloc`` option:
> +
> +    The current implementation works properly only when the guest memory
> is pre-allocated, so it is required to
> +    use a QEMU version (e.g. 1.6) which supports ``-mem-prealloc``. The ``-
> mem-prealloc`` option must be
> +    specified explicitly in the QEMU command line.
> +
> +*   User space VHOST will not work with a QEMU version without shared
> memory mapping:
> +
> +    As shared memory mapping is mandatory for user space VHOST to work
> properly with the guest, user space VHOST
> +    needs access to the shared memory from the guest to receive and
> transmit packets. It is important to make sure
> +    the QEMU version supports shared memory mapping.
> +
> +*   Issues with ``virsh destroy`` not destroying the VM:
> +
> +    Using libvirt ``virsh create`` the ``qemu-wrap.py`` spawns a new process to
> run ``qemu-kvm``. This impacts the behavior
> +    of ``virsh destroy`` which kills the process running ``qemu-wrap.py``
> without actually destroying the VM (it leaves
> +    the ``qemu-kvm`` process running):
> +
> +    This following patch should fix this issue:
> +        http://dpdk.org/ml/archives/dev/2014-June/003607.html
> +
> +*   In an Ubuntu environment, QEMU fails to start a new guest normally
> with user space VHOST due to not being able
> +    to allocate huge pages for the new guest:
> +
> +    The solution for this issue is to add ``-boot c`` into the QEMU command
> line to make sure the huge pages are
> +    allocated properly and then the guest should start normally.
> +
> +    Use ``cat /proc/meminfo`` to check if there is any changes in the value of
> ``HugePages_Total`` and ``HugePages_Free``
> +    after the guest startup.
> +
> +*   Log message: ``eventfd_link: module verification failed: signature and/or
> required key missing - tainting kernel``:
> 
> -    user@target:cat /sys/kernel/mm/hugepages/hugepages-<pagesize> /
> nr_hugepages
> +    This log message may be ignored. The message occurs due to the kernel
> module ``eventfd_link``, which is not a standard
> +    Linux module but which is necessary for the user space VHOST current
> implementation (CUSE-based) to communicate with
> +    the guest.
> 
> -The command above indicates how many hugepages are free to support
> QEMU's allocation request.
> 
>  Running DPDK in the Virtual Machine
>  -----------------------------------
> --
> V4: Fixed typos and syntax.
> V3: Fixed indentation issue that prevented PDFs from building.
> 
> 
> 1.8.1.4

Acked-by Siobhan Butler <siobhan.a.butler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

Re: [PATCH v4] doc: Update doc for vhost sample

[Thomas Monjalon]

> > From: Ouyang Changchun <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> > 
> > Added some documentation on common issues for the vhost sample app
> > and how to resolve them.
> > 
> > Signed-off-by: Changchun Ouyang <changchun.ouyang-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> > Signed-off-by: John McNamara <john.mcnamara-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> 
> Acked-by Siobhan Butler <siobhan.a.butler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

Applied, thanks