From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from dpdk.org (dpdk.org [92.243.14.124])
by inbox.dpdk.org (Postfix) with ESMTP id 01146A04DB;
Thu, 15 Oct 2020 12:39:06 +0200 (CEST)
Received: from [92.243.14.124] (localhost [127.0.0.1])
by dpdk.org (Postfix) with ESMTP id 499E11DEB3;
Thu, 15 Oct 2020 12:38:28 +0200 (CEST)
Received: from mga06.intel.com (mga06.intel.com [134.134.136.31])
by dpdk.org (Postfix) with ESMTP id 1B7881DE8A
for <dev@dpdk.org>; Thu, 15 Oct 2020 12:38:26 +0200 (CEST)
IronPort-SDR: V4RU2UsRZptqOJSfG/rgUpOF04o/gx8nY/uuR3xfexU9CdZTKOv1/b9yknDVm19474cuVGpn6n
jAu7/2X3/Fmg==
X-IronPort-AV: E=McAfee;i="6000,8403,9774"; a="227964234"
X-IronPort-AV: E=Sophos;i="5.77,378,1596524400"; d="scan'208";a="227964234"
X-Amp-Result: SKIPPED(no attachment in message)
X-Amp-File-Uploaded: False
Received: from fmsmga006.fm.intel.com ([10.253.24.20])
by orsmga104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
15 Oct 2020 03:38:25 -0700
IronPort-SDR: U6oJBa1K9UjuKxBbPtbH+dq3sTqEIzCBzv2l2xR6Y+hkPtCVOZSaQNuMlzXjszTlJjulUHWR2H
qPFa87k6chzQ==
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.77,378,1596524400"; d="scan'208";a="520728502"
Received: from silpixa00400355.ir.intel.com (HELO
silpixa00400355.ger.corp.intel.com) ([10.237.222.239])
by fmsmga006.fm.intel.com with ESMTP; 15 Oct 2020 03:38:22 -0700
From: Ciara Power <ciara.power@intel.com>
To: dev@dpdk.org
Cc: viktorin@rehivetech.com, 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>
Date: Thu, 15 Oct 2020 11:37:58 +0100
Message-Id: <20201015103814.253636-3-ciara.power@intel.com>
X-Mailer: git-send-email 2.22.0
In-Reply-To: <20201015103814.253636-1-ciara.power@intel.com>
References: <20200807155859.63888-1-ciara.power@intel.com>
<20201015103814.253636-1-ciara.power@intel.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Subject: [dpdk-dev] [PATCH v6 02/18] doc: add detail on using max SIMD
bitwidth
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>
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>
---
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