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 2AAA9A04B3; Tue, 28 Jan 2020 04:20:50 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 7F9751C06B; Tue, 28 Jan 2020 04:19:51 +0100 (CET) Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) by dpdk.org (Postfix) with ESMTP id 12B161C00E for ; Tue, 28 Jan 2020 04:19:44 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by fmsmga101.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 27 Jan 2020 19:19:44 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.70,372,1574150400"; d="scan'208";a="307809658" Received: from msmoczyx-mobl.ger.corp.intel.com ([10.104.121.42]) by fmsmga001.fm.intel.com with ESMTP; 27 Jan 2020 19:19:42 -0800 From: Marcin Smoczynski To: akhil.goyal@nxp.com, konstantin.ananyev@intel.com, roy.fan.zhang@intel.com, declan.doherty@intel.com, radu.nicolau@intel.com, pablo.de.lara.guarch@intel.com Cc: dev@dpdk.org, Marcin Smoczynski Date: Tue, 28 Jan 2020 04:16:42 +0100 Message-Id: <20200128031642.15256-9-marcinx.smoczynski@intel.com> X-Mailer: git-send-email 2.21.0.windows.1 In-Reply-To: <20200128031642.15256-1-marcinx.smoczynski@intel.com> References: <20200115182832.17012-1-marcinx.smoczynski@intel.com> <20200128031642.15256-1-marcinx.smoczynski@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v4 8/8] doc: add cpu crypto related documentation 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" Update documentation with a description of cpu crypto in cryptodev, ipsec and security libraries. Add release notes for 20.02. Signed-off-by: Marcin Smoczynski --- doc/guides/cryptodevs/aesni_gcm.rst | 5 ++++ doc/guides/prog_guide/cryptodev_lib.rst | 31 +++++++++++++++++++++++++ doc/guides/prog_guide/ipsec_lib.rst | 8 +++++++ doc/guides/prog_guide/rte_security.rst | 15 ++++++++---- doc/guides/rel_notes/release_20_02.rst | 8 +++++++ 5 files changed, 63 insertions(+), 4 deletions(-) diff --git a/doc/guides/cryptodevs/aesni_gcm.rst b/doc/guides/cryptodevs/aesni_gcm.rst index 151aa3060..6b1a3d2a0 100644 --- a/doc/guides/cryptodevs/aesni_gcm.rst +++ b/doc/guides/cryptodevs/aesni_gcm.rst @@ -9,6 +9,11 @@ The AES-NI GCM PMD (**librte_pmd_aesni_gcm**) provides poll mode crypto driver support for utilizing Intel multi buffer library (see AES-NI Multi-buffer PMD documentation to learn more about it, including installation). +The AES-NI GCM PMD supports synchronous mode of operation with +``rte_cryptodev_sym_cpu_crypto_process`` function call for both AES-GCM and +GMAC, however GMAC support is limited to one segment per operation. Please +refer to ``rte_crypto`` programmer's guide for more detail. + Features -------- diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst index ac1643774..1a01e1bda 100644 --- a/doc/guides/prog_guide/cryptodev_lib.rst +++ b/doc/guides/prog_guide/cryptodev_lib.rst @@ -600,6 +600,37 @@ chain. }; }; +Synchronous mode +---------------- + +Some cryptodevs support synchronous mode alongside with a standard asynchronous +mode. In that case operations are performed directly when calling +``rte_cryptodev_sym_cpu_crypto_process`` method instead of enqueuing and +dequeuing an operation before. This mode of operation allows cryptodevs which +utilize CPU cryptographic acceleration to have significant performance boost +comparing to standard asynchronous approach. Cryptodevs supporting synchronous +mode have ``RTE_CRYPTODEV_FF_SYM_CPU_CRYPTO`` feature flag set. + +To perform a synchronous operation a call to +``rte_cryptodev_sym_cpu_crypto_process`` has to be made with vectorized +operation descriptor (``struct rte_crypto_sym_vec``) containing: + +- ``num`` - number of operations to perform, +- pointer to an array of size ``num`` containing a scatter-gather list + descriptors of performed operations (``struct rte_crypto_sgl``). Each instance + of ``struct rte_crypto_sgl`` consists of a number of segments and a pointer to + an array of segment descriptors ``struct rte_crypto_vec``; +- pointers to arrays of size ``num`` containing IV, AAD and digest information, +- pointer to an array of size ``num`` where status information will be stored + for each operation. + +Function returns a number of successfully completed operations and sets +appropriate status number for each operation in the status array provided as +a call argument. Status different than zero must be treated as error. + +For more details, e.g. how to convert an mbuf to an SGL, please refer to an +example usage in the IPsec library implementation. + Sample code ----------- diff --git a/doc/guides/prog_guide/ipsec_lib.rst b/doc/guides/prog_guide/ipsec_lib.rst index 1ce0db453..e6a21fae6 100644 --- a/doc/guides/prog_guide/ipsec_lib.rst +++ b/doc/guides/prog_guide/ipsec_lib.rst @@ -81,6 +81,14 @@ In that mode the library functions perform - verify that crypto device operations (encryption, ICV generation) were completed successfully +RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In that mode the library functions perform same operations as in +``RTE_SECURITY_ACTION_TYPE_NONE``. The only differnce is that crypto operations +are performed with CPU crypto synchronous API. + + RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/prog_guide/rte_security.rst b/doc/guides/prog_guide/rte_security.rst index f77fb89dc..a911c676b 100644 --- a/doc/guides/prog_guide/rte_security.rst +++ b/doc/guides/prog_guide/rte_security.rst @@ -511,13 +511,20 @@ Offload. /**< No security actions */ RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO, /**< Crypto processing for security protocol is processed inline - * during transmission */ + * during transmission + */ RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL, /**< All security protocol processing is performed inline during - * transmission */ - RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL + * transmission + */ + RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL, /**< All security protocol processing including crypto is performed - * on a lookaside accelerator */ + * on a lookaside accelerator + */ + RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO + /**< Crypto processing for security protocol is processed by CPU + * synchronously + */ }; The ``rte_security_session_protocol`` is defined as diff --git a/doc/guides/rel_notes/release_20_02.rst b/doc/guides/rel_notes/release_20_02.rst index 50e2c1484..b6cf0c4d1 100644 --- a/doc/guides/rel_notes/release_20_02.rst +++ b/doc/guides/rel_notes/release_20_02.rst @@ -143,6 +143,14 @@ New Features Added a new OCTEON TX2 rawdev PMD for End Point mode of operation. See the :doc:`../rawdevs/octeontx2_ep` for more details on this new PMD. +* **Added synchronous Crypto burst API.** + + A new API is introduced in crypto library to handle synchronous cryptographic + operations allowing to achieve performance gain for cryptodevs which use + CPU based acceleration, such as Intel AES-NI. An example implementation + for aesni_gcm cryptodev is provided including unit tests. The IPsec example + application and ipsec library itself were changed to allow utilization of this + new feature. Removed Items ------------- -- 2.17.1