]>
Commit | Line | Data |
---|---|---|
9f95a23c TL |
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 | |
f67539c2 TL |
41 | API. Currently, QATzip speeds up gzip compression and decompression at the |
42 | time of writing. | |
9f95a23c TL |
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 | |
f67539c2 TL |
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. | |
9f95a23c TL |
69 | |
70 | Configuration | |
71 | ============= | |
1e59de90 TL |
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 | |
9f95a23c TL |
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 |