From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 9CD39A04B7; Tue, 13 Oct 2020 13:05:38 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id BD5AC1DAB5; Tue, 13 Oct 2020 13:04:54 +0200 (CEST) Received: from mga05.intel.com (mga05.intel.com [192.55.52.43]) by dpdk.org (Postfix) with ESMTP id 81EC51DA6F for ; Tue, 13 Oct 2020 13:04:50 +0200 (CEST) IronPort-SDR: iyy5ux3w8GBamnvvGfbcb08W47sV6q9Kc3jUqJ5eGPstl1XHkvBTSDLzPjYgDITBcjTup8l9EO rcRg6EVNu1mw== X-IronPort-AV: E=McAfee;i="6000,8403,9772"; a="250584564" X-IronPort-AV: E=Sophos;i="5.77,370,1596524400"; d="scan'208";a="250584564" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga007.fm.intel.com ([10.253.24.52]) by fmsmga105.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 13 Oct 2020 04:04:49 -0700 IronPort-SDR: g1wN0QWWHb0CGUQ5iaWQ8aiFo3gUnMF7dclYXRgXmgc93Z4kA2QUXevtyupx+jkSh/zNe58W5H yUjGNllJmmTA== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.77,370,1596524400"; d="scan'208";a="299525058" Received: from silpixa00400355.ir.intel.com (HELO silpixa00400355.ger.corp.intel.com) ([10.237.222.239]) by fmsmga007.fm.intel.com with ESMTP; 13 Oct 2020 04:04:46 -0700 From: Ciara Power 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 , Anatoly Burakov , John McNamara , Marko Kovacevic Date: Tue, 13 Oct 2020 12:04:22 +0100 Message-Id: <20201013110437.309110-3-ciara.power@intel.com> X-Mailer: git-send-email 2.22.0 In-Reply-To: <20201013110437.309110-1-ciara.power@intel.com> References: <20200807155859.63888-1-ciara.power@intel.com> <20201013110437.309110-1-ciara.power@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v5 02/17] 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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 Cc: John McNamara Cc: Marko Kovacevic Signed-off-by: Ciara Power --- 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=``: + + 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, + }; + + 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