git.droids-corp.org / dpdk.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
net/ixgbe: add tuned Rx/Tx parameters
[dpdk.git] / doc / guides / sample_app_ug / l2_forward_crypto.rst
diff --git a/doc/guides/sample_app_ug/l2_forward_crypto.rst b/doc/guides/sample_app_ug/l2_forward_crypto.rst
index 2880c43..855afd8 100644 (file)
--- a/doc/guides/sample_app_ug/l2_forward_crypto.rst
+++ b/doc/guides/sample_app_ug/l2_forward_crypto.rst
@@ -1,32 +1,5 @@
-..  BSD LICENSE
-    Copyright(c) 2016-2017 Intel Corporation. All rights reserved.
-    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.
 
 .. _l2_fwd_crypto_app:
 
 
 .. _l2_fwd_crypto_app:
 
@@ -46,7 +19,7 @@ for each packet that is received on a RX_PORT and performs L2 forwarding.
 The destination port is the adjacent port from the enabled portmask, that is,
 if the first four ports are enabled (portmask 0xf),
 ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other.
 The destination port is the adjacent port from the enabled portmask, that is,
 if the first four ports are enabled (portmask 0xf),
 ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other.
-Also, the MAC addresses are affected as follows:
+Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows:
 
 *   The source MAC address is replaced by the TX_PORT MAC address
 
 
 *   The source MAC address is replaced by the TX_PORT MAC address
 
@@ -55,26 +28,9 @@ Also, the MAC addresses are affected as follows:
 Compiling the Application
 -------------------------
 
 Compiling the Application
 -------------------------
 
-#.  Go to the example directory:
+To compile the sample application see :doc:`compiling`.
 
 
-    .. code-block:: console
-
-        export RTE_SDK=/path/to/rte_sdk
-        cd ${RTE_SDK}/examples/l2fwd-crypto
-
-#.  Set the target (a default target is used if not specified). For example:
-
-    .. code-block:: console
-
-        export RTE_TARGET=x86_64-native-linuxapp-gcc
-
-    *See the DPDK Getting Started Guide* for possible RTE_TARGET values.
-
-#.  Build the application:
-
-    .. code-block:: console
-
-        make
+The application is located in the ``l2fwd-crypt`` sub-directory.
 
 Running the Application
 -----------------------
 
 Running the Application
 -----------------------
@@ -84,13 +40,16 @@ The application requires a number of command line options:
 .. code-block:: console
 
     ./build/l2fwd-crypto [EAL options] -- [-p PORTMASK] [-q NQ] [-s] [-T PERIOD] /
 .. code-block:: console
 
     ./build/l2fwd-crypto [EAL options] -- [-p PORTMASK] [-q NQ] [-s] [-T PERIOD] /
-    [--cdev_type HW/SW/ANY] [--chain HASH_CIPHER/CIPHER_HASH/CIPHER_ONLY/HASH_ONLY] /
+    [--cdev_type HW/SW/ANY] [--chain HASH_CIPHER/CIPHER_HASH/CIPHER_ONLY/HASH_ONLY/AEAD] /
     [--cipher_algo ALGO] [--cipher_op ENCRYPT/DECRYPT] [--cipher_key KEY] /
     [--cipher_key_random_size SIZE] [--cipher_iv IV] [--cipher_iv_random_size SIZE] /
     [--auth_algo ALGO] [--auth_op GENERATE/VERIFY] [--auth_key KEY] /
     [--auth_key_random_size SIZE] [--auth_iv IV] [--auth_iv_random_size SIZE] /
     [--cipher_algo ALGO] [--cipher_op ENCRYPT/DECRYPT] [--cipher_key KEY] /
     [--cipher_key_random_size SIZE] [--cipher_iv IV] [--cipher_iv_random_size SIZE] /
     [--auth_algo ALGO] [--auth_op GENERATE/VERIFY] [--auth_key KEY] /
     [--auth_key_random_size SIZE] [--auth_iv IV] [--auth_iv_random_size SIZE] /
+    [--aead_algo ALGO] [--aead_op ENCRYPT/DECRYPT] [--aead_key KEY] /
+    [--aead_key_random_size SIZE] [--aead_iv] [--aead_iv_random_size SIZE] /
     [--aad AAD] [--aad_random_size SIZE] /
     [--aad AAD] [--aad_random_size SIZE] /
-    [--digest size SIZE] [--sessionless] [--cryptodev_mask MASK]
+    [--digest size SIZE] [--sessionless] [--cryptodev_mask MASK] /
+    [--mac-updating] [--no-mac-updating]
 
 where,
 
 
 where,
 
@@ -156,7 +115,7 @@ where,
 
     Note that if --auth_iv is used, this will be ignored.
 
 
     Note that if --auth_iv is used, this will be ignored.
 
-*   aead_algo: select the AEAD algorithm
+*   aead_algo: select the AEAD algorithm (default is aes-gcm)
 
 *   aead_op: select the AEAD operation to perform: ENCRYPT or DECRYPT
 
 
 *   aead_op: select the AEAD operation to perform: ENCRYPT or DECRYPT
 
@@ -191,6 +150,8 @@ where,
 
     (default is all cryptodevs).
 
 
     (default is all cryptodevs).
 
+*   [no-]mac-updating: Enable or disable MAC addresses updating (enabled by default).
+
 
 The application requires that crypto devices capable of performing
 the specified crypto operation are available on application initialization.
 
 The application requires that crypto devices capable of performing
 the specified crypto operation are available on application initialization.
@@ -201,8 +162,8 @@ To run the application in linuxapp environment with 2 lcores, 2 ports and 2 cryp
 
 .. code-block:: console
 
 
 .. code-block:: console
 
-    $ ./build/l2fwd-crypto -l 0-1 -n 4 --vdev "cryptodev_aesni_mb_pmd" \
-    --vdev "cryptodev_aesni_mb_pmd" -- -p 0x3 --chain CIPHER_HASH \
+    $ ./build/l2fwd-crypto -l 0-1 -n 4 --vdev "crypto_aesni_mb0" \
+    --vdev "crypto_aesni_mb1" -- -p 0x3 --chain CIPHER_HASH \
     --cipher_op ENCRYPT --cipher_algo aes-cbc \
     --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f \
     --auth_op GENERATE --auth_algo aes-xcbc-mac \
     --cipher_op ENCRYPT --cipher_algo aes-cbc \
     --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f \
     --auth_op GENERATE --auth_algo aes-xcbc-mac \
@@ -211,6 +172,14 @@ To run the application in linuxapp environment with 2 lcores, 2 ports and 2 cryp
 Refer to the *DPDK Getting Started Guide* for general information on running applications
 and the Environment Abstraction Layer (EAL) options.
 
 Refer to the *DPDK Getting Started Guide* for general information on running applications
 and the Environment Abstraction Layer (EAL) options.
 
+.. Note::
+
+    * The ``l2fwd-crypto`` sample application requires IPv4 packets for crypto operation.
+
+    * If multiple Ethernet ports is passed, then equal number of crypto devices are to be passed.
+
+    * All crypto devices shall use the same session.
+
 Explanation
 -----------
 
 Explanation
 -----------
 
@@ -360,8 +329,14 @@ This session is created and is later attached to the crypto operation:
                    uint8_t cdev_id)
    {
            struct rte_crypto_sym_xform *first_xform;
                    uint8_t cdev_id)
    {
            struct rte_crypto_sym_xform *first_xform;
+           struct rte_cryptodev_sym_session *session;
+           uint8_t socket_id = rte_cryptodev_socket_id(cdev_id);
+           struct rte_mempool *sess_mp = session_pool_socket[socket_id];
 
 
-           if (options->xform_chain == L2FWD_CRYPTO_CIPHER_HASH) {
+
+           if (options->xform_chain == L2FWD_CRYPTO_AEAD) {
+                   first_xform = &options->aead_xform;
+           } else if (options->xform_chain == L2FWD_CRYPTO_CIPHER_HASH) {
                    first_xform = &options->cipher_xform;
                    first_xform->next = &options->auth_xform;
            } else if (options->xform_chain == L2FWD_CRYPTO_HASH_CIPHER) {
                    first_xform = &options->cipher_xform;
                    first_xform->next = &options->auth_xform;
            } else if (options->xform_chain == L2FWD_CRYPTO_HASH_CIPHER) {
@@ -373,8 +348,16 @@ This session is created and is later attached to the crypto operation:
                    first_xform = &options->auth_xform;
            }
 
                    first_xform = &options->auth_xform;
            }
 
-           /* Setup Cipher Parameters */
-           return rte_cryptodev_sym_session_create(cdev_id, first_xform);
+           session = rte_cryptodev_sym_session_create(sess_mp);
+
+           if (session == NULL)
+                   return NULL;
+
+          if (rte_cryptodev_sym_session_init(cdev_id, session,
+                                first_xform, sess_mp) < 0)
+                   return NULL;
+
+          return session;
    }
 
    ...
    }
 
    ...
DPDK repo used for reviews