Skip to contentSkip to conversation

cryptodev: fix sym session mempool creation description

PATCH Applied Fan Zhang 2 participants 2 messages Jan 6, 2023 – Feb 5, 2023

lore
Share & tools
lore

Fan Zhang

author
#0 lore raw

PATCH 1/1 cryptodev: fix sym session mempool creation description

After the session mempool creation API is changed, some description is no longer valid. This patch fixes the descriptions in both API comment and the programmer's guide.

Fixes bdce2564dbf7 ("cryptodev: rework session framework")
---
 doc/guides/prog_guide/cryptodev_lib.rst       |  41 +-
 .../prog_guide/img/cryptodev_sym_sess.svg     | 417 ------------------
 lib/cryptodev/rte_cryptodev.h                 |  17 +-
 3 files changed, 26 insertions(+), 449 deletions(-)
 delete mode 100644 doc/guides/prog_guide/img/cryptodev_sym_sess.svg
doc/guides/prog_guide/cryptodev_lib.rst +16 -25
index 01aad842a9..6963229898 100644
@@ -499,37 +499,28 @@ a flow. Crypto sessions cache this immutable data in a optimal way for the
 underlying PMD and this allows further acceleration of the offload of
 Crypto workloads.
 
-.. figure:: img/cryptodev_sym_sess.*
-
 The Crypto device framework provides APIs to create session mempool and allocate
 and initialize sessions for crypto devices, where sessions are mempool objects.
 The application has to use ``rte_cryptodev_sym_session_pool_create()`` to
-create the session header mempool that creates a mempool with proper element
-size automatically and stores necessary information for safely accessing the
-session in the mempool's private data field.
-
-To create a mempool for storing session private data, the application has two
-options. The first is to create another mempool with elt size equal to or
-bigger than the maximum session private data size of all crypto devices that
-will share the same session header. The creation of the mempool shall use the
-traditional ``rte_mempool_create()`` with the correct ``elt_size``. The other
-option is to change the ``elt_size`` parameter in
-``rte_cryptodev_sym_session_pool_create()`` to the correct value. The first
-option is more complex to implement but may result in better memory usage as
-a session header normally takes smaller memory footprint as the session private
-data.
+create the session mempool header and the private data with the size specified
+by the user through the ``elt_size`` parameter in the function. The session
+private data is for the driver to initialize and access during crypto operations,
+hence the ``elt_size`` should be big enough for all drivers that will share this
+mempool. To obtain the proper session private data size of a crypto device, the
+user can call ``rte_cryptodev_sym_get_private_session_size()`` function. In case
+of heterogeneous crypto devices will share the same session mempool, the maximum
+session private data size of them should be passed.
 
 Once the session mempools have been created, ``rte_cryptodev_sym_session_create()``
-is used to allocate an uninitialized session from the given mempool.
-The session then must be initialized using ``rte_cryptodev_sym_session_init()``
-for each of the required crypto devices. A symmetric transform chain
-is used to specify the operation and its parameters. See the section below for
-details on transforms.
+is used to allocate and initialize the session from the given mempool. The
+created session can ONLY be used by the crypto devices sharing the same driver ID
+as the device ID passed into the function as the parameter. In addition, a symmetric
+transform chain is used to specify the operation and its parameters.
+See the section below for details on transforms.
 
-When a session is no longer used, user must call ``rte_cryptodev_sym_session_clear()``
-for each of the crypto devices that are using the session, to free all driver
-private session data. Once this is done, session should be freed using
-``rte_cryptodev_sym_session_free`` which returns them to their mempool.
+When a session is no longer used, user must call ``rte_cryptodev_sym_session_free()``
+to uninitialize the session data and return the session back to the mempool it
+belongs.
 
 
 Transforms and Transform Chaining
doc/guides/prog_guide/img/cryptodev_sym_sess.svg deleted +0 -417

418 lines not on this page · raw message

lib/cryptodev/rte_cryptodev.h +10 -7
index 86d792e2e7..ed4112c625 100644
@@ -911,11 +911,14 @@ rte_cryptodev_get_sec_ctx(uint8_t dev_id);
  * @param nb_elts
  *   The number of elements in the mempool.
  * @param elt_size
- *   The size of the element. This value will be ignored if it is smaller than
- *   the minimum session header size required for the system. For the user who
- *   want to use the same mempool for sym session and session private data it
- *   can be the maximum value of all existing devices' private data and session
- *   header sizes.
+ *   The size of the element. This should be the size of the cryptodev PMD
+ *   session private data obtained through
+ *   rte_cryptodev_sym_get_private_session_size() function call.
+ *   For the user who wants to use the same mempool for heterogeneous PMDs
+ *   this value should be the maximum value of their private session sizes.
+ *   Please note the created mempool will have bigger elt size than this
+ *   value as necessary session header and the possible padding are filled
+ *   into each elt.
  * @param cache_size
  *   The number of per-lcore cache elements
  * @param priv_size
@@ -926,8 +929,8 @@ rte_cryptodev_get_sec_ctx(uint8_t dev_id);
  *   constraint for the reserved zone.
  *
  * @return
- *  - On success return size of the session
- *  - On failure returns 0
+ *  - On success returns the created session mempool pointer
+ *  - On failure returns NULL
  */
 __rte_experimental
 struct rte_mempool *
Signature · 1 line
2.25.1