diff mbox

[dpdk-dev] doc/compress: add compression level guide for ISA-L

Message ID 1527090841-75874-1-git-send-email-lee.daly@intel.com (mailing list archive)
State Superseded, archived
Delegated to: Pablo de Lara Guarch
Headers

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK

Commit Message

Daly, Lee May 23, 2018, 3:54 p.m. UTC 
  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>
---
 doc/guides/compressdevs/isal.rst | 63 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 55 insertions(+), 8 deletions(-)

Comments

Kovacevic, Marko May 24, 2018, 9:07 a.m. UTC | #1 
> 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>
> ---
>  doc/guides/compressdevs/isal.rst | 63
> +++++++++++++++++++++++++++++++++++-----
>  1 file changed, 55 insertions(+), 8 deletions(-)
> 
> diff --git a/doc/guides/compressdevs/isal.rst
> b/doc/guides/compressdevs/isal.rst
> index 2024437..9c8dfea 100644
> --- a/doc/guides/compressdevs/isal.rst
> +++ b/doc/guides/compressdevs/isal.rst
> @@ -6,7 +6,8 @@ ISA-L Compression Poll Mode Driver
>

 
<...>

> 
>  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.
>

For the above line all I'll say is in the .rst file keep it to 80 characters per line as its way to long
In this case everything else is ok for me. Once you make the changes you can add my ack.

Acked-by: Marko Kovacevic <marko.kovacevic@intel.com>
diff mbox

Patch

diff --git a/doc/guides/compressdevs/isal.rst b/doc/guides/compressdevs/isal.rst
index 2024437..9c8dfea 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,71 @@  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
 ------------