diff mbox series

[v2,5/5] doc: add ZLIB PMD documentation

Message ID 1530550631-22841-6-git-send-email-shally.verma@caviumnetworks.com (mailing list archive)
State Changes Requested, archived
Delegated to: Pablo de Lara Guarch
Headers
Series compress: add ZLIB compression PMD |

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK

Commit Message

Shally Verma July 2, 2018, 4:57 p.m. UTC 
  add zlib pmd feature specification and overview documentation

Signed-off-by: Sunila Sahu <sunila.sahu@caviumnetworks.com>
Signed-off-by: Shally Verma <shally.verma@caviumnetworks.com>
Signed-off-by: Ashish Gupta <ashish.gupta@caviumnetworks.com>
---
 MAINTAINERS                               |  2 +
 doc/guides/compressdevs/features/zlib.ini | 22 ++++++++++
 doc/guides/compressdevs/zlib.rst          | 68 +++++++++++++++++++++++++++++++
 3 files changed, 92 insertions(+)

Comments

De Lara Guarch, Pablo July 11, 2018, 2:02 p.m. UTC | #1 
> -----Original Message-----
> From: Shally Verma [mailto:shally.verma@caviumnetworks.com]
> Sent: Monday, July 2, 2018 5:57 PM
> To: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>
> Cc: dev@dpdk.org; pathreya@caviumnetworks.com;
> mchalla@caviumnetworks.com; Sunila Sahu
> <sunila.sahu@caviumnetworks.com>; Ashish Gupta
> <ashish.gupta@caviumnetworks.com>
> Subject: [PATCH v2 5/5] doc: add ZLIB PMD documentation
> 

Better change title to "add ZLIB PMD guide", to avoid duplication.

> add zlib pmd feature specification and overview documentation
> 
> Signed-off-by: Sunila Sahu <sunila.sahu@caviumnetworks.com>
> Signed-off-by: Shally Verma <shally.verma@caviumnetworks.com>
> Signed-off-by: Ashish Gupta <ashish.gupta@caviumnetworks.com>
> ---
>  MAINTAINERS                               |  2 +
>  doc/guides/compressdevs/features/zlib.ini | 22 ++++++++++
>  doc/guides/compressdevs/zlib.rst          | 68
> +++++++++++++++++++++++++++++++
>  3 files changed, 92 insertions(+)
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 448bbe1..1c217b0 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -854,6 +854,8 @@ F: doc/guides/compressdevs/features/isal.ini
>  ZLIB
>  M: Sunila Sahu <sunila.sahu@caviumnetworks.com>
>  F: drivers/compress/zlib/
> +F: doc/guides/compressdevs/zlib.rst
> +F: doc/guides/compressdevs/features/zlib.ini
> 
>  Eventdev Drivers
>  ----------------
> diff --git a/doc/guides/compressdevs/features/zlib.ini
> b/doc/guides/compressdevs/features/zlib.ini
> new file mode 100644
> index 0000000..bdc0fc4
> --- /dev/null
> +++ b/doc/guides/compressdevs/features/zlib.ini
> @@ -0,0 +1,22 @@
> +;
> +; Refer to default.ini for the full list of available PMD features.
> +;
> +; Supported features of 'ZLIB' compression driver.
> +;
> +[Features]
> +HW Accelerated =
> +CPU SSE        =
> +CPU AVX        =
> +CPU AVX2       =
> +CPU AVX512     =
> +CPU NEON       =
> +Stateful       =
> +By-Pass        =
> +Chained mbufs  =
> +Deflate        = Y
> +LZS            =
> +Adler32        =
> +Crc32          =
> +Adler32&Crc32  =
> +Fixed          = Y
> +Dynamic        = Y

No need to include the features that the PMD does not support
(plus, some of those names have been changed).

> diff --git a/doc/guides/compressdevs/zlib.rst
> b/doc/guides/compressdevs/zlib.rst
> new file mode 100644
> index 0000000..7dd5c74
> --- /dev/null
> +++ b/doc/guides/compressdevs/zlib.rst

...

> +
> +Installation
> +------------
> +
> +* To build DPDK with ZLIB library, the user is required to download the ``libz``

Zlib?

> library.
> +* Use following command for installation.
> +
> +*  For Fedora users ::
> +  yum install zlib-devel
> +*  For ubuntu users ::

Ubuntu

> +  apt-get install zlib1g-dev

I am seeing a build error because of these lines:

doc/guides/compressdevs/zlib.rst:41: WARNING: Literal block expected; none found.
doc/guides/compressdevs/zlib.rst:41: WARNING: Bullet list ends without a blank line; unexpected unindent.
doc/guides/compressdevs/zlib.rst:42: WARNING: Block quote ends without a blank line; unexpected unindent.
doc/guides/compressdevs/zlib.rst:43: WARNING: Literal block expected; none found.
doc/guides/compressdevs/zlib.rst:43: WARNING: Bullet list ends without a blank line; unexpected unindent.
doc/guides/compressdevs/zlib.rst: WARNING: document isn't included in any toctree

> +
> +* Once downloaded, the user needs to build the library.
> +
> +* make can  be used to install the library on their system, before building
> DPDK::
> +
> +    make
> +    sudo make install

This is not required for packages in distros. I assume that this is then for building from source code.
In that case, I think it would be good to differentiate between the two scenarios.
Verma, Shally July 11, 2018, 5:16 p.m. UTC | #2 
>-----Original Message-----
>From: De Lara Guarch, Pablo [mailto:pablo.de.lara.guarch@intel.com]
>Sent: 11 July 2018 19:32
>To: Verma, Shally <Shally.Verma@cavium.com>
>Cc: dev@dpdk.org; Athreya, Narayana Prasad <NarayanaPrasad.Athreya@cavium.com>; Challa, Mahipal
><Mahipal.Challa@cavium.com>; Sahu, Sunila <Sunila.Sahu@cavium.com>; Gupta, Ashish <Ashish.Gupta@cavium.com>
>Subject: RE: [PATCH v2 5/5] doc: add ZLIB PMD documentation
>
>External Email
>
>> -----Original Message-----
>> From: Shally Verma [mailto:shally.verma@caviumnetworks.com]
>> Sent: Monday, July 2, 2018 5:57 PM
>> To: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>
>> Cc: dev@dpdk.org; pathreya@caviumnetworks.com;
>> mchalla@caviumnetworks.com; Sunila Sahu
>> <sunila.sahu@caviumnetworks.com>; Ashish Gupta
>> <ashish.gupta@caviumnetworks.com>
>> Subject: [PATCH v2 5/5] doc: add ZLIB PMD documentation
>>
>
>Better change title to "add ZLIB PMD guide", to avoid duplication.
>
>> add zlib pmd feature specification and overview documentation
>>
>> Signed-off-by: Sunila Sahu <sunila.sahu@caviumnetworks.com>
>> Signed-off-by: Shally Verma <shally.verma@caviumnetworks.com>
>> Signed-off-by: Ashish Gupta <ashish.gupta@caviumnetworks.com>
>> ---
>>  MAINTAINERS                               |  2 +
>>  doc/guides/compressdevs/features/zlib.ini | 22 ++++++++++
>>  doc/guides/compressdevs/zlib.rst          | 68
>> +++++++++++++++++++++++++++++++
>>  3 files changed, 92 insertions(+)
>>
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index 448bbe1..1c217b0 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -854,6 +854,8 @@ F: doc/guides/compressdevs/features/isal.ini
>>  ZLIB
>>  M: Sunila Sahu <sunila.sahu@caviumnetworks.com>
>>  F: drivers/compress/zlib/
>> +F: doc/guides/compressdevs/zlib.rst
>> +F: doc/guides/compressdevs/features/zlib.ini
>>
>>  Eventdev Drivers
>>  ----------------
>> diff --git a/doc/guides/compressdevs/features/zlib.ini
>> b/doc/guides/compressdevs/features/zlib.ini
>> new file mode 100644
>> index 0000000..bdc0fc4
>> --- /dev/null
>> +++ b/doc/guides/compressdevs/features/zlib.ini
>> @@ -0,0 +1,22 @@
>> +;
>> +; Refer to default.ini for the full list of available PMD features.
>> +;
>> +; Supported features of 'ZLIB' compression driver.
>> +;
>> +[Features]
>> +HW Accelerated =
>> +CPU SSE        =
>> +CPU AVX        =
>> +CPU AVX2       =
>> +CPU AVX512     =
>> +CPU NEON       =
>> +Stateful       =
>> +By-Pass        =
>> +Chained mbufs  =
>> +Deflate        = Y
>> +LZS            =
>> +Adler32        =
>> +Crc32          =
>> +Adler32&Crc32  =
>> +Fixed          = Y
>> +Dynamic        = Y
>
>No need to include the features that the PMD does not support
>(plus, some of those names have been changed).
>
You mean remove entry with empty values like >> +Crc32          =

>> diff --git a/doc/guides/compressdevs/zlib.rst
>> b/doc/guides/compressdevs/zlib.rst
>> new file mode 100644
>> index 0000000..7dd5c74
>> --- /dev/null
>> +++ b/doc/guides/compressdevs/zlib.rst
>
>...
>
>> +
>> +Installation
>> +------------
>> +
>> +* To build DPDK with ZLIB library, the user is required to download the ``libz``
>
>Zlib?
Library is available with name libz .

Thanks
Shally
>
>> library.
>> +* Use following command for installation.
>> +
>> +*  For Fedora users ::
>> +  yum install zlib-devel
>> +*  For ubuntu users ::
>
>Ubuntu
>
>> +  apt-get install zlib1g-dev
>
>I am seeing a build error because of these lines:
>
>doc/guides/compressdevs/zlib.rst:41: WARNING: Literal block expected; none found.
>doc/guides/compressdevs/zlib.rst:41: WARNING: Bullet list ends without a blank line; unexpected unindent.
>doc/guides/compressdevs/zlib.rst:42: WARNING: Block quote ends without a blank line; unexpected unindent.
>doc/guides/compressdevs/zlib.rst:43: WARNING: Literal block expected; none found.
>doc/guides/compressdevs/zlib.rst:43: WARNING: Bullet list ends without a blank line; unexpected unindent.
>doc/guides/compressdevs/zlib.rst: WARNING: document isn't included in any toctree
>
>> +
>> +* Once downloaded, the user needs to build the library.
>> +
>> +* make can  be used to install the library on their system, before building
>> DPDK::
>> +
>> +    make
>> +    sudo make install
>
>This is not required for packages in distros. I assume that this is then for building from source code.
>In that case, I think it would be good to differentiate between the two scenarios.
>
>
De Lara Guarch, Pablo July 11, 2018, 8:56 p.m. UTC | #3 
> -----Original Message-----
> From: Verma, Shally [mailto:Shally.Verma@cavium.com]
> Sent: Wednesday, July 11, 2018 6:16 PM
> To: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>
> Cc: dev@dpdk.org; Athreya, Narayana Prasad
> <NarayanaPrasad.Athreya@cavium.com>; Challa, Mahipal
> <Mahipal.Challa@cavium.com>; Sahu, Sunila <Sunila.Sahu@cavium.com>;
> Gupta, Ashish <Ashish.Gupta@cavium.com>
> Subject: RE: [PATCH v2 5/5] doc: add ZLIB PMD documentation
> 
> 
> 
> >-----Original Message-----
> >From: De Lara Guarch, Pablo [mailto:pablo.de.lara.guarch@intel.com]
> >Sent: 11 July 2018 19:32
> >To: Verma, Shally <Shally.Verma@cavium.com>
> >Cc: dev@dpdk.org; Athreya, Narayana Prasad
> ><NarayanaPrasad.Athreya@cavium.com>; Challa, Mahipal
> ><Mahipal.Challa@cavium.com>; Sahu, Sunila <Sunila.Sahu@cavium.com>;
> >Gupta, Ashish <Ashish.Gupta@cavium.com>
> >Subject: RE: [PATCH v2 5/5] doc: add ZLIB PMD documentation
> >
> >External Email
> >
> >> -----Original Message-----
> >> From: Shally Verma [mailto:shally.verma@caviumnetworks.com]
> >> Sent: Monday, July 2, 2018 5:57 PM
> >> To: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>
> >> Cc: dev@dpdk.org; pathreya@caviumnetworks.com;
> >> mchalla@caviumnetworks.com; Sunila Sahu
> >> <sunila.sahu@caviumnetworks.com>; Ashish Gupta
> >> <ashish.gupta@caviumnetworks.com>
> >> Subject: [PATCH v2 5/5] doc: add ZLIB PMD documentation
> >>
> >
> >Better change title to "add ZLIB PMD guide", to avoid duplication.
> >
> >> add zlib pmd feature specification and overview documentation
> >>
> >> Signed-off-by: Sunila Sahu <sunila.sahu@caviumnetworks.com>
> >> Signed-off-by: Shally Verma <shally.verma@caviumnetworks.com>
> >> Signed-off-by: Ashish Gupta <ashish.gupta@caviumnetworks.com>
> >> ---
> >>  MAINTAINERS                               |  2 +
> >>  doc/guides/compressdevs/features/zlib.ini | 22 ++++++++++
> >>  doc/guides/compressdevs/zlib.rst          | 68
> >> +++++++++++++++++++++++++++++++
> >>  3 files changed, 92 insertions(+)
> >>
> >> diff --git a/MAINTAINERS b/MAINTAINERS index 448bbe1..1c217b0 100644
> >> --- a/MAINTAINERS
> >> +++ b/MAINTAINERS
> >> @@ -854,6 +854,8 @@ F: doc/guides/compressdevs/features/isal.ini
> >>  ZLIB
> >>  M: Sunila Sahu <sunila.sahu@caviumnetworks.com>
> >>  F: drivers/compress/zlib/
> >> +F: doc/guides/compressdevs/zlib.rst
> >> +F: doc/guides/compressdevs/features/zlib.ini
> >>
> >>  Eventdev Drivers
> >>  ----------------
> >> diff --git a/doc/guides/compressdevs/features/zlib.ini
> >> b/doc/guides/compressdevs/features/zlib.ini
> >> new file mode 100644
> >> index 0000000..bdc0fc4
> >> --- /dev/null
> >> +++ b/doc/guides/compressdevs/features/zlib.ini
> >> @@ -0,0 +1,22 @@
> >> +;
> >> +; Refer to default.ini for the full list of available PMD features.
> >> +;
> >> +; Supported features of 'ZLIB' compression driver.
> >> +;
> >> +[Features]
> >> +HW Accelerated =
> >> +CPU SSE        =
> >> +CPU AVX        =
> >> +CPU AVX2       =
> >> +CPU AVX512     =
> >> +CPU NEON       =
> >> +Stateful       =
> >> +By-Pass        =
> >> +Chained mbufs  =
> >> +Deflate        = Y
> >> +LZS            =
> >> +Adler32        =
> >> +Crc32          =
> >> +Adler32&Crc32  =
> >> +Fixed          = Y
> >> +Dynamic        = Y
> >
> >No need to include the features that the PMD does not support (plus,
> >some of those names have been changed).
> >
> You mean remove entry with empty values like >> +Crc32          =

Exactly.
diff mbox series

Patch

diff --git a/MAINTAINERS b/MAINTAINERS
index 448bbe1..1c217b0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -854,6 +854,8 @@  F: doc/guides/compressdevs/features/isal.ini
 ZLIB
 M: Sunila Sahu <sunila.sahu@caviumnetworks.com>
 F: drivers/compress/zlib/
+F: doc/guides/compressdevs/zlib.rst
+F: doc/guides/compressdevs/features/zlib.ini
 
 Eventdev Drivers
 ----------------
diff --git a/doc/guides/compressdevs/features/zlib.ini b/doc/guides/compressdevs/features/zlib.ini
new file mode 100644
index 0000000..bdc0fc4
--- /dev/null
+++ b/doc/guides/compressdevs/features/zlib.ini
@@ -0,0 +1,22 @@ 
+;
+; Refer to default.ini for the full list of available PMD features.
+;
+; Supported features of 'ZLIB' compression driver.
+;
+[Features]
+HW Accelerated =
+CPU SSE        =
+CPU AVX        =
+CPU AVX2       =
+CPU AVX512     =
+CPU NEON       =
+Stateful       =
+By-Pass        =
+Chained mbufs  =
+Deflate        = Y
+LZS            =
+Adler32        =
+Crc32          =
+Adler32&Crc32  =
+Fixed          = Y
+Dynamic        = Y
diff --git a/doc/guides/compressdevs/zlib.rst b/doc/guides/compressdevs/zlib.rst
new file mode 100644
index 0000000..7dd5c74
--- /dev/null
+++ b/doc/guides/compressdevs/zlib.rst
@@ -0,0 +1,68 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Cavium Networks.
+
+ZLIB Compression Poll Mode Driver
+==================================
+
+The ZLIB PMD (**librte_pmd_zlib**) provides poll mode compression &
+decompression driver based on SW zlib library,
+
+Features
+--------
+
+ZLIB PMD has support for:
+
+Compression/Decompression algorithm:
+
+* DEFLATE
+
+Huffman code type:
+
+* FIXED
+* DYNAMIC
+
+Window size support:
+
+* Min - 256 bytes
+* Max - 32K
+
+Limitations
+-----------
+
+* Chained mbufs are not supported.
+
+Installation
+------------
+
+* To build DPDK with ZLIB library, the user is required to download the ``libz`` library.
+* Use following command for installation.
+
+*  For Fedora users ::
+  yum install zlib-devel
+*  For ubuntu users ::
+  apt-get install zlib1g-dev
+
+* Once downloaded, the user needs to build the library.
+
+* make can  be used to install the library on their system, before building DPDK::
+
+    make
+    sudo make install
+
+Initialization
+--------------
+
+In order to enable this virtual compression PMD, user must:
+
+* Set ``CONFIG_RTE_LIBRTE_PMD_ZLIB=y`` in config/common_base.
+
+To use the PMD in an application, user must:
+
+* Call ``rte_vdev_init("compress_zlib")`` within the application.
+
+* Use ``--vdev="compress_zlib"`` 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).