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