doc: add compression driver and ISA-L PMD guides

This adds general compression drivers feature guide
as well as the ISA-L PMD documentation and guide.

Signed-off-by: Lee Daly <lee.daly@intel.com>
Reviewed-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
This commit is contained in:
Lee Daly 2018-05-09 17:14:35 +01:00 committed by Pablo de Lara
parent 7bf4f0630a
commit 5a44154361
10 changed files with 159 additions and 1 deletions

1
.gitignore vendored
View File

@ -3,6 +3,7 @@ doc/guides/cryptodevs/overview_feature_table.txt
doc/guides/cryptodevs/overview_cipher_table.txt
doc/guides/cryptodevs/overview_auth_table.txt
doc/guides/cryptodevs/overview_aead_table.txt
doc/guides/compressdevs/overview_feature_table.txt
cscope.out.po
cscope.out.in
cscope.out

View File

@ -350,6 +350,7 @@ F: lib/librte_compressdev/
F: drivers/compress/
F: test/test/test_compressdev*
F: doc/guides/prog_guide/compressdev.rst
F: doc/guides/compressdevs/features/default.ini
Eventdev API
M: Jerin Jacob <jerin.jacob@caviumnetworks.com>
@ -827,6 +828,8 @@ T: git://dpdk.org/next/dpdk-next-crypto
ISA-L
M: Lee Daly <lee.daly@intel.com>
F: drivers/compress/isal/
F: doc/guides/compressdevs/isal.rst
F: doc/guides/compressdevs/features/isal.ini
Eventdev Drivers

View File

@ -0,0 +1,24 @@
;
; Features of a default compression driver.
;
; This file defines the features that are valid for inclusion in
; the other driver files and also the order that they appear in
; the features table in the documentation.
;
[Features]
HW Accelerated =
CPU SSE =
CPU AVX =
CPU AVX2 =
CPU AVX512 =
CPU NEON =
Stateful =
By-Pass =
Chained mbufs =
Deflate =
LZS =
Adler32 =
Crc32 =
Adler32&Crc32 =
Fixed =
Dynamic =

View File

@ -0,0 +1,22 @@
;
; Refer to default.ini for the full list of available PMD features.
;
; Supported features of 'ISA-L' compression driver.
;
[Features]
HW Accelerated =
CPU SSE = Y
CPU AVX = Y
CPU AVX2 = Y
CPU AVX512 = Y
CPU NEON =
Stateful =
By-Pass =
Chained mbufs =
Deflate = Y
LZS =
Adler32 =
Crc32 =
Adler32&Crc32 =
Fixed = Y
Dynamic = Y

View File

@ -0,0 +1,13 @@
.. SPDX-License-Identifier: BSD-3-Clause
Copyright(c) 2018 Intel Corporation.
Compression Device Drivers
==========================
.. toctree::
:maxdepth: 2
:numbered:
overview
isal

View File

@ -0,0 +1,76 @@
.. 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 compression and decompression
Features
--------
ISA-L PMD has support for:
Compression/Decompression algorithm:
* DEFLATE
Huffman code type:
* FIXED
* DYNAMIC
Window size support:
* 32K
Limitations
-----------
* Chained mbufs are not supported, for future release.
* Compressdev level 0, no compression, is not supported. ISA-L level 0 used for fixed huffman codes.
* Checksums are not supported, for future release.
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).

View File

@ -0,0 +1,12 @@
.. SPDX-License-Identifier: BSD-3-Clause
Copyright(c) 2018 Intel Corporation.
Compression Device Supported Functionality Matrices
===================================================
Supported Feature Flags
-----------------------
.. _table_compression_pmd_features:
.. include:: overview_feature_table.txt

View File

@ -388,6 +388,11 @@ def setup(app):
'AEAD',
'AEAD algorithms in crypto drivers',
'AEAD algorithm')
table_file = dirname(__file__) + '/compressdevs/overview_feature_table.txt'
generate_overview_table(table_file, 1,
'Features',
'Features availability in compression drivers',
'Feature')
if LooseVersion(sphinx_version) < LooseVersion('1.3.1'):
print('Upgrade sphinx to version >= 1.3.1 for '

View File

@ -17,6 +17,7 @@ DPDK documentation
nics/index
bbdevs/index
cryptodevs/index
compressdevs/index
eventdevs/index
rawdevs/index
mempool/index

View File

@ -147,7 +147,8 @@ New Features
* **Added a new compression poll mode driver using Intels ISA-L.**
Added the new ``ISA-L`` compression driver, for compression and decompression
operations in software.
operations in software. See the :doc:`../compressdevs/isal` compression driver
guide for details on this new driver.
* **Added the Event Timer Adapter Library.**