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.bura...@intel.com>
Cc: John McNamara <john.mcnam...@intel.com>
Cc: Marko Kovacevic <marko.kovace...@intel.com>
Signed-off-by: Ciara Power <ciara.po...@intel.com>
Acked-by: Kevin Laatz <kevin.la...@intel.com>
---
v6: Updated enum value.
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..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)
------------------------------------------
--
2.22.0
