[v5,8/8] doc: add cpu crypto related documentation
Checks
Commit Message
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 <marcinx.smoczynski@intel.com>
---
doc/guides/cryptodevs/aesni_gcm.rst | 7 +++++-
doc/guides/prog_guide/cryptodev_lib.rst | 33 ++++++++++++++++++++++++-
doc/guides/prog_guide/ipsec_lib.rst | 10 +++++++-
doc/guides/prog_guide/rte_security.rst | 15 ++++++++---
doc/guides/rel_notes/release_20_02.rst | 8 ++++++
5 files changed, 66 insertions(+), 7 deletions(-)
Comments
>
> 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 <marcinx.smoczynski@intel.com>
> ---
This patch need to be split and squashed in the relevant patches of this series.
@@ -1,5 +1,5 @@
.. SPDX-License-Identifier: BSD-3-Clause
- Copyright(c) 2016-2019 Intel Corporation.
+ Copyright(c) 2016-2020 Intel Corporation.
AES-NI GCM Crypto Poll Mode Driver
==================================
@@ -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
--------
@@ -1,5 +1,5 @@
.. SPDX-License-Identifier: BSD-3-Clause
- Copyright(c) 2016-2017 Intel Corporation.
+ Copyright(c) 2016-2020 Intel Corporation.
Cryptography Device Library
===========================
@@ -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
-----------
@@ -1,5 +1,5 @@
.. SPDX-License-Identifier: BSD-3-Clause
- Copyright(c) 2018 Intel Corporation.
+ Copyright(c) 2018-2020 Intel Corporation.
IPsec Packet Processing Library
===============================
@@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -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
@@ -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
-------------