1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2016 Intel Corporation. 3 4dpdk-test-crypto-perf Application 5================================= 6 7The ``dpdk-test-crypto-perf`` tool is a Data Plane Development Kit (DPDK) 8utility that allows measuring performance parameters of PMDs available in the 9crypto tree. There are available two measurement types: throughput and latency. 10User can use multiple cores to run tests on but only 11one type of crypto PMD can be measured during single application 12execution. Cipher parameters, type of device, type of operation and 13chain mode have to be specified in the command line as application 14parameters. These parameters are checked using device capabilities 15structure. 16 17Limitations 18----------- 19On hardware devices the cycle-count doesn't always represent the actual offload 20cost. The cycle-count only represents the offload cost when the hardware 21accelerator is not fully loaded, when loaded the cpu cycles freed up by the 22offload are still consumed by the test tool and included in the cycle-count. 23These cycles are consumed by retries and inefficient API calls enqueuing and 24dequeuing smaller bursts than specified by the cmdline parameter. This results 25in a larger cycle-count measurement and should not be interpreted as an offload 26cost measurement. Using "pmd-cyclecount" mode will give a better idea of 27actual costs of hardware acceleration. 28 29On hardware devices the throughput measurement is not necessarily the maximum 30possible for the device, e.g. it may be necessary to use multiple cores to keep 31the hardware accelerator fully loaded and so measure maximum throughput. 32 33 34Linearization setting 35--------------------- 36 37It is possible linearized input segmented packets just before crypto operation 38for devices which doesn't support scatter-gather, and allows to measure 39performance also for this use case. 40 41To set on the linearization options add below definition to the 42``cperf_ops.h`` file:: 43 44 #define CPERF_LINEARIZATION_ENABLE 45 46 47Running the Application 48----------------------- 49 50The 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 56EAL Options 57~~~~~~~~~~~ 58 59The following are the EAL command-line options that can be used in conjunction 60with the ``dpdk-test-crypto-perf`` application. 61See 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 76Application Options 77~~~~~~~~~~~~~~~~~~~ 78 79The 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_aesni_gcm 150 crypto_aesni_mb 151 crypto_armv8 152 crypto_cn9k 153 crypto_cn10k 154 crypto_dpaa_sec 155 crypto_dpaa2_sec 156 crypto_kasumi 157 crypto_mvsam 158 crypto_null 159 crypto_octeontx 160 crypto_openssl 161 crypto_qat 162 crypto_scheduler 163 crypto_snow3g 164 crypto_zuc 165 166* ``--optype <name>`` 167 168 Set operation type, where ``name`` is one of the following:: 169 170 cipher-only 171 auth-only 172 cipher-then-auth 173 auth-then-cipher 174 aead 175 pdcp 176 docsis 177 modex 178 ecdsa_p256r1 179 eddsa_25519 180 sm2 181 ipsec 182 tls-record 183 184 For GCM/CCM algorithms you should use aead flag. 185 186* ``--sessionless`` 187 188 Enable session-less crypto operations mode. 189 190* ``--shared-session`` 191 192 Enable sharing sessions between all queue pairs on a single crypto PMD. 193 This can be useful for benchmarking this setup, 194 or finding and debugging concurrency errors 195 that can occur while using sessions on multiple lcores simultaneously. 196 197* ``--out-of-place`` 198 199 Enable out-of-place crypto operations mode. 200 201* ``--test-file <name>`` 202 203 Set test vector file path. See the Test Vector File chapter. 204 205* ``--test-name <name>`` 206 207 Set specific test name section in the test vector file. 208 209* ``--cipher-algo <name>`` 210 211 Set cipher algorithm name, where ``name`` is one of the following:: 212 213 3des-cbc 214 3des-ecb 215 3des-ctr 216 aes-cbc 217 aes-ctr 218 aes-ecb 219 aes-f8 220 aes-xts 221 arc4 222 null 223 kasumi-f8 224 snow3g-uea2 225 zuc-eea3 226 227* ``--cipher-op <mode>`` 228 229 Set cipher operation mode, where ``mode`` is one of the following:: 230 231 encrypt 232 decrypt 233 234* ``--cipher-key-sz <n>`` 235 236 Set the size of cipher key. 237 238* ``--cipher-iv-sz <n>`` 239 240 Set the size of cipher iv. 241 242* ``--auth-algo <name>`` 243 244 Set authentication algorithm name, where ``name`` is one 245 of the following:: 246 247 aes-cbc-mac 248 aes-cmac 249 aes-gmac 250 aes-xcbc-mac 251 md5 252 md5-hmac 253 sha1 254 sha1-hmac 255 sha2-224 256 sha2-224-hmac 257 sha2-256 258 sha2-256-hmac 259 sha2-384 260 sha2-384-hmac 261 sha2-512 262 sha2-512-hmac 263 kasumi-f9 264 snow3g-uia2 265 zuc-eia3 266 267* ``--auth-op <mode>`` 268 269 Set authentication operation mode, where ``mode`` is one of 270 the following:: 271 272 verify 273 generate 274 275* ``--auth-key-sz <n>`` 276 277 Set the size of authentication key. 278 279* ``--auth-iv-sz <n>`` 280 281 Set the size of auth iv. 282 283* ``--aead-algo <name>`` 284 285 Set AEAD algorithm name, where ``name`` is one 286 of the following:: 287 288 aes-ccm 289 aes-gcm 290 291* ``--aead-op <mode>`` 292 293 Set AEAD operation mode, where ``mode`` is one of 294 the following:: 295 296 encrypt 297 decrypt 298 299* ``--aead-key-sz <n>`` 300 301 Set the size of AEAD key. 302 303* ``--aead-iv-sz <n>`` 304 305 Set the size of AEAD iv. 306 307* ``--aead-aad-sz <n>`` 308 309 Set the size of AEAD aad. 310 311* ``--digest-sz <n>`` 312 313 Set the size of digest. 314 315* ``--desc-nb <n>`` 316 317 Set number of descriptors for each crypto device. 318 319* ``--pmd-cyclecount-delay-ms <n>`` 320 321 Add a delay (in milliseconds) between enqueue and dequeue in 322 pmd-cyclecount benchmarking mode (useful when benchmarking 323 hardware acceleration). 324 325* ``--csv-friendly`` 326 327 Enable test result output CSV friendly rather than human friendly. 328 329* ``--pdcp-sn-sz <n>`` 330 331 Set PDCP sequence number size(n) in bits. Valid values of n will 332 be 5/7/12/15/18. 333 334* ``--pdcp-domain <control/user>`` 335 336 Set PDCP domain to specify short_mac/control/user plane. 337 338* ``--docsis-hdr-sz <n>`` 339 340 Set DOCSIS header size(n) in bytes. 341 342* ``--pdcp-ses-hfn-en`` 343 344 Enable fixed session based HFN instead of per packet HFN. 345 346* ``--enable-sdap`` 347 348 Enable Service Data Adaptation Protocol. 349 350* ``--modex-len <n>`` 351 352 Set modex length for asymmetric crypto perf test. 353 Supported lengths are 60, 128, 255, 448. Default length is 128. 354 355* ``--asym-op <sign/verify/encrypt/decrypt>`` 356 357 Set Asymmetric crypto operation mode. 358 To be used with SM2 asymmetric crypto ops. 359 Default is ``sign``. 360 361* ``--tls-version <TLS1.2/TLS1.3/DTLS1.2>`` 362 363 Set TLS/DTLS protocol version for perf test (default is TLS1.2). 364 365* ``--low-prio-qp-mask <mask>`` 366 367 Set low priority for queue pairs set in the hexadecimal mask. 368 This is an optional parameter, if not set all queue pairs will be on same high priority. 369 370Test Vector File 371~~~~~~~~~~~~~~~~ 372 373The test vector file is a text file contain information about test vectors. 374The file is made of the sections. The first section doesn't have header. 375It contain global information used in each test variant vectors - 376typically information about plaintext, ciphertext, cipher key, auth key, 377initial vector. All other sections begin header. 378The sections contain particular information typically digest. 379 380**Format of the file:** 381 382Each line beginning with sign '#' contain comment and it is ignored by parser:: 383 384 # <comment> 385 386Header line is just name in square bracket:: 387 388 [<section name>] 389 390Data line contain information token then sign '=' and 391a string of bytes in C byte array format:: 392 393 <token> = <C byte array> 394 395**Tokens list:** 396 397* ``plaintext`` 398 399 Original plaintext to be encrypted. 400 401* ``ciphertext`` 402 403 Encrypted plaintext string. 404 405* ``cipher_key`` 406 407 Key used in cipher operation. 408 409* ``auth_key`` 410 411 Key used in auth operation. 412 413* ``cipher_iv`` 414 415 Cipher Initial Vector. 416 417* ``auth_iv`` 418 419 Auth Initial Vector. 420 421* ``aad`` 422 423 Additional data. 424 425* ``digest`` 426 427 Digest string. 428 429Examples 430-------- 431 432Call application for performance throughput test of single Aesni MB PMD 433for cipher encryption aes-cbc and auth generation sha1-hmac, 434one million operations, burst size 32, packet size 64:: 435 436 dpdk-test-crypto-perf -l 6-7 --vdev crypto_aesni_mb -a 0000:00:00.0 -- 437 --ptest throughput --devtype crypto_aesni_mb --optype cipher-then-auth 438 --cipher-algo aes-cbc --cipher-op encrypt --cipher-key-sz 16 --auth-algo 439 sha1-hmac --auth-op generate --auth-key-sz 64 --digest-sz 12 440 --total-ops 10000000 --burst-sz 32 --buffer-sz 64 441 442Call application for performance latency test of two Aesni MB PMD executed 443on two cores for cipher encryption aes-cbc, ten operations in silent mode:: 444 445 dpdk-test-crypto-perf -l 4-7 --vdev crypto_aesni_mb1 446 --vdev crypto_aesni_mb2 -a 0000:00:00.0 -- --devtype crypto_aesni_mb 447 --cipher-algo aes-cbc --cipher-key-sz 16 --cipher-iv-sz 16 448 --cipher-op encrypt --optype cipher-only --silent 449 --ptest latency --total-ops 10 450 451Call application for verification test of single open ssl PMD 452for cipher encryption aes-gcm and auth generation aes-gcm,ten operations 453in silent mode, test vector provide in file "test_aes_gcm.data" 454with packet verification:: 455 456 dpdk-test-crypto-perf -l 4-7 --vdev crypto_openssl -a 0000:00:00.0 -- 457 --devtype crypto_openssl --aead-algo aes-gcm --aead-key-sz 16 458 --aead-iv-sz 16 --aead-op encrypt --aead-aad-sz 16 --digest-sz 16 459 --optype aead --silent --ptest verify --total-ops 10 460 --test-file test_aes_gcm.data 461 462Test vector file for cipher algorithm aes cbc 256 with authorization sha:: 463 464 # Global Section 465 plaintext = 466 0xff, 0xca, 0xfb, 0xf1, 0x38, 0x20, 0x2f, 0x7b, 0x24, 0x98, 0x26, 0x7d, 0x1d, 0x9f, 0xb3, 0x93, 467 0xd9, 0xef, 0xbd, 0xad, 0x4e, 0x40, 0xbd, 0x60, 0xe9, 0x48, 0x59, 0x90, 0x67, 0xd7, 0x2b, 0x7b, 468 0x8a, 0xe0, 0x4d, 0xb0, 0x70, 0x38, 0xcc, 0x48, 0x61, 0x7d, 0xee, 0xd6, 0x35, 0x49, 0xae, 0xb4, 469 0xaf, 0x6b, 0xdd, 0xe6, 0x21, 0xc0, 0x60, 0xce, 0x0a, 0xf4, 0x1c, 0x2e, 0x1c, 0x8d, 0xe8, 0x7b 470 ciphertext = 471 0x77, 0xF9, 0xF7, 0x7A, 0xA3, 0xCB, 0x68, 0x1A, 0x11, 0x70, 0xD8, 0x7A, 0xB6, 0xE2, 0x37, 0x7E, 472 0xD1, 0x57, 0x1C, 0x8E, 0x85, 0xD8, 0x08, 0xBF, 0x57, 0x1F, 0x21, 0x6C, 0xAD, 0xAD, 0x47, 0x1E, 473 0x0D, 0x6B, 0x79, 0x39, 0x15, 0x4E, 0x5B, 0x59, 0x2D, 0x76, 0x87, 0xA6, 0xD6, 0x47, 0x8F, 0x82, 474 0xB8, 0x51, 0x91, 0x32, 0x60, 0xCB, 0x97, 0xDE, 0xBE, 0xF0, 0xAD, 0xFC, 0x23, 0x2E, 0x22, 0x02 475 cipher_key = 476 0xE4, 0x23, 0x33, 0x8A, 0x35, 0x64, 0x61, 0xE2, 0x49, 0x03, 0xDD, 0xC6, 0xB8, 0xCA, 0x55, 0x7A, 477 0xd0, 0xe7, 0x4b, 0xfb, 0x5d, 0xe5, 0x0c, 0xe7, 0x6f, 0x21, 0xb5, 0x52, 0x2a, 0xbb, 0xc7, 0xf7 478 auth_key = 479 0xaf, 0x96, 0x42, 0xf1, 0x8c, 0x50, 0xdc, 0x67, 0x1a, 0x43, 0x47, 0x62, 0xc7, 0x04, 0xab, 0x05, 480 0xf5, 0x0c, 0xe7, 0xa2, 0xa6, 0x23, 0xd5, 0x3d, 0x95, 0xd8, 0xcd, 0x86, 0x79, 0xf5, 0x01, 0x47, 481 0x4f, 0xf9, 0x1d, 0x9d, 0x36, 0xf7, 0x68, 0x1a, 0x64, 0x44, 0x58, 0x5d, 0xe5, 0x81, 0x15, 0x2a, 482 0x41, 0xe4, 0x0e, 0xaa, 0x1f, 0x04, 0x21, 0xff, 0x2c, 0xf3, 0x73, 0x2b, 0x48, 0x1e, 0xd2, 0xf7 483 cipher_iv = 484 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F 485 # Section sha 1 hmac buff 32 486 [sha1_hmac_buff_32] 487 digest = 488 0x36, 0xCA, 0x49, 0x6A, 0xE3, 0x54, 0xD8, 0x4F, 0x0B, 0x76, 0xD8, 0xAA, 0x78, 0xEB, 0x9D, 0x65, 489 0x2C, 0xCA, 0x1F, 0x97 490 # Section sha 256 hmac buff 32 491 [sha256_hmac_buff_32] 492 digest = 493 0x1C, 0xB2, 0x3D, 0xD1, 0xF9, 0xC7, 0x6C, 0x49, 0x2E, 0xDA, 0x94, 0x8B, 0xF1, 0xCF, 0x96, 0x43, 494 0x67, 0x50, 0x39, 0x76, 0xB5, 0xA1, 0xCE, 0xA1, 0xD7, 0x77, 0x10, 0x07, 0x43, 0x37, 0x05, 0xB4 495 496 497Graph Crypto Perf Results 498------------------------- 499 500The ``dpdk-graph-crypto-perf.py`` tool is a simple script to automate 501running crypto performance tests, and graphing the results. 502It can be found in the ``app/test-crypto-perf/`` directory. 503The output graphs include various grouped barcharts for throughput 504tests, and histogram and boxplot graphs for latency tests. 505These are output to PDF files, with one PDF per test suite graph type. 506 507 508Dependencies 509~~~~~~~~~~~~ 510 511The following python modules must be installed to run the script: 512 513.. code-block:: console 514 515 pip3 install img2pdf plotly pandas psutil kaleido 516 517 518Test Configuration 519~~~~~~~~~~~~~~~~~~ 520 521The test cases run by the script are defined by a JSON config file. 522Some config files can be found in ``app/test-crypto-perf/configs/``, 523or the user may create a new one following the same format as the config files provided. 524 525An example of this format is shown below for one test suite in the ``crypto-perf-aesni-mb.json`` file. 526This shows the required default config for the test suite, and one test case. 527The test case has additional app config that will be combined with 528the default config when running the test case. 529 530.. code-block:: c 531 532 "throughput": { 533 "default": { 534 "eal": { 535 "l": "1,2", 536 "vdev": "crypto_aesni_mb" 537 }, 538 "app": { 539 "csv-friendly": true, 540 "buffer-sz": "64,128,256,512,768,1024,1408,2048", 541 "burst-sz": "1,4,8,16,32", 542 "ptest": "throughput", 543 "devtype": "crypto_aesni_mb" 544 } 545 }, 546 "AES-CBC-128 SHA1-HMAC auth-then-cipher decrypt": { 547 "cipher-algo": "aes-cbc", 548 "cipher-key-sz": "16", 549 "auth-algo": "sha1-hmac", 550 "optype": "auth-then-cipher", 551 "cipher-op": "decrypt" 552 } 553 } 554 555.. note:: 556 The specific test cases only allow modification of app parameters, 557 and not EAL parameters. 558 The default case is required for each test suite in the config file, 559 to specify EAL parameters. 560 561Currently, crypto_qat, crypto_aesni_mb, and crypto_aesni_gcm devices for 562both throughput and latency ptests are supported. 563 564 565Usage 566~~~~~ 567 568.. code-block:: console 569 570 ./dpdk-graph-crypto-perf <config_file> 571 572The ``config_file`` positional argument is required to run the script. 573This points to a valid JSON config file containing test suites. 574 575.. code-block:: console 576 577 ./dpdk-graph-crypto-perf configs/crypto-perf-aesni-mb.json 578 579The following are the application optional command-line options: 580 581* ``-h, --help`` 582 583 Display usage information and quit. 584 585* ``-f <file_path>, --file-path <file_path>`` 586 587 Provide path to ``dpdk-test-crypto-perf`` application. 588 The script uses the installed app by default. 589 590 .. code-block:: console 591 592 ./dpdk-graph-crypto-perf <config_file> \ 593 -f <build_dir>/app/dpdk-test-crypto-perf 594 595* ``-t <test_suite_list>, --test-suites <test_suite_list>`` 596 597 Specify test suites to run. All test suites are run by default. 598 599 To run crypto-perf-qat latency test suite only: 600 601 .. code-block:: console 602 603 ./dpdk-graph-crypto-perf configs/crypto-perf-qat -t latency 604 605 To run both crypto-perf-aesni-mb throughput and latency test suites 606 607 .. code-block:: console 608 609 ./dpdk-graph-crypto-perf configs/crypto-perf-aesni-mb -t throughput latency 610 611* ``-o <output_path>, --output-path <output_path>`` 612 613 Specify directory to use for output files. 614 The default is to use the script's directory. 615 616 .. code-block:: console 617 618 ./dpdk-graph-crypto-perf <config_file> -o <output_dir> 619 620* ``-v, --verbose`` 621 622 Enable verbose output. This displays ``dpdk-test-crypto-perf`` app output in real-time. 623 624 .. code-block:: console 625 626 ./dpdk-graph-crypto-perf <config_file> -v 627 628 .. warning:: 629 Latency performance tests have a large amount of output. 630 It is not recommended to use the verbose option for latency tests. 631