From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by dpdk.org (Postfix) with ESMTP id 40CE91B703 for ; Wed, 9 May 2018 18:14:57 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga103.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 09 May 2018 09:14:56 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.49,382,1520924400"; d="scan'208";a="222921251" Received: from silpixa00399501.ir.intel.com ([10.237.223.69]) by orsmga005.jf.intel.com with ESMTP; 09 May 2018 09:14:55 -0700 From: Lee Daly 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 Date: Wed, 9 May 2018 17:14:35 +0100 Message-Id: <1525882475-183214-11-git-send-email-lee.daly@intel.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1525882475-183214-1-git-send-email-lee.daly@intel.com> References: <1525782775-138647-2-git-send-email-lee.daly@intel.com> <1525882475-183214-1-git-send-email-lee.daly@intel.com> Subject: [dpdk-dev] [PATCH v6 10/10] doc: add compression driver and ISA-L PMD docs X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 09 May 2018 16:14:58 -0000 This adds general compression drivers feature guide as well as the ISA-L PMD documentation and guide. Signed-off-by: Lee Daly --- .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 | 74 ++++++++++++++++++++++++++++ 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 +- 11 files changed, 170 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 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 +T: git://dpdk.org/next/dpdk-next-crypto +F: doc/guides/compressdevs/features/default.ini + +ISA-L PMD +M: Lee Daly +F: drivers/compress/isal +F: doc/guides/compressdevs/isal.rst +F: doc/guides/compressdevs/features/isal.ini + Eventdev Drivers ---------------- M: Jerin Jacob 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 () # 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..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 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..0b20321 --- /dev/null +++ b/doc/guides/compressdevs/isal.rst @@ -0,0 +1,74 @@ +.. 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 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 --- 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