From 5a441543615a6893db7862bbc7d224795ed9ac5e Mon Sep 17 00:00:00 2001 From: Lee Daly Date: Wed, 9 May 2018 17:14:35 +0100 Subject: [PATCH] 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 Reviewed-by: Pablo de Lara --- .gitignore | 1 + MAINTAINERS | 3 + 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 | 76 ++++++++++++++++++++ doc/guides/compressdevs/overview.rst | 12 ++++ doc/guides/conf.py | 5 ++ doc/guides/index.rst | 1 + doc/guides/rel_notes/release_18_05.rst | 3 +- 10 files changed, 159 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 diff --git a/.gitignore b/.gitignore index 6df5ba0686..9105e26c56 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 377043093d..7cc88602aa 100644 --- 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 @@ -827,6 +828,8 @@ T: git://dpdk.org/next/dpdk-next-crypto ISA-L M: Lee Daly 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 index 0000000000..795fc5577b --- /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 0000000000..ad2718df02 --- /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 index 0000000000..bc59ce810a --- /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 0000000000..2024437c7e --- /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 ``_. + +* 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 0000000000..ca37de1756 --- /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 38de280eff..c883306d77 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 f7dffb682f..8a9ed65c87 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 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 2592469aff..458b47ffb1 100644 --- 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.**