1.. BSD LICENSE 2 Copyright(c) 2016 Intel Corporation. All rights reserved. 3 All rights reserved. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions 7 are met: 8 9 * Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 * Redistributions in binary form must reproduce the above copyright 12 notice, this list of conditions and the following disclaimer in 13 the documentation and/or other materials provided with the 14 distribution. 15 * Neither the name of Intel Corporation nor the names of its 16 contributors may be used to endorse or promote products derived 17 from this software without specific prior written permission. 18 19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31dpdk-test-crypto-perf Application 32================================= 33 34The ``dpdk-test-crypto-perf`` tool is a Data Plane Development Kit (DPDK) 35utility that allows measuring performance parameters of PMDs available in the 36crypto tree. There are available two measurement types: throughput and latency. 37User can use multiply cores to run tests on but only 38one type of crypto PMD can be measured during single application 39execution. Cipher parameters, type of device, type of operation and 40chain mode have to be specified in the command line as application 41parameters. These parameters are checked using device capabilities 42structure. 43 44Limitations 45----------- 46On hardware devices the cycle-count doesn't always represent the actual offload 47cost. The cycle-count only represents the offload cost when the hardware 48accelerator is not fully loaded, when loaded the cpu cycles freed up by the 49offload are still consumed by the test tool and included in the cycle-count. 50These cycles are consumed by retries and inefficient API calls enqueuing and 51dequeuing smaller bursts than specified by the cmdline parameter. This results 52in a larger cycle-count measurement and should not be interpreted as an offload 53cost measurement. Using "pmd-cyclecount" mode will give a better idea of 54actual costs of hardware acceleration. 55 56On hardware devices the throughput measurement is not necessarily the maximum 57possible for the device, e.g. it may be necessary to use multiple cores to keep 58the hardware accelerator fully loaded and so measure maximum throughput. 59 60Compiling the Application 61------------------------- 62 63**Step 1: PMD setting** 64 65The ``dpdk-test-crypto-perf`` tool depends on crypto device drivers PMD which 66are disabled by default in the build configuration file ``common_base``. 67The crypto device drivers PMD which should be tested can be enabled by setting:: 68 69 CONFIG_RTE_LIBRTE_PMD_<name>=y 70 71Setting example for open ssl PMD:: 72 73 CONFIG_RTE_LIBRTE_PMD_OPENSSL=y 74 75**Step 2: Linearization setting** 76 77It is possible linearized input segmented packets just before crypto operation 78for devices which doesn't support scatter-gather, and allows to measure 79performance also for this use case. 80 81To set on the linearization options add below definition to the 82``cperf_ops.h`` file:: 83 84 #define CPERF_LINEARIZATION_ENABLE 85 86**Step 3: Build the application** 87 88Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the 89``dpdk-test-crypto-perf`` applcation. 90 91Initially, the user must select a DPDK target to choose the correct target type 92and compiler options to use when building the libraries. 93The user must have all libraries, modules, updates and compilers installed 94in the system prior to this, 95as described in the earlier chapters in this Getting Started Guide. 96 97Running the Application 98----------------------- 99 100The tool application has a number of command line options: 101 102.. code-block:: console 103 104 dpdk-test-crypto-perf [EAL Options] -- [Application Options] 105 106EAL Options 107~~~~~~~~~~~ 108 109The following are the EAL command-line options that can be used in conjunction 110with the ``dpdk-test-crypto-perf`` applcation. 111See the DPDK Getting Started Guides for more information on these options. 112 113* ``-c <COREMASK>`` or ``-l <CORELIST>`` 114 115 Set the hexadecimal bitmask of the cores to run on. The corelist is a 116 list cores to use. 117 118* ``-w <PCI>`` 119 120 Add a PCI device in white list. 121 122* ``--vdev <driver><id>`` 123 124 Add a virtual device. 125 126Appication Options 127~~~~~~~~~~~~~~~~~~ 128 129The following are the appication command-line options: 130 131* ``--ptest type`` 132 133 Set test type, where ``type`` is one of the following:: 134 135 throughput 136 latency 137 verify 138 pmd-cyclecount 139 140* ``--silent`` 141 142 Disable options dump. 143 144* ``--pool-sz <n>`` 145 146 Set the number of mbufs to be allocated in the mbuf pool. 147 148* ``--total-ops <n>`` 149 150 Set the number of total operations performed. 151 152* ``--burst-sz <n>`` 153 154 Set the number of packets per burst. 155 156 This can be set as: 157 * Single value (i.e. ``--burst-sz 16``) 158 * Range of values, using the following structure ``min:inc:max``, 159 where ``min`` is minimum size, ``inc`` is the increment size and ``max`` 160 is the maximum size (i.e. ``--burst-sz 16:2:32``) 161 * List of values, up to 32 values, separated in commas (i.e. ``--burst-sz 16,24,32``) 162 163* ``--buffer-sz <n>`` 164 165 Set the size of single packet (plaintext or ciphertext in it). 166 167 This can be set as: 168 * Single value (i.e. ``--buffer-sz 16``) 169 * Range of values, using the following structure ``min:inc:max``, 170 where ``min`` is minimum size, ``inc`` is the increment size and ``max`` 171 is the maximum size (i.e. ``--buffer-sz 16:2:32``) 172 * List of values, up to 32 values, separated in commas (i.e. ``--buffer-sz 32,64,128``) 173 174 175* ``--segments-nb <n>`` 176 177 Set the number of segments per packet. 178 179* ``--devtype <name>`` 180 181 Set device type, where ``name`` is one of the following:: 182 183 crypto_null 184 crypto_aesni_mb 185 crypto_aesni_gcm 186 crypto_openssl 187 crypto_qat 188 crypto_snow3g 189 crypto_kasumi 190 crypto_zuc 191 crypto_dpaa2_sec 192 crypto_armv8 193 crypto_scheduler 194 195* ``--optype <name>`` 196 197 Set operation type, where ``name`` is one of the following:: 198 199 cipher-only 200 auth-only 201 cipher-then-auth 202 auth-then-cipher 203 aead 204 205 For GCM/CCM algorithms you should use aead flag. 206 207* ``--sessionless`` 208 209 Enable session-less crypto operations mode. 210 211* ``--out-of-place`` 212 213 Enable out-of-place crypto operations mode. 214 215* ``--test-file <name>`` 216 217 Set test vector file path. See the Test Vector File chapter. 218 219* ``--test-name <name>`` 220 221 Set specific test name section in the test vector file. 222 223* ``--cipher-algo <name>`` 224 225 Set cipher algorithm name, where ``name`` is one of the following:: 226 227 3des-cbc 228 3des-ecb 229 3des-ctr 230 aes-cbc 231 aes-ctr 232 aes-ecb 233 aes-f8 234 aes-xts 235 arc4 236 null 237 kasumi-f8 238 snow3g-uea2 239 zuc-eea3 240 241* ``--cipher-op <mode>`` 242 243 Set cipher operation mode, where ``mode`` is one of the following:: 244 245 encrypt 246 decrypt 247 248* ``--cipher-key-sz <n>`` 249 250 Set the size of cipher key. 251 252* ``--cipher-iv-sz <n>`` 253 254 Set the size of cipher iv. 255 256* ``--auth-algo <name>`` 257 258 Set authentication algorithm name, where ``name`` is one 259 of the following:: 260 261 3des-cbc 262 aes-cbc-mac 263 aes-cmac 264 aes-gmac 265 aes-xcbc-mac 266 md5 267 md5-hmac 268 sha1 269 sha1-hmac 270 sha2-224 271 sha2-224-hmac 272 sha2-256 273 sha2-256-hmac 274 sha2-384 275 sha2-384-hmac 276 sha2-512 277 sha2-512-hmac 278 kasumi-f9 279 snow3g-uia2 280 zuc-eia3 281 282* ``--auth-op <mode>`` 283 284 Set authentication operation mode, where ``mode`` is one of 285 the following:: 286 287 verify 288 generate 289 290* ``--auth-key-sz <n>`` 291 292 Set the size of authentication key. 293 294* ``--auth-iv-sz <n>`` 295 296 Set the size of auth iv. 297 298* ``--aead-algo <name>`` 299 300 Set AEAD algorithm name, where ``name`` is one 301 of the following:: 302 303 aes-ccm 304 aes-gcm 305 306* ``--aead-op <mode>`` 307 308 Set AEAD operation mode, where ``mode`` is one of 309 the following:: 310 311 encrypt 312 decrypt 313 314* ``--aead-key-sz <n>`` 315 316 Set the size of AEAD key. 317 318* ``--aead-iv-sz <n>`` 319 320 Set the size of AEAD iv. 321 322* ``--aead-aad-sz <n>`` 323 324 Set the size of AEAD aad. 325 326* ``--digest-sz <n>`` 327 328 Set the size of digest. 329 330* ``--desc-nb <n>`` 331 332 Set number of descriptors for each crypto device. 333 334* ``--pmd-cyclecount-delay-ms <n>`` 335 336 Add a delay (in milliseconds) between enqueue and dequeue in 337 pmd-cyclecount benchmarking mode (useful when benchmarking 338 hardware acceleration). 339 340* ``--csv-friendly`` 341 342 Enable test result output CSV friendly rather than human friendly. 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, aut key, 351initial vector. All other sections begin header. 352The sections contain particular information typically digest. 353 354**Format of the file:** 355 356Each line beginig 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 tocken then sign '=' and 365a string of bytes in C byte array format:: 366 367 <tocken> = <C byte array> 368 369**Tockens list:** 370 371* ``plaintext`` 372 373 Original plaintext to be crypted. 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 -w 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 -w 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 -w 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