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            docsis
 197
 198         For GCM/CCM algorithms you should use aead flag.
 199
 200 * ``--sessionless``
 201
 202         Enable session-less crypto operations mode.
 203
 204 * ``--out-of-place``
 205
 206         Enable out-of-place crypto operations mode.
 207
 208 * ``--test-file <name>``
 209
 210         Set test vector file path. See the Test Vector File chapter.
 211
 212 * ``--test-name <name>``
 213
 214         Set specific test name section in the test vector file.
 215
 216 * ``--cipher-algo <name>``
 217
 218         Set cipher algorithm name, where ``name`` is one of the following::
 219
 220            3des-cbc
 221            3des-ecb
 222            3des-ctr
 223            aes-cbc
 224            aes-ctr
 225            aes-ecb
 226            aes-f8
 227            aes-xts
 228            arc4
 229            null
 230            kasumi-f8
 231            snow3g-uea2
 232            zuc-eea3
 233
 234 * ``--cipher-op <mode>``
 235
 236         Set cipher operation mode, where ``mode`` is one of the following::
 237
 238            encrypt
 239            decrypt
 240
 241 * ``--cipher-key-sz <n>``
 242
 243         Set the size of cipher key.
 244
 245 * ``--cipher-iv-sz <n>``
 246
 247         Set the size of cipher iv.
 248
 249 * ``--auth-algo <name>``
 250
 251         Set authentication algorithm name, where ``name`` is one
 252         of the following::
 253
 254            3des-cbc
 255            aes-cbc-mac
 256            aes-cmac
 257            aes-gmac
 258            aes-xcbc-mac
 259            md5
 260            md5-hmac
 261            sha1
 262            sha1-hmac
 263            sha2-224
 264            sha2-224-hmac
 265            sha2-256
 266            sha2-256-hmac
 267            sha2-384
 268            sha2-384-hmac
 269            sha2-512
 270            sha2-512-hmac
 271            kasumi-f9
 272            snow3g-uia2
 273            zuc-eia3
 274
 275 * ``--auth-op <mode>``
 276
 277         Set authentication operation mode, where ``mode`` is one of
 278         the following::
 279
 280            verify
 281            generate
 282
 283 * ``--auth-key-sz <n>``
 284
 285         Set the size of authentication key.
 286
 287 * ``--auth-iv-sz <n>``
 288
 289         Set the size of auth iv.
 290
 291 * ``--aead-algo <name>``
 292
 293         Set AEAD algorithm name, where ``name`` is one
 294         of the following::
 295
 296            aes-ccm
 297            aes-gcm
 298
 299 * ``--aead-op <mode>``
 300
 301         Set AEAD operation mode, where ``mode`` is one of
 302         the following::
 303
 304            encrypt
 305            decrypt
 306
 307 * ``--aead-key-sz <n>``
 308
 309         Set the size of AEAD key.
 310
 311 * ``--aead-iv-sz <n>``
 312
 313         Set the size of AEAD iv.
 314
 315 * ``--aead-aad-sz <n>``
 316
 317         Set the size of AEAD aad.
 318
 319 * ``--digest-sz <n>``
 320
 321         Set the size of digest.
 322
 323 * ``--desc-nb <n>``
 324
 325         Set number of descriptors for each crypto device.
 326
 327 * ``--pmd-cyclecount-delay-ms <n>``
 328
 329         Add a delay (in milliseconds) between enqueue and dequeue in
 330         pmd-cyclecount benchmarking mode (useful when benchmarking
 331         hardware acceleration).
 332
 333 * ``--csv-friendly``
 334
 335         Enable test result output CSV friendly rather than human friendly.
 336
 337 * ``--pdcp-sn-sz <n>``
 338
 339         Set PDCP sequence number size(n) in bits. Valid values of n will
 340         be 5/7/12/15/18.
 341
 342 * ``--pdcp-domain <control/user>``
 343
 344         Set PDCP domain to specify Control/user plane.
 345
 346 * ``--docsis-hdr-sz <n>``
 347
 348         Set DOCSIS header size(n) in bytes.
 349
 350 Test Vector File
 351 ~~~~~~~~~~~~~~~~
 352
 353 The test vector file is a text file contain information about test vectors.
 354 The file is made of the sections. The first section doesn't have header.
 355 It contain global information used in each test variant vectors -
 356 typically information about plaintext, ciphertext, cipher key, auth key,
 357 initial vector. All other sections begin header.
 358 The sections contain particular information typically digest.
 359
 360 **Format of the file:**
 361
 362 Each line beginning with sign '#' contain comment and it is ignored by parser::
 363
 364    # <comment>
 365
 366 Header line is just name in square bracket::
 367
 368    [<section name>]
 369
 370 Data line contain information token then sign '=' and
 371 a string of bytes in C byte array format::
 372
 373    <token> = <C byte array>
 374
 375 **Tokens list:**
 376
 377 * ``plaintext``
 378
 379         Original plaintext to be encrypted.
 380
 381 * ``ciphertext``
 382
 383         Encrypted plaintext string.
 384
 385 * ``cipher_key``
 386
 387         Key used in cipher operation.
 388
 389 * ``auth_key``
 390
 391         Key used in auth operation.
 392
 393 * ``cipher_iv``
 394
 395         Cipher Initial Vector.
 396
 397 * ``auth_iv``
 398
 399         Auth Initial Vector.
 400
 401 * ``aad``
 402
 403         Additional data.
 404
 405 * ``digest``
 406
 407         Digest string.
 408
 409 Examples
 410 --------
 411
 412 Call application for performance throughput test of single Aesni MB PMD
 413 for cipher encryption aes-cbc and auth generation sha1-hmac,
 414 one million operations, burst size 32, packet size 64::
 415
 416    dpdk-test-crypto-perf -l 6-7 --vdev crypto_aesni_mb -w 0000:00:00.0 --
 417    --ptest throughput --devtype crypto_aesni_mb --optype cipher-then-auth
 418    --cipher-algo aes-cbc --cipher-op encrypt --cipher-key-sz 16 --auth-algo
 419    sha1-hmac --auth-op generate --auth-key-sz 64 --digest-sz 12
 420    --total-ops 10000000 --burst-sz 32 --buffer-sz 64
 421
 422 Call application for performance latency test of two Aesni MB PMD executed
 423 on two cores for cipher encryption aes-cbc, ten operations in silent mode::
 424
 425    dpdk-test-crypto-perf -l 4-7 --vdev crypto_aesni_mb1
 426    --vdev crypto_aesni_mb2 -w 0000:00:00.0 -- --devtype crypto_aesni_mb
 427    --cipher-algo aes-cbc --cipher-key-sz 16 --cipher-iv-sz 16
 428    --cipher-op encrypt --optype cipher-only --silent
 429    --ptest latency --total-ops 10
 430
 431 Call application for verification test of single open ssl PMD
 432 for cipher encryption aes-gcm and auth generation aes-gcm,ten operations
 433 in silent mode, test vector provide in file "test_aes_gcm.data"
 434 with packet verification::
 435
 436    dpdk-test-crypto-perf -l 4-7 --vdev crypto_openssl -w 0000:00:00.0 --
 437    --devtype crypto_openssl --aead-algo aes-gcm --aead-key-sz 16
 438    --aead-iv-sz 16 --aead-op encrypt --aead-aad-sz 16 --digest-sz 16
 439    --optype aead --silent --ptest verify --total-ops 10
 440    --test-file test_aes_gcm.data
 441
 442 Test vector file for cipher algorithm aes cbc 256 with authorization sha::
 443
 444    # Global Section
 445    plaintext =
 446    0xff, 0xca, 0xfb, 0xf1, 0x38, 0x20, 0x2f, 0x7b, 0x24, 0x98, 0x26, 0x7d, 0x1d, 0x9f, 0xb3, 0x93,
 447    0xd9, 0xef, 0xbd, 0xad, 0x4e, 0x40, 0xbd, 0x60, 0xe9, 0x48, 0x59, 0x90, 0x67, 0xd7, 0x2b, 0x7b,
 448    0x8a, 0xe0, 0x4d, 0xb0, 0x70, 0x38, 0xcc, 0x48, 0x61, 0x7d, 0xee, 0xd6, 0x35, 0x49, 0xae, 0xb4,
 449    0xaf, 0x6b, 0xdd, 0xe6, 0x21, 0xc0, 0x60, 0xce, 0x0a, 0xf4, 0x1c, 0x2e, 0x1c, 0x8d, 0xe8, 0x7b
 450    ciphertext =
 451    0x77, 0xF9, 0xF7, 0x7A, 0xA3, 0xCB, 0x68, 0x1A, 0x11, 0x70, 0xD8, 0x7A, 0xB6, 0xE2, 0x37, 0x7E,
 452    0xD1, 0x57, 0x1C, 0x8E, 0x85, 0xD8, 0x08, 0xBF, 0x57, 0x1F, 0x21, 0x6C, 0xAD, 0xAD, 0x47, 0x1E,
 453    0x0D, 0x6B, 0x79, 0x39, 0x15, 0x4E, 0x5B, 0x59, 0x2D, 0x76, 0x87, 0xA6, 0xD6, 0x47, 0x8F, 0x82,
 454    0xB8, 0x51, 0x91, 0x32, 0x60, 0xCB, 0x97, 0xDE, 0xBE, 0xF0, 0xAD, 0xFC, 0x23, 0x2E, 0x22, 0x02
 455    cipher_key =
 456    0xE4, 0x23, 0x33, 0x8A, 0x35, 0x64, 0x61, 0xE2, 0x49, 0x03, 0xDD, 0xC6, 0xB8, 0xCA, 0x55, 0x7A,
 457    0xd0, 0xe7, 0x4b, 0xfb, 0x5d, 0xe5, 0x0c, 0xe7, 0x6f, 0x21, 0xb5, 0x52, 0x2a, 0xbb, 0xc7, 0xf7
 458    auth_key =
 459    0xaf, 0x96, 0x42, 0xf1, 0x8c, 0x50, 0xdc, 0x67, 0x1a, 0x43, 0x47, 0x62, 0xc7, 0x04, 0xab, 0x05,
 460    0xf5, 0x0c, 0xe7, 0xa2, 0xa6, 0x23, 0xd5, 0x3d, 0x95, 0xd8, 0xcd, 0x86, 0x79, 0xf5, 0x01, 0x47,
 461    0x4f, 0xf9, 0x1d, 0x9d, 0x36, 0xf7, 0x68, 0x1a, 0x64, 0x44, 0x58, 0x5d, 0xe5, 0x81, 0x15, 0x2a,
 462    0x41, 0xe4, 0x0e, 0xaa, 0x1f, 0x04, 0x21, 0xff, 0x2c, 0xf3, 0x73, 0x2b, 0x48, 0x1e, 0xd2, 0xf7
 463    cipher_iv =
 464    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F
 465    # Section sha 1 hmac buff 32
 466    [sha1_hmac_buff_32]
 467    digest =
 468    0x36, 0xCA, 0x49, 0x6A, 0xE3, 0x54, 0xD8, 0x4F, 0x0B, 0x76, 0xD8, 0xAA, 0x78, 0xEB, 0x9D, 0x65,
 469    0x2C, 0xCA, 0x1F, 0x97
 470    # Section sha 256 hmac buff 32
 471    [sha256_hmac_buff_32]
 472    digest =
 473    0x1C, 0xB2, 0x3D, 0xD1, 0xF9, 0xC7, 0x6C, 0x49, 0x2E, 0xDA, 0x94, 0x8B, 0xF1, 0xCF, 0x96, 0x43,
 474    0x67, 0x50, 0x39, 0x76, 0xB5, 0xA1, 0xCE, 0xA1, 0xD7, 0x77, 0x10, 0x07, 0x43, 0x37, 0x05, 0xB4