diff mbox series

[ovs-dev,v3,04/12] docs/dpdk/bridge: add miniflow extract section.

Message ID 20210517135708.685517-5-kumar.amber@intel.com
State Superseded
Headers show
Series MFEX Infrastructure + Optimizations | expand

Commit Message

Kumar Amber May 17, 2021, 1:57 p.m. UTC
This commit adds a section to the dpdk/bridge.rst netdev documentation,
detailing the added miniflow functionality. The newly added commands are
documented, and sample output is provided.

The use of auto-validator and special study function is also described
in detail as well as running fuzzy tests.

Signed-off-by: Kumar Amber <kumar.amber@intel.com>
Co-authored-by: Cian Ferriter <cian.ferriter@intel.com>
Signed-off-by: Cian Ferriter <cian.ferriter@intel.com>
Co-authored-by: Harry van Haaren <harry.van.haaren@intel.com>
Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
 Documentation/topics/dpdk/bridge.rst | 105 +++++++++++++++++++++++++++
 NEWS                                 |   3 +
 2 files changed, 108 insertions(+)
diff mbox series


diff --git a/Documentation/topics/dpdk/bridge.rst b/Documentation/topics/dpdk/bridge.rst
index ca90d7bdb..e71d47d40 100644
--- a/Documentation/topics/dpdk/bridge.rst
+++ b/Documentation/topics/dpdk/bridge.rst
@@ -251,3 +251,108 @@  available in order to test it with the OVS unit test suite. When building with
 a CPU that supports AVX512, use the following configure option ::
     $ ./configure --enable-dpif-default-avx512
+Miniflow Extract
+Miniflow extract (MFEX) performs parsing of the raw packets and extracts the
+important header information into a compressed miniflow. This miniflow is
+composed of bits and blocks where the bits signify which blocks are set or
+have values where as the blocks hold the metadata, ip, udp, vlan, etc. These
+values are used by the datapath for switching decisions later.
+Most modern CPUs are have SIMD capabilities. These SIMD instructions are able
+to process a vector rather than act on one single data. OVS provides multiple
+implementations of miniflow extract. This allows the user to take advantage
+of SIMD instructions like AVX512 to gain additional performance.
+A list of implementations can be obtained by the following command. The
+command also shows whether the CPU supports each implementation ::
+    $ ovs-appctl dpif-netdev/miniflow-parser-get
+        Available Optimized Miniflow Extracts:
+          autovalidator (available: True)
+          disable (available: True)
+          study (available: True)
+          avx512_ip_udp (available: True)
+An implementation can be selected manually by the following command ::
+    $ ovs-appctl dpif-netdev/miniflow-parser-set study
+Also user can select the study implementation which studies the traffic for
+a specific number of packets by applying all availbale implementaions of
+miniflow extract and than chooses the one with most optimal result for that
+traffic pattern.
+Miniflow Extract Validation
+As multiple versions of miniflow extract 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 miniflow implementations, an
+``autovalidator`` implementation of the miniflow exists. This implementation
+runs all other available miniflow extract implementations, and verifies that
+the results are identical.
+Running the OVS unit tests with the autovalidator enabled ensures all
+implementations provide the same results.
+To set the Miniflow autovalidator, use this command ::
+    $ ovs-appctl dpif-netdev/miniflow-parser-set autovalidator
+Unit Test Miniflow Extract
+Unit test can also be used to test the workflow mentioned above by running
+the following test-case in tests/system-dpdk.at ::
+    make check-dpdk TESTSUITEFLAGS=6
+    6: OVS-DPDK - MFEX Autovalidator
+The unit test uses mulitple traffic type to test the correctness of the
+Running Fuzzy test with Autovalidator
+Fuzzy tests can also be done on minfilow extract with the help of
+auto-validator and Scapy. The steps below describes the steps to
+reproduce the setup with IP being fuzzed to generate packets.
+Scapy is used to create fuzzy IP packets and save them into a PCAP ::
+    pkt = fuzz(Ether()/IP()/TCP())
+Set the miniflow extract to autovalidator using ::
+    $ ovs-appctl dpif-netdev/miniflow-parser-set autovalidator
+OVS is configured to receive the generated packets ::
+    $ ovs-vsctl add-port br0 pcap0 -- \
+        set Interface pcap0 type=dpdk options:dpdk-devargs=net_pcap0
+        "rx_pcap=fuzzy.pcap"
+With this workflow, the autovalidator will ensure that all MFEX
+implementations are classifying each packet in exactly the same way.
+If an optimized MFEX implementation causes a different miniflow to be
+generated, the autovalidator has ovs_assert and logging statements that
+will inform about the issue.
+Unit Fuzzy test with Autovalidator
+The prerquiste before running the unit test is to run the script provided ::
+    tests/pcap/fuzzy.py
+This script generates a pcap with mulitple type of fuzzed packets to be used
+in the below unit test-case.
+Unit test can also be used to test the workflow mentioned above by running
+the following test-case in tests/system-dpdk.at ::
+    make check-dpdk TESTSUITEFLAGS=7
+    7: OVS-DPDK - MFEX Autovalidator Fuzzy
diff --git a/NEWS b/NEWS
index 5a4a2a811..69091979a 100644
--- a/NEWS
+++ b/NEWS
@@ -18,6 +18,9 @@  Post-v2.15.0
      * Optimize dp_netdev_output by enhancing compiler optimization potential.
      * Optimize netdev sending by assuming the happy case, and using fallback
        for if the netdev doesnt meet the required HWOL needs of a packet.
+     * An optimized miniflow extract (mfex) implementation is now available,
+       which uses CPU SIMD ISA to parse specific traffic profiles efficiently.
+       Refer to the documentation for details on how to enable it at runtime.
    - ovs-ctl:
      * New option '--no-record-hostname' to disable hostname configuration
        in ovsdb on startup.