doc/guides/tools/cryptoperf.rst

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