Merge pull request #5 from intel/QATZSTDPlugin_0.1.0_release

Qatzstd plugin 0.1.0 release

LICENSE.ZSTD

@@ -0,0 +1,30 @@
+BSD License
+
+For Zstandard software
+
+Copyright (c) Meta Platforms, Inc. and affiliates. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Facebook, nor Meta, nor the names of its contributors may
+   be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Makefile

@@ -47,6 +47,10 @@ lib:
 test:
 	$(Q)$(MAKE) -C $(TESTDIR) $@
 
+.PHONY: benchmark
+benchmark:
+	$(Q)$(MAKE) -C $(TESTDIR) $@
+
 .PHONY: install
 install:
 	$(Q)$(MAKE) -C $(LIBDIR) $@

QAT-ZSTD-Plugin-third-party-programs.txt

@@ -0,0 +1,41 @@
+QAT ZSTD Plugin Third Party Programs File
+
+This file contains the list of third party software (“third party programs”) contained in the Intel software and their required notices and/or license terms. This third party software, even if included with the distribution of the Intel software, may be governed by separate license terms, including without limitation, third party license terms, other Intel software license terms, and open source software license terms. These separate license terms govern your use of the third party programs as set forth in the “third-party-programs.txt” or other similarly-named text file.
+
+Third party programs and their corresponding required notices and/or license terms are listed below.
+
+-------------------------------------------------------------
+1. 	Software Released under the BSD License:
+
+	Zstandard
+	Copyright (c) Meta Platforms, Inc. and affiliates.
+
+BSD License
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Facebook, nor Meta, nor the names of its contributors may
+   be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+-------------------------------------------------------------
+Other names and brands may be claimed as the property of others.

README.md

@@ -34,7 +34,7 @@ Intel® 4xxx (Intel® QuickAssist Technology Gen 4)
 
 ZSTD* library of version 1.5.4+
 
-[Intel® QAT Driver for Linux* Hardware v2.0][2]
+[Intel® QAT Driver for Linux* Hardware v2.0][2] or [Intel® QuickAssist Technology Library (QATlib)][3] of version 22.07.0+
 
 ## Limitations
 
@@ -45,17 +45,25 @@ ZSTD* library of version 1.5.4+
  5. Stream history is not currently supported. All advanced ZSTD* compression APIs, including streaming APIs, work with QAT sequence producer, but each block is treated as an independent chunk without history from previous blocks.
  6. Multi-threading within a single compression is not currently supported. In other words, compression will fail if `ZSTD_c_nbWorkers` > 0 and an external sequence producer is registered. Multi-threading across compressions is fine: simply create one CCtx per thread.
 
-For more details about ZSTD* sequence producer, please refer to [zstd.h][3].
+For more details about ZSTD* sequence producer, please refer to [zstd.h][4].
 
 ## Installation Instructions
 
 ### Build and install Intel® QuickAssist Technology Driver
 
-Download from [Intel® QAT Driver for Linux* Hardware v2.0][2], follow the guidance: [Intel® QuickAssist Technology Software for Linux* - Getting Started Guide][4].
+Users can choose [Intel® QAT Driver for Linux* Hardware v2.0][2](out-of-tree) or [Intel® QuickAssist Technology Library (QATlib)][3](in-tree) according to their requirements.
 
-If installing the Intel® QAT 2.0 driver for use in a virtual environment, please refer to [Using Intel® Virtualization Technology (Intel® VT) with Intel® QuickAssist Technology][5]
+If using out-of-tree driver, the user needs to set `ICP_ROOT` environment variable:
 
-After installing the QAT driver, please refer to [Intel® QuickAssist Technology Software for Linux* - Programmer's Guide][6] to the update QAT configuration file according to requirements.
+`ICP_ROOT`: the root directory of the QAT driver source tree
+
+#### Build and install Intel® QAT Driver for Linux* Hardware v2.0
+
+Download from [Intel® QAT Driver for Linux* Hardware v2.0][2], follow the guidance: [Intel® QuickAssist Technology Software for Linux* - Getting Started Guide][5].
+
+If installing the Intel® QAT 2.0 driver for use in a virtual environment, please refer to [Using Intel® Virtualization Technology (Intel® VT) with Intel® QuickAssist Technology][6]
+
+After installing the QAT driver, please refer to [Intel® QuickAssist Technology Software for Linux* - Programmer's Guide][7] to the update QAT configuration file according to requirements.
 
 QAT ZSTD Plugin needs a [SHIM] section by default.
 There are two ways to change:
@@ -68,17 +76,17 @@ After updating the configuration files, please restart QAT.
     service qat_service restart
 ```
 
+#### Install QATlib
+
+QATlib has been upstream to some platforms, RedHat, SUSE. Users also can install QATlib from source code according to [qatlib/INSTALL][8].
+
 ### Build QAT sequence producer library
 
 Shared Virtual Memory (SVM) allows direct submission of an applications buffer, thus removing the memcpy cycle cost, cache thrashing, and memory bandwidth. The SVM feature enables passing virtual addresses to the QAT hardware for processing acceleration requests.
 
 QAT sequence producer library runs on the SVM environment by default.
 
-To enable SVM, please refer to [Using Intel® Virtualization Technology (Intel® VT) with Intel® QuickAssist Technology][5] to update the BIOS and [Intel® QuickAssist Technology Software for Linux* - Programmer's Guide][6] chapter 3.3 to update driver configuration.
-
-Set `ICP_ROOT` environment variable:
-
-`ICP_ROOT`: the root directory of the QAT driver source tree
+To enable SVM, please refer to [Using Intel® Virtualization Technology (Intel® VT) with Intel® QuickAssist Technology][6] to update the BIOS and [Intel® QuickAssist Technology Software for Linux* - Programmer's Guide][7] chapter 3.3 to update driver configuration.
 
 ```bash
     make
@@ -94,7 +102,7 @@ If ZSTD* 1.5.4 library is not installed, need to specify path to ZSTD* lib sourc
 
 If SVM is not enabled, memory passed to Intel® QuickAssist Technology hardware must be DMA’able.
 
-Intel provides a User Space DMA-able Memory (USDM) component (kernel driver and corresponding user space library) which allocates/frees DMA-able memory, mapped to user space, performs virtual to physical address translation on memory allocated by this library. Please refer to [Intel® QuickAssist Technology Software for Linux* - Programmer's Guide][6] chapter 3.3.
+Intel provides a User Space DMA-able Memory (USDM) component (kernel driver and corresponding user space library) which allocates/frees DMA-able memory, mapped to user space, performs virtual to physical address translation on memory allocated by this library. Please refer to [Intel® QuickAssist Technology Software for Linux* - Programmer's Guide][7] chapter 3.3.
 
 To enable USDM, please compile with "ENABLE_USDM_DRV=1".
 
@@ -111,9 +119,100 @@ To enable USDM, please compile with "ENABLE_USDM_DRV=1".
 
 ### Build and run benchmark tool
 
+If SVM is not enabled, please compile with "ENABLE_USDM_DRV=1".
+
+```bash
+    make benchmark ENABLE_USDM_DRV=1
+```
+
+The `benchmark` is a tool used to perform QAT sequence producer performance tests, it supports the following options:
+
+```bash
+    -t#       Set maximum threads [1 - 128] (default: 1)
+    -l#       Set iteration loops [1 - 1000000](default: 1)
+    -c#       Set chunk size (default: 32K)
+    -E#       Auto/enable/disable searchForExternalRepcodes(0: auto; 1: enable; 2: disable; default: auto)
+    -L#       Set compression level [1 - 12] (default: 1)
+    -m#       Benchmark mode, 0: software compression; 1:QAT compression(default: 1)
+```
+
+In order to get a better performance, increasing the number of threads with `-t` is a better way. The number of dc instances provided by Intel® QAT needs to be increased while increasing test threads, it can be increased by modifying the `NumberDcInstances` in `/etc/4xxx_devx.conf`. Note that the test threads number should not exceed the number of dc instances, as this ensures that each test thread can obtain a dc instance.
+For more Intel® QAT configuration information, please refer to [Intel® QuickAssist Technology Software for Linux* - Programmer's Guide][7] chapter 5.
+An example usage of benchmark tool with [Silesia compression corpus][9]:
+
+```bash
+   ./benchmark -m1 -l100 -c64K -t64 -E2 Silesia
+```
+
+which used the following Intel® QAT configuration file:
+
+```bash
+    # QAT configuration file /etc/4xxx_devx.conf
+    ##############################################
+    # User Process Instance Section
+    ##############################################
+    [SHIM]
+    NumberCyInstances = 0
+    NumberDcInstances = 64
+    NumProcesses = 1
+    LimitDevAccess = 0
+
+    # Data Compression - User instance #0
+    Dc1Name = "Dc0"
+    Dc1IsPolled = 1
+    # List of core affinities
+    Dc1CoreAffinity = 0
+
+    # Data Compression - User instance #1
+    Dc2Name = "Dc1"
+    Dc2IsPolled = 1
+    # List of core affinities
+    Dc2CoreAffinity = 1
+    ...
+    # Data Compression - User instance #63
+    Dc63Name = "Dc63"
+    Dc63IsPolled = 1
+    # List of core affinities
+    Dc63CoreAffinity = 63
+```
+
+### How to integrate QAT sequence producer into `zstd`
+Integrating QAT sequence producer into the `zstd` command can speed up its compression, The following sample code shows how to enable QAT sequence producer by modifying the code of `FIO_compressZstdFrame` in `zstd/programs/fileio.c`.
+
+Start QAT device and register qatSequenceProducer before starting compression job.
+
+```c
+    /* Start QAT device, start QAT device at any
+    time before compression job started */
+    QZSTD_startQatDevice();
+    /* Create sequence producer state for QAT sequence producer */
+    void *sequenceProducerState = QZSTD_createSeqProdState();
+    /* register qatSequenceProducer */
+    ZSTD_registerSequenceProducer(
+        ress.cctx,
+        sequenceProducerState,
+        qatSequenceProducer
+    );
+    /* Enable sequence producer fallback */
+    ZSTD_CCtx_setParameter(ress.cctx,, ZSTD_c_enableSeqProducerFallback, 1);
+```
+
+Stop QAT device after compression job
+
+```c
+    /* Free sequence producer state */
+    QZSTD_freeSeqProdState(sequenceProducerState);
+    /* Please call QZSTD_stopQatDevice before
+    QAT is no longer used or the process exits */
+    QZSTD_stopQatDevice();
+```
+
+Then recompile `zstd` with flag `-lqatseqprod`. Currently, only single-threaded mode compression is supported to using QAT sequence producer, please run `zstd` with the `--single-thread`.
+
+Note : some parameters of `zstd` do not support sequence producer, for more zstd usage information please refer to [zstd manual][10].
+
 ```bash
-    make benchmark
-    ./test/benchmark [TEST FILENAME]
+    ./zstd --single-thread [TEST FILENAME]
 ```
 
 ### How to integrate QAT sequence producer into applications
@@ -178,7 +277,11 @@ Intel, the Intel logo are trademarks of Intel Corporation in the U.S. and/or oth
 
 [1]:https://github.com/facebook/zstd/releases/tag/v1.5.4
 [2]:https://www.intel.com/content/www/us/en/download/765501.html
-[3]:https://github.com/facebook/zstd/blob/dev/lib/zstd.h
-[4]:https://www.intel.com/content/www/us/en/content-details/632506/intel-quickassist-technology-intel-qat-software-for-linux-getting-started-guide-hardware-version-2-0.html
-[5]:https://www.intel.com/content/www/us/en/content-details/709210/using-intel-virtualization-technology-intel-vt-with-intel-quickassist-technology-application-note.html
-[6]:https://www.intel.com/content/www/us/en/content-details/743912/intel-quickassist-technology-intel-qat-software-for-linux-programmers-guide-hardware-version-2-0.html
+[3]:https://github.com/intel/qatlib
+[4]:https://github.com/facebook/zstd/blob/dev/lib/zstd.h
+[5]:https://www.intel.com/content/www/us/en/content-details/632506/intel-quickassist-technology-intel-qat-software-for-linux-getting-started-guide-hardware-version-2-0.html
+[6]:https://www.intel.com/content/www/us/en/content-details/709210/using-intel-virtualization-technology-intel-vt-with-intel-quickassist-technology-application-note.html
+[7]:https://www.intel.com/content/www/us/en/content-details/743912/intel-quickassist-technology-intel-qat-software-for-linux-programmers-guide-hardware-version-2-0.html
+[8]:https://github.com/intel/qatlib/blob/main/INSTALL
+[9]:https://sun.aei.polsl.pl//~sdeor/index.php?page=silesia
+[10]:https://github.com/facebook/zstd/blob/dev/doc/zstd_manual.html

src/Makefile

@@ -42,22 +42,29 @@ INCLUDEDIR ?= $(INSTALLDIR)/include
 
 CP ?= cp
 
-QATFLAGS = -I$(ICP_ROOT)/quickassist/include	\
-		   -I$(ICP_ROOT)/quickassist/include/dc	\
-		   -I$(ICP_ROOT)/quickassist/lookaside/access_layer/include
+ENABLE_USDM_DRV ?= 0
+ifneq ($(ICP_ROOT), )
+	QATFLAGS = -I$(ICP_ROOT)/quickassist/include	\
+		   	   -I$(ICP_ROOT)/quickassist/include/dc	\
+		       -I$(ICP_ROOT)/quickassist/lookaside/access_layer/include
+	LDFLAGS  = -Wl,-rpath,$(ICP_ROOT)/build -L$(ICP_ROOT)/build -lqat_s
+	ifneq ($(ENABLE_USDM_DRV), 0)
+		QATFLAGS += -I$(ICP_ROOT)/quickassist/utilities/libusdm_drv -DENABLE_USDM_DRV
+		LDFLAGS  += -lusdm_drv_s
+	endif
+else
+	QATFLAGS = -DINTREE
+	LDFLAGS  = -lqat
+	ifneq ($(ENABLE_USDM_DRV), 0)
+		QATFLAGS += -DENABLE_USDM_DRV
+		LDFLAGS	 += -lusdm
+	endif
+endif
 
 ifdef ZSTDLIB
 CFLAGS   += -I$(ZSTDLIB)
 endif
 
-LDFLAGS  = -L$(ICP_ROOT)/build -lqat_s
-
-ENABLE_USDM_DRV ?= 0
-ifneq ($(ENABLE_USDM_DRV), 0)
-  	QATFLAGS += -I$(ICP_ROOT)/quickassist/utilities/libusdm_drv -DENABLE_USDM_DRV
-  	LDFLAGS  += -lusdm_drv_s
-endif
-
 CFLAGS += -Wall -Werror -Wextra -Wcast-align -Wshadow -Wstrict-aliasing=1 \
 		  -Wswitch-enum -Wdeclaration-after-statement -Wstrict-prototypes \
 		  -Wundef -Wpointer-arith -Wvla -Wformat=2 -Winit-self \