1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2016 Intel Corporation.
4 dpdk-test-crypto-perf Application
5 =================================
7 The ``dpdk-test-crypto-perf`` tool is a Data Plane Development Kit (DPDK)
8 utility that allows measuring performance parameters of PMDs available in the
9 crypto tree. There are available two measurement types: throughput and latency.
10 User can use multiply cores to run tests on but only
11 one type of crypto PMD can be measured during single application
12 execution. Cipher parameters, type of device, type of operation and
13 chain mode have to be specified in the command line as application
14 parameters. These parameters are checked using device capabilities
19 On hardware devices the cycle-count doesn't always represent the actual offload
20 cost. The cycle-count only represents the offload cost when the hardware
21 accelerator is not fully loaded, when loaded the cpu cycles freed up by the
22 offload are still consumed by the test tool and included in the cycle-count.
23 These cycles are consumed by retries and inefficient API calls enqueuing and
24 dequeuing smaller bursts than specified by the cmdline parameter. This results
25 in a larger cycle-count measurement and should not be interpreted as an offload
26 cost measurement. Using "pmd-cyclecount" mode will give a better idea of
27 actual costs of hardware acceleration.
29 On hardware devices the throughput measurement is not necessarily the maximum
30 possible for the device, e.g. it may be necessary to use multiple cores to keep
31 the hardware accelerator fully loaded and so measure maximum throughput.
37 It is possible linearized input segmented packets just before crypto operation
38 for devices which doesn't support scatter-gather, and allows to measure
39 performance also for this use case.
41 To set on the linearization options add below definition to the
42 ``cperf_ops.h`` file::
44 #define CPERF_LINEARIZATION_ENABLE
47 Running the Application
48 -----------------------
50 The tool application has a number of command line options:
52 .. code-block:: console
54 dpdk-test-crypto-perf [EAL Options] -- [Application Options]
59 The following are the EAL command-line options that can be used in conjunction
60 with the ``dpdk-test-crypto-perf`` application.
61 See the DPDK Getting Started Guides for more information on these options.
63 * ``-c <COREMASK>`` or ``-l <CORELIST>``
65 Set the hexadecimal bitmask of the cores to run on. The corelist is a
70 Add a PCI device in allow list.
72 * ``--vdev <driver><id>``
79 The following are the application command-line options:
83 Set test type, where ``type`` is one of the following::
96 Set the number of mbufs to be allocated in the mbuf pool.
100 Set the number of total operations performed.
104 Set the number of packets per burst.
107 * Single value (i.e. ``--burst-sz 16``)
108 * Range of values, using the following structure ``min:inc:max``,
109 where ``min`` is minimum size, ``inc`` is the increment size and ``max``
110 is the maximum size (i.e. ``--burst-sz 16:2:32``)
111 * List of values, up to 32 values, separated in commas (i.e. ``--burst-sz 16,24,32``)
113 * ``--buffer-sz <n>``
115 Set the size of single packet (plaintext or ciphertext in it).
118 * Single value (i.e. ``--buffer-sz 16``)
119 * Range of values, using the following structure ``min:inc:max``,
120 where ``min`` is minimum size, ``inc`` is the increment size and ``max``
121 is the maximum size (i.e. ``--buffer-sz 16:2:32``)
122 * List of values, up to 32 values, separated in commas (i.e. ``--buffer-sz 32,64,128``)
126 Set the distribution of packet sizes.
128 A list of weights must be passed, containing the same number of items than buffer-sz,
129 so each item in this list will be the weight of the packet size on the same position
130 in the buffer-sz parameter (a list have to be passed in that parameter).
134 To test a distribution of 20% packets of 64 bytes, 40% packets of 100 bytes and 40% packets
135 of 256 bytes, the command line would be: ``--buffer-sz 64,100,256 --imix 20,40,40``.
136 Note that the weights do not have to be percentages, so using ``--imix 1,2,2`` would result
137 in the same distribution
139 * ``--segment-sz <n>``
141 Set the size of the segment to use, for Scatter Gather List testing.
142 By default, it is set to the size of the maximum buffer size, including the digest size,
143 so a single segment is created.
145 * ``--devtype <name>``
147 Set device type, where ``name`` is one of the following::
166 * ``--optype <name>``
168 Set operation type, where ``name`` is one of the following::
179 For GCM/CCM algorithms you should use aead flag.
183 Enable session-less crypto operations mode.
187 Enable out-of-place crypto operations mode.
189 * ``--test-file <name>``
191 Set test vector file path. See the Test Vector File chapter.
193 * ``--test-name <name>``
195 Set specific test name section in the test vector file.
197 * ``--cipher-algo <name>``
199 Set cipher algorithm name, where ``name`` is one of the following::
215 * ``--cipher-op <mode>``
217 Set cipher operation mode, where ``mode`` is one of the following::
222 * ``--cipher-key-sz <n>``
224 Set the size of cipher key.
226 * ``--cipher-iv-sz <n>``
228 Set the size of cipher iv.
230 * ``--auth-algo <name>``
232 Set authentication algorithm name, where ``name`` is one
256 * ``--auth-op <mode>``
258 Set authentication operation mode, where ``mode`` is one of
264 * ``--auth-key-sz <n>``
266 Set the size of authentication key.
268 * ``--auth-iv-sz <n>``
270 Set the size of auth iv.
272 * ``--aead-algo <name>``
274 Set AEAD algorithm name, where ``name`` is one
280 * ``--aead-op <mode>``
282 Set AEAD operation mode, where ``mode`` is one of
288 * ``--aead-key-sz <n>``
290 Set the size of AEAD key.
292 * ``--aead-iv-sz <n>``
294 Set the size of AEAD iv.
296 * ``--aead-aad-sz <n>``
298 Set the size of AEAD aad.
300 * ``--digest-sz <n>``
302 Set the size of digest.
306 Set number of descriptors for each crypto device.
308 * ``--pmd-cyclecount-delay-ms <n>``
310 Add a delay (in milliseconds) between enqueue and dequeue in
311 pmd-cyclecount benchmarking mode (useful when benchmarking
312 hardware acceleration).
316 Enable test result output CSV friendly rather than human friendly.
318 * ``--pdcp-sn-sz <n>``
320 Set PDCP sequence number size(n) in bits. Valid values of n will
323 * ``--pdcp-domain <control/user>``
325 Set PDCP domain to specify short_mac/control/user plane.
327 * ``--docsis-hdr-sz <n>``
329 Set DOCSIS header size(n) in bytes.
331 * ``--pdcp-ses-hfn-en``
333 Enable fixed session based HFN instead of per packet HFN.
335 * ``--modex-len <n>``
337 Set modex length for asymmetric crypto perf test.
338 Supported lengths are 60, 128, 255, 448. Default length is 128.
343 The test vector file is a text file contain information about test vectors.
344 The file is made of the sections. The first section doesn't have header.
345 It contain global information used in each test variant vectors -
346 typically information about plaintext, ciphertext, cipher key, auth key,
347 initial vector. All other sections begin header.
348 The sections contain particular information typically digest.
350 **Format of the file:**
352 Each line beginning with sign '#' contain comment and it is ignored by parser::
356 Header line is just name in square bracket::
360 Data line contain information token then sign '=' and
361 a string of bytes in C byte array format::
363 <token> = <C byte array>
369 Original plaintext to be encrypted.
373 Encrypted plaintext string.
377 Key used in cipher operation.
381 Key used in auth operation.
385 Cipher Initial Vector.
402 Call application for performance throughput test of single Aesni MB PMD
403 for cipher encryption aes-cbc and auth generation sha1-hmac,
404 one million operations, burst size 32, packet size 64::
406 dpdk-test-crypto-perf -l 6-7 --vdev crypto_aesni_mb -a 0000:00:00.0 --
407 --ptest throughput --devtype crypto_aesni_mb --optype cipher-then-auth
408 --cipher-algo aes-cbc --cipher-op encrypt --cipher-key-sz 16 --auth-algo
409 sha1-hmac --auth-op generate --auth-key-sz 64 --digest-sz 12
410 --total-ops 10000000 --burst-sz 32 --buffer-sz 64
412 Call application for performance latency test of two Aesni MB PMD executed
413 on two cores for cipher encryption aes-cbc, ten operations in silent mode::
415 dpdk-test-crypto-perf -l 4-7 --vdev crypto_aesni_mb1
416 --vdev crypto_aesni_mb2 -a 0000:00:00.0 -- --devtype crypto_aesni_mb
417 --cipher-algo aes-cbc --cipher-key-sz 16 --cipher-iv-sz 16
418 --cipher-op encrypt --optype cipher-only --silent
419 --ptest latency --total-ops 10
421 Call application for verification test of single open ssl PMD
422 for cipher encryption aes-gcm and auth generation aes-gcm,ten operations
423 in silent mode, test vector provide in file "test_aes_gcm.data"
424 with packet verification::
426 dpdk-test-crypto-perf -l 4-7 --vdev crypto_openssl -a 0000:00:00.0 --
427 --devtype crypto_openssl --aead-algo aes-gcm --aead-key-sz 16
428 --aead-iv-sz 16 --aead-op encrypt --aead-aad-sz 16 --digest-sz 16
429 --optype aead --silent --ptest verify --total-ops 10
430 --test-file test_aes_gcm.data
432 Test vector file for cipher algorithm aes cbc 256 with authorization sha::
436 0xff, 0xca, 0xfb, 0xf1, 0x38, 0x20, 0x2f, 0x7b, 0x24, 0x98, 0x26, 0x7d, 0x1d, 0x9f, 0xb3, 0x93,
437 0xd9, 0xef, 0xbd, 0xad, 0x4e, 0x40, 0xbd, 0x60, 0xe9, 0x48, 0x59, 0x90, 0x67, 0xd7, 0x2b, 0x7b,
438 0x8a, 0xe0, 0x4d, 0xb0, 0x70, 0x38, 0xcc, 0x48, 0x61, 0x7d, 0xee, 0xd6, 0x35, 0x49, 0xae, 0xb4,
439 0xaf, 0x6b, 0xdd, 0xe6, 0x21, 0xc0, 0x60, 0xce, 0x0a, 0xf4, 0x1c, 0x2e, 0x1c, 0x8d, 0xe8, 0x7b
441 0x77, 0xF9, 0xF7, 0x7A, 0xA3, 0xCB, 0x68, 0x1A, 0x11, 0x70, 0xD8, 0x7A, 0xB6, 0xE2, 0x37, 0x7E,
442 0xD1, 0x57, 0x1C, 0x8E, 0x85, 0xD8, 0x08, 0xBF, 0x57, 0x1F, 0x21, 0x6C, 0xAD, 0xAD, 0x47, 0x1E,
443 0x0D, 0x6B, 0x79, 0x39, 0x15, 0x4E, 0x5B, 0x59, 0x2D, 0x76, 0x87, 0xA6, 0xD6, 0x47, 0x8F, 0x82,
444 0xB8, 0x51, 0x91, 0x32, 0x60, 0xCB, 0x97, 0xDE, 0xBE, 0xF0, 0xAD, 0xFC, 0x23, 0x2E, 0x22, 0x02
446 0xE4, 0x23, 0x33, 0x8A, 0x35, 0x64, 0x61, 0xE2, 0x49, 0x03, 0xDD, 0xC6, 0xB8, 0xCA, 0x55, 0x7A,
447 0xd0, 0xe7, 0x4b, 0xfb, 0x5d, 0xe5, 0x0c, 0xe7, 0x6f, 0x21, 0xb5, 0x52, 0x2a, 0xbb, 0xc7, 0xf7
449 0xaf, 0x96, 0x42, 0xf1, 0x8c, 0x50, 0xdc, 0x67, 0x1a, 0x43, 0x47, 0x62, 0xc7, 0x04, 0xab, 0x05,
450 0xf5, 0x0c, 0xe7, 0xa2, 0xa6, 0x23, 0xd5, 0x3d, 0x95, 0xd8, 0xcd, 0x86, 0x79, 0xf5, 0x01, 0x47,
451 0x4f, 0xf9, 0x1d, 0x9d, 0x36, 0xf7, 0x68, 0x1a, 0x64, 0x44, 0x58, 0x5d, 0xe5, 0x81, 0x15, 0x2a,
452 0x41, 0xe4, 0x0e, 0xaa, 0x1f, 0x04, 0x21, 0xff, 0x2c, 0xf3, 0x73, 0x2b, 0x48, 0x1e, 0xd2, 0xf7
454 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F
455 # Section sha 1 hmac buff 32
458 0x36, 0xCA, 0x49, 0x6A, 0xE3, 0x54, 0xD8, 0x4F, 0x0B, 0x76, 0xD8, 0xAA, 0x78, 0xEB, 0x9D, 0x65,
459 0x2C, 0xCA, 0x1F, 0x97
460 # Section sha 256 hmac buff 32
461 [sha256_hmac_buff_32]
463 0x1C, 0xB2, 0x3D, 0xD1, 0xF9, 0xC7, 0x6C, 0x49, 0x2E, 0xDA, 0x94, 0x8B, 0xF1, 0xCF, 0x96, 0x43,
464 0x67, 0x50, 0x39, 0x76, 0xB5, 0xA1, 0xCE, 0xA1, 0xD7, 0x77, 0x10, 0x07, 0x43, 0x37, 0x05, 0xB4
467 Graph Crypto Perf Results
468 -------------------------
470 The ``dpdk-graph-crypto-perf.py`` tool is a simple script to automate
471 running crypto performance tests, and graphing the results.
472 It can be found in the ``app/test-crypto-perf/`` directory.
473 The output graphs include various grouped barcharts for throughput
474 tests, and histogram and boxplot graphs for latency tests.
475 These are output to PDF files, with one PDF per test suite graph type.
481 The following python modules must be installed to run the script:
483 .. code-block:: console
485 pip3 install img2pdf plotly pandas psutil kaleido
491 The test cases run by the script are defined by a JSON config file.
492 Some config files can be found in ``app/test-crypto-perf/configs/``,
493 or the user may create a new one following the same format as the config files provided.
495 An example of this format is shown below for one test suite in the ``crypto-perf-aesni-mb.json`` file.
496 This shows the required default config for the test suite, and one test case.
497 The test case has additional app config that will be combined with
498 the default config when running the test case.
506 "vdev": "crypto_aesni_mb"
509 "csv-friendly": true,
510 "buffer-sz": "64,128,256,512,768,1024,1408,2048",
511 "burst-sz": "1,4,8,16,32",
512 "ptest": "throughput",
513 "devtype": "crypto_aesni_mb"
516 "AES-CBC-128 SHA1-HMAC auth-then-cipher decrypt": {
517 "cipher-algo": "aes-cbc",
518 "cipher-key-sz": "16",
519 "auth-algo": "sha1-hmac",
520 "optype": "auth-then-cipher",
521 "cipher-op": "decrypt"
526 The specific test cases only allow modification of app parameters,
527 and not EAL parameters.
528 The default case is required for each test suite in the config file,
529 to specify EAL parameters.
531 Currently, crypto_qat, crypto_aesni_mb, and crypto_aesni_gcm devices for
532 both throughput and latency ptests are supported.
538 .. code-block:: console
540 ./dpdk-graph-crypto-perf <config_file>
542 The ``config_file`` positional argument is required to run the script.
543 This points to a valid JSON config file containing test suites.
545 .. code-block:: console
547 ./dpdk-graph-crypto-perf configs/crypto-perf-aesni-mb.json
549 The following are the application optional command-line options:
553 Display usage information and quit.
555 * ``-f <file_path>, --file-path <file_path>``
557 Provide path to ``dpdk-test-crypto-perf`` application.
558 The script uses the installed app by default.
560 .. code-block:: console
562 ./dpdk-graph-crypto-perf <config_file> \
563 -f <build_dir>/app/dpdk-test-crypto-perf
565 * ``-t <test_suite_list>, --test-suites <test_suite_list>``
567 Specify test suites to run. All test suites are run by default.
569 To run crypto-perf-qat latency test suite only:
571 .. code-block:: console
573 ./dpdk-graph-crypto-perf configs/crypto-perf-qat -t latency
575 To run both crypto-perf-aesni-mb throughput and latency test suites
577 .. code-block:: console
579 ./dpdk-graph-crypto-perf configs/crypto-perf-aesni-mb -t throughput latency
581 * ``-o <output_path>, --output-path <output_path>``
583 Specify directory to use for output files.
584 The default is to use the script's directory.
586 .. code-block:: console
588 ./dpdk-graph-crypto-perf <config_file> -o <output_dir>
592 Enable verbose output. This displays ``dpdk-test-crypto-perf`` app output in real-time.
594 .. code-block:: console
596 ./dpdk-graph-crypto-perf <config_file> -v
599 Latency performance tests have a large amount of output.
600 It is not recommended to use the verbose option for latency tests.