DPDK patches and discussions
 help / color / mirror / Atom feed
* [dpdk-dev] [PATCH] doc: new l2fwd-crypto sample app guide
@ 2016-04-07 14:49 Pablo de Lara
  2016-04-07 15:59 ` Declan Doherty
  0 siblings, 1 reply; 3+ messages in thread
From: Pablo de Lara @ 2016-04-07 14:49 UTC (permalink / raw)
  To: dev; +Cc: declan.doherty, john.mcnamara, Pablo de Lara

Signed-off-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
---
 .../sample_app_ug/img/l2_fwd_encrypt_flow.svg      | 194 +++++++++
 doc/guides/sample_app_ug/index.rst                 |   3 +
 doc/guides/sample_app_ug/l2_forward_crypto.rst     | 467 +++++++++++++++++++++
 3 files changed, 664 insertions(+)
 create mode 100644 doc/guides/sample_app_ug/img/l2_fwd_encrypt_flow.svg
 create mode 100644 doc/guides/sample_app_ug/l2_forward_crypto.rst

diff --git a/doc/guides/sample_app_ug/img/l2_fwd_encrypt_flow.svg b/doc/guides/sample_app_ug/img/l2_fwd_encrypt_flow.svg
new file mode 100644
index 0000000..492c3df
--- /dev/null
+++ b/doc/guides/sample_app_ug/img/l2_fwd_encrypt_flow.svg
@@ -0,0 +1,194 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by Microsoft Visio, SVG Export l2fwd-crypto-encrypt-flow.svg Page-1 -->
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ev="http://www.w3.org/2001/xml-events"
+		width="10.3779in" height="2.38075in" viewBox="0 0 747.207 171.414" xml:space="preserve" color-interpolation-filters="sRGB"
+		class="st15">
+	<style type="text/css">
+	<![CDATA[
+		.st1 {visibility:visible}
+		.st2 {fill:#5b9bd5;fill-opacity:0.25;filter:url(#filter_2);stroke:#5b9bd5;stroke-opacity:0.25}
+		.st3 {fill:#ffc000;stroke:#40709c;stroke-width:0.75}
+		.st4 {fill:#feffff;font-family:Calibri;font-size:0.833336em}
+		.st5 {font-size:1em}
+		.st6 {fill:#4672c4;stroke:#40709c;stroke-width:0.75}
+		.st7 {fill:#538135;stroke:#40709c;stroke-width:0.75}
+		.st8 {marker-end:url(#mrkr4-58);stroke:#41719c;stroke-dasharray:3,3;stroke-linecap:round;stroke-linejoin:round;stroke-width:1}
+		.st9 {fill:#41719c;fill-opacity:1;stroke:#41719c;stroke-opacity:1;stroke-width:0.28409090909091}
+		.st10 {marker-end:url(#mrkr4-58);stroke:#41719c;stroke-linecap:round;stroke-linejoin:round;stroke-width:1}
+		.st11 {fill:none;filter:url(#filter_2);stroke:#5b9bd5;stroke-opacity:0.22}
+		.st12 {stroke:#c7c8c8;stroke-width:0.25}
+		.st13 {fill:none;stroke:none;stroke-width:0.25}
+		.st14 {fill:#5b9bd5;font-family:Calibri;font-size:1.00001em}
+		.st15 {fill:none;fill-rule:evenodd;font-size:12px;overflow:visible;stroke-linecap:square;stroke-miterlimit:3}
+	]]>
+	</style>
+
+	<defs id="Markers">
+		<g id="lend4">
+			<path d="M 2 1 L 0 0 L 2 -1 L 2 1 " style="stroke:none"/>
+		</g>
+		<marker id="mrkr4-58" class="st9" refX="-7.04" orient="auto" markerUnits="strokeWidth" overflow="visible">
+			<use xlink:href="#lend4" transform="scale(-3.52,-3.52) "/>
+		</marker>
+	</defs>
+	<defs id="Filters">
+		<filter id="filter_2">
+			<feGaussianBlur stdDeviation="2"/>
+		</filter>
+	</defs>
+	<g>
+		<title>Page-1</title>
+		<g id="shape101-1" transform="translate(3.73674,-5.34781)">
+			<title>Circle.53</title>
+			<desc>RX P0 Q0</desc>
+			<g id="shadow101-2" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+				<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st2"/>
+			</g>
+			<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st3"/>
+			<text x="21.35" y="141.75" class="st4">RX <tspan x="14.52" dy="1.2em" class="st5">P</tspan>0 Q0</text>		</g>
+		<g id="shape102-8" transform="translate(101.797,-5.34781)">
+			<title>Circle.56</title>
+			<desc>RX</desc>
+			<g id="shadow102-9" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+				<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st2"/>
+			</g>
+			<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st6"/>
+			<text x="21.35" y="147.75" class="st4">RX</text>		</g>
+		<g id="shape103-14" transform="translate(395.977,-5.34781)">
+			<title>Circle.57</title>
+			<desc>CRYPTO DEQ</desc>
+			<g id="shadow103-15" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+				<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st2"/>
+			</g>
+			<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st7"/>
+			<text x="10.52" y="141.75" class="st4">CRYPTO <tspan x="17.78" dy="1.2em" class="st5">DEQ</tspan></text>		</g>
+		<g id="shape104-21" transform="translate(297.917,-5.34781)">
+			<title>Circle.58</title>
+			<desc>CRYPTO ENQ</desc>
+			<g id="shadow104-22" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+				<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st2"/>
+			</g>
+			<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st7"/>
+			<text x="10.52" y="141.75" class="st4">CRYPTO <tspan x="17.63" dy="1.2em" class="st5">ENQ</tspan></text>		</g>
+		<g id="shape105-28" transform="translate(690.158,-5.34781)">
+			<title>Circle.73</title>
+			<desc>TX P0 Q0</desc>
+			<g id="shadow105-29" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+				<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st2"/>
+			</g>
+			<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st3"/>
+			<text x="21.63" y="141.75" class="st4">TX <tspan x="14.52" dy="1.2em" class="st5">P</tspan>0 Q0</text>		</g>
+		<g id="shape106-35" transform="translate(494.037,-5.34781)">
+			<title>Circle.74</title>
+			<desc>MAC</desc>
+			<g id="shadow106-36" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+				<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st2"/>
+			</g>
+			<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st6"/>
+			<text x="16.83" y="147.75" class="st4">MAC</text>		</g>
+		<g id="shape107-41" transform="translate(199.857,-5.34781)">
+			<title>Circle.61</title>
+			<desc>PAD</desc>
+			<g id="shadow107-42" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+				<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st2"/>
+			</g>
+			<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st6"/>
+			<text x="18.11" y="147.75" class="st4">PAD</text>		</g>
+		<g id="shape108-47" transform="translate(592.097,-5.34781)">
+			<title>Circle.62</title>
+			<desc>TX</desc>
+			<g id="shadow108-48" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st1">
+				<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st2"/>
+			</g>
+			<path d="M0 144.75 A26.6643 26.6643 0 0 1 53.33 144.75 A26.6643 26.6643 0 1 1 0 144.75 Z" class="st6"/>
+			<text x="21.63" y="147.75" class="st4">TX</text>		</g>
+		<g id="shape109-53" transform="translate(57.0653,-24.9255)">
+			<title>Dynamic connector.63</title>
+			<path d="M0 164.33 L37.69 164.33" class="st8"/>
+		</g>
+		<g id="shape110-59" transform="translate(155.125,-24.9255)">
+			<title>Dynamic connector.65</title>
+			<path d="M0 164.33 L37.69 164.33" class="st10"/>
+		</g>
+		<g id="shape111-64" transform="translate(253.186,-24.9255)">
+			<title>Dynamic connector.66</title>
+			<path d="M0 164.33 L37.69 164.33" class="st10"/>
+		</g>
+		<g id="shape112-69" transform="translate(351.246,-24.9255)">
+			<title>Dynamic connector.67</title>
+			<path d="M0 164.33 L37.69 164.33" class="st8"/>
+		</g>
+		<g id="shape113-74" transform="translate(449.306,-24.9255)">
+			<title>Dynamic connector.68</title>
+			<path d="M0 164.33 L37.69 164.33" class="st10"/>
+		</g>
+		<g id="shape114-79" transform="translate(547.366,-24.9255)">
+			<title>Dynamic connector.69</title>
+			<path d="M0 164.33 L37.69 164.33" class="st10"/>
+		</g>
+		<g id="shape115-84" transform="translate(645.426,-24.9255)">
+			<title>Dynamic connector.70</title>
+			<path d="M0 164.33 L37.69 164.33" class="st8"/>
+		</g>
+		<g id="shape116-89" transform="translate(174.599,68.9848) rotate(90)">
+			<title>Left Brace</title>
+			<g id="shadow116-90" transform="matrix(1,0,0,1,1.97279,-0.345598)" class="st1">
+				<path d="M28.35 171.41 A24.4921 16.4101 0 0 1 14.17 167.43 L14.17 95.44 L0 95.44 L14.17 95.44 L14.17 23.46 A24.4921
+							 16.4101 0 0 1 28.35 19.47" class="st11"/>
+			</g>
+			<path d="M28.35 171.41 A24.4921 16.4101 0 0 1 14.17 167.43 L14.17 95.44 L0 95.44 L14.17 95.44 L14.17 23.46 A24.4921 16.4101
+						 0 0 1 28.35 19.47" class="st12"/>
+		</g>
+		<g id="shape117-97" transform="translate(371.271,68.9848) rotate(90)">
+			<title>Left Brace.74</title>
+			<g id="shadow117-98" transform="matrix(1,0,0,1,1.97279,-0.345598)" class="st1">
+				<path d="M28.35 171.41 A23.1398 15.504 0 0 1 14.17 163.51 L14.17 95.44 L0 95.44 L14.17 95.44 L14.17 27.38 A23.1398
+							 15.504 0 0 1 28.35 19.47" class="st11"/>
+			</g>
+			<path d="M28.35 171.41 A23.1398 15.504 0 0 1 14.17 163.51 L14.17 95.44 L0 95.44 L14.17 95.44 L14.17 27.38 A23.1398 15.504
+						 0 0 1 28.35 19.47" class="st12"/>
+		</g>
+		<g id="shape118-105" transform="translate(212.048,-117.835)">
+			<title>Sheet.118</title>
+			<desc>Stage 2: Pad packets and enqueue crypto operations</desc>
+			<rect x="0" y="118.085" width="127.559" height="53.3286" class="st13"/>
+			<text x="13.85" y="133.95" class="st14">Stage 2: Pad packets <tspan x="14.65" dy="1.2em" class="st5">and enqueue crypto </tspan><tspan
+						x="37.46" dy="1.2em" class="st5">operations</tspan></text>		</g>
+		<g id="shape119-110" transform="translate(15.3756,-117.835)">
+			<title>Sheet.119</title>
+			<desc>Stage 1: Read packets from port</desc>
+			<rect x="0" y="118.085" width="127.559" height="53.3286" class="st13"/>
+			<text x="10.71" y="141.15" class="st14">Stage 1: Read packets <tspan x="40.13" dy="1.2em" class="st5">from port</tspan></text>		</g>
+		<g id="shape120-114" transform="translate(567.943,68.9848) rotate(90)">
+			<title>Left Brace.78</title>
+			<g id="shadow120-115" transform="matrix(1,0,0,1,1.97279,-0.345598)" class="st1">
+				<path d="M28.35 171.41 A37.9502 8.92454 0 0 1 14.17 166.08 L14.17 144.75 L0 144.75 L14.17 144.75 L14.17 123.42 A37.9502
+							 8.92454 0 0 1 28.35 118.09" class="st11"/>
+			</g>
+			<path d="M28.35 171.41 A37.9502 8.92454 0 0 1 14.17 166.08 L14.17 144.75 L0 144.75 L14.17 144.75 L14.17 123.42 A37.9502
+						 8.92454 0 0 1 28.35 118.09" class="st12"/>
+		</g>
+		<g id="shape121-122" transform="translate(371.106,-117.835)">
+			<title>Sheet.121</title>
+			<desc>Stage 3: Dequeue processed crypto operations</desc>
+			<rect x="0" y="118.085" width="99.248" height="53.3286" class="st13"/>
+			<text x="6.71" y="133.95" class="st14">Stage 3: Dequeue <tspan x="7.83" dy="1.2em" class="st5">processed crypto </tspan><tspan
+						x="23.31" dy="1.2em" class="st5">operations</tspan></text>		</g>
+		<g id="shape122-127" transform="translate(666.003,71.9952) rotate(90)">
+			<title>Left Brace.80</title>
+			<g id="shadow122-128" transform="matrix(1,0,0,1,1.97279,-0.345598)" class="st1">
+				<path d="M28.35 171.41 A22.2255 24.1253 0 0 1 14.17 161.02 L14.17 48.34 L0 48.34 L14.17 48.34 L14.17 -64.35 A22.2255
+							 24.1253 0 0 1 28.35 -74.74" class="st11"/>
+			</g>
+			<path d="M28.35 171.41 A22.2255 24.1253 0 0 1 14.17 161.02 L14.17 48.34 L0 48.34 L14.17 48.34 L14.17 -64.35 A22.2255
+						 24.1253 0 0 1 28.35 -74.74" class="st12"/>
+		</g>
+		<g id="shape123-135" transform="translate(553.887,-111.814)">
+			<title>Sheet.123</title>
+			<desc>Stage 4: Modify Packet MAC header and transmit</desc>
+			<rect x="0" y="118.085" width="127.559" height="53.3286" class="st13"/>
+			<text x="8.01" y="133.95" class="st14">Stage 4: Modify Packet <tspan x="22.85" dy="1.2em" class="st5">MAC header and </tspan><tspan
+						x="43.12" dy="1.2em" class="st5">transmit </tspan></text>		</g>
+	</g>
+</svg>
diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
index eea6a45..930f68c 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -47,6 +47,7 @@ Sample Applications User Guide
     ip_reassembly
     kernel_nic_interface
     keep_alive
+    l2_forward_crypto
     l2_forward_job_stats
     l2_forward_real_virtual
     l2_forward_cat
@@ -90,6 +91,8 @@ Sample Applications User Guide
 
 :numref:`figure_l2_fwd_virtenv_benchmark_setup` :ref:`figure_l2_fwd_virtenv_benchmark_setup`
 
+:numref:`figure_l2_fwd_encrypt_flow` :ref:`figure_l2_fwd_encrypt_flow`
+
 :numref:`figure_ipv4_acl_rule` :ref:`figure_ipv4_acl_rule`
 
 :numref:`figure_example_rules` :ref:`figure_example_rules`
diff --git a/doc/guides/sample_app_ug/l2_forward_crypto.rst b/doc/guides/sample_app_ug/l2_forward_crypto.rst
new file mode 100644
index 0000000..bffb17b
--- /dev/null
+++ b/doc/guides/sample_app_ug/l2_forward_crypto.rst
@@ -0,0 +1,467 @@
+..  BSD LICENSE
+    Copyright(c) 2016 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.
+
+.. _l2_fwd_crypto_app:
+
+L2 Forwarding with Crypto Sample Application
+============================================
+
+The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example of packet processing using
+the Data Plane Development Kit (DPDK), in conjunction with the Cryptodev library.
+
+Overview
+--------
+
+The L2 Forwarding with Crypto sample appplication performs a crypto operation (cipher/hash)
+specified by the user from command line (or using the default values),
+with a crypto device capable of doing that operation,
+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.
+Also, the MAC addresses are affected as follows:
+
+*   The source MAC address is replaced by the TX_PORT MAC address
+
+*   The destination MAC address is replaced by  02:00:00:00:00:TX_PORT_ID
+
+Compiling the Application
+-------------------------
+
+#.  Go to the example directory:
+
+    .. 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
+
+Running the Application
+-----------------------
+
+The application requires a number of command line options:
+
+.. 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] /
+    [--cipher_algo ALGO] [--cipher_op ENCRYPT/DECRYPT] [--cipher_key KEY] /
+    [--cipher_key_random_size SIZE] [--iv IV] [--iv_random_size SIZE] /
+    [--auth_algo ALGO] [--auth_op GENERATE/VERIFY] [--auth_key KEY] /
+    [--auth_key_random_size SIZE] [--aad AAD] [--aad_random_size SIZE] /
+    [--digest size SIZE] [--sessionless]
+
+where,
+
+*   p PORTMASK: A hexadecimal bitmask of the ports to configure (default is all the ports)
+
+*   q NQ: A number of queues (=ports) per lcore (default is 1)
+
+*   s: manage all ports from single core
+
+*   T PERIOD: statistics will be refreshed each PERIOD seconds
+
+    (0 to disable, 10 default, 86400 maximum)
+
+*   cdev_type: select preferred crypto device type: HW, SW or anything (ANY)
+
+    (default is ANY)
+
+*   chain: select the operation chaining to perform: Cipher->Hash (CIPHER_HASH),
+
+    Hash->Cipher (HASH_CIPHER), Cipher (CIPHER_ONLY), Hash(HASH_ONLY)
+
+    (default is Cipher->Hash)
+
+*   cipher_algo: select the ciphering algorithm (default is AES CBC)
+
+*   cipher_op: select the ciphering operation to perform: ENCRYPT or DECRYPT
+
+    (default is ENCRYPT)
+
+*   cipher_key: set the ciphering key to be used. Bytes has to be separated with ":"
+
+*   cipher_key_random_size: set the size of the ciphering key,
+
+    which will be generated randomly.
+
+    Note that if --cipher_key is used, this will be ignored.
+
+*   iv: set the IV to be used. Bytes has to be separated with ":"
+
+*   iv_random_size: set the size of the IV, which will be generated randomly.
+
+    Note that if --iv is used, this will be ignored.
+
+*   auth_algo: select the authentication algorithm (default is SHA1-HMAC)
+
+*   cipher_op: select the authentication operation to perform: GENERATE or VERIFY
+
+    (default is GENERATE)
+
+*   auth_key: set the authentication key to be used. Bytes has to be separated with ":"
+
+*   auth_key_random_size: set the size of the authentication key,
+
+    which will be generated randomly.
+
+    Note that if --auth_key is used, this will be ignored.
+
+*   aad: set the AAD to be used. Bytes has to be separated with ":"
+
+*   aad_random_size: set the size of the AAD, which will be generated randomly.
+
+    Note that if --aad is used, this will be ignored.
+
+*   digest_size: set the size of the digest to be generated/verified.
+
+*   sessionless: no crypto session will be created.
+
+
+The application requires that crypto devices capable of performing
+the specified crypto operation are available on application initialization.
+This means that HW crypto device/s must be bound to a DPDK driver or
+a SW crypto device/s (virtual crypto PMD) must be created (using --vdev).
+
+To run the application in linuxapp environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
+
+.. code-block:: console
+
+    $ ./build/l2fwd -c 0x3 -n 4 --vdev "cryptodev_aesni_mb_pmd" \
+    --vdev "cryptodev_aesni_mb_pmd" -- -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 SHA1_HMAC \
+    --auth_key 10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f
+
+Refer to the *DPDK Getting Started Guide* for general information on running applications
+and the Environment Abstraction Layer (EAL) options.
+
+Explanation
+-----------
+
+The L2 forward with Crypto application demonstrates the performance of a crypto operation
+on a packet received on a RX PORT before forwarding it to a TX PORT.
+
+The following figure illustrates a sample flow of a packet in the application,
+from reception until transmission.
+
+.. _figure_l2_fwd_encrypt_flow:
+
+.. figure:: img/l2_fwd_encrypt_flow.*
+
+   Encryption flow Through the L2 Forwarding with Crypto Application
+
+
+The following sections provide some explanation of the application.
+
+Crypto operation specification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All the packets received in all the ports get transformed by the crypto device/s
+(ciphering and/or authentication).
+The crypto operation to be performed on the packet is parsed from the command line
+(go to "Running the Application section for all the options).
+
+If no parameter is passed, the default crypto operation is:
+
+* Encryption with AES-CBC with 128 bit key.
+
+* Authentication with SHA1-HMAC (generation).
+
+* Keys, IV and AAD are generated randomly.
+
+There are two methods to pass keys, IV and ADD from the command line:
+
+* Passing the full key, separated bytes by ":"::
+
+   --cipher_key 00:11:22:33:44
+
+* Passing the size, so key is generated randomly::
+
+   --cipher_key_random_size 16
+
+**Note**:
+   If full key is passed (first method) and the size is passed as well (second method),
+   the latter will be ignored.
+
+Size of these keys are checked (regardless the method), before starting the app,
+to make sure that it is supported by the crypto devices.
+
+Crypto device initialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the cryption operation is defined, crypto devices are initialized.
+The crypto devices must be either bound to a DPDK driver (if they are physical devices)
+or created using the EAL option --vdev (if they are virtual devices),
+when running the application.
+
+The initialize_cryptodevs() function performs the device initialization.
+It iterates through the list of the available crypto devices and
+check which ones are capable of performing the operation.
+Each device has a set of capabilities associated with it,
+which are stored in the device info structure, so the function checks if the operation
+is within the structure of each device.
+
+The following code checks if the device supports the specified cipher algorithm
+(similar for the authentication algorithm):
+
+.. code-block:: c
+
+   /* Check if device supports cipher algo */
+   i = 0;
+   opt_cipher_algo = options->cipher_xform.cipher.algo;
+   cap = &dev_info.capabilities[i];
+   while (cap->op != RTE_CRYPTO_OP_TYPE_UNDEFINED) {
+           cap_cipher_algo = cap->sym.cipher.algo;
+           if (cap->sym.xform_type ==
+                           RTE_CRYPTO_SYM_XFORM_CIPHER) {
+                   if (cap_cipher_algo == opt_cipher_algo) {
+                           if (check_type(options, &dev_info) == 0)
+                                   break;
+                   }
+           }
+           cap = &dev_info.capabilities[++i];
+   }
+
+If a capable crypto device is found, key sizes are checked to see if they are supported
+(cipher key and IV for the ciphering):
+
+.. code-block:: c
+
+   /*
+    * Check if length of provided cipher key is supported
+    * by the algorithm chosen.
+    */
+   if (options->ckey_param) {
+           if (check_supported_size(
+                           options->cipher_xform.cipher.key.length,
+                           cap->sym.cipher.key_size.min,
+                           cap->sym.cipher.key_size.max,
+                           cap->sym.cipher.key_size.increment)
+                                   != 0) {
+                   printf("Unsupported cipher key length\n");
+                   return -1;
+           }
+   /*
+    * Check if length of the cipher key to be randomly generated
+    * is supported by the algorithm chosen.
+    */
+   } else if (options->ckey_random_size != -1) {
+           if (check_supported_size(options->ckey_random_size,
+                           cap->sym.cipher.key_size.min,
+                           cap->sym.cipher.key_size.max,
+                           cap->sym.cipher.key_size.increment)
+                                   != 0) {
+                   printf("Unsupported cipher key length\n");
+                   return -1;
+           }
+           options->cipher_xform.cipher.key.length =
+                                   options->ckey_random_size;
+   /* No size provided, use minimum size. */
+   } else
+           options->cipher_xform.cipher.key.length =
+                           cap->sym.cipher.key_size.min;
+
+After all the checks, the device is configured and it is added to the
+crypto device list.
+
+**Note**:
+   The number of crypto devices that supports the specified crypto operation
+   must be at least the number of ports to be used.
+
+Session creation
+~~~~~~~~~~~~~~~~
+
+The crypto operation has a crypto session associated to it, which contains
+information such as the transform chain to perform (e.g. ciphering then hashing),
+pointers to the keys, lengths... etc.
+
+This session is created and is later attached to the crypto operation:
+
+.. code-block:: c
+
+   static struct rte_cryptodev_sym_session *
+   initialize_crypto_session(struct l2fwd_crypto_options *options,
+                   uint8_t cdev_id)
+   {
+           struct rte_crypto_sym_xform *first_xform;
+
+           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->auth_xform;
+                   first_xform->next = &options->cipher_xform;
+           } else if (options->xform_chain == L2FWD_CRYPTO_CIPHER_ONLY) {
+                   first_xform = &options->cipher_xform;
+           } else {
+                   first_xform = &options->auth_xform;
+           }
+
+           /* Setup Cipher Parameters */
+           return rte_cryptodev_sym_session_create(cdev_id, first_xform);
+   }
+
+   ...
+
+   port_cparams[i].session = initialize_crypto_session(options,
+                                port_cparams[i].dev_id);
+
+Crypto operation creation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Given N packets received from a RX PORT, N crypto operations are allocated
+and filled:
+
+.. code-block:: c
+
+   if (nb_rx) {
+   /*
+    * If we can't allocate a crypto_ops, then drop
+    * the rest of the burst and dequeue and
+    * process the packets to free offload structs
+    */
+   if (rte_crypto_op_bulk_alloc(
+                   l2fwd_crypto_op_pool,
+                   RTE_CRYPTO_OP_TYPE_SYMMETRIC,
+                   ops_burst, nb_rx) !=
+                                   nb_rx) {
+           for (j = 0; j < nb_rx; j++)
+                   rte_pktmbuf_free(pkts_burst[i]);
+
+           nb_rx = 0;
+   }
+
+After filling the crypto operation (including session attachment),
+the mbuf which will be transformed is attached to it::
+
+   op->sym->m_src = m;
+
+Since no destination mbuf is set, the source mbuf will be overwritten
+after the operation is done (in-place).
+
+Crypto operation enqueueing/dequeueing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the operation has been created, it has to be enqueued in one of the crypto devices.
+Before doing so, for performance reasons, the operation stays in a buffer.
+When the buffer has enough operations (MAX_PKT_BURST), they are enqueued in the device,
+which will perform the operation at that moment:
+
+.. code-block:: c
+
+   static int
+   l2fwd_crypto_enqueue(struct rte_crypto_op *op,
+                   struct l2fwd_crypto_params *cparams)
+   {
+           unsigned lcore_id, len;
+           struct lcore_queue_conf *qconf;
+
+           lcore_id = rte_lcore_id();
+
+           qconf = &lcore_queue_conf[lcore_id];
+           len = qconf->op_buf[cparams->dev_id].len;
+           qconf->op_buf[cparams->dev_id].buffer[len] = op;
+           len++;
+
+           /* enough ops to be sent */
+           if (len == MAX_PKT_BURST) {
+                   l2fwd_crypto_send_burst(qconf, MAX_PKT_BURST, cparams);
+                   len = 0;
+           }
+
+           qconf->op_buf[cparams->dev_id].len = len;
+           return 0;
+   }
+
+   ...
+
+   static int
+   l2fwd_crypto_send_burst(struct lcore_queue_conf *qconf, unsigned n,
+                   struct l2fwd_crypto_params *cparams)
+   {
+           struct rte_crypto_op **op_buffer;
+           unsigned ret;
+
+           op_buffer = (struct rte_crypto_op **)
+                           qconf->op_buf[cparams->dev_id].buffer;
+
+           ret = rte_cryptodev_enqueue_burst(cparams->dev_id,
+                           cparams->qp_id, op_buffer, (uint16_t) n);
+
+           crypto_statistics[cparams->dev_id].enqueued += ret;
+           if (unlikely(ret < n)) {
+                   crypto_statistics[cparams->dev_id].errors += (n - ret);
+                   do {
+                           rte_pktmbuf_free(op_buffer[ret]->sym->m_src);
+                           rte_crypto_op_free(op_buffer[ret]);
+                   } while (++ret < n);
+           }
+
+           return 0;
+   }
+
+After this, the operations are dequeued from the device, and the transformed mbuf
+is extracted from the operation. Then, the operation is freed and the mbuf is
+forwarded as it is done in the L2 forwarding application.
+
+.. code-block:: c
+
+   /* Dequeue packets from Crypto device */
+   do {
+           nb_rx = rte_cryptodev_dequeue_burst(
+                           cparams->dev_id, cparams->qp_id,
+                           ops_burst, MAX_PKT_BURST);
+
+           crypto_statistics[cparams->dev_id].dequeued +=
+                           nb_rx;
+
+           /* Forward crypto'd packets */
+           for (j = 0; j < nb_rx; j++) {
+                   m = ops_burst[j]->sym->m_src;
+
+                   rte_crypto_op_free(ops_burst[j]);
+                   l2fwd_simple_forward(m, portid);
+           }
+   } while (nb_rx == MAX_PKT_BURST);
-- 
2.5.5

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2016-04-07 16:46 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-04-07 14:49 [dpdk-dev] [PATCH] doc: new l2fwd-crypto sample app guide Pablo de Lara
2016-04-07 15:59 ` Declan Doherty
2016-04-07 16:46   ` Thomas Monjalon

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).