From: Miaomiao Liu <miaomiao.liu@intel.com>
Date: Fri, 21 Jan 2022 07:45:44 +0000 (+0800)
Subject: doc/radosgw: update QAT acceleration to specify the configuration
X-Git-Tag: v18.0.0~1479^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F44707%2Fhead;p=ceph.git

doc/radosgw: update QAT acceleration to specify the configuration

add and change the configuration steps to enable latest version of QAT
driver on QAT based encryption and compression

Signed-off-by: Miaomiao Liu <miaomiao.liu@intel.com>
---

diff --git a/doc/install/build-ceph.rst b/doc/install/build-ceph.rst
index f6e6e6e8bb5d..28f1163ff8bd 100644
--- a/doc/install/build-ceph.rst
+++ b/doc/install/build-ceph.rst
@@ -29,6 +29,8 @@ and tools::
 .. note:: Some distributions that support Google's memory profiler tool may use
    a different package name (e.g., ``libgoogle-perftools4``).
 
+.. _build-ceph:
+
 Build Ceph
 ==========
 
diff --git a/doc/radosgw/qat-accel.rst b/doc/radosgw/qat-accel.rst
index 4e661c63d015..90d65346e3af 100644
--- a/doc/radosgw/qat-accel.rst
+++ b/doc/radosgw/qat-accel.rst
@@ -69,21 +69,82 @@ hardware is available and QAT is capable to handle it.
 
 Configuration
 =============
-1. QAT based Encryption for RGW 
-
-Edit the Ceph configuration file to make use of QAT based crypto plugin::
-
-    plugin crypto accelerator = crypto_qat
-
-2. QAT Support for Compression
-
-One CMake option have to be used to trigger QAT based compression::
-
-    -DWITH_QATZIP=ON
-
-Edit the Ceph configuration file to enable QAT support for compression::
-
-    qat compressor enabled=true
+#. Prerequisites
+
+   Make sure the QAT driver with version v1.7.L.4.14.0 or higher has been installed.
+   Remember to set an environment variable "ICP_ROOT" for your QAT driver package
+   root directory. 
+
+   To enable the QAT based encryption and compression, user needs to modify the QAT
+   configuration files. For example, for Intel QuickAssist Adapter 8970 product, revise 
+   c6xx_dev0/1/2.conf in the directory ``/etc/`` and keep them the same, e.g.:
+
+   .. code-block:: ini
+        
+      #...
+      # User Process Instance Section
+      ##############################################
+      [CEPH]
+      NumberCyInstances = 1
+      NumberDcInstances = 1
+      NumProcesses = 8
+      LimitDevAccess = 1
+      # Crypto - User instance #0
+      Cy0Name = "SSL0"
+      Cy0IsPolled = 1
+      # List of core affinities
+      Cy0CoreAffinity = 0
+       
+      # Data Compression - User instance #0
+      Dc0Name = "Dc0"
+      Dc0IsPolled = 1
+      # List of core affinities
+      Dc0CoreAffinity = 0
+
+#. QAT based Encryption for RGW 
+
+   The CMake option ``WITH_QAT=ON`` must be configured. If you build Ceph from
+   source code (see: :ref:`build-ceph`), navigate to your cloned Ceph repository 
+   and execute the following:
+
+   .. prompt:: bash $ 
+
+      cd ceph
+      ./do_cmake.sh -DWITH_QAT=ON
+      cd build
+      ininja
+
+   .. note::
+     The section name of the QAT configuration files must be ``CEPH`` since 
+     the section name is set as "CEPH" in Ceph cropto source code.
+  
+   Then, edit the Ceph configuration file to make use of QAT based crypto plugin::
+
+      plugin crypto accelerator = crypto_qat
+
+#. QAT Support for Compression
+
+   Before starting, make sure both QAT driver and `QATzip`_  have been installed. Besides 
+   "ICP_ROOT", remember to set the environment variable "QZ_ROOT" for the root directory
+   of your QATzip source tree.
+
+   The following CMake options have to be configured to trigger QAT based compression
+   when building Ceph:
+  
+   .. prompt:: bash $
+
+      ./do_cmake.sh -DWITH_QAT=ON -DWITH_QATZIP=ON
+
+   Then, set an environment variable to clarify the section name of User Process Instance
+   Section in QAT configuration files, e.g.:
+  
+   .. prompt:: bash $
+
+      export QAT_SECTION_NAME=CEPH
+
+   Next, edit the Ceph configuration file to enable QAT support for compression::
+
+      qat compressor enabled=true
 
 
 .. _QAT Support for Compression: https://github.com/ceph/ceph/pull/19714