doc: add private data info in crypto guide

[dpdk.git] / doc / guides / prog_guide / cryptodev_lib.rst

diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst
index 75ae085..b279a20 100644 (file)
--- a/doc/guides/prog_guide/cryptodev_lib.rst
+++ b/doc/guides/prog_guide/cryptodev_lib.rst
@@ -1,32 +1,5 @@
-..  BSD LICENSE
-    Copyright(c) 2016-2017 Intel Corporation. All rights reserved.
-
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions
-    are met:
-
-    * Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in
-    the documentation and/or other materials provided with the
-    distribution.
-    * Neither the name of Intel Corporation nor the names of its
-    contributors may be used to endorse or promote products derived
-    from this software without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2016-2017 Intel Corporation.
 
 Cryptography Device Library
 ===========================
@@ -70,6 +43,15 @@ From the command line using the --vdev EAL option
 
    --vdev  'crypto_aesni_mb0,max_nb_queue_pairs=2,max_nb_sessions=1024,socket_id=0'
 
+.. Note::
+
+   * If DPDK application requires multiple software crypto PMD devices then required
+     number of ``--vdev`` with appropriate libraries are to be added.
+
+   * An Application with crypto PMD instaces sharing the same library requires unique ID.
+
+   Example: ``--vdev  'crypto_aesni_mb0' --vdev  'crypto_aesni_mb1'``
+
 Our using the rte_vdev_init API within the application code.
 
 .. code-block:: c
@@ -317,6 +299,33 @@ directly from the devices processed queue, and for virtual device's from a
 enqueue call.
 
 
+Private data
+~~~~~~~~~~~~
+For session-based operations, the set and get API provides a mechanism for an
+application to store and retrieve the private data information stored along with
+the crypto session.
+
+For example, suppose an application is submitting a crypto operation with a session
+associated and wants to indicate private data information which is required to be
+used after completion of the crypto operation. In this case, the application can use
+the set API to set the private data and retrieve it using get API.
+
+.. code-block:: c
+
+       int rte_cryptodev_sym_session_set_private_data(
+               struct rte_cryptodev_sym_session *sess, void *data, uint16_t size);
+
+       void * rte_cryptodev_sym_session_get_private_data(
+               struct rte_cryptodev_sym_session *sess);
+
+
+For session-less mode, the private data information can be placed along with the
+``struct rte_crypto_op``. The ``rte_crypto_op::private_data_offset`` indicates the
+start of private data information. The offset is counted from the start of the
+rte_crypto_op including other crypto information such as the IVs (since there can
+be an IV also for authentication).
+
+
 Enqueue / Dequeue Burst APIs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -539,12 +548,12 @@ chain.
 
                 struct {
                     uint8_t *data;
-                    phys_addr_t phys_addr;
+                    rte_iova_t phys_addr;
                 } digest; /**< Digest parameters */
 
                 struct {
                     uint8_t *data;
-                    phys_addr_t phys_addr;
+                    rte_iova_t phys_addr;
                 } aad;
                 /**< Additional authentication parameters */
             } aead;
@@ -566,7 +575,7 @@ chain.
 
                     struct {
                         uint8_t *data;
-                        phys_addr_t phys_addr;
+                        rte_iova_t phys_addr;
                     } digest; /**< Digest parameters */
                 } auth;
             };