[dpdk-dev] [PATCH 3/3] doc: add initialization section for virtual crypto PMDs

[Pablo de Lara]

Explain how to create/initialize virtual crypto PMDs,
through command line and within an application.

Signed-off-by: Pablo de Lara <pablo.de.lara.guarch at intel.com>
---
 doc/guides/cryptodevs/aesni_gcm.rst | 38 ++++++++++++++++++++++++++++++++-----
 doc/guides/cryptodevs/aesni_mb.rst  | 36 +++++++++++++++++++++++++++++++----
 doc/guides/cryptodevs/null.rst      | 24 +++++++++++++++++++++++
 doc/guides/cryptodevs/snow3g.rst    | 35 +++++++++++++++++++++++++++++++---
 4 files changed, 121 insertions(+), 12 deletions(-)

diff --git a/doc/guides/cryptodevs/aesni_gcm.rst b/doc/guides/cryptodevs/aesni_gcm.rst
index bbd22e2..7ff1c6b 100644
--- a/doc/guides/cryptodevs/aesni_gcm.rst
+++ b/doc/guides/cryptodevs/aesni_gcm.rst
@@ -50,6 +50,39 @@ Authentication algorithms:
 
 * RTE_CRYPTO_AUTH_AES_GCM
 
+Initialization
+--------------
+
+In order to enable this virtual crypto PMD, user must:
+
+* Export the environmental variable AESNI_MULTI_BUFFER_LIB_PATH with the path where
+  the library was extracted.
+
+* Build the multi buffer library (go to Installation section in AES-NI MB PMD documentation).
+
+* 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("cryptodev_aesni_gcm_pmd") within the application.
+
+* Use --vdev="cryptodev_aesni_gcm_pmd" in the EAL options, which will call rte_eal_vdev_init() internally.
+
+The following parameters (all optional) can be provided in the previous two calls:
+
+* socket_id: Specify the socket where the memory for the device is going to be allocated
+  (by default, socket_id will be the socket where the core that is creating the PMD is running on).
+
+* max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default).
+
+* max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default).
+
+Example:
+
+.. code-block:: console
+
+    ./l2fwd-crypto -c 40 -n 4 --vdev="cryptodev_aesni_gcm_pmd,socket_id=1,max_nb_sessions=128"
+
 Limitations
 -----------
 
@@ -59,8 +92,3 @@ Limitations
 * 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.
-
-The environmental variable
-AESNI_MULTI_BUFFER_LIB_PATH must be exported with the path where you extracted
-and built the multi buffer library and finally set
-CONFIG_RTE_LIBRTE_PMD_AESNI_GCM=y in config/common_base.
diff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/aesni_mb.rst
index 0f4b920..9e04853 100644
--- a/doc/guides/cryptodevs/aesni_mb.rst
+++ b/doc/guides/cryptodevs/aesni_mb.rst
@@ -79,7 +79,35 @@ the Makefile of the release package.
 
 	make YASM=/usr/bin/yasm
 
-The environmental variable
-AESNI_MULTI_BUFFER_LIB_PATH must be exported with the path where you extracted
-and built the multi buffer library and finally set
-CONFIG_RTE_LIBRTE_PMD_AESNI_MB=y in config/common_linuxapp.
+Initialization
+--------------
+
+In order to enable this virtual crypto PMD, user must:
+
+* 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_MB=y in config/common_base.
+
+To use the PMD in an application, user must:
+
+* Call rte_eal_vdev_init("cryptodev_aesni_mb_pmd") within the application.
+
+* Use --vdev="cryptodev_aesni_mb_pmd" in the EAL options, which will call rte_eal_vdev_init() internally.
+
+The following parameters (all optional) can be provided in the previous two calls:
+
+* socket_id: Specify the socket where the memory for the device is going to be allocated
+  (by default, socket_id will be the socket where the core that is creating the PMD is running on).
+
+* max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default).
+
+* max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default).
+
+Example:
+
+.. code-block:: console
+
+    ./l2fwd-crypto -c 40 -n 4 --vdev="cryptodev_aesni_mb_pmd,socket_id=1,max_nb_sessions=128"
diff --git a/doc/guides/cryptodevs/null.rst b/doc/guides/cryptodevs/null.rst
index 6408391..b68d4cd 100644
--- a/doc/guides/cryptodevs/null.rst
+++ b/doc/guides/cryptodevs/null.rst
@@ -70,3 +70,27 @@ Installation
 
 The Null Crypto PMD is enabled and built by default in both the Linux and
 FreeBSD builds.
+
+Initialization
+--------------
+
+To use the PMD in an application, user must:
+
+* Call rte_eal_vdev_init("cryptodev_null_pmd") within the application.
+
+* Use --vdev="cryptodev_null_pmd" in the EAL options, which will call rte_eal_vdev_init() internally.
+
+The following parameters (all optional) can be provided in the previous two calls:
+
+* socket_id: Specify the socket where the memory for the device is going to be allocated
+  (by default, socket_id will be the socket where the core that is creating the PMD is running on).
+
+* max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default).
+
+* max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default).
+
+Example:
+
+.. code-block:: console
+
+    ./l2fwd-crypto -c 40 -n 4 --vdev="cryptodev_null_pmd,socket_id=1,max_nb_sessions=128"
diff --git a/doc/guides/cryptodevs/snow3g.rst b/doc/guides/cryptodevs/snow3g.rst
index 7e38d20..c1098b1 100644
--- a/doc/guides/cryptodevs/snow3g.rst
+++ b/doc/guides/cryptodevs/snow3g.rst
@@ -91,6 +91,35 @@ and compiling it on their system before building DPDK::
    +void sso_snow3gStateInitialize_1(sso_snow3gKeyState1_t * pCtx, sso_snow3g_key_schedule_t *pKeySched, uint8_t *pIV);
 
 
-The environmental variable ``LIBSSO_PATH`` must be exported with the path
-where you extracted and built the libsso library and finally set
-``CONFIG_RTE_LIBRTE_PMD_SNOW3G=y`` in ``config/common_base``.
+Initialization
+--------------
+
+In order to enable this virtual crypto PMD, user must:
+
+* Export the environmental variable LIBSSO_PATH with the path where
+  the library was extracted.
+
+* Build the LIBSSO library (explained in Installation section).
+
+* Set CONFIG_RTE_LIBRTE_PMD_SNOW3G=y in config/common_base.
+
+To use the PMD in an application, user must:
+
+* Call rte_eal_vdev_init("cryptodev_snow3g_pmd") within the application.
+
+* Use --vdev="cryptodev_snow3g_pmd" in the EAL options, which will call rte_eal_vdev_init() internally.
+
+The following parameters (all optional) can be provided in the previous two calls:
+
+* socket_id: Specify the socket where the memory for the device is going to be allocated
+  (by default, socket_id will be the socket where the core that is creating the PMD is running on).
+
+* max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default).
+
+* max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default).
+
+Example:
+
+.. code-block:: console
+
+    ./l2fwd-crypto -c 40 -n 4 --vdev="cryptodev_snow3g_pmd,socket_id=1,max_nb_sessions=128"
-- 
2.5.5