doc/guides/compressdevs/isal.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 ISA-L Compression Poll Mode Driver
   5 ==================================
   6
   7 The ISA-L PMD (**librte_pmd_isal_comp**) provides poll mode compression &
   8 decompression driver support for utilizing Intel ISA-L library,
   9 which implements the deflate algorithm for both Deflate(compression) and Inflate(decompression).
  10
  11
  12 Features
  13 --------
  14
  15 ISA-L PMD has support for:
  16
  17 Compression/Decompression algorithm:
  18
  19     * DEFLATE
  20
  21 Huffman code type:
  22
  23     * FIXED
  24     * DYNAMIC
  25
  26 Window size support:
  27
  28     * 32K
  29
  30 Level guide:
  31
  32 The ISA-L levels have been mapped to somewhat correspond to the same ZLIB level,
  33 i.e. ZLIB L1 gives a compression ratio similar to ISA-L L1.
  34 Compressdev level 0 enables "No Compression", which passes the uncompressed
  35 data to the output buffer, plus deflate headers.
  36 The ISA-L library does not support this, therefore compressdev level 0 is not supported.
  37
  38 The compressdev API has 10 levels, 0-9. ISA-L has 4 levels of compression, 0-3.
  39 As a result the level mappings from the API to the PMD are shown below.
  40
  41 .. _table_ISA-L_compression_levels:
  42
  43 .. table:: Level mapping from Compressdev to ISA-L PMD.
  44
  45    +-------------+----------------------------------------------+-----------------------------------------------+
  46    | Compressdev | PMD Functionality                            | Internal ISA-L                                |
  47    | API Level   |                                              | Level                                         |
  48    +=============+==============================================+===============================================+
  49    | 0           | No compression, Not Supported                | ---                                           |
  50    +-------------+----------------------------------------------+-----------------------------------------------+
  51    | 1           | Dynamic (Fast compression)                   | 1                                             |
  52    +-------------+----------------------------------------------+-----------------------------------------------+
  53    | 2           | Dynamic                                      | 2                                             |
  54    |             | (Higher compression ratio)                   |                                               |
  55    +-------------+----------------------------------------------+-----------------------------------------------+
  56    | 3           | Dynamic                                      | 3                                             |
  57    |             | (Best compression ratio)                     | (Level 2 if                                   |
  58    |             |                                              | no AVX512/AVX2)                               |
  59    +-------------+----------------------------------------------+-----------------------------------------------+
  60    | 4           | Dynamic (Best compression ratio)             | Same as above                                 |
  61    +-------------+----------------------------------------------+-----------------------------------------------+
  62    | 5           | Dynamic (Best compression ratio)             | Same as above                                 |
  63    +-------------+----------------------------------------------+-----------------------------------------------+
  64    | 6           | Dynamic (Best compression ratio)             | Same as above                                 |
  65    +-------------+----------------------------------------------+-----------------------------------------------+
  66    | 7           | Dynamic (Best compression ratio)             | Same as above                                 |
  67    +-------------+----------------------------------------------+-----------------------------------------------+
  68    | 8           | Dynamic (Best compression ratio)             | Same as above                                 |
  69    +-------------+----------------------------------------------+-----------------------------------------------+
  70    | 9           | Dynamic (Best compression ratio)             | Same as above                                 |
  71    +-------------+----------------------------------------------+-----------------------------------------------+
  72
  73 .. Note::
  74
  75  The above table only shows mapping when API calls for dynamic compression.
  76  For fixed compression, regardless of API level, internally ISA-L level 0 is always used.
  77
  78 Limitations
  79 -----------
  80
  81 * Compressdev level 0, no compression, is not supported.
  82
  83 * Checksums will not be supported until future release.
  84
  85 Installation
  86 ------------
  87
  88 * To build DPDK with Intel's ISA-L library, the user is required to download the library from `<https://github.com/01org/isa-l>`_.
  89
  90 * Once downloaded, the user needs to build the library, the ISA-L autotools are usually sufficient::
  91
  92     ./autogen.sh
  93     ./configure
  94
  95 * make can  be used to install the library on their system, before building DPDK::
  96
  97     make
  98     sudo make install
  99
 100 * To build with meson, the **libisal.pc** file, must be copied into "pkgconfig",
 101   e.g. /usr/lib/pkgconfig or /usr/lib64/pkgconfig depending on your system,
 102   for meson to find the ISA-L library. The **libisal.pc** is located in library sources::
 103
 104     cp isal/libisal.pc /usr/lib/pkgconfig/
 105
 106
 107 Initialization
 108 --------------
 109
 110 In order to enable this virtual compression PMD, user must:
 111
 112 * Set ``CONFIG_RTE_LIBRTE_PMD_ISAL=y`` in config/common_base.
 113
 114 To use the PMD in an application, user must:
 115
 116 * Call ``rte_vdev_init("compress_isal")`` within the application.
 117
 118 * Use ``--vdev="compress_isal"`` in the EAL options, which will call ``rte_vdev_init()`` internally.
 119
 120 The following parameter (optional) can be provided in the previous two calls:
 121
 122 * ``socket_id:`` Specify the socket where the memory for the device is going to be allocated
 123   (by default, socket_id will be the socket where the core that is creating the PMD is running on).