doc/guides/tools/comp_perf.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 dpdk-test-compress-perf Tool
   5 ============================
   6
   7 The ``dpdk-test-compress-perf`` tool is a Data Plane Development Kit (DPDK)
   8 utility that allows measuring performance parameters of PMDs available in the
   9 compress tree. User can use multiple cores to run tests on but only
  10 one type of compression PMD can be measured during single application
  11 execution. The tool reads the data from a file (--input-file),
  12 dumps all the file into a buffer and fills out the data of input mbufs,
  13 which are passed to compress device with compression operations.
  14 Then, the output buffers are fed into the decompression stage, and the resulting
  15 data is compared against the original data (verification phase). After that,
  16 a number of iterations are performed, compressing first and decompressing later,
  17 to check the throughput rate (showing cycles/iteration, cycles/Byte and Gbps,
  18 for compression and decompression).
  19 Another option: ``pmd-cyclecount``, gives the user the opportunity to measure
  20 the number of cycles per operation for the 3 phases: setup, enqueue_burst and
  21 dequeue_burst, for both compression and decompression. An optional delay can be
  22 inserted between enqueue and dequeue so no cycles are wasted in retries while
  23 waiting for a hardware device to finish. Although artificial, this allows
  24 to measure the minimum offload cost which could be achieved in a perfectly
  25 tuned system. Comparing the results of the two tests gives information about
  26 the trade-off between throughput and cycle-count.
  27
  28 .. Note::
  29
  30         if the max-num-sgl-segs x seg_sz > input size then segments number in
  31         the chain will be lower than value passed into max-num-sgl-segs.
  32
  33
  34 Limitations
  35 ~~~~~~~~~~~
  36
  37 * Stateful operation is not supported in this version.
  38
  39 EAL Options
  40 ~~~~~~~~~~~
  41
  42 The following are the EAL command-line options that can be used in conjunction
  43 with the ``dpdk-test-compress-perf`` application.
  44 See the DPDK Getting Started Guides for more information on these options.
  45
  46 *   ``-c <COREMASK>`` or ``-l <CORELIST>``
  47
  48         Set the hexadecimal bitmask of the cores to run on. The corelist is a
  49         list cores to use.
  50
  51 .. Note::
  52
  53         One lcore is needed for process admin, tests are run on all other cores.
  54         To run tests on two lcores, three lcores must be passed to the tool.
  55
  56 *   ``-w <PCI>``
  57
  58         Add a PCI device in white list.
  59
  60 *   ``--vdev <driver><id>``
  61
  62         Add a virtual device.
  63
  64 Application Options
  65 ~~~~~~~~~~~~~~~~~~~
  66
  67  ``--ptest [throughput/verify/pmd-cyclecount]``: set test type (default: throughput)
  68
  69  ``--driver-name NAME``: compress driver to use
  70
  71  ``--input-file NAME``: file to compress and decompress
  72
  73  ``--extended-input-sz N``: extend file data up to this size (default: no extension)
  74
  75  ``--seg-sz N``: size of segment to store the data (default: 2048)
  76
  77  ``--burst-sz N``: compress operation burst size
  78
  79  ``--pool-sz N``: mempool size for compress operations/mbufs (default: 8192)
  80
  81  ``--max-num-sgl-segs N``: maximum number of segments for each mbuf (default: 16)
  82
  83  ``--num-iter N``: number of times the file will be compressed/decompressed (default: 10000)
  84
  85  ``--operation [comp/decomp/comp_and_decomp]``: perform test on compression, decompression or both operations
  86
  87  ``--huffman-enc [fixed/dynamic/default]``: Huffman encoding (default: dynamic)
  88
  89  ``--compress-level N``: compression level, which could be a single value, list or range (default: range between 1 and 9)
  90
  91  ``--window-sz N``: base two log value of compression window size (default: max supported by PMD)
  92
  93  ``--external-mbufs``: allocate and use memzones as external buffers instead of keeping the data directly in mbuf areas
  94
  95  ``--cc-delay-us N``: delay between enqueue and dequeue operations in microseconds, valid only for the cyclecount test (default: 500 us)
  96
  97  ``-h``: prints this help
  98
  99
 100 Compiling the Tool
 101 ------------------
 102
 103 **Step 1: PMD setting**
 104
 105 The ``dpdk-test-compress-perf`` tool depends on compression device drivers PMD which
 106 can be disabled by default in the build configuration file ``common_base``.
 107 The compression device drivers PMD which should be tested can be enabled by setting e.g.::
 108
 109    CONFIG_RTE_LIBRTE_PMD_ISAL=y
 110
 111
 112 Running the Tool
 113 ----------------
 114
 115 The tool has a number of command line options. Here is the sample command line:
 116
 117 .. code-block:: console
 118
 119    ./build/app/dpdk-test-compress-perf  -l 4 -- --driver-name compress_qat --input-file test.txt --seg-sz 8192
 120     --compress-level 1:1:9 --num-iter 10 --extended-input-sz 1048576  --max-num-sgl-segs 16 --huffman-enc fixed