summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLee Daly <lee.daly@intel.com>2018-05-24 12:04:49 +0100
committerThomas Monjalon <thomas@monjalon.net>2018-05-28 03:07:55 +0200
commit8a38e972384e7d049e6d63d7ae4d8893df870fc3 (patch)
treeb4b462153de13ffbbdc26d0dbed4058ef01fd370
parent006bb2cc209f6ba11230743c0402e6c29a29efc8 (diff)
downloaddpdk-8a38e972384e7d049e6d63d7ae4d8893df870fc3.zip
dpdk-8a38e972384e7d049e6d63d7ae4d8893df870fc3.tar.gz
dpdk-8a38e972384e7d049e6d63d7ae4d8893df870fc3.tar.xz
doc: add compression level guide for ISA-L
This expands the ISA-L documentation to give more a detailed explanation of the mapping between the compressdev API levels and PMD levels. Signed-off-by: Lee Daly <lee.daly@intel.com> Acked-by: Marko Kovacevic <marko.kovacevic@intel.com>
-rw-r--r--doc/guides/compressdevs/isal.rst65
1 files changed, 57 insertions, 8 deletions
diff --git a/doc/guides/compressdevs/isal.rst b/doc/guides/compressdevs/isal.rst
index 2024437..276ff06 100644
--- a/doc/guides/compressdevs/isal.rst
+++ b/doc/guides/compressdevs/isal.rst
@@ -6,7 +6,8 @@ ISA-L Compression Poll Mode Driver
The ISA-L PMD (**librte_pmd_isal_comp**) provides poll mode compression &
decompression driver support for utilizing Intel ISA-L library,
-which implements the deflate algorithm for both compression and decompression
+which implements the deflate algorithm for both Deflate(compression) and Inflate(decompression).
+
Features
--------
@@ -15,25 +16,73 @@ ISA-L PMD has support for:
Compression/Decompression algorithm:
-* DEFLATE
+ * DEFLATE
Huffman code type:
-* FIXED
-* DYNAMIC
+ * FIXED
+ * DYNAMIC
Window size support:
-* 32K
+ * 32K
+
+Level guide:
+
+The ISA-L levels have been mapped to somewhat correspond to the same ZLIB level,
+i.e. ZLIB L1 gives a compression ratio similar to ISA-L L1.
+Compressdev level 0 enables "No Compression", which passes the uncompressed
+data to the output buffer, plus deflate headers.
+The ISA-L library does not support this, therefore compressdev level 0 is not supported.
+
+The compressdev API has 10 levels, 0-9. ISA-L has 4 levels of compression, 0-3.
+As a result the level mappings from the API to the PMD are shown below.
+
+.. _table_ISA-L_compression_levels:
+
+.. table:: Level mapping from Compressdev to ISA-L PMD.
+
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | Compressdev | PMD Functionality | Internal ISA-L |
+ | API Level | | Level |
+ +=============+==============================================+===============================================+
+ | 0 | No compression, Not Supported | --- |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | 1 | Dynamic (Fast compression) | 1 |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | 2 | Dynamic | 2 |
+ | | (Higher compression ratio) | |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | 3 | Dynamic | 3 |
+ | | (Best compression ratio) | (Level 2 if |
+ | | | no AVX512/AVX2) |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | 4 | Dynamic (Best compression ratio) | Same as above |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | 5 | Dynamic (Best compression ratio) | Same as above |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | 6 | Dynamic (Best compression ratio) | Same as above |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | 7 | Dynamic (Best compression ratio) | Same as above |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | 8 | Dynamic (Best compression ratio) | Same as above |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+ | 9 | Dynamic (Best compression ratio) | Same as above |
+ +-------------+----------------------------------------------+-----------------------------------------------+
+
+.. Note::
+
+ The above table only shows mapping when API calls for dynamic compression.
+ For fixed compression, regardless of API level, internally ISA-L level 0 is always used.
Limitations
-----------
-* Chained mbufs are not supported, for future release.
+* Chained mbufs will not be supported until a future release, meaning max data size being passed to PMD through a single mbuf is 64K - 1. If data is larger than this it will need to be split up and sent as multiple operations.
-* Compressdev level 0, no compression, is not supported. ISA-L level 0 used for fixed huffman codes.
+* Compressdev level 0, no compression, is not supported.
-* Checksums are not supported, for future release.
+* Checksums will not be supported until future release.
Installation
------------