Sample Applications

The software package contains a performance sample as well as functional sample applications. This section describes the steps required to build and execute these applications.

Performance Sample Code

The sample application is provided for the user space.

Compiling the Performance Sample Code

Note

• These instructions assume the software package was untarred in the $ICP_ROOT directory.

• For details on running user space applications as non-root user refer to the section Running Applications as Non-Root User.

1. Open a terminal window and switch to superuser. Provide root password when prompted.

   su
   

2. Switch to the $ICP_ROOT directory and compile the installation samples.

   cd $ICP_ROOT
   make samples-install
   

This compiles the acceleration sample code for user space. It also compiles the memory mapping driver used with the user space application.

Note

The command above also builds the functional sample applications described in Functional Sample Applications.

Default Configuration Files

By default, the QAT configuration files enable asymmetric crypto and data compression services. If symmetric crypto is desired, the service must be enabled in the QAT configuration file. The QAT configuration files are included in /etc folder and are named 4xxx_dev<x>.conf where x is the device number.

In this file, replace the line:

ServicesEnabled = asym;dc

With:

ServicesEnabled = sym;dc

Default Configuration Demo

Here is a demonstration of how to enable the asymmetric crypto service in the default configuration files.

Loading the Sample Code Application

Note

In user space, before launching the cpa_sample_code application, the environmental variable LD_LIBRARY_PATH may need to be set to the path where libqat_s.so is located. This may be /usr/local/lib or $ICP_ROOT/build.

The acceleration kernel module must be installed and the software must be started before attempting to execute the sample code. This can be verified by running the following commands:

lsmod | grep "qa"
service qat_service status

Typical output is similar to the following:

$ lsmod | grep "qa"
qat_4xxx               61440  0
intel_qat             401408  2 qat_4xxx,usdm_drv
uio                    20480  1 intel_qat
irqbypass              16384  4 intel_qat,vfio_pci_core,idxd_mdev,kvm

$ service qat_service status
Checking status of all devices.
There is 8 QAT acceleration device(s) in the system:
qat_dev0 - type: 4xxx,  inst_id: 0,  node_id: 0,  bsf: 0000:6b:00.0,  #accel: 1 #engines: 9 state: up
qat_dev1 - type: 4xxx,  inst_id: 1,  node_id: 0,  bsf: 0000:70:00.0,  #accel: 1 #engines: 9 state: up
qat_dev2 - type: 4xxx,  inst_id: 2,  node_id: 0,  bsf: 0000:75:00.0,  #accel: 1 #engines: 9 state: up
qat_dev3 - type: 4xxx,  inst_id: 3,  node_id: 0,  bsf: 0000:7a:00.0,  #accel: 1 #engines: 9 state: up
qat_dev4 - type: 4xxx,  inst_id: 4,  node_id: 1,  bsf: 0000:e8:00.0,  #accel: 1 #engines: 9 state: up
qat_dev5 - type: 4xxx,  inst_id: 5,  node_id: 1,  bsf: 0000:ed:00.0,  #accel: 1 #engines: 9 state: up
qat_dev6 - type: 4xxx,  inst_id: 6,  node_id: 1,  bsf: 0000:f2:00.0,  #accel: 1 #engines: 9 state: up
qat_dev7 - type: 4xxx,  inst_id: 7,  node_id: 1,  bsf: 0000:f7:00.0,  #accel: 1 #engines: 9 state: up

Note

If the modules are not returned from the first command, refer to the installation instructions for additional information on starting the acceleration software.

In user space, the sample code is executed with the command:

./build/cpa_sample_code

Sample Code Parameters

The application allows the run-time parameters listed below:

Sample Code Parameters

Parameter	Description
cyNumBuffers=w	Number of buffers submitted for each iteration. (default=20)
cySymLoops=x	Number of iterations of all symmetric code tests. (default= 5000)
cyAsymLoops=y	Number of iterations of all asymmetric code tests. (default=5000)
runTests=1	Run symmetric code tests.
runTests=2	Run RSA test code.
runTests=4	Run DSA test code.
runTests=8	Run ECDSA test code.
runTests=16	Run Diffie-Hellman code tests.
runTests=32	Run compression code tests.
runTests=63	Run all tests except the chained hash and compression tests. (default)
runTests=128	Run chained hash and compression test code.
runStateful=1	Enable stateful compression tests. Applies when compression code tests are run.
signOfLife=1	Indicates shorter test run that verifies the acceleration software is working. This parameter executes a subset of sample tests. Details are included in signOfLife Test Parameter. (default=0)
getLatency=1	Measures the processing time for the request being processed. Requires NumberCyInstances=1 and NumberDcInstances=1 to be configured in [SSL] section of the driver configuration file. Performance sample code needs to be compiled with flag to enable latency measurements. make samples-install LATENCY_CODE=1
getOffloadCost=1	Measures the average number of cycles spent for single request offloading. Requires NumberCyInstances=1 and NumberDcInstances=1 to be configured in [SSL] section of the driver configuration file.
includeLZ4=1	Include LZ4 compression tests. Applies when compression code tests are run.

signOfLife Test Parameter

The signOfLife parameter is used to specify that a subset of the sample tests are executed with smaller iteration counts. This provides a quick test to verify the acceleration software and hardware are set up correctly.

Note

If the signOfLife parameter is not specified, the full run of tests can take a significant amount of time to complete.

User Space

After installing the sample code, the user space application is located at /usr/local/bin and $ICP_ROOT/build.

Then run the following commands:

cpa_sample_code signOfLife=1

Test Results

When running the application, the results are printed to the terminal window in which the application is launched.

Here is an example of the log messages created during the test:

Algorithm Chaining - AES256-CBC HMAC-SHA512 Number of threads 2
Total Submissions 20
Total Responses 20
Packet Size 512

A similar pattern is repeated for each of the tests.

Note

During asymmetric crypto tests, warning messages similar to the following may be observed:

ECDSA Warning! SYMMETRIC operation is not supported on Instance. Using calcSWDigest instead.

These warning messages can be safely ignored. The test itself is working as designed.

Performance Sample Code Demo

Here is a demonstration of the performance sample code running.

Functional Sample Applications

The software package contains sample code that demonstrates how to use the Intel^® QuickAssist Technology APIs and build the structures required for various use cases.

For more details, refer to the Intel^® QuickAssist Technology API Programmer’s Guide.

Compiling the Acceleration Functional Sample Code

Note

These instructions assume the software package has been untarred to the $ICP_ROOT directory.

The acceleration functional sample code can be compiled manually.

Note

This step is not required if make samples-install command was issued in the Performance Sample Code section.

1. Compile for the user space using the following commands:

   cd $ICP_ROOT/quickassist/lookaside/access_layer/src/sample_code/functional
   make all
   

The generated sample applications are located at: $ICP_ROOT/quickassist/lookaside/access_layer/src/sample_code/functional/build

Executing the Acceleration Functional Sample Code in User Space

1. To execute the acceleration functional sample code in user space, use a command similar to the following:

   cd $ICP_ROOT/quickassist/lookaside/access_layer/src/sample_code/functional/build
   ./hash_file_sample
   

Note

The hash_file_sample is one of the functional user space applications. You can launch the other user space applications in a similar fashion.