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