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