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