[v5,02/17] doc: add detail on using max SIMD bitwidth

  This patch adds documentation on the usage of the max SIMD bitwidth EAL
setting, and how to use it to enable AVX-512 at runtime.

Cc: Anatoly Burakov <anatoly.burakov@intel.com>
Cc: John McNamara <john.mcnamara@intel.com>
Cc: Marko Kovacevic <marko.kovacevic@intel.com>

Signed-off-by: Ciara Power <ciara.power@intel.com>

---
v4: Updated docs to reflect renamed enum.
v3:
  - Added enum value for disabling use of max SIMD to doc.
  - Added entry to HowTo index.
---
 doc/guides/howto/avx512.rst                   | 36 +++++++++++++++++++
 doc/guides/howto/index.rst                    |  1 +
 doc/guides/linux_gsg/eal_args.include.rst     | 16 +++++++++
 .../prog_guide/env_abstraction_layer.rst      | 32 +++++++++++++++++
 4 files changed, 85 insertions(+)
 create mode 100644 doc/guides/howto/avx512.rst
  

> -----Original Message-----
> From: Ciara Power <ciara.power@intel.com>
> Sent: Tuesday, October 13, 2020 7:04 PM
> To: dev@dpdk.org
> Cc: viktorin@rehivetech.com; Ruifeng Wang <Ruifeng.Wang@arm.com>;
> jerinj@marvell.com; drc@linux.vnet.ibm.com; bruce.richardson@intel.com;
> konstantin.ananyev@intel.com; Ciara Power <ciara.power@intel.com>;
> Anatoly Burakov <anatoly.burakov@intel.com>; John McNamara
> <john.mcnamara@intel.com>; Marko Kovacevic
> <marko.kovacevic@intel.com>
> Subject: [PATCH v5 02/17] doc: add detail on using max SIMD bitwidth
> 
> This patch adds documentation on the usage of the max SIMD bitwidth EAL
> setting, and how to use it to enable AVX-512 at runtime.
> 
> Cc: Anatoly Burakov <anatoly.burakov@intel.com>
> Cc: John McNamara <john.mcnamara@intel.com>
> Cc: Marko Kovacevic <marko.kovacevic@intel.com>
> 
> Signed-off-by: Ciara Power <ciara.power@intel.com>
> 
> ---
> v4: Updated docs to reflect renamed enum.
> v3:
>   - Added enum value for disabling use of max SIMD to doc.
>   - Added entry to HowTo index.
> ---
>  doc/guides/howto/avx512.rst                   | 36 +++++++++++++++++++
>  doc/guides/howto/index.rst                    |  1 +
>  doc/guides/linux_gsg/eal_args.include.rst     | 16 +++++++++
>  .../prog_guide/env_abstraction_layer.rst      | 32 +++++++++++++++++
>  4 files changed, 85 insertions(+)
>  create mode 100644 doc/guides/howto/avx512.rst
> 
> diff --git a/doc/guides/howto/avx512.rst b/doc/guides/howto/avx512.rst
> new file mode 100644 index 0000000000..6eb3755775
> --- /dev/null
> +++ b/doc/guides/howto/avx512.rst
> @@ -0,0 +1,36 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2020 Intel Corporation.
> +
> +
> +Using AVX-512 with DPDK
> +=======================
> +
> +AVX-512 is not used by default in DPDK, but it can be selected at
> +runtime by apps through the use of EAL API, and by the user with a
> +commandline argument. DPDK has a setting for max SIMD bitwidth, which
> can be modified and will then limit the vector path taken by the code.
> +
> +
> +Using the API in apps
> +---------------------
> +
> +Apps can request DPDK uses AVX-512 at runtime, if it provides improved
> application performance.
> +This can be done by modifying the EAL setting for max SIMD bitwidth to
> +512, as by default it is 256, which does not allow for AVX-512.
> +
> +.. code-block:: c
> +
> +   rte_set_max_simd_bitwidth(RTE_SIMD_512);
> +
> +This API should only be called once at initialization, before EAL init.
> +For more information on the possible enum values to use as a parameter,
> go to :ref:`max_simd_bitwidth`:
> +
> +
> +Using the command-line argument
> +---------------------------------------------
> +
> +The user can select to use AVX-512 at runtime, using the following
> argument to set the max bitwidth::
> +
> +   ./app/dpdk-testpmd --force-max-simd-bitwidth=512
> +
> +This will override any further changes to the max SIMD bitwidth in
> +DPDK, which is useful for testing purposes.
> diff --git a/doc/guides/howto/index.rst b/doc/guides/howto/index.rst index
> 5a97ea508c..c2a2c60ddb 100644
> --- a/doc/guides/howto/index.rst
> +++ b/doc/guides/howto/index.rst
> @@ -20,3 +20,4 @@ HowTo Guides
>      telemetry
>      debug_troubleshoot
>      openwrt
> +    avx512
> diff --git a/doc/guides/linux_gsg/eal_args.include.rst
> b/doc/guides/linux_gsg/eal_args.include.rst
> index 0fe4457968..a0bfbd1a98 100644
> --- a/doc/guides/linux_gsg/eal_args.include.rst
> +++ b/doc/guides/linux_gsg/eal_args.include.rst
> @@ -210,3 +210,19 @@ Other options
>  *    ``--no-telemetry``:
> 
>      Disable telemetry.
> +
> +*    ``--force-max-simd-bitwidth=<val>``:
> +
> +    Specify the maximum SIMD bitwidth size to handle. This limits which
> vector paths,
> +    if any, are taken, as any paths taken must use a bitwidth below the max
> bitwidth limit.
> +    For example, to allow all SIMD bitwidths up to and including AVX-512::
> +
> +        --force-max-simd-bitwidth=512
> +
> +    The following example shows limiting the bitwidth to 64-bits to disable all
> vector code::
> +
> +        --force-max-simd-bitwidth=64
> +
> +    To disable use of max SIMD bitwidth limit::
> +
> +        --force-max-simd-bitwidth=0
> diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst
> b/doc/guides/prog_guide/env_abstraction_layer.rst
> index 936c885081..04bb910386 100644
> --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> @@ -486,6 +486,38 @@ the desired addressing mode when virtual devices
> that are not directly attached  To facilitate forcing the IOVA mode to a specific
> value the EAL command line option ``--iova-mode`` can  be used to select
> either physical addressing('pa') or virtual addressing('va').
> 
> +.. _max_simd_bitwidth:
> +
> +
> +Max SIMD bitwidth
> +~~~~~~~~~~~~~~~~~
> +
> +The EAL provides a single setting to limit the max SIMD bitwidth used
> +by DPDK, which is used in determining the vector path, if any, chosen by a
> component.
> +The value can be set at runtime by an application using the
> +'rte_set_max_simd_bitwidth(uint16_t bitwidth)' function, which should
> only be called once at initialization, before EAL init.
> +The value can be overridden by the user using the EAL command-line
> option '--force-max-simd-bitwidth'.
> +
> +When choosing a vector path, along with checking the CPU feature
> +support, the value of the max SIMD bitwidth must also be checked, and can
> be retrieved using the 'rte_get_max_simd_bitwidth()' function.
> +The value should be compared against the enum values for accepted max
> SIMD bitwidths:
> +
> +.. code-block:: c
> +
> +   enum rte_max_simd {
> +       RTE_SIMD_DISABLED = 64,
> +       RTE_SIMD_128 = 128,
> +       RTE_SIMD_256 = 256,
> +       RTE_SIMD_512 = 512,
> +       RTE_SIMD_MAX = UINT16_MAX,
RTE_SIMD_MAX is inconsistent with patch 1/17. Needs update.

> +   };
> +
> +    if (rte_get_max_simd_bitwidth() >= RTE_SIMD_512)
> +        /* Take AVX-512 vector path */
> +    else if (rte_get_max_simd_bitwidth() >= RTE_SIMD_256)
> +        /* Take AVX2 vector path */
> +
> +
>  Memory Segments and Memory Zones (memzone)
>  ------------------------------------------
> 
> --
> 2.22.0