===============================================================================
August 2022
===============================================================================

Quick References
================

    - https://intel.com/quickassist (marketing/overview)
    
	- https://developer.intel.com/quickassist (developers)

	- Intel® QuickAssist (QAT) Message of the Week (Full Collateral List)
	  https://cdrdv2.intel.com/v1/dl/getContent/738128 (requires account)
    
    - Getting Started Guides:

Intel® QuickAssist Technology Software for Linux* - Getting Started Guide - HW version 1.7
https://cdrdv2.intel.com/v1/dl/getContent/710059 (public)

Intel® QuickAssist Technology Software for Linux* - Getting Started Guide - HW version 1.8
https://cdrdv2.intel.com/v1/dl/getContent/729701 (requires account)

Intel® QuickAssist Technology Software for Linux* - Getting Started Guide - HW version 2.0
https://cdrdv2.intel.com/v1/dl/getContent/632506 (requires account)

    - Programmer's Guides:

Intel® QuickAssist Technology Software for Linux* - Programmer's Guide - HW version 1.7
https://cdrdv2.intel.com/v1/dl/getContent/710060 (public)

Intel® QuickAssist Technology Software for Linux* - Programmer's Guide - HW version v1.8
https://cdrdv2.intel.com/v1/dl/getContent/613626 (requires account)

Intel® QuickAssist Technology Software for Linux* - Programmer's Guide - HW version 2.0
(TBD)

===============================================================================

Overview
=========

Intel® QuickAssist Technology provides cryptographic and compression acceleration
capabilities used to improve performance and efficiency across the data center.

Note: This README applies to QAT1.7, QAT1.8, and QAT2.0 devices. Not all 
sections may apply to your device generation.

Previously existing build system has been replaced by Autotools solution
in order to provide with the widely known and easy to use tool to build and
install source packages.

===============================================================================

Licensing
==========

The Licensing of the files within this project splits under various set of
licenses which are listed below.
 - Dual BSD/GPLv2 License
 - BSD License
 - GPLv2 License
 - OpenSSL License
 - ZLIB License

For full GPLv2 License, please see the file LICENSE.GPL contained in the top
level folder.
For full OpenSSL License, please see the file LICENSE.OPENSSL contained in
the top level folder.
For Dual BSD/GPLv2, BSD and ZLIB Licenses, please see the file headers of
the relevant files.

Binary files are provided under the binary redistribution license. Please see
the file binary-redistribution-license.txt contained in the top level folder. 


===============================================================================

Compilation and installation

===============================================================================

1) QAT compilation requires the following dependencies:

	Libraries:
	- libboost	>= 1.14
	- libudev	>= 1.47

	Tools:
	- gcc		>= 4.4.7
	- g++		>= 4.4.7
	- pkg-config	>= 0.9.0

1.1) (QAT2.0 Hardware)
	Development packages:
	- zlib 		>= 1.2.3
	- yasm

1.2) (QAT2.0 Hardware)
	Static libraries included in QAT software package:
	- isa-l          = 2.26

===============================================================================

2) Configuration process:

	To setup the default build configuration - call:
	./configure

	Any other configuration setup can be found under
	"configuration options section" or by calling:

	./configure --help

===============================================================================

3) Compilation process:

	After the package has been configured properly,
	follow the steps below:

	Build and install:
	# make
	# make install

	Build and install sample code:
	# make samples
	# make samples-install

	Uninstall and clean up:
	# make uninstall
	# make clean
	# make distclean

NOTE: If kernel module signing is required for the QAT out-of-tree drivers, (e.g. if UEFI
      Secure Boot is enabled), one can incorporate this step by setting the 'mod_sign_cmd' 
      environment variable prior to invoking the 'make install' command.

      The mod_sign_cmd environment variable should be set to the path of the required kernel 
      headers sign-file program and include it's first three command line arguments.
      e.g.:

      # export mod_sign_cmd='<kernel header path>/scripts/sign-file sha256 /root/priv.key /root/pub.der'

===============================================================================

4) Configuration options

    These are common examples of the configure command:

    # ./configure ICP_ANY_FLAG=path or
    # ./configure --enable-something

    If it is required to use more than one flag at once:

        ./configure ICP_ANY_PATH=path ICP_ANY_NAME=name --enable-something

Options are split into two following sections:

Build flags:
	This set of flags has to be set (initial values are assigned by default)
	in order to process the proper QAT build.

	If a different setup if required - flags can be easily modified.

	Warning.
	Please keep in mind that any incorrect change might cause
	compilation problems - in such case default configuration setup is
	recommended to fix it.

	ICP_ROOT
		Path to the directory where acceleration software is extracted.
		(QAT package root directory)
	
		Type: path
		Default value: `pwd`

	ICP_BUILDSYSTEM_PATH
		Path to build system folder located under
		the quickassist directory.

		Type: path
		Default value: `pwd`/quickassist/build_system

	ICP_BUILD_OUTPUT
		Path to the output build directory where
		executables/libraries will be placed.

		Type: path
		Default value: `pwd`/build

	ICP_ENV_DIR
		Path to the directory containing the environment build files.

		Type: path
		Default value: pwd`/quickassist/build_system/build_files/ env_files

	ICP_TOOLS_TARGET
		Software platform target (Set ‘accelcomp’ for Intel® Communications
		Chipset Series Software platforms).

		Type: name
		Default value: accelcomp

	SYSROOT
        (QAT2.0 Hardware)
		Set the logical root directory for headers and libraries. This variable
		is used for cross-compilation. This variable is optional.

		Type: path
		Default value: none


Features flags:
	Enables or disables the additional features supported by QAT package

	--disable-option-checking
        (QAT 1.7/1.8 Hardware)
		Ignores unrecognized configure options when run along with it.

	--enable-icp-debug
		Enables debugging.

	--enable-qat-uio
        (QAT2.0 Hardware)
		Enables Userspace I/O.

	--disable-param-check
		Disables parameters checking in the top-level APIs
		(Use for performance optimization).

	--disable-dc-dyn
        (QAT2.0 Hardware)
                Disables Dynamic compression support.

	--disable-stats
		Disables statistic collection (Use for performance optimization).

	--enable-drbg-poll-and-wait
        (QAT2.0 Hardware)
		Modifies the behavior of DRBG HT functions to use
		single threaded operation.

	--enable-icp-log-syslog
		Enables debugging messages to be outputted to the
		system log instead of standard output.

	--enable-icp-nonblocking-partials-perform
		Partial operations results are not being blocked.

	--enable-icp-sriov
		Enables Single-root I/O Virtualization in the QAT
		driver (available options: host, guest).

		Due to not common calling convention there is an example of
		invoke possibility:

		./configure --enable-icp-sriov=host or
		./configure --enable-icp-sriov=guest

	--enable-icp-trace
		Enables tracing for the Cryptography API.

	--enable-icp-asym-only
        (QAT2.0 Hardware)
		Enables driver to support asymmetric crypto
		services only.

	--enable-icp-sym-only
        (QAT2.0 Hardware)
		Enables driver to support symmetric crypto
		services only.

	--enable-icp-dc-only
		Enables driver supports only compression service
		(Can optimize size of build objects).

	--enable-icp-dc-sym-only
		Enables driver to support data compression and
		symmetric crypto services only.

	--enable-icp-dc-return-counters-on-error
		Enables updates of consumed/produced results in case of
                error during compression or decompression operations.

	--enable-icp-hb-fail-sim
        (QAT 1.7/1.8 Hardware)
		Enable Heartbeat Failure Simulation.

	--enable-qat-coexistence
		Enable driver co-existence with legacy 1.6 driver.

	--enable-qat-lkcf
		Enables QAT registration with Linux Kernel Crypto
		Framework

	--disable-dc-strict-mode
        (QAT 1.7/1.8 Hardware)
		Disables strict mode for data compression.

	--enable-dc-error-simulation
        (QAT 1.7/1.8 Hardware)
		Enables Data Compression Error Simulation.

	--enable-kapi
        (QAT 1.7/1.8 Hardware)
		Enables Intel(R) QuickAssist API in Kernel space.

	--enable-icp-without-thread
        (QAT 1.7/1.8 Hardware)
		Removes mutex and spin locks for single thread applications.

	--enable-legacy-algorithms
        (QAT 1.7+ only)
		Enable legacy algorithms.

	MAX_MR
		Number of Miller Rabin rounds for prime operations. Setting this
		to a smaller value reduces the memory usage required by the
		driver.

		Type: value
		Default value: 50

	KERNEL_SOURCE_ROOT
		Path to kernel sources directory.

		Type: path
		Default value: /lib/modules/`uname –r`/build/

        USE_HARD_CODED_PRIMES
        (QAT2.0 Hardware)
		Is auto enabled for C4XXX device to use pregenerated primes for 
                sample code use

                Type: value
                Auto value: 1 for C4XXX device and 0 for all other devices 

===============================================================================

5) Known Issues

The current build system does not support dependency checking functionality
which cause a call of clean during make.

To avoid building the QAT package twice, first during "make" and second during
"make install" call, it is recommended to call only the "make install", omitting "make":

	make install

This same issue applies to "make samples" and "make samples-install".


Legal/Disclaimers
===================

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL(R) PRODUCTS.
NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL
PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S 
TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY 
WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO 
SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING 
TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY 
PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are 
not intended for use in medical, life saving, life sustaining, critical control
 or safety systems, or in nuclear facility applications.

Intel may make changes to specifications and product descriptions at any time,
without notice.

(C) Intel Corporation 2022

* Other names and brands may be claimed as the property of others.

===============================================================================

