New upstream version 17.08

[deb_dpdk.git] / doc / guides / cryptodevs / aesni_mb.rst

diff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/aesni_mb.rst
index e812e95..b3b937f 100644 (file)
--- a/doc/guides/cryptodevs/aesni_mb.rst
+++ b/doc/guides/cryptodevs/aesni_mb.rst
@@ -1,5 +1,5 @@
 ..  BSD LICENSE
 ..  BSD LICENSE

-    Copyright(c) 2015 Intel Corporation. All rights reserved.
+    Copyright(c) 2015-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
 
     Redistribution and use in source and binary forms, with or without
     modification, are permitted provided that the following conditions


@@ -27,7 +27,7 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 

-AESN-NI Multi Buffer Crytpo Poll Mode Driver
+AESN-NI Multi Buffer Crypto Poll Mode Driver

 ============================================
 
 
 ============================================
 
 


@@ -51,36 +51,53 @@ Cipher algorithms:
 * RTE_CRYPTO_CIPHER_AES128_CTR
 * RTE_CRYPTO_CIPHER_AES192_CTR
 * RTE_CRYPTO_CIPHER_AES256_CTR
 * RTE_CRYPTO_CIPHER_AES128_CTR
 * RTE_CRYPTO_CIPHER_AES192_CTR
 * RTE_CRYPTO_CIPHER_AES256_CTR

+* RTE_CRYPTO_CIPHER_AES_DOCSISBPI

 
 Hash algorithms:
 
 
 Hash algorithms:
 

+* RTE_CRYPTO_HASH_MD5_HMAC

 * RTE_CRYPTO_HASH_SHA1_HMAC
 * RTE_CRYPTO_HASH_SHA1_HMAC

+* RTE_CRYPTO_HASH_SHA224_HMAC

 * RTE_CRYPTO_HASH_SHA256_HMAC
 * RTE_CRYPTO_HASH_SHA256_HMAC

+* RTE_CRYPTO_HASH_SHA384_HMAC

 * RTE_CRYPTO_HASH_SHA512_HMAC
 * RTE_CRYPTO_HASH_SHA512_HMAC

+* RTE_CRYPTO_HASH_AES_XCBC_HMAC

 
 Limitations
 -----------
 
 * Chained mbufs are not supported.
 
 Limitations
 -----------
 
 * Chained mbufs are not supported.

-* Hash only is not supported.
-* Cipher only is not supported.

 * Only in-place is currently supported (destination address is the same as source address).
 * Only in-place is currently supported (destination address is the same as source address).

-* Only supports session-oriented API implementation (session-less APIs are not supported).
-*  Not performance tuned.
+

 
 Installation
 ------------
 
 
 Installation
 ------------
 

-To build DPDK with the AESNI_MB_PMD the user is required to download the mult-
-buffer library from `here <https://downloadcenter.intel.com/download/22972>`_
-and compile it on their user system before building DPDK. When building the
-multi-buffer library it is necessary to have YASM package installed and also
-requires the overriding of YASM path when building, as a path is hard coded in
-the Makefile of the release package.
+To build DPDK with the AESNI_MB_PMD the user is required to download the multi-buffer
+library from `here <https://github.com/01org/intel-ipsec-mb>`_
+and compile it on their user system before building DPDK.
+The latest version of the library supported by this PMD is v0.46, which
+can be downloaded in `<https://github.com/01org/intel-ipsec-mb/archive/v0.46.zip>`_.

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-       make YASM=/usr/bin/yasm
+       make
+
+As a reference, the following table shows a mapping between the past DPDK versions
+and the Multi-Buffer library version supported by them:
+
+.. _table_aesni_mb_versions:
+
+.. table:: DPDK and Multi-Buffer library version compatibility
+
+   =============  ============================
+   DPDK version   Multi-buffer library version
+   =============  ============================
+   2.2 - 16.11    0.43 - 0.44
+   17.02          0.44
+   17.05+         0.45+
+   =============  ============================
+

 
 Initialization
 --------------
 
 Initialization
 --------------


@@ -96,9 +113,9 @@ In order to enable this virtual crypto PMD, user must:
 
 To use the PMD in an application, user must:
 
 
 To use the PMD in an application, user must:
 

-* Call rte_eal_vdev_init("crypto_aesni_mb") within the application.
+* Call rte_vdev_init("crypto_aesni_mb") within the application.

 
 

-* Use --vdev="crypto_aesni_mb" in the EAL options, which will call rte_eal_vdev_init() internally.
+* Use --vdev="crypto_aesni_mb" in the EAL options, which will call rte_vdev_init() internally.

 
 The following parameters (all optional) can be provided in the previous two calls:
 
 
 The following parameters (all optional) can be provided in the previous two calls:
 


@@ -113,4 +130,18 @@ Example:
 
 .. code-block:: console
 
 
 .. code-block:: console
 

-    ./l2fwd-crypto -c 40 -n 4 --vdev="crypto_aesni_mb,socket_id=1,max_nb_sessions=128"
+    ./l2fwd-crypto -l 1 -n 4 --vdev="crypto_aesni_mb,socket_id=0,max_nb_sessions=128" \
+    -- -p 1 --cdev SW --chain CIPHER_HASH --cipher_algo "aes-cbc" --auth_algo "sha1-hmac"
+
+Extra notes
+-----------
+
+For AES Counter mode (AES-CTR), the library supports two different sizes for Initialization
+Vector (IV):
+
+* 12 bytes: used mainly for IPSec, as it requires 12 bytes from the user, which internally
+  are appended the counter block (4 bytes), which is set to 1 for the first block
+  (no padding required from the user)
+
+* 16 bytes: when passing 16 bytes, the library will take them and use the last 4 bytes
+  as the initial counter block for the first block.