d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
ad8f40dabe
numam-dpdk/doc/guides/sample_app_ug/intel_quickassist.rst
John McNamara 4a22e6ee3d doc: refactor figure numbers into references 
This change adds automatic figure references to the docs. The
figure numbers in the generated Html and PDF docs are now
automatically numbered based on section.

Requires Sphinx >= 1.3.1.

The patch makes the following changes.

* Changes image:: tag to figure:: and moves image caption
  to the figure.

* Adds captions to figures that didn't previously have any.

* Un-templates the |image-name| substitution definitions
  into explicit figure:: tags. They weren't used more
  than once anyway and Sphinx doesn't support them
  for figure.

* Adds a target to each image that didn't previously
  have one so that they can be cross-referenced.

* Renamed existing image target to match the image
  name for consistency.

* Replaces the Figures lists with automatic :numref:
  :ref: entries to generate automatic numbering
  and captions.

* Replaces "Figure" references with automatic :numref:
  references.

Signed-off-by: John McNamara <john.mcnamara@intel.com>
2015-05-25 15:59:36 +02:00

222 lines
9.4 KiB
ReStructuredText
Raw Blame History

.. 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 Chapter 10 , "L3 Forwarding Sample Application" 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.
Reference in New Issue View Git Blame Copy Permalink