doc/guides/sample_app_ug/intel_quickassist.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 Intel® QuickAssist Technology Sample Application
  32 ================================================
  33
  34 This sample application demonstrates the use of the cryptographic operations provided
  35 by the Intel® QuickAssist Technology from within the Intel® DPDK environment.
  36 Therefore, building and running this application requires having both the Intel® DPDK and
  37 the QuickAssist Technology Software Library installed, as well as at least one
  38 Intel® QuickAssist Technology hardware device present in the system.
  39
  40 For this sample application, there is a dependency on either of:
  41
  42 *   Intel® Communications Chipset 8900 to 8920 Series Software for Linux* package
  43
  44 *   Intel® Communications Chipset 8925 to 8955 Series Software for Linux* package
  45
  46 Overview
  47 --------
  48
  49 An overview of the application is provided in Figure 11.
  50 For simplicity, only two NIC ports and one Intel® QuickAssist Technology device are shown in this diagram,
  51 although the number of NIC ports and Intel® QuickAssist Technology devices can be different.
  52
  53 .. _figure_11:
  54
  55 **Figure 11. Intel® QuickAssist Technology Application Block Diagram**
  56
  57 .. image14_png has been renamed
  58
  59 |quickassist_block_diagram|
  60
  61 The application allows the configuration of the following items:
  62
  63 *   Number of NIC ports
  64
  65 *   Number of logical cores (lcores)
  66
  67 *   Mapping of NIC RX queues to logical cores
  68
  69 Each lcore communicates with every cryptographic acceleration engine in the system through a pair of dedicated input - output queues.
  70 Each lcore has a dedicated NIC TX queue with every NIC port in the system.
  71 Therefore, each lcore reads packets from its NIC RX queues and cryptographic accelerator output queues and
  72 writes packets to its NIC TX queues and cryptographic accelerator input queues.
  73
  74 Each incoming packet that is read from a NIC RX queue is either directly forwarded to its destination NIC TX port (forwarding path)
  75 or first sent to one of the Intel® QuickAssist Technology devices for either encryption or decryption
  76 before being sent out on its destination NIC TX port (cryptographic path).
  77
  78 The application supports IPv4 input packets only.
  79 For each input packet, the decision between the forwarding path and
  80 the cryptographic path is taken at the classification stage based on the value of the IP source address field read from the input packet.
  81 Assuming that the IP source address is A.B.C.D, then if:
  82
  83 *   D = 0: the forwarding path is selected (the packet is forwarded out directly)
  84
  85 *   D = 1: the cryptographic path for encryption is selected (the packet is first encrypted and then forwarded out)
  86
  87 *   D = 2: the cryptographic path for decryption is selected (the packet is first decrypted and then forwarded out)
  88
  89 For the cryptographic path cases (D = 1 or D = 2), byte C specifies the cipher algorithm and
  90 byte B the cryptographic hash algorithm to be used for the current packet.
  91 Byte A is not used and can be any value.
  92 The cipher and cryptographic hash algorithms supported by this application are listed in the crypto.h header file.
  93
  94 For each input packet, the destination NIC TX port is decided at the forwarding stage (executed after the cryptographic stage,
  95 if enabled for the packet) by looking at the RX port index of the dst_ports[ ] array,
  96 which was initialized at startup, being the outport the adjacent enabled port.
  97 For example, if ports 1,3,5 and 6 are enabled, for input port 1, outport port will be 3 and vice versa,
  98 and for input port 5, output port will be 6 and vice versa.
  99
 100 For the cryptographic path, it is the payload of the IPv4 packet that is encrypted or decrypted.
 101
 102 Setup
 103 ~~~~~
 104
 105 Building and running this application requires having both the Intel® DPDK package and
 106 the QuickAssist Technology Software Library installed,
 107 as well as at least one Intel® QuickAssist Technology hardware device present in the system.
 108
 109 For more details on how to build and run Intel® DPDK and Intel® QuickAssist Technology applications,
 110 please refer to the following documents:
 111
 112 *   *Intel® DPDK Getting Started Guide*
 113
 114 *   Intel® Communications Chipset 8900 to 8920 Series Software for Linux* Getting Started Guide (440005)
 115
 116 *   Intel® Communications Chipset 8925 to 8955 Series Software for Linux* Getting Started Guide (523128)
 117
 118 For more details on the actual platforms used to validate this application, as well as performance numbers,
 119 please refer to the Test Report, which is accessible by contacting your Intel representative.
 120
 121 Building the Application
 122 ------------------------
 123
 124 Steps to build the application:
 125
 126 #.  Set up the following environment variables:
 127
 128     .. code-block:: console
 129
 130         export RTE_SDK=<Absolute path to the Intel DPDK installation folder>
 131         export ICP_ROOT=<Absolute path to the Intel QAT installation folder>
 132
 133 #.  Set the target (a default target is used if not specified). For example:
 134
 135     .. code-block:: console
 136
 137         export RTE_TARGET=x86_64-native-linuxapp-gcc
 138
 139     Refer to the *Intel® DPDK Getting Started Guide* for possible RTE_TARGET values.
 140
 141 #.  Build the application:
 142
 143     .. code-block:: console
 144
 145         cd ${RTE_SDK}/examples/dpdk_qat
 146         make
 147
 148 Running the Application
 149 -----------------------
 150
 151 Intel® QuickAssist Technology Configuration Files
 152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 153
 154 The Intel® QuickAssist Technology configuration files used by the application are located in the config_files folder in the application folder.
 155 There following sets of configuration files are included in the Intel® DPDK package:
 156
 157 *   Stargo CRB (single CPU socket): located in the stargo folder
 158
 159     *   dh89xxcc_qa_dev0.conf
 160
 161 *   Shumway CRB (dual CPU socket): located in the shumway folder
 162
 163     *   dh89xxcc_qa_dev0.conf
 164
 165     *   dh89xxcc_qa_dev1.conf
 166
 167 *   Coleto Creek: located in the coleto folder
 168
 169     *   dh895xcc_qa_dev0.conf
 170
 171 The relevant configuration file(s) must be copied to the /etc/ directory.
 172
 173 Please note that any change to these configuration files requires restarting the Intel®
 174 QuickAssist Technology driver using the following command:
 175
 176 .. code-block:: console
 177
 178     # service qat_service restart
 179
 180 Refer to the following documents for information on the Intel® QuickAssist Technology configuration files:
 181
 182 *   Intel®  Communications Chipset 8900 to 8920 Series Software Programmer's Guide
 183
 184 *   Intel®  Communications Chipset 8925 to 8955 Series Software Programmer's Guide
 185
 186 *   Intel®  Communications Chipset 8900 to 8920 Series Software for Linux* Getting Started Guide.
 187
 188 *   Intel®  Communications Chipset 8925 to 8955 Series Software for Linux* Getting Started Guide.
 189
 190 Traffic Generator Setup and Application Startup
 191 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 192
 193 The application has a number of command line options:
 194
 195     dpdk_qat [EAL options] -- -p PORTMASK [--no-promisc] [--config '(port,queue,lcore)[,(port,queue,lcore)]']
 196
 197 where,
 198
 199 *   -p PORTMASK: Hexadecimal bitmask of ports to configure
 200
 201 *   --no-promisc: Disables promiscuous mode for all ports,
 202     so that only packets with the Ethernet MAC destination address set to the Ethernet address of the port are accepted.
 203     By default promiscuous mode is enabled so that packets are accepted regardless of the packet's Ethernet MAC destination address.
 204
 205 *   --config'(port,queue,lcore)[,(port,queue,lcore)]':  determines which queues from which ports are mapped to which cores.
 206
 207 Refer to Chapter 10 , "L3 Forwarding Sample Application" for more detailed descriptions of the --config command line option.
 208
 209 As an example, to run the application with two ports and two cores,
 210 which are using different Intel® QuickAssist Technology execution engines,
 211 performing AES-CBC-128 encryption with AES-XCBC-MAC-96 hash, the following settings can be used:
 212
 213 *   Traffic generator source IP address: 0.9.6.1
 214
 215 *   Command line:
 216
 217     .. code-block:: console
 218
 219         ./build/dpdk_qat -c 0xff -n 2 -- -p 0x3 --config '(0,0,1),(1,0,2)'
 220
 221 Refer to the *Intel® DPDK Test Report* for more examples of traffic generator setup and the application startup command lines.
 222 If no errors are generated in response to the startup commands, the application is running correctly.
 223
 224 .. |quickassist_block_diagram| image:: img/quickassist_block_diagram.png