ceph/doc/radosgw/qat-accel.rst

   1 ===============================================
   2 QAT Acceleration for Encryption and Compression
   3 ===============================================
   4
   5 Intel QAT (QuickAssist Technology) can provide extended accelerated encryption
   6 and compression services by offloading the actual encryption and compression
   7 request(s) to the hardware QuickAssist accelerators, which are more efficient
   8 in terms of cost and power than general purpose CPUs for those specific
   9 compute-intensive workloads.
  10
  11 See `QAT Support for Compression`_ and `QAT based Encryption for RGW`_.
  12
  13
  14 QAT in the Software Stack
  15 =========================
  16
  17 Application developers can access QuickAssist features through the QAT API.
  18 The QAT API is the top-level API for QuickAssist technology, and enables easy
  19 interfacing between the customer application and the QuickAssist acceleration
  20 driver.
  21
  22 The QAT API accesses the QuickAssist driver, which in turn drives the
  23 QuickAssist Accelerator hardware. The QuickAssist driver is responsible for
  24 exposing the acceleration services to the application software.
  25
  26 A user can write directly to the QAT API, or the use of QAT can be done via
  27 frameworks that have been enabled by others including Intel (for example, zlib*,
  28 OpenSSL* libcrypto*, and the Linux* Kernel Crypto Framework).
  29
  30 QAT Environment Setup
  31 =====================
  32 1. QuickAssist Accelerator hardware is necessary to make use of accelerated
  33    encryption and compression services. And QAT driver in kernel space have to
  34    be loaded to drive the hardware.
  35
  36 The driver package can be downloaded from `Intel Quickassist Technology`_.
  37
  38 2. The implementation for QAT based encryption is directly base on QAT API which
  39    is included the driver package. But QAT support for compression depends on
  40    QATzip project, which is a user space library which builds on top of the QAT
  41    API. Currently, QATzip speeds up gzip compression and decompression at the
  42    time of writing.
  43
  44 See `QATzip`_.
  45
  46 Implementation
  47 ==============
  48 1. QAT based Encryption for RGW
  49
  50 `OpenSSL support for RGW encryption`_ has been merged into Ceph, and Intel also
  51 provides one `QAT Engine`_ for OpenSSL. So, theoretically speaking, QAT based
  52 encryption in Ceph can be directly supported through OpenSSl+QAT Engine.
  53
  54 But the QAT Engine for OpenSSL currently supports chained operations only, and
  55 so Ceph will not be able to utilize QAT hardware feature for crypto operations
  56 based on OpenSSL crypto plugin. As a result, one QAT plugin based on native
  57 QAT API is added into crypto framework.
  58
  59 2. QAT Support for Compression
  60
  61 As mentioned above, QAT support for compression is based on QATzip library in
  62 user space, which is designed to take full advantage of the performance provided
  63 by QuickAssist Technology. Unlike QAT based encryption, QAT based compression
  64 is supported through a tool class for QAT acceleration rather than a compressor
  65 plugin. The common tool class can transparently accelerate the existing compression
  66 types, but only zlib compressor can be supported at the time of writing. So
  67 user is allowed to use it to speed up zlib compressor as long as the QAT
  68 hardware is available and QAT is capable to handle it.
  69
  70 Configuration
  71 =============
  72 #. Prerequisites
  73
  74    Make sure the QAT driver with version v1.7.L.4.14.0 or higher has been installed.
  75    Remember to set an environment variable "ICP_ROOT" for your QAT driver package
  76    root directory.
  77
  78    To enable the QAT based encryption and compression, user needs to modify the QAT
  79    configuration files. For example, for Intel QuickAssist Adapter 8970 product, revise
  80    c6xx_dev0/1/2.conf in the directory ``/etc/`` and keep them the same, e.g.:
  81
  82    .. code-block:: ini
  83
  84       #...
  85       # User Process Instance Section
  86       ##############################################
  87       [CEPH]
  88       NumberCyInstances = 1
  89       NumberDcInstances = 1
  90       NumProcesses = 8
  91       LimitDevAccess = 1
  92       # Crypto - User instance #0
  93       Cy0Name = "SSL0"
  94       Cy0IsPolled = 1
  95       # List of core affinities
  96       Cy0CoreAffinity = 0
  97
  98       # Data Compression - User instance #0
  99       Dc0Name = "Dc0"
 100       Dc0IsPolled = 1
 101       # List of core affinities
 102       Dc0CoreAffinity = 0
 103
 104 #. QAT based Encryption for RGW
 105
 106    The CMake option ``WITH_QAT=ON`` must be configured. If you build Ceph from
 107    source code (see: :ref:`build-ceph`), navigate to your cloned Ceph repository
 108    and execute the following:
 109
 110    .. prompt:: bash $
 111
 112       cd ceph
 113       ./do_cmake.sh -DWITH_QAT=ON
 114       cd build
 115       ininja
 116
 117    .. note::
 118      The section name of the QAT configuration files must be ``CEPH`` since
 119      the section name is set as "CEPH" in Ceph crypto source code.
 120
 121    Then, edit the Ceph configuration file to make use of QAT based crypto plugin::
 122
 123       plugin crypto accelerator = crypto_qat
 124
 125 #. QAT Support for Compression
 126
 127    Before starting, make sure both QAT driver and `QATzip`_  have been installed. Besides
 128    "ICP_ROOT", remember to set the environment variable "QZ_ROOT" for the root directory
 129    of your QATzip source tree.
 130
 131    The following CMake options have to be configured to trigger QAT based compression
 132    when building Ceph:
 133
 134    .. prompt:: bash $
 135
 136       ./do_cmake.sh -DWITH_QAT=ON -DWITH_QATZIP=ON
 137
 138    Then, set an environment variable to clarify the section name of User Process Instance
 139    Section in QAT configuration files, e.g.:
 140
 141    .. prompt:: bash $
 142
 143       export QAT_SECTION_NAME=CEPH
 144
 145    Next, edit the Ceph configuration file to enable QAT support for compression::
 146
 147       qat compressor enabled=true
 148
 149
 150 .. _QAT Support for Compression: https://github.com/ceph/ceph/pull/19714
 151 .. _QAT based Encryption for RGW: https://github.com/ceph/ceph/pull/19386
 152 .. _Intel Quickassist Technology: https://01.org/intel-quickassist-technology
 153 .. _QATzip: https://github.com/intel/QATzip
 154 .. _OpenSSL support for RGW encryption: https://github.com/ceph/ceph/pull/15168
 155 .. _QAT Engine: https://github.com/intel/QAT_Engine