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

From: Kumar Amber <kumar.amber@intel.com>

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>

---

v5:
- fix review comments(Ian, Flavio, Eelco)
---
---
 Documentation/topics/dpdk/bridge.rst | 49 ++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

On 6 Jul 2021, at 15:11, Cian Ferriter wrote:

> From: Kumar Amber <kumar.amber@intel.com>
>
> 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>
>
> ---
>
> v5:
> - fix review comments(Ian, Flavio, Eelco)
> ---
> ---
>  Documentation/topics/dpdk/bridge.rst | 49 ++++++++++++++++++++++++++++
>  1 file changed, 49 insertions(+)
>
> diff --git a/Documentation/topics/dpdk/bridge.rst b/Documentation/topics/dpdk/bridge.rst
> index 2d0850836..2901e8096 100644
> --- a/Documentation/topics/dpdk/bridge.rst
> +++ b/Documentation/topics/dpdk/bridge.rst
> @@ -256,3 +256,52 @@ 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.

I think this text should also explain why we have different miniflow extract functions, i.e. that a miniflow extract is traffic specific to speed up the lookup, whereas the scalar works for ALL traffic patterns.

> +
> +Most modern CPUs 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:

Not sure how it will look in v7, but the actual output on v6 shows:

$ ovs-appctl dpif-netdev/miniflow-parser-get
Available MFEX implementations:
  autovalidator (available: True, pmds: none)
  scalar (available: True, pmds: 1,15)
  study (available: True, pmds: none)


> +            autovalidator (available: True)(pmds: none)
> +            scalar (available: True)(pmds: 3)
> +            study (available: True)(pmds: none)
> +
> +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 available 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
> -- 
> 2.32.0