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 33Compiling the Application 34------------------------- 35 36**Step 1: PMD setting** 37 38The ``dpdk-test-crypto-perf`` tool depends on crypto device drivers PMD which 39are disabled by default in the build configuration file ``common_base``. 40The crypto device drivers PMD which should be tested can be enabled by setting:: 41 42 CONFIG_RTE_LIBRTE_PMD_<name>=y 43 44Setting example for open ssl PMD:: 45 46 CONFIG_RTE_LIBRTE_PMD_OPENSSL=y 47 48**Step 2: Linearization setting** 49 50It is possible linearized input segmented packets just before crypto operation 51for devices which doesn't support scatter-gather, and allows to measure 52performance also for this use case. 53 54To set on the linearization options add below definition to the 55``cperf_ops.h`` file:: 56 57 #define CPERF_LINEARIZATION_ENABLE 58 59**Step 3: Build the application** 60 61Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the 62``dpdk-test-crypto-perf`` application. 63 64Initially, the user must select a DPDK target to choose the correct target type 65and compiler options to use when building the libraries. 66The user must have all libraries, modules, updates and compilers installed 67in the system prior to this, 68as described in the earlier chapters in this Getting Started Guide. 69 70Running the Application 71----------------------- 72 73The tool application has a number of command line options: 74 75.. code-block:: console 76 77 dpdk-test-crypto-perf [EAL Options] -- [Application Options] 78 79EAL Options 80~~~~~~~~~~~ 81 82The following are the EAL command-line options that can be used in conjunction 83with the ``dpdk-test-crypto-perf`` application. 84See the DPDK Getting Started Guides for more information on these options. 85 86* ``-c <COREMASK>`` or ``-l <CORELIST>`` 87 88 Set the hexadecimal bitmask of the cores to run on. The corelist is a 89 list cores to use. 90 91* ``-w <PCI>`` 92 93 Add a PCI device in white list. 94 95* ``--vdev <driver><id>`` 96 97 Add a virtual device. 98 99Application Options 100~~~~~~~~~~~~~~~~~~~ 101 102The following are the application command-line options: 103 104* ``--ptest type`` 105 106 Set test type, where ``type`` is one of the following:: 107 108 throughput 109 latency 110 verify 111 pmd-cyclecount 112 113* ``--silent`` 114 115 Disable options dump. 116 117* ``--pool-sz <n>`` 118 119 Set the number of mbufs to be allocated in the mbuf pool. 120 121* ``--total-ops <n>`` 122 123 Set the number of total operations performed. 124 125* ``--burst-sz <n>`` 126 127 Set the number of packets per burst. 128 129 This can be set as: 130 * Single value (i.e. ``--burst-sz 16``) 131 * Range of values, using the following structure ``min:inc:max``, 132 where ``min`` is minimum size, ``inc`` is the increment size and ``max`` 133 is the maximum size (i.e. ``--burst-sz 16:2:32``) 134 * List of values, up to 32 values, separated in commas (i.e. ``--burst-sz 16,24,32``) 135 136* ``--buffer-sz <n>`` 137 138 Set the size of single packet (plaintext or ciphertext in it). 139 140 This can be set as: 141 * Single value (i.e. ``--buffer-sz 16``) 142 * Range of values, using the following structure ``min:inc:max``, 143 where ``min`` is minimum size, ``inc`` is the increment size and ``max`` 144 is the maximum size (i.e. ``--buffer-sz 16:2:32``) 145 * List of values, up to 32 values, separated in commas (i.e. ``--buffer-sz 32,64,128``) 146 147* ``--imix <n>`` 148 149 Set the distribution of packet sizes. 150 151 A list of weights must be passed, containing the same number of items than buffer-sz, 152 so each item in this list will be the weight of the packet size on the same position 153 in the buffer-sz parameter (a list have to be passed in that parameter). 154 155 Example: 156 157 To test a distribution of 20% packets of 64 bytes, 40% packets of 100 bytes and 40% packets 158 of 256 bytes, the command line would be: ``--buffer-sz 64,100,256 --imix 20,40,40``. 159 Note that the weights do not have to be percentages, so using ``--imix 1,2,2`` would result 160 in the same distribution 161 162* ``--segment-sz <n>`` 163 164 Set the size of the segment to use, for Scatter Gather List testing. 165 By default, it is set to the size of the maximum buffer size, including the digest size, 166 so a single segment is created. 167 168* ``--devtype <name>`` 169 170 Set device type, where ``name`` is one of the following:: 171 172 crypto_null 173 crypto_aesni_mb 174 crypto_aesni_gcm 175 crypto_openssl 176 crypto_qat 177 crypto_snow3g 178 crypto_kasumi 179 crypto_zuc 180 crypto_dpaa_sec 181 crypto_dpaa2_sec 182 crypto_armv8 183 crypto_scheduler 184 crypto_mvsam 185 186* ``--optype <name>`` 187 188 Set operation type, where ``name`` is one of the following:: 189 190 cipher-only 191 auth-only 192 cipher-then-auth 193 auth-then-cipher 194 aead 195 pdcp 196 197 For GCM/CCM algorithms you should use aead flag. 198 199* ``--sessionless`` 200 201 Enable session-less crypto operations mode. 202 203* ``--out-of-place`` 204 205 Enable out-of-place crypto operations mode. 206 207* ``--test-file <name>`` 208 209 Set test vector file path. See the Test Vector File chapter. 210 211* ``--test-name <name>`` 212 213 Set specific test name section in the test vector file. 214 215* ``--cipher-algo <name>`` 216 217 Set cipher algorithm name, where ``name`` is one of the following:: 218 219 3des-cbc 220 3des-ecb 221 3des-ctr 222 aes-cbc 223 aes-ctr 224 aes-ecb 225 aes-f8 226 aes-xts 227 arc4 228 null 229 kasumi-f8 230 snow3g-uea2 231 zuc-eea3 232 233* ``--cipher-op <mode>`` 234 235 Set cipher operation mode, where ``mode`` is one of the following:: 236 237 encrypt 238 decrypt 239 240* ``--cipher-key-sz <n>`` 241 242 Set the size of cipher key. 243 244* ``--cipher-iv-sz <n>`` 245 246 Set the size of cipher iv. 247 248* ``--auth-algo <name>`` 249 250 Set authentication algorithm name, where ``name`` is one 251 of the following:: 252 253 3des-cbc 254 aes-cbc-mac 255 aes-cmac 256 aes-gmac 257 aes-xcbc-mac 258 md5 259 md5-hmac 260 sha1 261 sha1-hmac 262 sha2-224 263 sha2-224-hmac 264 sha2-256 265 sha2-256-hmac 266 sha2-384 267 sha2-384-hmac 268 sha2-512 269 sha2-512-hmac 270 kasumi-f9 271 snow3g-uia2 272 zuc-eia3 273 274* ``--auth-op <mode>`` 275 276 Set authentication operation mode, where ``mode`` is one of 277 the following:: 278 279 verify 280 generate 281 282* ``--auth-key-sz <n>`` 283 284 Set the size of authentication key. 285 286* ``--auth-iv-sz <n>`` 287 288 Set the size of auth iv. 289 290* ``--aead-algo <name>`` 291 292 Set AEAD algorithm name, where ``name`` is one 293 of the following:: 294 295 aes-ccm 296 aes-gcm 297 298* ``--aead-op <mode>`` 299 300 Set AEAD operation mode, where ``mode`` is one of 301 the following:: 302 303 encrypt 304 decrypt 305 306* ``--aead-key-sz <n>`` 307 308 Set the size of AEAD key. 309 310* ``--aead-iv-sz <n>`` 311 312 Set the size of AEAD iv. 313 314* ``--aead-aad-sz <n>`` 315 316 Set the size of AEAD aad. 317 318* ``--digest-sz <n>`` 319 320 Set the size of digest. 321 322* ``--desc-nb <n>`` 323 324 Set number of descriptors for each crypto device. 325 326* ``--pmd-cyclecount-delay-ms <n>`` 327 328 Add a delay (in milliseconds) between enqueue and dequeue in 329 pmd-cyclecount benchmarking mode (useful when benchmarking 330 hardware acceleration). 331 332* ``--csv-friendly`` 333 334 Enable test result output CSV friendly rather than human friendly. 335 336* ``--pdcp-sn-sz <n>`` 337 338 Set PDCP sequence number size(n) in bits. Valid values of n will 339 be 5/7/12/15/18. 340 341* ``--pdcp-domain <control/user>`` 342 343 Set PDCP domain to specify Control/user plane. 344 345Test Vector File 346~~~~~~~~~~~~~~~~ 347 348The test vector file is a text file contain information about test vectors. 349The file is made of the sections. The first section doesn't have header. 350It contain global information used in each test variant vectors - 351typically information about plaintext, ciphertext, cipher key, auth key, 352initial vector. All other sections begin header. 353The sections contain particular information typically digest. 354 355**Format of the file:** 356 357Each line beginning with sign '#' contain comment and it is ignored by parser:: 358 359 # <comment> 360 361Header line is just name in square bracket:: 362 363 [<section name>] 364 365Data line contain information token then sign '=' and 366a string of bytes in C byte array format:: 367 368 <token> = <C byte array> 369 370**Tokens list:** 371 372* ``plaintext`` 373 374 Original plaintext to be encrypted. 375 376* ``ciphertext`` 377 378 Encrypted plaintext string. 379 380* ``cipher_key`` 381 382 Key used in cipher operation. 383 384* ``auth_key`` 385 386 Key used in auth operation. 387 388* ``cipher_iv`` 389 390 Cipher Initial Vector. 391 392* ``auth_iv`` 393 394 Auth Initial Vector. 395 396* ``aad`` 397 398 Additional data. 399 400* ``digest`` 401 402 Digest string. 403 404Examples 405-------- 406 407Call application for performance throughput test of single Aesni MB PMD 408for cipher encryption aes-cbc and auth generation sha1-hmac, 409one million operations, burst size 32, packet size 64:: 410 411 dpdk-test-crypto-perf -l 6-7 --vdev crypto_aesni_mb -w 0000:00:00.0 -- 412 --ptest throughput --devtype crypto_aesni_mb --optype cipher-then-auth 413 --cipher-algo aes-cbc --cipher-op encrypt --cipher-key-sz 16 --auth-algo 414 sha1-hmac --auth-op generate --auth-key-sz 64 --digest-sz 12 415 --total-ops 10000000 --burst-sz 32 --buffer-sz 64 416 417Call application for performance latency test of two Aesni MB PMD executed 418on two cores for cipher encryption aes-cbc, ten operations in silent mode:: 419 420 dpdk-test-crypto-perf -l 4-7 --vdev crypto_aesni_mb1 421 --vdev crypto_aesni_mb2 -w 0000:00:00.0 -- --devtype crypto_aesni_mb 422 --cipher-algo aes-cbc --cipher-key-sz 16 --cipher-iv-sz 16 423 --cipher-op encrypt --optype cipher-only --silent 424 --ptest latency --total-ops 10 425 426Call application for verification test of single open ssl PMD 427for cipher encryption aes-gcm and auth generation aes-gcm,ten operations 428in silent mode, test vector provide in file "test_aes_gcm.data" 429with packet verification:: 430 431 dpdk-test-crypto-perf -l 4-7 --vdev crypto_openssl -w 0000:00:00.0 -- 432 --devtype crypto_openssl --aead-algo aes-gcm --aead-key-sz 16 433 --aead-iv-sz 16 --aead-op encrypt --aead-aad-sz 16 --digest-sz 16 434 --optype aead --silent --ptest verify --total-ops 10 435 --test-file test_aes_gcm.data 436 437Test vector file for cipher algorithm aes cbc 256 with authorization sha:: 438 439 # Global Section 440 plaintext = 441 0xff, 0xca, 0xfb, 0xf1, 0x38, 0x20, 0x2f, 0x7b, 0x24, 0x98, 0x26, 0x7d, 0x1d, 0x9f, 0xb3, 0x93, 442 0xd9, 0xef, 0xbd, 0xad, 0x4e, 0x40, 0xbd, 0x60, 0xe9, 0x48, 0x59, 0x90, 0x67, 0xd7, 0x2b, 0x7b, 443 0x8a, 0xe0, 0x4d, 0xb0, 0x70, 0x38, 0xcc, 0x48, 0x61, 0x7d, 0xee, 0xd6, 0x35, 0x49, 0xae, 0xb4, 444 0xaf, 0x6b, 0xdd, 0xe6, 0x21, 0xc0, 0x60, 0xce, 0x0a, 0xf4, 0x1c, 0x2e, 0x1c, 0x8d, 0xe8, 0x7b 445 ciphertext = 446 0x77, 0xF9, 0xF7, 0x7A, 0xA3, 0xCB, 0x68, 0x1A, 0x11, 0x70, 0xD8, 0x7A, 0xB6, 0xE2, 0x37, 0x7E, 447 0xD1, 0x57, 0x1C, 0x8E, 0x85, 0xD8, 0x08, 0xBF, 0x57, 0x1F, 0x21, 0x6C, 0xAD, 0xAD, 0x47, 0x1E, 448 0x0D, 0x6B, 0x79, 0x39, 0x15, 0x4E, 0x5B, 0x59, 0x2D, 0x76, 0x87, 0xA6, 0xD6, 0x47, 0x8F, 0x82, 449 0xB8, 0x51, 0x91, 0x32, 0x60, 0xCB, 0x97, 0xDE, 0xBE, 0xF0, 0xAD, 0xFC, 0x23, 0x2E, 0x22, 0x02 450 cipher_key = 451 0xE4, 0x23, 0x33, 0x8A, 0x35, 0x64, 0x61, 0xE2, 0x49, 0x03, 0xDD, 0xC6, 0xB8, 0xCA, 0x55, 0x7A, 452 0xd0, 0xe7, 0x4b, 0xfb, 0x5d, 0xe5, 0x0c, 0xe7, 0x6f, 0x21, 0xb5, 0x52, 0x2a, 0xbb, 0xc7, 0xf7 453 auth_key = 454 0xaf, 0x96, 0x42, 0xf1, 0x8c, 0x50, 0xdc, 0x67, 0x1a, 0x43, 0x47, 0x62, 0xc7, 0x04, 0xab, 0x05, 455 0xf5, 0x0c, 0xe7, 0xa2, 0xa6, 0x23, 0xd5, 0x3d, 0x95, 0xd8, 0xcd, 0x86, 0x79, 0xf5, 0x01, 0x47, 456 0x4f, 0xf9, 0x1d, 0x9d, 0x36, 0xf7, 0x68, 0x1a, 0x64, 0x44, 0x58, 0x5d, 0xe5, 0x81, 0x15, 0x2a, 457 0x41, 0xe4, 0x0e, 0xaa, 0x1f, 0x04, 0x21, 0xff, 0x2c, 0xf3, 0x73, 0x2b, 0x48, 0x1e, 0xd2, 0xf7 458 cipher_iv = 459 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F 460 # Section sha 1 hmac buff 32 461 [sha1_hmac_buff_32] 462 digest = 463 0x36, 0xCA, 0x49, 0x6A, 0xE3, 0x54, 0xD8, 0x4F, 0x0B, 0x76, 0xD8, 0xAA, 0x78, 0xEB, 0x9D, 0x65, 464 0x2C, 0xCA, 0x1F, 0x97 465 # Section sha 256 hmac buff 32 466 [sha256_hmac_buff_32] 467 digest = 468 0x1C, 0xB2, 0x3D, 0xD1, 0xF9, 0xC7, 0x6C, 0x49, 0x2E, 0xDA, 0x94, 0x8B, 0xF1, 0xCF, 0x96, 0x43, 469 0x67, 0x50, 0x39, 0x76, 0xB5, 0xA1, 0xCE, 0xA1, 0xD7, 0x77, 0x10, 0x07, 0x43, 0x37, 0x05, 0xB4 470