be3109054dbe56bac3a66bd5b9600fd7d10f8cf2
[dpdk.git] / doc / guides / tools / cryptoperf.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2016 Intel Corporation.
3
4 dpdk-test-crypto-perf Application
5 =================================
6
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
15 structure.
16
17 Limitations
18 -----------
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.
28
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.
32
33
34 Linearization setting
35 ---------------------
36
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.
40
41 To set on the linearization options add below definition to the
42 ``cperf_ops.h`` file::
43
44    #define CPERF_LINEARIZATION_ENABLE
45
46
47 Running the Application
48 -----------------------
49
50 The tool application has a number of command line options:
51
52 .. code-block:: console
53
54    dpdk-test-crypto-perf [EAL Options] -- [Application Options]
55
56 EAL Options
57 ~~~~~~~~~~~
58
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.
62
63 *   ``-c <COREMASK>`` or ``-l <CORELIST>``
64
65         Set the hexadecimal bitmask of the cores to run on. The corelist is a
66         list cores to use.
67
68 *   ``-a <PCI>``
69
70         Add a PCI device in allow list.
71
72 *   ``--vdev <driver><id>``
73
74         Add a virtual device.
75
76 Application Options
77 ~~~~~~~~~~~~~~~~~~~
78
79 The following are the application command-line options:
80
81 * ``--ptest type``
82
83         Set test type, where ``type`` is one of the following::
84
85            throughput
86            latency
87            verify
88            pmd-cyclecount
89
90 * ``--silent``
91
92         Disable options dump.
93
94 * ``--pool-sz <n>``
95
96         Set the number of mbufs to be allocated in the mbuf pool.
97
98 * ``--total-ops <n>``
99
100         Set the number of total operations performed.
101
102 * ``--burst-sz <n>``
103
104         Set the number of packets per burst.
105
106         This can be set as:
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``)
112
113 * ``--buffer-sz <n>``
114
115         Set the size of single packet (plaintext or ciphertext in it).
116
117         This can be set as:
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``)
123
124 * ``--imix <n>``
125
126         Set the distribution of packet sizes.
127
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).
131
132         Example:
133
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
138
139 * ``--segment-sz <n>``
140
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.
144
145 * ``--devtype <name>``
146
147         Set device type, where ``name`` is one of the following::
148
149            crypto_null
150            crypto_aesni_mb
151            crypto_aesni_gcm
152            crypto_openssl
153            crypto_qat
154            crypto_snow3g
155            crypto_kasumi
156            crypto_zuc
157            crypto_dpaa_sec
158            crypto_dpaa2_sec
159            crypto_armv8
160            crypto_scheduler
161            crypto_mvsam
162
163 * ``--optype <name>``
164
165         Set operation type, where ``name`` is one of the following::
166
167            cipher-only
168            auth-only
169            cipher-then-auth
170            auth-then-cipher
171            aead
172            pdcp
173            docsis
174
175         For GCM/CCM algorithms you should use aead flag.
176
177 * ``--sessionless``
178
179         Enable session-less crypto operations mode.
180
181 * ``--out-of-place``
182
183         Enable out-of-place crypto operations mode.
184
185 * ``--test-file <name>``
186
187         Set test vector file path. See the Test Vector File chapter.
188
189 * ``--test-name <name>``
190
191         Set specific test name section in the test vector file.
192
193 * ``--cipher-algo <name>``
194
195         Set cipher algorithm name, where ``name`` is one of the following::
196
197            3des-cbc
198            3des-ecb
199            3des-ctr
200            aes-cbc
201            aes-ctr
202            aes-ecb
203            aes-f8
204            aes-xts
205            arc4
206            null
207            kasumi-f8
208            snow3g-uea2
209            zuc-eea3
210
211 * ``--cipher-op <mode>``
212
213         Set cipher operation mode, where ``mode`` is one of the following::
214
215            encrypt
216            decrypt
217
218 * ``--cipher-key-sz <n>``
219
220         Set the size of cipher key.
221
222 * ``--cipher-iv-sz <n>``
223
224         Set the size of cipher iv.
225
226 * ``--auth-algo <name>``
227
228         Set authentication algorithm name, where ``name`` is one
229         of the following::
230
231            3des-cbc
232            aes-cbc-mac
233            aes-cmac
234            aes-gmac
235            aes-xcbc-mac
236            md5
237            md5-hmac
238            sha1
239            sha1-hmac
240            sha2-224
241            sha2-224-hmac
242            sha2-256
243            sha2-256-hmac
244            sha2-384
245            sha2-384-hmac
246            sha2-512
247            sha2-512-hmac
248            kasumi-f9
249            snow3g-uia2
250            zuc-eia3
251
252 * ``--auth-op <mode>``
253
254         Set authentication operation mode, where ``mode`` is one of
255         the following::
256
257            verify
258            generate
259
260 * ``--auth-key-sz <n>``
261
262         Set the size of authentication key.
263
264 * ``--auth-iv-sz <n>``
265
266         Set the size of auth iv.
267
268 * ``--aead-algo <name>``
269
270         Set AEAD algorithm name, where ``name`` is one
271         of the following::
272
273            aes-ccm
274            aes-gcm
275
276 * ``--aead-op <mode>``
277
278         Set AEAD operation mode, where ``mode`` is one of
279         the following::
280
281            encrypt
282            decrypt
283
284 * ``--aead-key-sz <n>``
285
286         Set the size of AEAD key.
287
288 * ``--aead-iv-sz <n>``
289
290         Set the size of AEAD iv.
291
292 * ``--aead-aad-sz <n>``
293
294         Set the size of AEAD aad.
295
296 * ``--digest-sz <n>``
297
298         Set the size of digest.
299
300 * ``--desc-nb <n>``
301
302         Set number of descriptors for each crypto device.
303
304 * ``--pmd-cyclecount-delay-ms <n>``
305
306         Add a delay (in milliseconds) between enqueue and dequeue in
307         pmd-cyclecount benchmarking mode (useful when benchmarking
308         hardware acceleration).
309
310 * ``--csv-friendly``
311
312         Enable test result output CSV friendly rather than human friendly.
313
314 * ``--pdcp-sn-sz <n>``
315
316         Set PDCP sequence number size(n) in bits. Valid values of n will
317         be 5/7/12/15/18.
318
319 * ``--pdcp-domain <control/user>``
320
321         Set PDCP domain to specify Control/user plane.
322
323 * ``--docsis-hdr-sz <n>``
324
325         Set DOCSIS header size(n) in bytes.
326
327 * ``--pdcp-ses-hfn-en``
328
329         Enable fixed session based HFN instead of per packet HFN.
330
331 Test Vector File
332 ~~~~~~~~~~~~~~~~
333
334 The test vector file is a text file contain information about test vectors.
335 The file is made of the sections. The first section doesn't have header.
336 It contain global information used in each test variant vectors -
337 typically information about plaintext, ciphertext, cipher key, auth key,
338 initial vector. All other sections begin header.
339 The sections contain particular information typically digest.
340
341 **Format of the file:**
342
343 Each line beginning with sign '#' contain comment and it is ignored by parser::
344
345    # <comment>
346
347 Header line is just name in square bracket::
348
349    [<section name>]
350
351 Data line contain information token then sign '=' and
352 a string of bytes in C byte array format::
353
354    <token> = <C byte array>
355
356 **Tokens list:**
357
358 * ``plaintext``
359
360         Original plaintext to be encrypted.
361
362 * ``ciphertext``
363
364         Encrypted plaintext string.
365
366 * ``cipher_key``
367
368         Key used in cipher operation.
369
370 * ``auth_key``
371
372         Key used in auth operation.
373
374 * ``cipher_iv``
375
376         Cipher Initial Vector.
377
378 * ``auth_iv``
379
380         Auth Initial Vector.
381
382 * ``aad``
383
384         Additional data.
385
386 * ``digest``
387
388         Digest string.
389
390 Examples
391 --------
392
393 Call application for performance throughput test of single Aesni MB PMD
394 for cipher encryption aes-cbc and auth generation sha1-hmac,
395 one million operations, burst size 32, packet size 64::
396
397    dpdk-test-crypto-perf -l 6-7 --vdev crypto_aesni_mb -a 0000:00:00.0 --
398    --ptest throughput --devtype crypto_aesni_mb --optype cipher-then-auth
399    --cipher-algo aes-cbc --cipher-op encrypt --cipher-key-sz 16 --auth-algo
400    sha1-hmac --auth-op generate --auth-key-sz 64 --digest-sz 12
401    --total-ops 10000000 --burst-sz 32 --buffer-sz 64
402
403 Call application for performance latency test of two Aesni MB PMD executed
404 on two cores for cipher encryption aes-cbc, ten operations in silent mode::
405
406    dpdk-test-crypto-perf -l 4-7 --vdev crypto_aesni_mb1
407    --vdev crypto_aesni_mb2 -a 0000:00:00.0 -- --devtype crypto_aesni_mb
408    --cipher-algo aes-cbc --cipher-key-sz 16 --cipher-iv-sz 16
409    --cipher-op encrypt --optype cipher-only --silent
410    --ptest latency --total-ops 10
411
412 Call application for verification test of single open ssl PMD
413 for cipher encryption aes-gcm and auth generation aes-gcm,ten operations
414 in silent mode, test vector provide in file "test_aes_gcm.data"
415 with packet verification::
416
417    dpdk-test-crypto-perf -l 4-7 --vdev crypto_openssl -a 0000:00:00.0 --
418    --devtype crypto_openssl --aead-algo aes-gcm --aead-key-sz 16
419    --aead-iv-sz 16 --aead-op encrypt --aead-aad-sz 16 --digest-sz 16
420    --optype aead --silent --ptest verify --total-ops 10
421    --test-file test_aes_gcm.data
422
423 Test vector file for cipher algorithm aes cbc 256 with authorization sha::
424
425    # Global Section
426    plaintext =
427    0xff, 0xca, 0xfb, 0xf1, 0x38, 0x20, 0x2f, 0x7b, 0x24, 0x98, 0x26, 0x7d, 0x1d, 0x9f, 0xb3, 0x93,
428    0xd9, 0xef, 0xbd, 0xad, 0x4e, 0x40, 0xbd, 0x60, 0xe9, 0x48, 0x59, 0x90, 0x67, 0xd7, 0x2b, 0x7b,
429    0x8a, 0xe0, 0x4d, 0xb0, 0x70, 0x38, 0xcc, 0x48, 0x61, 0x7d, 0xee, 0xd6, 0x35, 0x49, 0xae, 0xb4,
430    0xaf, 0x6b, 0xdd, 0xe6, 0x21, 0xc0, 0x60, 0xce, 0x0a, 0xf4, 0x1c, 0x2e, 0x1c, 0x8d, 0xe8, 0x7b
431    ciphertext =
432    0x77, 0xF9, 0xF7, 0x7A, 0xA3, 0xCB, 0x68, 0x1A, 0x11, 0x70, 0xD8, 0x7A, 0xB6, 0xE2, 0x37, 0x7E,
433    0xD1, 0x57, 0x1C, 0x8E, 0x85, 0xD8, 0x08, 0xBF, 0x57, 0x1F, 0x21, 0x6C, 0xAD, 0xAD, 0x47, 0x1E,
434    0x0D, 0x6B, 0x79, 0x39, 0x15, 0x4E, 0x5B, 0x59, 0x2D, 0x76, 0x87, 0xA6, 0xD6, 0x47, 0x8F, 0x82,
435    0xB8, 0x51, 0x91, 0x32, 0x60, 0xCB, 0x97, 0xDE, 0xBE, 0xF0, 0xAD, 0xFC, 0x23, 0x2E, 0x22, 0x02
436    cipher_key =
437    0xE4, 0x23, 0x33, 0x8A, 0x35, 0x64, 0x61, 0xE2, 0x49, 0x03, 0xDD, 0xC6, 0xB8, 0xCA, 0x55, 0x7A,
438    0xd0, 0xe7, 0x4b, 0xfb, 0x5d, 0xe5, 0x0c, 0xe7, 0x6f, 0x21, 0xb5, 0x52, 0x2a, 0xbb, 0xc7, 0xf7
439    auth_key =
440    0xaf, 0x96, 0x42, 0xf1, 0x8c, 0x50, 0xdc, 0x67, 0x1a, 0x43, 0x47, 0x62, 0xc7, 0x04, 0xab, 0x05,
441    0xf5, 0x0c, 0xe7, 0xa2, 0xa6, 0x23, 0xd5, 0x3d, 0x95, 0xd8, 0xcd, 0x86, 0x79, 0xf5, 0x01, 0x47,
442    0x4f, 0xf9, 0x1d, 0x9d, 0x36, 0xf7, 0x68, 0x1a, 0x64, 0x44, 0x58, 0x5d, 0xe5, 0x81, 0x15, 0x2a,
443    0x41, 0xe4, 0x0e, 0xaa, 0x1f, 0x04, 0x21, 0xff, 0x2c, 0xf3, 0x73, 0x2b, 0x48, 0x1e, 0xd2, 0xf7
444    cipher_iv =
445    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F
446    # Section sha 1 hmac buff 32
447    [sha1_hmac_buff_32]
448    digest =
449    0x36, 0xCA, 0x49, 0x6A, 0xE3, 0x54, 0xD8, 0x4F, 0x0B, 0x76, 0xD8, 0xAA, 0x78, 0xEB, 0x9D, 0x65,
450    0x2C, 0xCA, 0x1F, 0x97
451    # Section sha 256 hmac buff 32
452    [sha256_hmac_buff_32]
453    digest =
454    0x1C, 0xB2, 0x3D, 0xD1, 0xF9, 0xC7, 0x6C, 0x49, 0x2E, 0xDA, 0x94, 0x8B, 0xF1, 0xCF, 0x96, 0x43,
455    0x67, 0x50, 0x39, 0x76, 0xB5, 0xA1, 0xCE, 0xA1, 0xD7, 0x77, 0x10, 0x07, 0x43, 0x37, 0x05, 0xB4
456
457
458 Graph Crypto Perf Results
459 -------------------------
460
461 The ``dpdk-graph-crypto-perf.py`` tool is a simple script to automate
462 running crypto performance tests, and graphing the results.
463 It can be found in the ``app/test-crypto-perf/`` directory.
464 The output graphs include various grouped barcharts for throughput
465 tests, and histogram and boxplot graphs for latency tests.
466 These are output to PDF files, with one PDF per test suite graph type.
467
468
469 Dependencies
470 ~~~~~~~~~~~~
471
472 The following python modules must be installed to run the script:
473
474 .. code-block:: console
475
476    pip3 install img2pdf plotly pandas psutil kaleido
477
478
479 Test Configuration
480 ~~~~~~~~~~~~~~~~~~
481
482 The test cases run by the script are defined by a JSON config file.
483 Some config files can be found in ``app/test-crypto-perf/configs/``,
484 or the user may create a new one following the same format as the config files provided.
485
486 An example of this format is shown below for one test suite in the ``crypto-perf-aesni-mb.json`` file.
487 This shows the required default config for the test suite, and one test case.
488 The test case has additional app config that will be combined with
489 the default config when running the test case.
490
491 .. code-block:: c
492
493    "throughput": {
494        "default": {
495            "eal": {
496                "l": "1,2",
497                "vdev": "crypto_aesni_mb"
498            },
499            "app": {
500                "csv-friendly": true,
501                "buffer-sz": "64,128,256,512,768,1024,1408,2048",
502                "burst-sz": "1,4,8,16,32",
503                "ptest": "throughput",
504                "devtype": "crypto_aesni_mb"
505            }
506         },
507        "AES-CBC-128 SHA1-HMAC auth-then-cipher decrypt": {
508                "cipher-algo": "aes-cbc",
509                "cipher-key-sz": "16",
510                "auth-algo": "sha1-hmac",
511                "optype": "auth-then-cipher",
512                "cipher-op": "decrypt"
513         }
514    }
515
516 .. note::
517    The specific test cases only allow modification of app parameters,
518    and not EAL parameters.
519    The default case is required for each test suite in the config file,
520    to specify EAL parameters.
521
522 Currently, crypto_qat, crypto_aesni_mb, and crypto_aesni_gcm devices for
523 both throughput and latency ptests are supported.
524
525
526 Usage
527 ~~~~~
528
529 .. code-block:: console
530
531    ./dpdk-graph-crypto-perf <config_file>
532
533 The ``config_file`` positional argument is required to run the script.
534 This points to a valid JSON config file containing test suites.
535
536 .. code-block:: console
537
538    ./dpdk-graph-crypto-perf configs/crypto-perf-aesni-mb.json
539
540 The following are the application optional command-line options:
541
542 * ``-h, --help``
543
544   Display usage information and quit.
545
546 * ``-f <file_path>, --file-path <file_path>``
547
548   Provide path to ``dpdk-test-crypto-perf`` application.
549   The script uses the installed app by default.
550
551   .. code-block:: console
552
553      ./dpdk-graph-crypto-perf <config_file> \
554          -f <build_dir>/app/dpdk-test-crypto-perf
555
556 * ``-t <test_suite_list>, --test-suites <test_suite_list>``
557
558   Specify test suites to run. All test suites are run by default.
559
560   To run crypto-perf-qat latency test suite only:
561
562   .. code-block:: console
563
564      ./dpdk-graph-crypto-perf configs/crypto-perf-qat -t latency
565
566   To run both crypto-perf-aesni-mb throughput and latency test suites
567
568   .. code-block:: console
569
570      ./dpdk-graph-crypto-perf configs/crypto-perf-aesni-mb -t throughput latency
571
572 * ``-o <output_path>, --output-path <output_path>``
573
574   Specify directory to use for output files.
575   The default is to use the script's directory.
576
577   .. code-block:: console
578
579      ./dpdk-graph-crypto-perf <config_file> -o <output_dir>
580
581 * ``-v, --verbose``
582
583   Enable verbose output. This displays ``dpdk-test-crypto-perf`` app output in real-time.
584
585   .. code-block:: console
586
587      ./dpdk-graph-crypto-perf <config_file> -v
588
589   .. warning::
590      Latency performance tests have a large amount of output.
591      It is not recommended to use the verbose option for latency tests.