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.smoczyn...@intel.com>
---
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
