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