[v3,03/18] doc: add detail on using max SIMD bitwidth

Message ID 20200930130415.11211-4-ciara.power@intel.com (mailing list archive)
State Superseded, archived
Delegated to: David Marchand
Series add max SIMD bitwidth to EAL |


Context Check Description
ci/checkpatch success coding style OK

Commit Message

Power, Ciara Sept. 30, 2020, 1:03 p.m. UTC
  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>

  - 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..ebae0f2b4f
--- /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_MAX_512_SIMD);
+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
+    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 f64ae953d1..58f591e921 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_t {
+       RTE_NO_SIMD = 64,
+       RTE_MAX_128_SIMD = 128,
+       RTE_MAX_256_SIMD = 256,
+       RTE_MAX_512_SIMD = 512,
+   };
+    if (rte_get_max_simd_bitwidth() >= RTE_MAX_512_SIMD)
+        /* Take AVX-512 vector path */
+    else if (rte_get_max_simd_bitwidth() >= RTE_MAX_256_SIMD)
+        /* Take AVX2 vector path */
 Memory Segments and Memory Zones (memzone)