doc/guides/tools/cryptoperf.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2016 Intel Corporation.
   3
   4 dpdk-test-crypto-perf Application
   5 =================================
   6
   7 The ``dpdk-test-crypto-perf`` tool is a Data Plane Development Kit (DPDK)
   8 utility that allows measuring performance parameters of PMDs available in the
   9 crypto tree. There are available two measurement types: throughput and latency.
  10 User can use multiply cores to run tests on but only
  11 one type of crypto PMD can be measured during single application
  12 execution. Cipher parameters, type of device, type of operation and
  13 chain mode have to be specified in the command line as application
  14 parameters. These parameters are checked using device capabilities
  15 structure.
  16
  17 Limitations
  18 -----------
  19 On hardware devices the cycle-count doesn't always represent the actual offload
  20 cost. The cycle-count only represents the offload cost when the hardware
  21 accelerator is not fully loaded, when loaded the cpu cycles freed up by the
  22 offload are still consumed by the test tool and included in the cycle-count.
  23 These cycles are consumed by retries and inefficient API calls enqueuing and
  24 dequeuing smaller bursts than specified by the cmdline parameter. This results
  25 in a larger cycle-count measurement and should not be interpreted as an offload
  26 cost measurement. Using "pmd-cyclecount" mode will give a better idea of
  27 actual costs of hardware acceleration.
  28
  29 On hardware devices the throughput measurement is not necessarily the maximum
  30 possible for the device, e.g. it may be necessary to use multiple cores to keep
  31 the hardware accelerator fully loaded and so measure maximum throughput.
  32
  33 Compiling the Application
  34 -------------------------
  35
  36 **Step 1: PMD setting**
  37
  38 The ``dpdk-test-crypto-perf`` tool depends on crypto device drivers PMD which
  39 are disabled by default in the build configuration file ``common_base``.
  40 The crypto device drivers PMD which should be tested can be enabled by setting::
  41
  42    CONFIG_RTE_LIBRTE_PMD_<name>=y
  43
  44 Setting example for open ssl PMD::
  45
  46    CONFIG_RTE_LIBRTE_PMD_OPENSSL=y
  47
  48 **Step 2: Linearization setting**
  49
  50 It is possible linearized input segmented packets just before crypto operation
  51 for devices which doesn't support scatter-gather, and allows to measure
  52 performance also for this use case.
  53
  54 To 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
  61 Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the
  62 ``dpdk-test-crypto-perf`` application.
  63
  64 Initially, the user must select a DPDK target to choose the correct target type
  65 and compiler options to use when building the libraries.
  66 The user must have all libraries, modules, updates and compilers installed
  67 in the system prior to this,
  68 as described in the earlier chapters in this Getting Started Guide.
  69
  70 Running the Application
  71 -----------------------
  72
  73 The 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
  79 EAL Options
  80 ~~~~~~~~~~~
  81
  82 The following are the EAL command-line options that can be used in conjunction
  83 with the ``dpdk-test-crypto-perf`` application.
  84 See 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
  99 Application Options
 100 ~~~~~~~~~~~~~~~~~~~
 101
 102 The 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
 345 Test Vector File
 346 ~~~~~~~~~~~~~~~~
 347
 348 The test vector file is a text file contain information about test vectors.
 349 The file is made of the sections. The first section doesn't have header.
 350 It contain global information used in each test variant vectors -
 351 typically information about plaintext, ciphertext, cipher key, auth key,
 352 initial vector. All other sections begin header.
 353 The sections contain particular information typically digest.
 354
 355 **Format of the file:**
 356
 357 Each line beginning with sign '#' contain comment and it is ignored by parser::
 358
 359    # <comment>
 360
 361 Header line is just name in square bracket::
 362
 363    [<section name>]
 364
 365 Data line contain information token then sign '=' and
 366 a 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
 404 Examples
 405 --------
 406
 407 Call application for performance throughput test of single Aesni MB PMD
 408 for cipher encryption aes-cbc and auth generation sha1-hmac,
 409 one 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
 417 Call application for performance latency test of two Aesni MB PMD executed
 418 on 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
 426 Call application for verification test of single open ssl PMD
 427 for cipher encryption aes-gcm and auth generation aes-gcm,ten operations
 428 in silent mode, test vector provide in file "test_aes_gcm.data"
 429 with 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
 437 Test 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