[v2,3/3] doc/guides/tools: add doc files

  Added:
 -  initial version of compression performance test
    description file.
 -  release note in release_18_11.rst

Signed-off-by: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>
Signed-off-by: Tomasz Jozwiak <tomaszx.jozwiak@intel.com>
---
 MAINTAINERS                            |  5 +++
 doc/guides/rel_notes/release_18_11.rst |  6 +++
 doc/guides/tools/comp_perf.rst         | 75 ++++++++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+)
 create mode 100644 doc/guides/tools/comp_perf.rst
  

>-----Original Message-----
>From: Tomasz Jozwiak <tomaszx.jozwiak@intel.com>
>Sent: 02 November 2018 15:14
>To: dev@dpdk.org; fiona.trahe@intel.com; tomaszx.jozwiak@intel.com; Verma, Shally <Shally.Verma@cavium.com>;
>akhil.goyal@nxp.com
>Subject: [PATCH v2 3/3] doc/guides/tools: add doc files
>
>External Email
>
>Added:
> -  initial version of compression performance test
>    description file.
> -  release note in release_18_11.rst
>
>Signed-off-by: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>
>Signed-off-by: Tomasz Jozwiak <tomaszx.jozwiak@intel.com>
>---
> MAINTAINERS                            |  5 +++
> doc/guides/rel_notes/release_18_11.rst |  6 +++
> doc/guides/tools/comp_perf.rst         | 75 ++++++++++++++++++++++++++++++++++
> 3 files changed, 86 insertions(+)
> create mode 100644 doc/guides/tools/comp_perf.rst
>
>diff --git a/MAINTAINERS b/MAINTAINERS
>index e60379d..cfda6dd 100644
>--- a/MAINTAINERS
>+++ b/MAINTAINERS
>@@ -1242,6 +1242,11 @@ M: Bernard Iremonger <bernard.iremonger@intel.com>
> F: app/test-pmd/
> F: doc/guides/testpmd_app_ug/
>
>+Compression performance test application
>+M: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>
>+F: app/test-compress-perf/
>+F: doc/guides/tools/comp_perf.rst
>+
> Crypto performance test application
> M: Declan Doherty <declan.doherty@intel.com>
> F: app/test-crypto-perf/
>diff --git a/doc/guides/rel_notes/release_18_11.rst b/doc/guides/rel_notes/release_18_11.rst
>index 376128f..8bc7d05 100644
>--- a/doc/guides/rel_notes/release_18_11.rst
>+++ b/doc/guides/rel_notes/release_18_11.rst
>@@ -285,6 +285,12 @@ New Features
>   this application doesn't need to launch dedicated worker threads for vhost
>   enqueue/dequeue operations.
>
>+* **Added a compression performance test tool.**
>+
>+   Added a new performance test tool to test the compressdev PMD. The tool tests
>+   compression ratio and compression throughput. Dynamic compression test is not
>+   supported yet.
>+
>
> API Changes
> -----------
>diff --git a/doc/guides/tools/comp_perf.rst b/doc/guides/tools/comp_perf.rst
>new file mode 100644
>index 0000000..2f43412
>--- /dev/null
>+++ b/doc/guides/tools/comp_perf.rst
>@@ -0,0 +1,75 @@
>+..  SPDX-License-Identifier: BSD-3-Clause
>+    Copyright(c) 2018 Intel Corporation.
>+
>+dpdk-test-crypto-perf Application
>+=================================
>+
>+The ``dpdk-test-compress-perf`` tool is a Data Plane Development Kit (DPDK)
>+utility that allows measuring performance parameters of PMDs available in the
>+compress tree. The application reads the data from a file (--input-file),
>+dumps all the file into a buffer and fills out the data of input mbufs,
>+which are passed to compress device with compression operations.
>+Then, the output buffers are fed into the decompression stage, and the resulting
>+data is compared against the original data (verification phase). After that,
>+a number of iterations are performed, compressing first and decompressing later,
>+to check the throughput rate
>+(showing cycles/iteration, cycles/Byte and Gbps, for compression and decompression).
>+
>+
>+Limitations
>+~~~~~~~~~~~
>+
>+* Only supports the fixed compression.
Perf app seem to support stateless only for now, so should mention as "supported for fixed and stateless operation only."
Thanks
Shally

>+
>+Command line options
>+--------------------
>+
>+ ``--driver-name NAME``: compress driver to use
>+
>+ ``--input-file NAME``: file to compress and decompress
>+
>+ ``--extended-input-sz N``: extend file data up to this size (default: no extension)
>+
>+ ``--seg-sz N``: size of segment to store the data (default: 2048)
>+
>+ ``--burst-sz N``: compress operation burst size
>+
>+ ``--pool-sz N``: mempool size for compress operations/mbufs (default: 8192)
>+
>+ ``--max-num-sgl-segs N``: maximum number of segments for each mbuf (default: 16)
>+
>+ ``--num-iter N``: number of times the file will be compressed/decompressed (default: 10000)
>+
>+ ``--operation [comp/decomp/comp_and_decomp]``: perform test on compression, decompression or both operations
>+
>+ ``--huffman-enc [fixed/default]``: Huffman encoding (default: fixed)
>+
>+ ``--compress-level N``: compression level, which could be a single value, list or range (default: range between 1 and 9)
>+
>+ ``--window-sz N``: base two log value of compression window size (default: max supported by PMD)
>+
>+ ``-h``: prints this help
>+
>+
>+Compiling the Application
>+-------------------------
>+
>+**Step 1: PMD setting**
>+
>+The ``dpdk-test-compress-perf`` tool depends on compression device drivers PMD which
>+can be disabled by default in the build configuration file ``common_base``.
>+The compression device drivers PMD which should be tested can be enabled by setting::
>+
>+   CONFIG_RTE_LIBRTE_PMD_ISAL=y
>+
>+
>+Running the Application
>+-----------------------
>+
>+The tool application has a number of command line options. Here is the sample command line:
>+
>+.. code-block:: console
>+
>+   ./build/app/dpdk-test-compress-perf  -l 4 -- --driver-name compress_qat --input-file test.txt --seg-sz 8192
>+    --compress-level 1:1:9 --num-iter 10 --extended-input-sz 1048576  --max-num-sgl-segs 16 --huffman-enc fixed
>+
>--
>2.7.4
  

> -----Original Message-----
> From: Verma, Shally [mailto:Shally.Verma@cavium.com]
> Sent: Monday, November 5, 2018 9:58 AM
> To: Jozwiak, TomaszX <tomaszx.jozwiak@intel.com>; dev@dpdk.org; Trahe,
> Fiona <fiona.trahe@intel.com>; akhil.goyal@nxp.com
> Subject: RE: [PATCH v2 3/3] doc/guides/tools: add doc files
> 
> 
> 
> >-----Original Message-----
> >From: Tomasz Jozwiak <tomaszx.jozwiak@intel.com>
> >Sent: 02 November 2018 15:14
> >To: dev@dpdk.org; fiona.trahe@intel.com; tomaszx.jozwiak@intel.com;
> >Verma, Shally <Shally.Verma@cavium.com>; akhil.goyal@nxp.com
> >Subject: [PATCH v2 3/3] doc/guides/tools: add doc files
> >
> >External Email
> >
> >Added:
> > -  initial version of compression performance test
> >    description file.
> > -  release note in release_18_11.rst
> >
> >Signed-off-by: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>
> >Signed-off-by: Tomasz Jozwiak <tomaszx.jozwiak@intel.com>
> >---
> > MAINTAINERS                            |  5 +++
> > doc/guides/rel_notes/release_18_11.rst |  6 +++
> > doc/guides/tools/comp_perf.rst         | 75
> ++++++++++++++++++++++++++++++++++
> > 3 files changed, 86 insertions(+)
> > create mode 100644 doc/guides/tools/comp_perf.rst
> >
> >diff --git a/MAINTAINERS b/MAINTAINERS
> >index e60379d..cfda6dd 100644
> >--- a/MAINTAINERS
> >+++ b/MAINTAINERS
> >@@ -1242,6 +1242,11 @@ M: Bernard Iremonger
> ><bernard.iremonger@intel.com>
> > F: app/test-pmd/
> > F: doc/guides/testpmd_app_ug/
> >
> >+Compression performance test application
> >+M: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>
> >+F: app/test-compress-perf/
> >+F: doc/guides/tools/comp_perf.rst
> >+
> > Crypto performance test application
> > M: Declan Doherty <declan.doherty@intel.com>
> > F: app/test-crypto-perf/
> >diff --git a/doc/guides/rel_notes/release_18_11.rst
> >b/doc/guides/rel_notes/release_18_11.rst
> >index 376128f..8bc7d05 100644
> >--- a/doc/guides/rel_notes/release_18_11.rst
> >+++ b/doc/guides/rel_notes/release_18_11.rst
> >@@ -285,6 +285,12 @@ New Features
> >   this application doesn't need to launch dedicated worker threads for vhost
> >   enqueue/dequeue operations.
> >
> >+* **Added a compression performance test tool.**
> >+
> >+   Added a new performance test tool to test the compressdev PMD. The
> tool tests
> >+   compression ratio and compression throughput. Dynamic compression
> test is not
> >+   supported yet.
> >+
> >
> > API Changes
> > -----------
> >diff --git a/doc/guides/tools/comp_perf.rst
> >b/doc/guides/tools/comp_perf.rst new file mode 100644 index
> >0000000..2f43412
> >--- /dev/null
> >+++ b/doc/guides/tools/comp_perf.rst
> >@@ -0,0 +1,75 @@
> >+..  SPDX-License-Identifier: BSD-3-Clause
> >+    Copyright(c) 2018 Intel Corporation.
> >+
> >+dpdk-test-crypto-perf Application
> >+=================================
> >+
> >+The ``dpdk-test-compress-perf`` tool is a Data Plane Development Kit
> >+(DPDK) utility that allows measuring performance parameters of PMDs
> >+available in the compress tree. The application reads the data from a
> >+file (--input-file), dumps all the file into a buffer and fills out
> >+the data of input mbufs, which are passed to compress device with
> compression operations.
> >+Then, the output buffers are fed into the decompression stage, and the
> >+resulting data is compared against the original data (verification
> >+phase). After that, a number of iterations are performed, compressing
> >+first and decompressing later, to check the throughput rate (showing
> >+cycles/iteration, cycles/Byte and Gbps, for compression and
> decompression).
> >+
> >+
> >+Limitations
> >+~~~~~~~~~~~
> >+
> >+* Only supports the fixed compression.
> Perf app seem to support stateless only for now, so should mention as
> "supported for fixed and stateless operation only."
> Thanks
> Shally

TJ: True Thx for this. Will be fixed

Thx, Tomek