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>

diff --git a/.gitignore b/.gitignore
index 6df5ba0..9105e26 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -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

diff --git a/MAINTAINERS b/MAINTAINERS
index 3770430..7cc8860 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -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

diff --git a/doc/guides/compressdevs/features/default.ini b/doc/guides/compressdevs/features/default.ini
new file mode 100644 (file)
index 0000000..795fc55
--- /dev/null
+++ b/doc/guides/compressdevs/features/default.ini
@@ -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        =

diff --git a/doc/guides/compressdevs/features/isal.ini b/doc/guides/compressdevs/features/isal.ini
new file mode 100644 (file)
index 0000000..ad2718d
--- /dev/null
+++ b/doc/guides/compressdevs/features/isal.ini
@@ -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

diff --git a/doc/guides/compressdevs/index.rst b/doc/guides/compressdevs/index.rst
new file mode 100644 (file)
index 0000000..bc59ce8
--- /dev/null
+++ b/doc/guides/compressdevs/index.rst
@@ -0,0 +1,13 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation.
+
+Compression Device Drivers
+==========================
+
+
+.. toctree::
+    :maxdepth: 2
+    :numbered:
+
+    overview
+    isal

diff --git a/doc/guides/compressdevs/isal.rst b/doc/guides/compressdevs/isal.rst
new file mode 100644 (file)
index 0000000..2024437
--- /dev/null
+++ b/doc/guides/compressdevs/isal.rst
@@ -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).

diff --git a/doc/guides/compressdevs/overview.rst b/doc/guides/compressdevs/overview.rst
new file mode 100644 (file)
index 0000000..ca37de1
--- /dev/null
+++ b/doc/guides/compressdevs/overview.rst
@@ -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

diff --git a/doc/guides/conf.py b/doc/guides/conf.py
index 38de280..c883306 100644 (file)
--- a/doc/guides/conf.py
+++ b/doc/guides/conf.py
@@ -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 '

diff --git a/doc/guides/index.rst b/doc/guides/index.rst
index f7dffb6..8a9ed65 100644 (file)
--- a/doc/guides/index.rst
+++ b/doc/guides/index.rst
@@ -17,6 +17,7 @@ DPDK documentation
    nics/index
    bbdevs/index
    cryptodevs/index
+   compressdevs/index
    eventdevs/index
    rawdevs/index
    mempool/index

diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst
index 2592469..458b47f 100644 (file)
--- a/doc/guides/rel_notes/release_18_05.rst
+++ b/doc/guides/rel_notes/release_18_05.rst
@@ -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.**