===============================================================================
November 2022
===============================================================================

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

    - https://intel.com/quickassist (overview)

      https://developer.intel.com/quickassist (developers)

    - Intel® QuickAssist Technology (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 - Customer Enabling Release
https://cdrdv2.intel.com/v1/dl/getContent/710059 (public)

    - Programmer's Guides:

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

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

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 and QAT1.8 devices. Not all
sections may apply to your device generation.

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

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
 - APACHE License
 - ZLIB License

For full GPLv2 License, please see the file LICENSE.GPL contained in the top
level folder.
For full APACHE License, please see the file LICENSE.APACHE 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
    - zlib       >= 1.2.3

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

    Development packages:
    - nasm

1.1)
    - libnl              (QAT 1.8 HW)

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

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 its 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
    # ./configure --enable-something
    # ./configure ICP_ANY_PATH=path ICP_ANY_NAME=name --enable-something

    Options are split into the two following sections: Feature flags and Build flags.

Feature flags:

    Enables or disables the additional features supported by QAT package.

    --disable-option-checking               (QAT 1.7/1.8 HW)
        Ignores unrecognized configure options.

    --enable-icp-debug
        Enables debugging.
        Warning: This option should never be enabled in a production environment
        as it may output private key information to the console/logs and may also
        introduce side channel timing attack vulnerabilities (disabled by default).

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

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

    --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.

        Example:
        ./configure --enable-icp-sriov=host
        ./configure --enable-icp-sriov=guest

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

    --enable-icp-sym-only
        Enables symmetric crypto services only.

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

    --enable-icp-dc-sym-only
        Enables 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 HW)
        Enable Heartbeat Failure Simulation.

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

    --disable-dc-strict-mode                (QAT 1.7/1.8 HW)
        Disables strict mode for data compression.
        Warning: Compressed data might not be de-compressible.

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

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

    --enable-legacy-algorithms              (QAT 1.7 and above)
        Enable legacy algorithms.

     --enable-icp-thread-specific-usdm
        USDM allocates and handles memory specific to threads.
        (For multi-thread apps, allocated memory information will be
        maintained separately for each thread).

     --enable-128k-slab
        Enables 128k slab allocator in USDM. It could improve performance
        and reduce memory consumption for the large amount of threads when
        thread specific memory allocator is enabled.

Build flags:

    This set of flags have to be set in order to process a proper QAT build.
    (Initial values are assigned by default)

    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 output 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

    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/

    DESTDIR
        An absolute path to a temporary staging directory. It allows redirecting
        the installation of all QuickAssist user-space components to DESTDIR,
        while retaining the usual directory structure inside DESTDIR.
        Must be always used in conjunction with INSTALL_MOD_PATH.

        Type: path
        Default value: none

    INSTALL_MOD_PATH
        An absolute path to a temporary staging directory. It allows redirecting
        the installation of all QuickAssist kernel modules to INSTALL_MOD_PATH,
        while retaining the usual directory structure inside INSTALL_MOD_PATH.
        Must be always used in conjunction with DESTDIR.

        Type: path
        Default value: none

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

5) Cross-compilation

To cross-compile this package on a build host with the intention of using
QuickAssist stack on another target host, the user is required to invoke "make"
with three build flags: KERNEL_SOURCE_ROOT, DESTDIR, and INSTALL_MOD_PATH.

DESTDIR and INSTALL_MOD_PATH can point to the same directory, but both must
always be set.
    # make install KERNEL_SOURCE_ROOT=/usr/src/kernels/6.8.5-301.fc40.x86_64 \
    #              DESTDIR=/home/user/install-user \
    #              INSTALL_MOD_PATH=/home/user/install-modules

Note:
    The build host is not aware of the details of the target host's configuration.
    Therefore, the installation process in a cross-compilation scenario skips target
    host dependent steps.
    It is the user's responsibility to properly configure the target host,
    e.g. deploy files from the staging directory to appropriate system locations,
    provide a QAT configuration file, set up QAT services, update system's library
    cache, reload udev rules, etc.

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

6) 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", it is recommended to invoke only "make install" omitting "make".

     # make install

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

     # 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.

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

