diff mbox series

[v8,02/18] doc: add detail on using max SIMD bitwidth

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


Context Check Description
ci/checkpatch success coding style OK

Commit Message

Power, Ciara Oct. 16, 2020, 8:13 a.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>
Acked-by: Kevin Laatz <kevin.laatz@intel.com>

v6: Updated enum value.
v4: Updated docs to reflect renamed enum.
  - 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 mbox series


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
+    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..90e43d2c1f 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 = INT16_MAX + 1,
+   };
+    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)