-The Crypto device framework provides a set of session pool management APIs for
-the creation and freeing of the sessions, utilizing the Mempool Library.
-
-The framework also provides hooks so the PMDs can pass the amount of memory
-required for that PMDs private session parameters, as well as initialization
-functions for the configuration of the session parameters and freeing function
-so the PMD can managed the memory on destruction of a session.
-
-**Note**: Sessions created on a particular device can only be used on Crypto
-devices of the same type, and if you try to use a session on a device different
-to that on which it was created then the Crypto operation will fail.
-
-``rte_cryptodev_sym_session_create()`` is used to create a symmetric session on
-Crypto device. A symmetric transform chain is used to specify the particular
-operation and its parameters. See the section below for details on transforms.
-
-.. code-block:: c
-
- struct rte_cryptodev_sym_session * rte_cryptodev_sym_session_create(
- uint8_t dev_id, struct rte_crypto_sym_xform *xform);
-
-**Note**: For AEAD operations the algorithm selected for authentication and
-ciphering must aligned, eg AES_GCM.
+The Crypto device framework provides APIs to allocate and initizalize sessions
+for crypto devices, where sessions are mempool objects.
+It is the application's responsibility to create and manage the session mempools.
+This approach allows for different scenarios such as having a single session
+mempool for all crypto devices (where the mempool object size is big
+enough to hold the private session of any crypto device), as well as having
+multiple session mempools of different sizes for better memory usage.
+
+An application can use ``rte_cryptodev_get_private_session_size()`` to
+get the private session size of given crypto device. This function would allow
+an application to calculate the max device session size of all crypto devices
+to create a single session mempool.
+If instead an application creates multiple session mempools, the Crypto device
+framework also provides ``rte_cryptodev_get_header_session_size`` to get
+the size of an uninitialized session.
+
+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.
+
+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.