From: Lee Daly <lee.daly@intel.com>
To: dev@dpdk.org
Cc: pablo.de.lara.guarch@intel.com, greg.b.tucker@intel.com,
deepak.k.jain@intel.com, fiona.trahe@intel.com,
Lee Daly <lee.daly@intel.com>
Subject: [dpdk-dev] [PATCH v4 10/10] doc: add compression driver and ISA-L PMD docs
Date: Sat, 28 Apr 2018 00:38:33 +0100 [thread overview]
Message-ID: <1524872313-196340-11-git-send-email-lee.daly@intel.com> (raw)
In-Reply-To: <1524872313-196340-1-git-send-email-lee.daly@intel.com>
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>
---
.gitignore | 1 +
MAINTAINERS | 12 ++++
devtools/test-build.sh | 4 ++
doc/guides/compressdevs/features/default.ini | 24 +++++++
doc/guides/compressdevs/features/isal.ini | 22 ++++++
doc/guides/compressdevs/index.rst | 13 ++++
doc/guides/compressdevs/isal.rst | 77 ++++++++++++++++++++
doc/guides/compressdevs/overview.rst | 12 ++++
doc/guides/compressdevs/overview_feature_table.txt | 84 ++++++++++++++++++++++
doc/guides/conf.py | 5 ++
doc/guides/index.rst | 1 +
doc/guides/rel_notes/release_18_05.rst | 3 +-
12 files changed, 257 insertions(+), 1 deletion(-)
create mode 100644 doc/guides/compressdevs/features/default.ini
create mode 100644 doc/guides/compressdevs/features/isal.ini
create mode 100644 doc/guides/compressdevs/index.rst
create mode 100644 doc/guides/compressdevs/isal.rst
create mode 100644 doc/guides/compressdevs/overview.rst
create mode 100644 doc/guides/compressdevs/overview_feature_table.txt
diff --git a/.gitignore b/.gitignore
index 6df5ba0..9105e26 100644
--- 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 d2dd61c..a22f37f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -766,6 +766,18 @@ F: doc/guides/cryptodevs/zuc.rst
F: doc/guides/cryptodevs/features/zuc.ini
+Compression Drivers
+-------------------
+M: Pablo de Lara <pablo.de.lara.guarch@intel.com>
+T: git://dpdk.org/next/dpdk-next-crypto
+F: doc/guides/compressdevs/features/default.ini
+
+ISA-L PMD
+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
----------------
M: Jerin Jacob <jerin.jacob@caviumnetworks.com>
diff --git a/devtools/test-build.sh b/devtools/test-build.sh
index 3362edc..66f3ece 100755
--- a/devtools/test-build.sh
+++ b/devtools/test-build.sh
@@ -45,6 +45,7 @@ default_path=$PATH
# - DPDK_DEP_SSL (y/[n])
# - DPDK_DEP_SZE (y/[n])
# - DPDK_DEP_ZLIB (y/[n])
+# - DPDK_DEP_ISAL (y/[n])
# - DPDK_MAKE_JOBS (int)
# - DPDK_NOTIFY (notify-send)
# - FLEXRAN_SDK
@@ -129,6 +130,7 @@ reset_env ()
unset DPDK_DEP_SSL
unset DPDK_DEP_SZE
unset DPDK_DEP_ZLIB
+ unset DPDK_DEP_ISAL
unset AESNI_MULTI_BUFFER_LIB_PATH
unset ARMV8_CRYPTO_LIB_PATH
unset FLEXRAN_SDK
@@ -178,6 +180,8 @@ config () # <directory> <target> <options>
test "$DPDK_DEP_ZLIB" != y || \
sed -ri 's,(BNX2X_PMD=)n,\1y,' $1/.config
sed -ri 's,(NFP_PMD=)n,\1y,' $1/.config
+ test "$DPDK_DEP_ISAL" != y || \
+ sed -ri 's,(ISAL_PMD=)n,\1y,' $1/.config
test "$DPDK_DEP_PCAP" != y || \
sed -ri 's,(PCAP=)n,\1y,' $1/.config
test -z "$ARMV8_CRYPTO_LIB_PATH" || \
diff --git a/doc/guides/compressdevs/features/default.ini b/doc/guides/compressdevs/features/default.ini
new file mode 100644
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
index 0000000..6a6ffb8
--- /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 = Y
+Crc32 = Y
+Adler32&Crc32 =
+Fixed = Y
+Dynamic = Y
diff --git a/doc/guides/compressdevs/index.rst b/doc/guides/compressdevs/index.rst
new file mode 100644
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
index 0000000..5b6134b
--- /dev/null
+++ b/doc/guides/compressdevs/isal.rst
@@ -0,0 +1,77 @@
+.. 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
+
+Checksum support:
+
+* Adler32
+* CRC32
+
+Window size support:
+
+* 32K
+
+Limitations
+-----------
+
+* Chained mbufs are not supported.
+
+* Compressdev level 0, no compression, is not supported. ISA-L level 0 used for fixed huffman codes.
+
+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
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/compressdevs/overview_feature_table.txt b/doc/guides/compressdevs/overview_feature_table.txt
new file mode 100644
index 0000000..8efa231
--- /dev/null
+++ b/doc/guides/compressdevs/overview_feature_table.txt
@@ -0,0 +1,84 @@
+
+.. raw:: html
+
+ <style>
+ .wy-nav-content {
+ opacity: .99;
+ }
+ table#id1 {
+ cursor: default;
+ overflow: hidden;
+ }
+ table#id1 th, table#id1 td {
+ text-align: center;
+ }
+ table#id1 th {
+ font-size: 72%;
+ white-space: pre-wrap;
+ vertical-align: top;
+ padding: 0.5em 0;
+ min-width: 0.9em;
+ width: 2em;
+ }
+ table#id1 col:first-child {
+ width: 0;
+ }
+ table#id1 th:first-child {
+ vertical-align: bottom;
+ }
+ table#id1 td {
+ font-size: 70%;
+ padding: 1px;
+ }
+ table#id1 td:first-child {
+ padding-left: 1em;
+ text-align: left;
+ }
+ table#id1 tr:nth-child(2n-1) td {
+ background-color: rgba(210, 210, 210, 0.2);
+ }
+ table#id1 th:not(:first-child):hover,
+ table#id1 td:not(:first-child):hover {
+ position: relative;
+ }
+ table#id1 th:not(:first-child):hover::after,
+ table#id1 td:not(:first-child):hover::after {
+ content: '';
+ height: 6000px;
+ top: -3000px;
+ width: 100%;
+ left: 0;
+ position: absolute;
+ z-index: -1;
+ background-color: #ffb;
+ }
+ table#id1 tr:hover td {
+ background-color: #ffb;
+ }
+ </style>
+
+.. table:: Features availability in compression drivers
+
+ ========================= =
+ Feature i
+ s
+ a
+ l
+ ========================= =
+ 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 Y
+ Crc32 Y
+ Adler32&Crc32
+ Fixed Y
+ Dynamic Y
+ ========================= =
diff --git a/doc/guides/conf.py b/doc/guides/conf.py
index 38de280..c883306 100644
--- 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 d60529d..18fe0ec 100644
--- 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
mempool/index
platform/index
diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst
index ce70d1f..d6a9d6f 100644
--- a/doc/guides/rel_notes/release_18_05.rst
+++ b/doc/guides/rel_notes/release_18_05.rst
@@ -78,7 +78,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.
API Changes
--
2.7.4
next prev parent reply other threads:[~2018-04-27 23:39 UTC|newest]
Thread overview: 70+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-03-09 16:50 [dpdk-dev] [PATCH] compress/isal: ISA-L compression PMD Lee Daly
2018-04-06 18:13 ` [dpdk-dev] [PATCH v2] " Lee Daly
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 00/11] add " Lee Daly
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 01/11] compress/isal: add skeleton " Lee Daly
2018-04-24 8:56 ` De Lara Guarch, Pablo
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 02/11] compress/isal: add pmd device init and de-init Lee Daly
2018-04-24 9:21 ` De Lara Guarch, Pablo
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 03/11] compress/isal: add basic pmd ops Lee Daly
2018-04-24 9:28 ` De Lara Guarch, Pablo
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 04/11] compress/isal: add private xform related ops Lee Daly
2018-04-24 9:45 ` De Lara Guarch, Pablo
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 05/11] compress/isal: add queue pair " Lee Daly
2018-04-24 9:56 ` De Lara Guarch, Pablo
2018-04-26 16:44 ` Daly, Lee
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 06/11] compress/isal: support enqueue/dequeue api Lee Daly
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 07/11] compress/isal: add stats related ops Lee Daly
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 08/11] compress/isal: add ISA-L compression functionality Lee Daly
2018-04-24 10:05 ` De Lara Guarch, Pablo
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 09/11] compress/isal: add ISA-L decomp functionality Lee Daly
2018-04-24 10:09 ` De Lara Guarch, Pablo
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 10/11] compress/isal: add generic compression driver docs Lee Daly
2018-04-23 14:47 ` Kovacevic, Marko
2018-04-24 10:47 ` De Lara Guarch, Pablo
2018-04-24 11:06 ` De Lara Guarch, Pablo
2018-04-25 14:25 ` Daly, Lee
2018-04-17 13:35 ` [dpdk-dev] [PATCH v3 11/11] compress/isal: add ISA-L compression PMD docs Lee Daly
2018-04-23 14:53 ` Kovacevic, Marko
2018-04-23 15:33 ` Kovacevic, Marko
2018-04-23 15:51 ` Daly, Lee
2018-04-24 11:04 ` De Lara Guarch, Pablo
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 00/10] add ISA-L compression PMD Lee Daly
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 01/10] compress/isal: add skeleton " Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 00/10] add " Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 01/10] compress/isal: add skeleton " Lee Daly
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 00/10] add " Lee Daly
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 01/10] compress/isal: add skeleton " Lee Daly
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 02/10] compress/isal: add pmd device init and de-init Lee Daly
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 03/10] compress/isal: add basic pmd ops Lee Daly
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 04/10] compress/isal: add private xform related ops Lee Daly
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 05/10] compress/isal: add queue pair " Lee Daly
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 06/10] compress/isal: support enqueue/dequeue api Lee Daly
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 07/10] compress/isal: add stats related ops Lee Daly
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 08/10] compress/isal: add ISA-L compression functionality Lee Daly
2018-05-09 17:39 ` Tucker, Greg B
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 09/10] compress/isal: add ISA-L decomp functionality Lee Daly
2018-05-09 17:41 ` Tucker, Greg B
2018-05-09 16:14 ` [dpdk-dev] [PATCH v6 10/10] doc: add compression driver and ISA-L PMD docs Lee Daly
2018-05-09 20:56 ` [dpdk-dev] [PATCH v6 00/10] add ISA-L compression PMD De Lara Guarch, Pablo
2018-05-09 21:36 ` De Lara Guarch, Pablo
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 02/10] compress/isal: add pmd device init and de-init Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 03/10] compress/isal: add basic pmd ops Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 04/10] compress/isal: add private xform related ops Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 05/10] compress/isal: add queue pair " Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 06/10] compress/isal: support enqueue/dequeue api Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 07/10] compress/isal: add stats related ops Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 08/10] compress/isal: add ISA-L compression functionality Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 09/10] compress/isal: add ISA-L decomp functionality Lee Daly
2018-05-08 12:32 ` [dpdk-dev] [PATCH v5 10/10] doc: add compression driver and ISA-L PMD docs Lee Daly
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 02/10] compress/isal: add pmd device init and de-init Lee Daly
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 03/10] compress/isal: add basic pmd ops Lee Daly
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 04/10] compress/isal: add private xform related ops Lee Daly
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 05/10] compress/isal: add queue pair " Lee Daly
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 06/10] compress/isal: support enqueue/dequeue api Lee Daly
2018-05-03 21:46 ` De Lara Guarch, Pablo
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 07/10] compress/isal: add stats related ops Lee Daly
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 08/10] compress/isal: add ISA-L compression functionality Lee Daly
2018-05-03 21:37 ` De Lara Guarch, Pablo
2018-04-27 23:38 ` [dpdk-dev] [PATCH v4 09/10] compress/isal: add ISA-L decomp functionality Lee Daly
2018-04-27 23:38 ` Lee Daly [this message]
2018-05-03 21:49 ` [dpdk-dev] [PATCH v4 10/10] doc: add compression driver and ISA-L PMD docs De Lara Guarch, Pablo
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1524872313-196340-11-git-send-email-lee.daly@intel.com \
--to=lee.daly@intel.com \
--cc=deepak.k.jain@intel.com \
--cc=dev@dpdk.org \
--cc=fiona.trahe@intel.com \
--cc=greg.b.tucker@intel.com \
--cc=pablo.de.lara.guarch@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).