> -----Original Message----- > From: Ciara Power <[email protected]> > Sent: Tuesday, October 13, 2020 7:04 PM > To: [email protected] > Cc: [email protected]; Ruifeng Wang <[email protected]>; > [email protected]; [email protected]; [email protected]; > [email protected]; Ciara Power <[email protected]>; > Anatoly Burakov <[email protected]>; John McNamara > <[email protected]>; Marko Kovacevic > <[email protected]> > 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 <[email protected]> > Cc: John McNamara <[email protected]> > Cc: Marko Kovacevic <[email protected]> > > Signed-off-by: Ciara Power <[email protected]> > > --- > 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
