diff options
Diffstat (limited to 'doc/guides/sample_app_ug/intel_quickassist.rst')
| -rw-r--r-- | doc/guides/sample_app_ug/intel_quickassist.rst | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/doc/guides/sample_app_ug/intel_quickassist.rst b/doc/guides/sample_app_ug/intel_quickassist.rst new file mode 100644 index 00000000..04d1593d --- /dev/null +++ b/doc/guides/sample_app_ug/intel_quickassist.rst @@ -0,0 +1,221 @@ +.. BSD LICENSE + Copyright(c) 2010-2014 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. + +Intel® QuickAssist Technology Sample Application +================================================ + +This sample application demonstrates the use of the cryptographic operations provided +by the Intel® QuickAssist Technology from within the DPDK environment. +Therefore, building and running this application requires having both the DPDK and +the QuickAssist Technology Software Library installed, as well as at least one +Intel® QuickAssist Technology hardware device present in the system. + +For this sample application, there is a dependency on either of: + +* Intel® Communications Chipset 8900 to 8920 Series Software for Linux* package + +* Intel® Communications Chipset 8925 to 8955 Series Software for Linux* package + +Overview +-------- + +An overview of the application is provided in :numref:`figure_quickassist_block_diagram`. +For simplicity, only two NIC ports and one Intel® QuickAssist Technology device are shown in this diagram, +although the number of NIC ports and Intel® QuickAssist Technology devices can be different. + +.. _figure_quickassist_block_diagram: + +.. figure:: img/quickassist_block_diagram.* + + Intel® QuickAssist Technology Application Block Diagram + + +The application allows the configuration of the following items: + +* Number of NIC ports + +* Number of logical cores (lcores) + +* Mapping of NIC RX queues to logical cores + +Each lcore communicates with every cryptographic acceleration engine in the system through a pair of dedicated input - output queues. +Each lcore has a dedicated NIC TX queue with every NIC port in the system. +Therefore, each lcore reads packets from its NIC RX queues and cryptographic accelerator output queues and +writes packets to its NIC TX queues and cryptographic accelerator input queues. + +Each incoming packet that is read from a NIC RX queue is either directly forwarded to its destination NIC TX port (forwarding path) +or first sent to one of the Intel® QuickAssist Technology devices for either encryption or decryption +before being sent out on its destination NIC TX port (cryptographic path). + +The application supports IPv4 input packets only. +For each input packet, the decision between the forwarding path and +the cryptographic path is taken at the classification stage based on the value of the IP source address field read from the input packet. +Assuming that the IP source address is A.B.C.D, then if: + +* D = 0: the forwarding path is selected (the packet is forwarded out directly) + +* D = 1: the cryptographic path for encryption is selected (the packet is first encrypted and then forwarded out) + +* D = 2: the cryptographic path for decryption is selected (the packet is first decrypted and then forwarded out) + +For the cryptographic path cases (D = 1 or D = 2), byte C specifies the cipher algorithm and +byte B the cryptographic hash algorithm to be used for the current packet. +Byte A is not used and can be any value. +The cipher and cryptographic hash algorithms supported by this application are listed in the crypto.h header file. + +For each input packet, the destination NIC TX port is decided at the forwarding stage (executed after the cryptographic stage, +if enabled for the packet) by looking at the RX port index of the dst_ports[ ] array, +which was initialized at startup, being the outport the adjacent enabled port. +For example, if ports 1,3,5 and 6 are enabled, for input port 1, outport port will be 3 and vice versa, +and for input port 5, output port will be 6 and vice versa. + +For the cryptographic path, it is the payload of the IPv4 packet that is encrypted or decrypted. + +Setup +~~~~~ + +Building and running this application requires having both the DPDK package and +the QuickAssist Technology Software Library installed, +as well as at least one Intel® QuickAssist Technology hardware device present in the system. + +For more details on how to build and run DPDK and Intel® QuickAssist Technology applications, +please refer to the following documents: + +* *DPDK Getting Started Guide* + +* Intel® Communications Chipset 8900 to 8920 Series Software for Linux* Getting Started Guide (440005) + +* Intel® Communications Chipset 8925 to 8955 Series Software for Linux* Getting Started Guide (523128) + +For more details on the actual platforms used to validate this application, as well as performance numbers, +please refer to the Test Report, which is accessible by contacting your Intel representative. + +Building the Application +------------------------ + +Steps to build the application: + +#. Set up the following environment variables: + + .. code-block:: console + + export RTE_SDK=<Absolute path to the DPDK installation folder> + export ICP_ROOT=<Absolute path to the Intel QAT installation folder> + +#. Set the target (a default target is used if not specified). For example: + + .. code-block:: console + + export RTE_TARGET=x86_64-native-linuxapp-gcc + + Refer to the *DPDK Getting Started Guide* for possible RTE_TARGET values. + +#. Build the application: + + .. code-block:: console + + cd ${RTE_SDK}/examples/dpdk_qat + make + +Running the Application +----------------------- + +Intel® QuickAssist Technology Configuration Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Intel® QuickAssist Technology configuration files used by the application are located in the config_files folder in the application folder. +There following sets of configuration files are included in the DPDK package: + +* Stargo CRB (single CPU socket): located in the stargo folder + + * dh89xxcc_qa_dev0.conf + +* Shumway CRB (dual CPU socket): located in the shumway folder + + * dh89xxcc_qa_dev0.conf + + * dh89xxcc_qa_dev1.conf + +* Coleto Creek: located in the coleto folder + + * dh895xcc_qa_dev0.conf + +The relevant configuration file(s) must be copied to the /etc/ directory. + +Please note that any change to these configuration files requires restarting the Intel® +QuickAssist Technology driver using the following command: + +.. code-block:: console + + # service qat_service restart + +Refer to the following documents for information on the Intel® QuickAssist Technology configuration files: + +* Intel® Communications Chipset 8900 to 8920 Series Software Programmer's Guide + +* Intel® Communications Chipset 8925 to 8955 Series Software Programmer's Guide + +* Intel® Communications Chipset 8900 to 8920 Series Software for Linux* Getting Started Guide. + +* Intel® Communications Chipset 8925 to 8955 Series Software for Linux* Getting Started Guide. + +Traffic Generator Setup and Application Startup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The application has a number of command line options: + + dpdk_qat [EAL options] -- -p PORTMASK [--no-promisc] [--config '(port,queue,lcore)[,(port,queue,lcore)]'] + +where, + +* -p PORTMASK: Hexadecimal bitmask of ports to configure + +* --no-promisc: Disables promiscuous mode for all ports, + so that only packets with the Ethernet MAC destination address set to the Ethernet address of the port are accepted. + By default promiscuous mode is enabled so that packets are accepted regardless of the packet's Ethernet MAC destination address. + +* --config'(port,queue,lcore)[,(port,queue,lcore)]': determines which queues from which ports are mapped to which cores. + +Refer to the :doc:`l3_forward` for more detailed descriptions of the --config command line option. + +As an example, to run the application with two ports and two cores, +which are using different Intel® QuickAssist Technology execution engines, +performing AES-CBC-128 encryption with AES-XCBC-MAC-96 hash, the following settings can be used: + +* Traffic generator source IP address: 0.9.6.1 + +* Command line: + + .. code-block:: console + + ./build/dpdk_qat -c 0xff -n 2 -- -p 0x3 --config '(0,0,1),(1,0,2)' + +Refer to the *DPDK Test Report* for more examples of traffic generator setup and the application startup command lines. +If no errors are generated in response to the startup commands, the application is running correctly. |