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

[Stokes, Ian]

> 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.
>

Thanks for the patch Amber/Harry/Cian.

Comments inline below.

Also is there a patch to update the OVS manpages for these commands also? Possibly later in the series?
 
> Signed-off-by: Kumar Amber <kumar.amber at intel.com>
> Co-authored-by: Cian Ferriter <cian.ferriter at intel.com>
> Signed-off-by: Cian Ferriter <cian.ferriter at intel.com>
> Co-authored-by: Harry van Haaren <harry.van.haaren at intel.com>
> Signed-off-by: Harry van Haaren <harry.van.haaren at intel.com>
> ---
>  Documentation/topics/dpdk/bridge.rst | 105 +++++++++++++++++++++++++++
>  NEWS                                 |   3 +
>  2 files changed, 108 insertions(+)
> 
> diff --git a/Documentation/topics/dpdk/bridge.rst
> b/Documentation/topics/dpdk/bridge.rst
> index f59e26cbe..b262b98f8 100644
> --- a/Documentation/topics/dpdk/bridge.rst
> +++ b/Documentation/topics/dpdk/bridge.rst
> @@ -256,3 +256,108 @@ The following line should be seen in the configure
> output when the above option
>  is used ::
> 
>      checking whether DPIF AVX512 is default implementation... yes
> +
> +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

Typo above "available implementations"
> +miniflow extract and than chooses the one with most optimal result for that
Would change than->then above
> +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
> +implementaions.
> +
> +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 bc1db7948..63a485309 100644
> --- a/NEWS
> +++ b/NEWS
> @@ -21,6 +21,9 @@ Post-v2.15.0
>       * Enable the AVX512 DPCLS implementation to use VPOPCNT instruction if
> the
>         CPU supports it. This enhances performance by using the native vpopcount
>         instructions, instead of the emulated version of vpopcount.
> +     * 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.
No need for the last line above I would think. Users will naturally look to documentation for features  info in general.

BR
Ian
>     - ovs-ctl:
>       * New option '--no-record-hostname' to disable hostname configuration
>         in ovsdb on startup.
> --
> 2.25.1
> 
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev