docs/dpdk/bridge: add datapath performance section.

This commit adds a section to the dpdk/bridge.rst netdev documentation,
detailing the added DPCLS functionality. The newly added commands are
documented, and sample output is provided.

Running the DPCLS autovalidator with unit tests by default is possible
through re-compiling the autovalidator to have the highest priority at
startup time. This avoids making changes to all tests, and enables
debug and CI builds to validate every lookup implementation with all
unit tests.

Add NEWS updates for CPU ISA, dynamic subtables, and AVX512 lookup.

Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
Acked-by: William Tu <u9012063@gmail.com>
Signed-off-by: Ian Stokes <ian.stokes@intel.com>

3 files changed, 110 insertions, 0 deletions

diff --git a/Documentation/intro/install/dpdk.rst b/Documentation/intro/install/dpdk.rst
index dbf88ec43..4d858304c 100644
--- a/Documentation/intro/install/dpdk.rst
+++ b/Documentation/intro/install/dpdk.rst
@@ -136,6 +136,16 @@ has to be configured to build against the DPDK library (``--with-dpdk``).
      While ``--with-dpdk`` is required, you can pass any other configuration
      option described in :ref:`general-configuring`.
 
+   It is strongly recommended to build OVS with at least ``-msse4.2`` and
+   ``-mpopcnt`` optimization flags. If these flags are not enabled, the AVX512
+   optimized DPCLS implementation is not available in the resulting binary.
+   For technical details see the subtable registration code in the
+   ``lib/dpif-netdev-lookup.c`` file.
+
+   An example that enables the AVX512 optimizations is::
+
+       $ ./configure --with-dpdk=$DPDK_BUILD CFLAGS="-Ofast -msse4.2 -mpopcnt"
+
 #. Build and install OVS, as described in :ref:`general-building`
 
 Additional information can be found in :doc:`general`.
@@ -147,6 +157,26 @@ Additional information can be found in :doc:`general`.
 
 __ https://github.com/openvswitch/ovs/blob/master/rhel/README.RHEL.rst
 
+
+Possible issues when enabling AVX512
+++++++++++++++++++++++++++++++++++++
+
+The enabling of ISA optimized builds requires build-system support.
+Certain versions of the assembler provided by binutils is known to have
+AVX512 assembling issues. The binutils versions affected are 2.30 and 2.31.
+As many distros backport fixes to previous versions of a package, checking
+the version output of ``as -v`` can err on the side of disabling AVX512. To
+remedy this, the OVS build system uses a build-time check to see if ``as``
+will correctly assemble the AVX512 code. The output of a good version when
+running the ``./configure`` step of the build process is as follows::
+
+   $ checking binutils avx512 assembler checks passing... yes
+
+If a bug is detected in the binutils assembler, it would indicate ``no``.
+Build an updated binutils, or request a backport of this binutils
+fix commit ``2069ccaf8dc28ea699bd901fdd35d90613e4402a`` to fix the issue.
+
+
 Setup
 -----
 
diff --git a/Documentation/topics/dpdk/bridge.rst b/Documentation/topics/dpdk/bridge.rst
index f0ef42ecc..526d5c959 100644
--- a/Documentation/topics/dpdk/bridge.rst
+++ b/Documentation/topics/dpdk/bridge.rst
@@ -137,3 +137,80 @@ currently turned off by default.
 To turn on SMC::
 
     $ ovs-vsctl --no-wait set Open_vSwitch . other_config:smc-enable=true
+
+Datapath Classifier Performance
+-------------------------------
+
+The datapath classifier (dpcls) performs wildcard rule matching, a compute
+intensive process of matching a packet ``miniflow`` to a rule ``miniflow``. The
+code that does this compute work impacts datapath performance, and optimizing
+it can provide higher switching performance.
+
+Modern CPUs provide extensive SIMD instructions which can be used to get higher
+performance. The CPU OVS is being deployed on must be capable of running these
+SIMD instructions in order to take advantage of the performance benefits.
+In OVS v2.14 runtime CPU detection was introduced to enable identifying if
+these CPU ISA additions are available, and to allow the user to enable them.
+
+OVS provides multiple implementations of dpcls. The following command enables
+the user to check what implementations are available in a running instance ::
+
+    $ ovs-appctl dpif-netdev/subtable-lookup-prio-get
+    Available lookup functions (priority : name)
+            0 : autovalidator
+            1 : generic
+            0 : avx512_gather
+
+To set the priority of a lookup function, run the ``prio-set`` command ::
+
+    $ ovs-appctl dpif-netdev/subtable-lookup-prio-set avx512_gather 5
+    Lookup priority change affected 1 dpcls ports and 1 subtables.
+
+The highest priority lookup function is used for classification, and the output
+above indicates that one subtable of one DPCLS port is has changed its lookup
+function due to the command being run. To verify the prioritization, re-run the
+get command, note the updated priority of the ``avx512_gather`` function ::
+
+    $ ovs-appctl dpif-netdev/subtable-lookup-prio-get
+    Available lookup functions (priority : name)
+            0 : autovalidator
+            1 : generic
+            5 : avx512_gather
+
+If two lookup functions have the same priority, the first one in the list is
+chosen, and the 2nd occurance of that priority is not used. Put in logical
+terms, a subtable is chosen if its priority is greater than the previous
+best candidate.
+
+CPU ISA Testing and Validation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As multiple versions of DPCLS can co-exist, each with different CPU ISA
+optimizations, it is important to validate that they all give the exact same
+results. To easily test all DPCLS implementations, an ``autovalidator``
+implementation of the DPCLS exists. This implementation runs all other
+available DPCLS implementations, and verifies that the results are identical.
+
+Running the OVS unit tests with the autovalidator enabled ensures all
+implementations provide the same results. Note that the performance of the
+autovalidator is lower than all other implementations, as it tests the scalar
+implementation against itself, and against all other enabled DPCLS
+implementations.
+
+To adjust the DPCLS autovalidator priority, use this command ::
+
+    $ ovs-appctl dpif-netdev/subtable-lookup-prio-set autovalidator 7
+
+Running Unit Tests with Autovalidator
++++++++++++++++++++++++++++++++++++++
+
+To run the OVS unit test suite with the DPCLS autovalidator as the default
+implementation, it is required to recompile OVS. During the recompilation,
+the default priority of the `autovalidator` implementation is set to the
+maximum priority, ensuring every test will be run with every lookup
+implementation ::
+
+    $ ./configure --enable-autovalidator
+
+Compile OVS in debug mode to have `ovs_assert` statements error out if
+there is a mis-match in the DPCLS lookup implementation.
diff --git a/NEWS b/NEWS
index e52e862e1..a88fc5462 100644
--- a/NEWS
+++ b/NEWS
@@ -26,6 +26,9 @@ Post-v2.13.0
      * New configuration knob 'other_config:lb-output-action' for bond ports
        that enables new datapath action 'lb_output' to avoid recirculation
        in balance-tcp mode.  Disabled by default.
+     * Add runtime CPU ISA detection to allow optimized ISA functions
+     * Add support for dynamically changing DPCLS subtable lookup functions
+     * Add ISA optimized DPCLS lookup function using AVX512
    - Tunnels: TC Flower offload
      * Tunnel Local endpoint address masked match are supported.
      * Tunnel Romte endpoint address masked match are supported.