VPP-279: Document changes for vnet/vnet/devices

Add doxygen documentation for DPDK crypto CLI command.

The move of DPDK to a plugin invalidated the local dir.dox. So moved
dpdk/dir.dox to dpdk/device/dir.dox to fix.

Change-Id: I229e2921c4b0cdd380021adb520cd2089a376afa
Signed-off-by: Billy McFall <bmcfall@redhat.com>

diff --git a/src/plugins/dpdk/dir.dox b/src/plugins/dpdk/device/dir.dox
similarity index 100%
rename from src/plugins/dpdk/dir.dox
rename to src/plugins/dpdk/device/dir.dox

diff --git a/src/plugins/dpdk/ipsec/cli.c b/src/plugins/dpdk/ipsec/cli.c
index 40cee39..cd0a603 100644 (file)
--- a/src/plugins/dpdk/ipsec/cli.c
+++ b/src/plugins/dpdk/ipsec/cli.c
@@ -136,11 +136,72 @@ done:
   return error;
 }
 
+/*?
+ * This command is used to display the DPDK Crypto device data. See
+ * @ref dpdk_crypto_ipsec_doc for more details on initializing the
+ * DPDK Crypto device.
+ *
+ * @cliexpar
+ * Example of displaying the DPDK Crypto device data when disabled:
+ * @cliexstart{show crypto device mapping}
+ * DPDK Cryptodev support is disabled
+ * @cliexend
+ * Example of displaying the DPDK Crypto device data when enabled:
+ * @cliexstart{show crypto device mapping}
+ * worker  crypto device id(type)
+ * 1       1(SW)
+ * 2       1(SW)
+ * @cliexend
+ * Example of displaying the DPDK Crypto device data when enabled with verbose:
+ * @cliexstart{show crypto device mapping verbose}
+ * worker      cipher                 auth dir     dev     qp
+ * 1          AES_CTR         AES-XCBC-MAC  in     1       0
+ * 1          AES_CTR          HMAC-SHA384  in     1       0
+ * 1          AES_CTR          HMAC-SHA384 out     1       1
+ * 1          AES_CBC          HMAC-SHA512  in     1       0
+ * 1          AES_CBC          HMAC-SHA256  in     1       0
+ * 1          AES_CBC         AES-XCBC-MAC out     1       1
+ * 1          AES_CTR         AES-XCBC-MAC out     1       1
+ * 1          AES_CBC          HMAC-SHA256 out     1       1
+ * 1          AES_CTR          HMAC-SHA512 out     1       1
+ * 1          AES_CTR          HMAC-SHA256  in     1       0
+ * 1          AES_CTR            HMAC-SHA1  in     1       0
+ * 1          AES_CBC          HMAC-SHA512 out     1       1
+ * 1          AES_CBC          HMAC-SHA384 out     1       1
+ * 1          AES_CTR            HMAC-SHA1 out     1       1
+ * 1          AES_CTR          HMAC-SHA256 out     1       1
+ * 1          AES_CBC            HMAC-SHA1  in     1       0
+ * 1          AES_CBC         AES-XCBC-MAC  in     1       0
+ * 1          AES_CTR          HMAC-SHA512  in     1       0
+ * 1          AES_CBC            HMAC-SHA1 out     1       1
+ * 1          AES_CBC          HMAC-SHA384  in     1       0
+ * 2          AES_CTR         AES-XCBC-MAC  in     1       2
+ * 2          AES_CTR          HMAC-SHA384  in     1       2
+ * 2          AES_CTR          HMAC-SHA384 out     1       3
+ * 2          AES_CBC          HMAC-SHA512  in     1       2
+ * 2          AES_CBC          HMAC-SHA256  in     1       2
+ * 2          AES_CBC         AES-XCBC-MAC out     1       3
+ * 2          AES_CTR         AES-XCBC-MAC out     1       3
+ * 2          AES_CBC          HMAC-SHA256 out     1       3
+ * 2          AES_CTR          HMAC-SHA512 out     1       3
+ * 2          AES_CTR          HMAC-SHA256  in     1       2
+ * 2          AES_CTR            HMAC-SHA1  in     1       2
+ * 2          AES_CBC          HMAC-SHA512 out     1       3
+ * 2          AES_CBC          HMAC-SHA384 out     1       3
+ * 2          AES_CTR            HMAC-SHA1 out     1       3
+ * 2          AES_CTR          HMAC-SHA256 out     1       3
+ * 2          AES_CBC            HMAC-SHA1  in     1       2
+ * 2          AES_CBC         AES-XCBC-MAC  in     1       2
+ * 2          AES_CTR          HMAC-SHA512  in     1       2
+ * 2          AES_CBC            HMAC-SHA1 out     1       3
+ * 2          AES_CBC          HMAC-SHA384  in     1       2
+ * @cliexend
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (lcore_cryptodev_map, static) = {
     .path = "show crypto device mapping",
     .short_help =
-    "show cryptodev device mapping <verbose>",
+    "show cryptodev device mapping [verbose]",
     .function = lcore_cryptodev_map_fn,
 };
 /* *INDENT-ON* */

diff --git a/src/plugins/dpdk/ipsec/dir.dox b/src/plugins/dpdk/ipsec/dir.dox
index ffebfc4..0550454 100644 (file)
--- a/src/plugins/dpdk/ipsec/dir.dox
+++ b/src/plugins/dpdk/ipsec/dir.dox
@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2016 Intel and/or its affiliates.
+ *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at:
@@ -12,7 +13,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+/* Doxygen directory documentation */
+
 /**
- @dir vnet/vnet/devices/dpdk/ipsec
- @brief IPSec ESP encrypt/decrypt using DPDK Cryptodev API
+@dir src/plugins/dpdk/ipsec
+@brief IPSec ESP encrypt/decrypt using DPDK Cryptodev API.
+
+This directory contains the source code for the DPDK Crypto abstraction layer.
+
 */
+/*? %%clicmd:group_label DPDK Crypto %% ?*/
+/*? %%syscfg:group_label DPDK Crypto %% ?*/

diff --git a/src/plugins/dpdk/ipsec/dpdk_crypto_ipsec_doc.md b/src/plugins/dpdk/ipsec/dpdk_crypto_ipsec_doc.md
index fed2fe0..b3d3cc4 100644 (file)
--- a/src/plugins/dpdk/ipsec/dpdk_crypto_ipsec_doc.md
+++ b/src/plugins/dpdk/ipsec/dpdk_crypto_ipsec_doc.md
@@ -40,7 +40,7 @@ A couple of ways to achive this:
 * uncomment/add it in the platforms config (ie. build-data/platforms/vpp.mk)
 * set the option when building vpp (ie. make vpp_uses_dpdk_cryptodev_sw=yes build-release)
 
-When enabling SW Cryptodev support, it means that you need to pre-build the required crypto libraries needed by those SW Cryptodev PMDs.
+When enabling SW Cryptodev support, it means that you need to pre-build the required crypto libraries needed by those SW Cryptodev PMDs. This requires nasm, see nasm section below.
 
 
 ### Crypto Resources allocation
@@ -84,3 +84,22 @@ For further details refer to [DPDK Crypto Device Driver documentation](http://dp
 The following CLI command displays the Cryptodev/Worker mapping:
 
     show crypto device mapping [verbose]
+
+
+### nasm
+
+Building the DPDK Crypto Libraries requires the open source project nasm (The Netwide
+Assembler) to be installed. Recommended version of nasm is 2.12.02. Minimum supported
+version of nasm is 2.11.06. Use the following command to determine the current nasm version:
+
+    nasm -v
+
+CentOS 7.3 and earlier and Fedora 21 and earlier use unsupported versions
+of nasm. Use the following set of commands to build a supported version:
+
+    wget http://www.nasm.us/pub/nasm/releasebuilds/2.12.02/nasm-2.12.02.tar.bz2
+    tar -xjvf nasm-2.12.02.tar.bz2
+    cd nasm-2.12.02/
+    ./configure
+    make
+    sudo make install