summaryrefslogtreecommitdiffstats
path: root/src/spdk/dpdk/doc/guides/compressdevs/isal.rst
blob: af1f41f240ea4750432a87627f778af5b025c136 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
..  SPDX-License-Identifier: BSD-3-Clause
    Copyright(c) 2018 Intel Corporation.

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 Deflate(compression) and Inflate(decompression).


Features
--------

ISA-L PMD has support for:

Compression/Decompression algorithm:

    * DEFLATE

Huffman code type:

    * FIXED
    * DYNAMIC

Window size support:

    * 32K

Checksum:

    * CRC32
    * ADLER32

To enable a checksum in the driver, the compression and/or decompression xform
structure, rte_comp_xform, must be filled with either of the CompressDev
checksum flags supported. ::

 compress_xform->compress.chksum = RTE_COMP_CHECKSUM_CRC32

 decompress_xform->decompress.chksum = RTE_COMP_CHECKSUM_CRC32

::

 compress_xform->compress.chksum = RTE_COMP_CHECKSUM_ADLER32

 decompress_xform->decompress.chksum = RTE_COMP_CHECKSUM_ADLER32

If you request a checksum for compression or decompression,
the checksum field in the operation structure,  ``op->output_chksum``,
will be filled with the checksum.

.. Note::

 For the compression case above, your output buffer will need to be large enough to hold the compressed data plus a scratchpad for the checksum at the end, the scratchpad is 8 bytes for CRC32 and 4 bytes for Adler32.

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

* Compressdev level 0, no compression, is not supported.

Installation
------------

* To build DPDK with Intel's ISA-L library, the user is required to download the library from `<https://github.com/01org/isa-l>`_.

* Once downloaded, the user needs to build the library, the ISA-L autotools are usually sufficient::

    ./autogen.sh
    ./configure

* make can  be used to install the library on their system, before building DPDK::

    make
    sudo make install

* To build with meson, the **libisal.pc** file, must be copied into "pkgconfig",
  e.g. /usr/lib/pkgconfig or /usr/lib64/pkgconfig depending on your system,
  for meson to find the ISA-L library. The **libisal.pc** is located in library sources::

    cp isal/libisal.pc /usr/lib/pkgconfig/


Initialization
--------------

In order to enable this virtual compression PMD, user must:

* Set ``CONFIG_RTE_LIBRTE_PMD_ISAL=y`` in config/common_base.

To use the PMD in an application, user must:

* Call ``rte_vdev_init("compress_isal")`` within the application.

* Use ``--vdev="compress_isal"`` in the EAL options, which will call ``rte_vdev_init()`` internally.

The following parameter (optional) can be provided in the previous two calls:

* ``socket_id:`` Specify the socket where the memory for the device is going to be allocated
  (by default, socket_id will be the socket where the core that is creating the PMD is running on).