From 8e700f55d356a701a17ccabbdd1b1b9e8468342c Mon Sep 17 00:00:00 2001
From: "Konstantin Volenbovskyi (kvolenbo)" <kvolenbo@cisco.com>
Date: Mon, 15 May 2017 16:21:57 +0200
Subject: [PATCH] OVS-DPDK integration documentation changed

Networking guide is changed to reference Neutron configuration
for OVS-DPDK and configuration for multiqueue virtio-net

Change-Id: I9da533266ab383ea6bdcf5be15625f73544e257d
Closes-Bug: 1689508
---
 .../source/config-ovs-dpdk.rst                | 87 +++++++++++++++++--
 1 file changed, 79 insertions(+), 8 deletions(-)

diff --git a/doc/networking-guide/source/config-ovs-dpdk.rst b/doc/networking-guide/source/config-ovs-dpdk.rst
index ec0e445e8d..cd61fc507f 100644
--- a/doc/networking-guide/source/config-ovs-dpdk.rst
+++ b/doc/networking-guide/source/config-ovs-dpdk.rst
@@ -30,7 +30,9 @@ Using DPDK in OVS requires the following minimum software versions:
 * QEMU 2.1.0
 * libvirt 1.2.13
 
-Multiqueue support is available if the following newer versions are used:
+Support of ``vhost-user`` multiqueue that enables use of multiqueue with
+``virtio-net`` and ``igb_uio`` is available if the following newer
+versions are used:
 
 * OVS 2.5
 * DPDK 2.2
@@ -39,15 +41,44 @@ Multiqueue support is available if the following newer versions are used:
 
 In both cases, install and configure Open vSwitch with DPDK support for each
 node. For more information, see the
-`OVS-DPDK <https://github.com/openvswitch/ovs/blob/v2.5.0/INSTALL.DPDK.md>`__
-installation guide.
+`OVS-DPDK <https://github.com/openvswitch/ovs/blob/master/Documentation/intro/install/dpdk.rst>`__
+installation guide (select an appropriate OVS version in the
+:guilabel:`Branch` drop-down menu).
+
+`Neutron configuration reference for OVS-DPDK
+<https://docs.openstack.org/developer/neutron/devref/ovs_vhostuser.html>`__
+for configuration of neutron OVS agent.
+
+In case you wish to configure multiqueue, see the
+`OVS configuration chapter on vhost-user
+<http://wiki.qemu.org/Documentation/vhost-user-ovs-dpdk#Enabling_multi-queue>`__
+in QEMU documentation.
+
+The technical background of multiqueue is explained in the corresponding
+`blueprint <https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/libvirt-virtiomq.html>`__.
+
+Additionally, OpenStack supports ``vhost-user`` reconnect feature starting
+from the Ocata release, as implementation of fix for
+`bug 1604924 <https://bugs.launchpad.net/neutron/+bug/1604924>`__.
+Starting from OpenStack Ocata release this feature is used without any
+configuration necessary in case the following minimum software versions
+are used:
+
+* OVS 2.6
+* DPDK 16.07
+* QEMU 2.7
+
+The support of this feature is not yet present in ML2 OVN and ODL
+mechanism drivers.
 
 Using vhost-user interfaces
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Once OVS is correctly configured with DPDK support, ``vhost-user`` interfaces
-are completely transparent to the guest. However, guests must request large
-pages. This can be done through flavors. For example:
+Once OVS and neutron are correctly configured with DPDK support,
+``vhost-user`` interfaces are completely transparent to the guest
+(except in case of multiqueue configuration described below).
+However, guests must request huge pages. This can be done through flavors.
+For example:
 
 .. code-block:: console
 
@@ -72,13 +103,53 @@ fashion as conventional interfaces. These interfaces can use the kernel
 
    $ openstack server create --nic net-id=$net_id ... testserver
 
+Using vhost-user multiqueue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use this feature, the following should be set in the flavor extra specs
+(flavor keys):
+
+.. code-block:: console
+
+   $ openstack flavor set $m1.large --property hw:vif_multiqueue_enabled=true
+
+This setting can be overridden by the image metadata property if the feature
+is enabled in the extra specs:
+
+.. code-block:: console
+
+   $ openstack image set --property hw_vif_mutliqueue_enabled=true IMAGE_NAME
+
+Support of ``virtio-net`` multiqueue needs to be present in kernel of
+guest VM and is available starting from Linux kernel 3.8.
+
+Check pre-set maximum for number of combined channels in channel
+configuration.
+Configuration of OVS and flavor done successfully should result in
+maximum being more than '1'):
+
+.. code-block:: console
+
+  $ ethtool -l INTERFACE_NAME
+
+To increase number of current combined channels run following command in
+guest VM:
+
+.. code-block:: console
+
+  $ ethtool -L INTERFACE_NAME combined QUEUES_NR
+
+The number of queues should typically match the number of vCPUs
+defined for the instance. In newer kernel versions
+this is configured automatically.
+
 Known limitations
 ~~~~~~~~~~~~~~~~~
 
 * This feature is only supported when using the libvirt compute driver, and the
   KVM/QEMU hypervisor.
-* Large pages are required for each instance running on hosts with OVS-DPDK.
-  If large pages are not present in the guest, the interface will appear but
+* Huge pages are required for each instance running on hosts with OVS-DPDK.
+  If huge pages are not present in the guest, the interface will appear but
   will not function.
 * Expect performance degradation of services using tap devices: these devices
   do not support DPDK. Example services include DVR, FWaaS, or LBaaS.