[dpdk-dev,v3,11/11] compress/isal: add ISA-L compression PMD docs
Checks
Commit Message
Signed-off-by: Lee Daly <lee.daly@intel.com>
---
MAINTAINERS | 5 ++
devtools/test-build.sh | 4 ++
doc/guides/compressdevs/features/isal.ini | 40 +++++++++++++
doc/guides/compressdevs/index.rst | 1 +
doc/guides/compressdevs/isal.rst | 94 +++++++++++++++++++++++++++++++
5 files changed, 144 insertions(+)
create mode 100644 doc/guides/compressdevs/features/isal.ini
create mode 100644 doc/guides/compressdevs/isal.rst
Comments
Few typos below
> Signed-off-by: Lee Daly <lee.daly@intel.com>
> ---
> MAINTAINERS | 5 ++
> devtools/test-build.sh | 4 ++
> doc/guides/compressdevs/features/isal.ini | 40 +++++++++++++
> doc/guides/compressdevs/index.rst | 1 +
> doc/guides/compressdevs/isal.rst | 94
> +++++++++++++++++++++++++++++++
<...>
> +; Supported features of 'ISA-L' compression driver.
> +;
> +[FEATURES]
> +HW Accelerated = N
> +CPU SSE = Y
> +CPU AVX = Y
> +CPU AVX2 = Y
> +CPU AVX512 = Y
> +CPU NEON = N
> +Stateful = N
> +By-Pass = N
> +Chained mbufs = N
> +;
> +; Supported algorithims of the 'ISA-L' compression driver.
algorithims / algorithms
> +;
> +[ALGORITHIM]
ALGORITHIM / ALGORITHM
<...>
> +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 algorithim for both compression and
> +decompression
algorithim / algorithm
<...>
> +
> +are usualy sufficient::
> +
> + ./autogen.sh
> + ./configure
> +
usualy / usually
<...>
> Signed-off-by: Lee Daly <lee.daly@intel.com>
> ---
> MAINTAINERS | 5 ++
> devtools/test-build.sh | 4 ++
> doc/guides/compressdevs/features/isal.ini | 40 +++++++++++++
> doc/guides/compressdevs/index.rst | 1 +
> doc/guides/compressdevs/isal.rst | 94
> +++++++++++++++++++++++++++++++
<...>
> +Limitations
> +-----------
> +
> +* Chained mbufs are not supported.
> +
> +* Compressdev level 0, no compression, is not supported. ISA-L level 0
> +used for
> +
> +fixed huffman codes.
For the bit above have the two lines together as it messes up the format and look of the sentance
* Compressdev level 0, no compression, is not supported. ISA-L level 0
used for fixed huffman codes.
> +* Out of order operations are not supported
> +
> +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>`_.
Same here,
+* 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 usualy sufficient::
> +
> + ./autogen.sh
> + ./configure
> +
Same above, also use 4 spaces to indent the code block not tabs,
* Once downloaded, the user needs to build the library, the ISA-L
autotools are usualy sufficient::
./autogen.sh
./configure
> +make can be used to install the library on their system, before building
> DPDK::
> +
> + make
> + sudo make install
Spaces instead of tabs for the commands above
> +* 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. "libisal.pc" is located in library sources,::
> +
> + cp isal/libisal.pc /usr/lib/pkgconfig/
> +
> +instructions on how to download below.
Same changes as above also you can get rid of the comma after sources
* 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. "libisal.pc" is located
in library sources ::
cp isal/libisal.pc /usr/lib/pkgconfig/
instructions on how to download below.
<...>
> +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 parameters (all 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).
In this section commands like CONFIG_RTE_LIBRTE_PMD_ISAL=y and --vdev="compress_isal"
Put them in `` `` quotes to highlight it's a command as it's a bit hard to see and also looks better.
Marko K
//snip
> Subject: RE: [dpdk-dev] [PATCH v3 11/11] compress/isal: add ISA-L compression
> PMD docs
>
>
> > Signed-off-by: Lee Daly <lee.daly@intel.com>
> > ---
> > MAINTAINERS | 5 ++
> > devtools/test-build.sh | 4 ++
> > doc/guides/compressdevs/features/isal.ini | 40 +++++++++++++
> > doc/guides/compressdevs/index.rst | 1 +
> > doc/guides/compressdevs/isal.rst | 94
> > +++++++++++++++++++++++++++++++
>
> <...>
>
> > +Limitations
> > +-----------
> > +
> > +* Chained mbufs are not supported.
> > +
> > +* Compressdev level 0, no compression, is not supported. ISA-L level
> > +0 used for
> > +
> > +fixed huffman codes.
>
[Lee] Thanks for the feedback on patchset, V4 to be sent in coming days.
> For the bit above have the two lines together as it messes up the format and
> look of the sentance
>
> * Compressdev level 0, no compression, is not supported. ISA-L level 0
> used for fixed huffman codes.
>
> > +* Out of order operations are not supported
> > +
> > +Installation
> > +------------
//snip
> -----Original Message-----
> From: Daly, Lee
> Sent: Tuesday, April 17, 2018 2:36 PM
> To: dev@dpdk.org
> Cc: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>; Tucker, Greg B
> <greg.b.tucker@intel.com>; Jain, Deepak K <deepak.k.jain@intel.com>; Trahe,
> Fiona <fiona.trahe@intel.com>; Daly, Lee <lee.daly@intel.com>
> Subject: [PATCH v3 11/11] compress/isal: add ISA-L compression PMD docs
Change title to " doc: add compress isa-l PMD guide
>
> Signed-off-by: Lee Daly <lee.daly@intel.com>
> ---
> MAINTAINERS | 5 ++
> devtools/test-build.sh | 4 ++
> doc/guides/compressdevs/features/isal.ini | 40 +++++++++++++
> doc/guides/compressdevs/index.rst | 1 +
> doc/guides/compressdevs/isal.rst | 94
> +++++++++++++++++++++++++++++++
> 5 files changed, 144 insertions(+)
> create mode 100644 doc/guides/compressdevs/features/isal.ini
> create mode 100644 doc/guides/compressdevs/isal.rst
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 37b9b1d..baccae7 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -771,6 +771,11 @@ Compression Drivers
> M: Pablo de Lara <pablo.de.lara.guarch@intel.com>
> T: git://dpdk.org/next/dpdk-next-crypto
Add F: doc/guides/compressdev/features/default.ini, but better in patch 10.
>
> +ISA-L PMD
> +M: Lee Daly <lee.daly@intel.com>
> +F: drivers/compress/isal
You can add these three lines above in the first patch
and then add the files below in this patch.
> +F: doc/guides/compressdevs/isal.rst
> +F: doc/guides/compressdevs/features/isal.ini
>
> Eventdev Drivers
> ----------------
> 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
...
> + 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
Add the changes for test-build.sh in first patch.
...
> diff --git a/doc/guides/compressdevs/index.rst
> b/doc/guides/compressdevs/index.rst
> index 9271cee..bc59ce8 100644
> --- a/doc/guides/compressdevs/index.rst
> +++ b/doc/guides/compressdevs/index.rst
> @@ -10,3 +10,4 @@ Compression Device Drivers
> :numbered:
>
> overview
> + isal
> diff --git a/doc/guides/compressdevs/isal.rst
> b/doc/guides/compressdevs/isal.rst
> new file mode 100644
> index 0000000..d76f7ae
> --- /dev/null
> +++ b/doc/guides/compressdevs/isal.rst
> @@ -0,0 +1,94 @@
> +.. 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 algorithim for both compression and
> +decompression
> +
> +Features
> +--------
> +
> +ISA-L PMD has support for:
> +
> +Compression/Decompression algorithm:
> +
> +* DEFLATE
> +
> +Huffman code type:
> +
> +* DEFAULT
> +* FIXED
> +* DYNAMIC
Remove DEFAULT, which is supported by all PMDs.
> +
> +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.
> +
> +* Out of order operations are not supported
I don't think this is a limitation. What kind of "out of order" do you mean here?
Some PMDs can process operations out of order, but that is expected from the API.
If a PMD processes them in order, it is also OK.
...
> +The following parameters (all optional) can be provided in the previous two
> calls:
There is only one parameter, so change to "the following parameter".
> +
> +* 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).
> --
> 2.7.4
This patchset contains the first compression PMD written under the DPDK
compression API, compressdev. The ISA-L compression driver utilizes Intel's
ISA-L compression library. It therefore has dependencies on both compressdev
and the ISA-L library, v2.22.0.
V2:
- Changes to keep in compliance with compressdev API,
- Enable meson build system,
- General rework & fixes,
- Documentation.
V3:
- Changes to keep in compliance with compressdev API,
- General rework,
- Split into patchset.
V4:
- Changes to keep in compliance with the compressdev API,
- Removed unnecessary branching in compression function, process_isal_deflate,
- Some minor documentation fixes,
- Minor reworks.
Lee Daly (10):
compress/isal: add skeleton ISA-L compression PMD
compress/isal: add pmd device init and de-init
compress/isal: add basic pmd ops
compress/isal: add private xform related ops
compress/isal: add queue pair related ops
compress/isal: support enqueue/dequeue api
compress/isal: add stats related ops
compress/isal: add ISA-L compression functionality
compress/isal: add ISA-L decomp functionality
doc: add compression driver and ISA-L PMD docs
.gitignore | 1 +
MAINTAINERS | 12 +
config/common_base | 5 +
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 | 4 +
drivers/Makefile | 2 +
drivers/compress/Makefile | 8 +
drivers/compress/isal/Makefile | 31 ++
drivers/compress/isal/isal_compress_pmd.c | 500 +++++++++++++++++++++
drivers/compress/isal/isal_compress_pmd_ops.c | 345 ++++++++++++++
drivers/compress/isal/isal_compress_pmd_private.h | 57 +++
drivers/compress/isal/meson.build | 14 +
drivers/compress/isal/rte_pmd_isal_version.map | 3 +
drivers/compress/meson.build | 8 +
drivers/meson.build | 1 +
mk/rte.app.mk | 5 +
24 files changed, 1238 insertions(+)
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
create mode 100644 drivers/compress/Makefile
create mode 100644 drivers/compress/isal/Makefile
create mode 100644 drivers/compress/isal/isal_compress_pmd.c
create mode 100644 drivers/compress/isal/isal_compress_pmd_ops.c
create mode 100644 drivers/compress/isal/isal_compress_pmd_private.h
create mode 100644 drivers/compress/isal/meson.build
create mode 100644 drivers/compress/isal/rte_pmd_isal_version.map
create mode 100644 drivers/compress/meson.build
@@ -771,6 +771,11 @@ Compression Drivers
M: Pablo de Lara <pablo.de.lara.guarch@intel.com>
T: git://dpdk.org/next/dpdk-next-crypto
+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
----------------
@@ -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" || \
new file mode 100644
@@ -0,0 +1,40 @@
+;
+; Refer to default.ini for the full list of available PMD features.
+;
+; Supported features of 'ISA-L' compression driver.
+;
+[FEATURES]
+HW Accelerated = N
+CPU SSE = Y
+CPU AVX = Y
+CPU AVX2 = Y
+CPU AVX512 = Y
+CPU NEON = N
+Stateful = N
+By-Pass = N
+Chained mbufs = N
+;
+; Supported algorithims of the 'ISA-L' compression driver.
+;
+[ALGORITHIM]
+Deflate = Y
+LZS = N
+;
+; Supported checksums of the 'ISA-L' compression driver.
+;
+[CHECKSUMS]
+Adler32 = Y
+Crc32 = Y
+Adler32&Crc32 = N
+;
+; Supported huffman codes of the 'ISA-L' compression driver.
+;
+[HUFFMAN CODES]
+Default = Y
+Fixed = Y
+Dynamic = N
+Semi-Dynamic = Y
+;
+; Supported others of the 'ISA-L' compression driver.
+;
+[OTHERS]
@@ -10,3 +10,4 @@ Compression Device Drivers
:numbered:
overview
+ isal
new file mode 100644
@@ -0,0 +1,94 @@
+.. 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 algorithim for both compression and decompression
+
+Features
+--------
+
+ISA-L PMD has support for:
+
+Compression/Decompression algorithm:
+
+* DEFLATE
+
+Huffman code type:
+
+* DEFAULT
+* 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.
+
+* Out of order operations are not supported
+
+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 usualy 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. "libisal.pc" is located in library sources,::
+
+ cp isal/libisal.pc /usr/lib/pkgconfig/
+
+instructions on how to download below.
+
+
+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 parameters (all 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).