doc: add cryptodev sample code

[dpdk.git] / doc / guides / cryptodevs / aesni_gcm.rst

diff --git a/doc/guides/cryptodevs/aesni_gcm.rst b/doc/guides/cryptodevs/aesni_gcm.rst
index ba9ecb5..6e9160a 100644 (file)
--- a/doc/guides/cryptodevs/aesni_gcm.rst
+++ b/doc/guides/cryptodevs/aesni_gcm.rst
@@ -1,5 +1,5 @@
 ..  BSD LICENSE
 ..  BSD LICENSE

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


@@ -32,44 +32,76 @@ AES-NI GCM Crypto Poll Mode Driver
 
 
 The AES-NI GCM PMD (**librte_pmd_aesni_gcm**) provides poll mode crypto driver
 
 
 The AES-NI GCM PMD (**librte_pmd_aesni_gcm**) provides poll mode crypto driver

-support for utilizing Intel ISA-L crypto library, which provides operation acceleration
-through the AES-NI instruction sets for AES-GCM authenticated cipher algorithm.
+support for utilizing Intel multi buffer library (see AES-NI Multi-buffer PMD documentation
+to learn more about it, including installation).

 
 Features
 --------
 
 AESNI GCM PMD has support for:
 
 
 Features
 --------
 
 AESNI GCM PMD has support for:
 

-Cipher algorithms:
-
-* RTE_CRYPTO_CIPHER_AES_GCM
-

 Authentication algorithms:
 
 Authentication algorithms:
 

-* RTE_CRYPTO_AUTH_AES_GCM

 * RTE_CRYPTO_AUTH_AES_GMAC
 
 * RTE_CRYPTO_AUTH_AES_GMAC
 

+AEAD algorithms:
+
+* RTE_CRYPTO_AEAD_AES_GCM
+
+
+Limitations
+-----------
+
+* Chained mbufs are supported but only out-of-place (destination mbuf must be contiguous).
+* Cipher only is not supported.
+
+

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

-To build DPDK with the AESNI_GCM_PMD the user is required to install
-the ``libisal_crypto`` library in the build environment.
-For download and more details please visit `<https://github.com/01org/isa-l_crypto>`_.
+To build DPDK with the AESNI_GCM_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
+
+       make
+
+As a reference, the following table shows a mapping between the past DPDK versions
+and the external crypto libraries supported by them:
+
+.. _table_aesni_gcm_versions:
+
+.. table:: DPDK and external crypto library version compatibility
+
+   =============  ================================
+   DPDK version   Crypto library version
+   =============  ================================
+   16.04 - 16.11  Multi-buffer library 0.43 - 0.44
+   17.02 - 17.05  ISA-L Crypto v2.18
+   17.08+         Multi-buffer library 0.46+
+   =============  ================================
+

 
 Initialization
 --------------
 
 In order to enable this virtual crypto PMD, user must:
 
 
 Initialization
 --------------
 
 In order to enable this virtual crypto PMD, user must:
 

-* Install the ISA-L crypto library (explained in Installation section).
+* Export the environmental variable AESNI_MULTI_BUFFER_LIB_PATH with the path where
+  the library was extracted.
+
+* Build the multi buffer library (explained in Installation section).

 
 * Set CONFIG_RTE_LIBRTE_PMD_AESNI_GCM=y in config/common_base.
 
 To use the PMD in an application, user must:
 
 
 * Set CONFIG_RTE_LIBRTE_PMD_AESNI_GCM=y in config/common_base.
 
 To use the PMD in an application, user must:
 

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

 
 

-* Use --vdev="crypto_aesni_gcm" in the EAL options, which will call rte_eal_vdev_init() internally.
+* Use --vdev="crypto_aesni_gcm" 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:
 


@@ -84,11 +116,5 @@ Example:
 
 .. code-block:: console
 
 
 .. code-block:: console
 

-    ./l2fwd-crypto -l 6 -n 4 --vdev="crypto_aesni_gcm,socket_id=1,max_nb_sessions=128"
-
-Limitations
------------
-
-* Chained mbufs are supported but only out-of-place (destination mbuf must be contiguous).
-* Hash only is not supported.
-* Cipher only is not supported.
+    ./l2fwd-crypto -l 1 -n 4 --vdev="crypto_aesni_gcm,socket_id=0,max_nb_sessions=128" \
+    -- -p 1 --cdev SW --chain AEAD --aead_algo "aes-gcm"