doc/guides/tools/testbbdev.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation
   3
   4 dpdk-test-bbdev Application
   5 ===========================
   6
   7 The ``dpdk-test-bbdev`` tool is a Data Plane Development Kit (DPDK) utility that
   8 allows measuring performance parameters of PMDs available in the bbdev framework.
   9 Available tests available for execution are: latency, throughput, validation and
  10 sanity tests. Execution of tests can be customized using various parameters
  11 passed to a python running script.
  12
  13 Compiling the Application
  14 -------------------------
  15
  16 **Step 1: PMD setting**
  17
  18 The ``dpdk-test-bbdev`` tool depends on crypto device drivers PMD which
  19 are disabled by default in the build configuration file ``common_base``.
  20 The bbdevice drivers PMD which should be tested can be enabled by setting
  21
  22    ``CONFIG_RTE_LIBRTE_PMD_<name>=y``
  23
  24 Setting example for (*turbo_sw*) PMD
  25
  26    ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y``
  27
  28 **Step 2: Build the application**
  29
  30 Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the
  31 ``dpdk-test-bbdev`` application.
  32
  33 Initially, the user must select a DPDK target to choose the correct target type
  34 and compiler options to use when building the libraries.
  35 The user must have all libraries, modules, updates and compilers installed
  36 in the system prior to this, as described in the earlier chapters in this
  37 Getting Started Guide.
  38
  39 Running the Application
  40 -----------------------
  41
  42 The tool application has a number of command line options:
  43
  44 .. code-block:: console
  45
  46   python test-bbdev.py [-h] [-p TESTAPP_PATH] [-e EAL_PARAMS] [-t TIMEOUT]
  47                        [-c TEST_CASE [TEST_CASE ...]]
  48                        [-v TEST_VECTOR [TEST_VECTOR...]] [-n NUM_OPS]
  49                        [-b BURST_SIZE [BURST_SIZE ...]] [-l NUM_LCORES]
  50
  51 command-line Options
  52 ~~~~~~~~~~~~~~~~~~~~
  53
  54 The following are the command-line options:
  55
  56 ``-h, --help``
  57  Shows help message and exit.
  58
  59 ``-p TESTAPP_PATH, --testapp_path TESTAPP_PATH``
  60  Indicates the path to the bbdev test app. If not specified path is set based
  61  on *$RTE_SDK* environment variable concatenated with "*/build/app/testbbdev*".
  62
  63 ``-e EAL_PARAMS, --eal_params EAL_PARAMS``
  64  Specifies EAL arguments which are passed to the test app. For more details,
  65  refer to DPDK documentation at http://dpdk.org/doc.
  66
  67 ``-t TIMEOUT, --timeout TIMEOUT``
  68  Specifies timeout in seconds. If not specified timeout is set to 300 seconds.
  69
  70 ``-c TEST_CASE [TEST_CASE ...], --test_cases TEST_CASE [TEST_CASE ...]``
  71  Defines test cases to run. If not specified all available tests are run.
  72
  73  The following tests can be run:
  74   * unittest
  75      Small unit tests witch check basic functionality of bbdev library.
  76   * latency
  77      Test calculates three latency metrics:
  78       * offload_latency_tc
  79          measures the cost of offloading enqueue and dequeue operations.
  80       * offload_latency_empty_q_tc
  81          measures the cost of offloading a dequeue operation from an empty queue.
  82          checks how long last dequeueing if there is no operations to dequeue
  83       * operation_latency_tc
  84          measures the time difference from the first attempt to enqueue till the
  85          first successful dequeue.
  86   * validation
  87      Test do enqueue on given vector and compare output after dequeueing.
  88   * throughput
  89      Test measures the achieved throughput on the available lcores.
  90      Results are printed in million operations per second and million bits per second.
  91   * interrupt
  92      The same test as 'throughput' but uses interrupts instead of PMD to perform
  93      the dequeue.
  94
  95  **Example usage:**
  96
  97  ``./test-bbdev.py -c validation``
  98   Runs validation test suite
  99
 100  ``./test-bbdev.py -c latency throughput``
 101   Runs latency and throughput test suites
 102
 103 ``-v TEST_VECTOR [TEST_VECTOR ...], --test_vector TEST_VECTOR [TEST_VECTOR ...]``
 104  Specifies paths to the test vector files. If not specified path is set based
 105  on *$RTE_SDK* environment variable concatenated with
 106  "*/app/test-bbdev/test_vectors/bbdev_vector_null.data*" and indicates default
 107  data file.
 108
 109  **Example usage:**
 110
 111  ``./test-bbdev.py -v app/test-bbdev/test_vectors/bbdev_vector_td_test1.data``
 112   Fills vector based on bbdev_vector_td_test1.data file and runs all tests
 113
 114  ``./test-bbdev.py -v bbdev_vector_td_test1.data bbdev_vector_te_test2.data``
 115   The bbdev test app is executed twice. First time vector is filled based on
 116   *bbdev_vector_td_test1.data* file and second time based on
 117   *bbdev_vector_te_test2.data* file. For both executions all tests are run.
 118
 119 ``-n NUM_OPS, --num_ops NUM_OPS``
 120  Specifies number of operations to process on device. If not specified num_ops
 121  is set to 32 operations.
 122
 123 ``-l NUM_LCORES, --num_lcores NUM_LCORES``
 124  Specifies number of lcores to run. If not specified num_lcores is set
 125  according to value from RTE configuration (EAL coremask)
 126
 127 ``-b BURST_SIZE [BURST_SIZE ...], --burst-size BURST_SIZE [BURST_SIZE ...]``
 128  Specifies operations enqueue/dequeue burst size. If not specified burst_size is
 129  set to 32. Maximum is 512.
 130
 131
 132 Parameter globbing
 133 ~~~~~~~~~~~~~~~~~~
 134
 135 Thanks to the globbing functionality in python test-bbdev.py script allows to
 136 run tests with different set of vector files without giving all of them explicitly.
 137
 138 **Example usage:**
 139
 140 .. code-block:: console
 141
 142   ./test-bbdev.py -v app/test-bbdev/test_vectors/bbdev_vector_*.data
 143
 144 It runs all tests with following vectors:
 145
 146 - ``bbdev_vector_null.data``
 147
 148 - ``bbdev_vector_td_default.data``
 149
 150 - ``bbdev_vector_te_default.data``
 151
 152
 153 .. code-block:: console
 154
 155   ./test-bbdev.py -v app/test-bbdev/test_vectors/bbdev_vector_t?_default.data
 156
 157 It runs all tests with "default" vectors:
 158
 159 - ``bbdev_vector_te_default.data``
 160
 161 - ``bbdev_vector_td_default.data``
 162
 163
 164 Running Tests
 165 -------------
 166
 167 Shortened tree of isg_cid-wireless_dpdk_ae with dpdk compiled for
 168 x86_64-native-linuxapp-icc target:
 169
 170 ::
 171
 172  |-- app
 173      |-- test-bbdev
 174          |-- test_vectors
 175              |-- bbdev_vector_null.data
 176              |-- bbdev_vector_td_default.data
 177              |-- bbdev_vector_te_default.data
 178
 179  |-- x86_64-native-linuxapp-icc
 180      |-- app
 181          |-- testbbdev
 182
 183 All bbdev devices
 184 ~~~~~~~~~~~~~~~~~
 185
 186 .. code-block:: console
 187
 188   ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev
 189   -v ./test_vectors/bbdev_vector_td_default.data
 190
 191 It runs all available tests using the test vector filled based on
 192 *bbdev_vector_td_default.data* file.
 193 By default number of operations to process on device is set to 32, timeout is
 194 set to 300s and operations enqueue/dequeue burst size is set to 32.
 195 Moreover a bbdev (*bbdev_null*) device will be created.
 196
 197 bbdev turbo_sw device
 198 ~~~~~~~~~~~~~~~~~~~~~
 199
 200 .. code-block:: console
 201
 202   ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev
 203   -e="--vdev=turbo_sw" -t 120 -c validation
 204   -v ./test_vectors/bbdev_vector_t?_default.data -n 64 -b 8 32
 205
 206 It runs **validation** test for each vector file that matches the given pattern.
 207 Number of operations to process on device is set to 64 and operations timeout is
 208 set to 120s and enqueue/dequeue burst size is set to 8 and to 32.
 209 Moreover a bbdev (*turbo_sw*) device will be created.
 210
 211
 212 bbdev null device
 213 ~~~~~~~~~~~~~~~~~
 214
 215 Executing bbdev null device with *bbdev_vector_null.data* helps in measuring the
 216 overhead introduced by the bbdev framework.
 217
 218 .. code-block:: console
 219
 220   ./test-bbdev.py -e="--vdev=bbdev_null0"
 221   -v ./test_vectors/bbdev_vector_null.data
 222
 223 **Note:**
 224
 225 bbdev_null device does not have to be defined explicitly as it is created by default.
 226
 227
 228
 229 Test Vector files
 230 =================
 231
 232 Test Vector files contain the data which is used to set turbo decoder/encoder
 233 parameters and buffers for validation purpose. New test vector files should be
 234 stored in ``app/test-bbdev/test_vectors/`` directory. Detailed description of
 235 the syntax of the test vector files is in the following section.
 236
 237
 238 Basic principles for test vector files
 239 --------------------------------------
 240 Line started with ``#`` is treated as a comment and is ignored.
 241
 242 If variable is a chain of values, values should be separated by a comma. If
 243 assignment is split into several lines, each line (except the last one) has to
 244 be ended with a comma.
 245 There is no comma after last value in last line. Correct assignment should
 246 look like the following:
 247
 248 .. parsed-literal::
 249
 250  variable =
 251  value, value, value, value,
 252  value, value
 253
 254 In case where variable is a single value correct assignment looks like the
 255 following:
 256
 257 .. parsed-literal::
 258
 259  variable =
 260  value
 261
 262 Length of chain variable is calculated by parser. Can not be defined
 263 explicitly.
 264
 265 Variable op_type has to be defined as a first variable in file. It specifies
 266 what type of operations will be executed. For decoder op_type has to be set to
 267 ``RTE_BBDEV_OP_TURBO_DEC`` and for encoder to ``RTE_BBDEV_OP_TURBO_ENC``.
 268
 269 Full details of the meaning and valid values for the below fields are
 270 documented in *rte_bbdev_op.h*
 271
 272
 273 Turbo decoder test vectors template
 274 -----------------------------------
 275
 276 For turbo decoder it has to be always set to ``RTE_BBDEV_OP_TURBO_DEC``
 277
 278 .. parsed-literal::
 279
 280     op_type =
 281     RTE_BBDEV_OP_TURBO_DEC
 282
 283 Chain of uint32_t values. Note that it is possible to define more than one
 284 input/output entries which will result in chaining two or more data structures
 285 for *segmented Transport Blocks*
 286
 287 .. parsed-literal::
 288
 289     input0 =
 290     0x00000000, 0x7f817f00, 0x7f7f8100, 0x817f8100, 0x81008100, 0x7f818100, 0x81817f00, 0x7f818100,
 291     0x81007f00, 0x7f818100, 0x817f8100, 0x81817f00, 0x81008100, 0x817f7f00, 0x7f7f8100, 0x81817f00
 292
 293 Chain of uint32_t values
 294
 295 .. parsed-literal::
 296
 297     input1 =
 298     0x7f7f0000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
 299     0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000
 300
 301 Chain of uint32_t values
 302
 303 .. parsed-literal::
 304
 305     input2 =
 306     0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
 307     0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000
 308
 309 Chain of uint32_t values
 310
 311 .. parsed-literal::
 312
 313     hard_output0 =
 314     0xa7d6732e
 315
 316 Chain of uint32_t values
 317
 318 .. parsed-literal::
 319
 320     hard_output1 =
 321     0xa61
 322
 323 Chain of uint32_t values
 324
 325 .. parsed-literal::
 326
 327     soft_output0 =
 328     0x817f817f, 0x7f817f7f, 0x81818181, 0x817f7f81, 0x7f818181, 0x8181817f, 0x817f817f, 0x8181817f
 329
 330 Chain of uint32_t values
 331
 332 .. parsed-literal::
 333
 334     soft_output1 =
 335     0x817f7f81, 0x7f7f7f81, 0x7f7f8181
 336
 337 uint32_t value
 338
 339 .. parsed-literal::
 340
 341     e =
 342     44
 343
 344 uint16_t value
 345
 346 .. parsed-literal::
 347
 348     k =
 349     40
 350
 351 uint8_t value
 352
 353 .. parsed-literal::
 354
 355     rv_index =
 356     0
 357
 358 uint8_t value
 359
 360 .. parsed-literal::
 361
 362     iter_max =
 363     8
 364
 365 uint8_t value
 366
 367 .. parsed-literal::
 368
 369     iter_min =
 370     4
 371
 372 uint8_t value
 373
 374 .. parsed-literal::
 375
 376     expected_iter_count =
 377     8
 378
 379 uint8_t value
 380
 381 .. parsed-literal::
 382
 383     ext_scale =
 384     15
 385
 386 uint8_t value
 387
 388 .. parsed-literal::
 389
 390     num_maps =
 391     0
 392
 393 Chain of flags for turbo decoder operation. Following flags can be used:
 394
 395 - ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE``
 396
 397 - ``RTE_BBDEV_TURBO_CRC_TYPE_24B``
 398
 399 - ``RTE_BBDEV_TURBO_EQUALIZER``
 400
 401 - ``RTE_BBDEV_TURBO_SOFT_OUT_SATURATE``
 402
 403 - ``RTE_BBDEV_TURBO_HALF_ITERATION_EVEN``
 404
 405 - ``RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH``
 406
 407 - ``RTE_BBDEV_TURBO_SOFT_OUTPUT``
 408
 409 - ``RTE_BBDEV_TURBO_EARLY_TERMINATION``
 410
 411 - ``RTE_BBDEV_TURBO_DEC_INTERRUPTS``
 412
 413 - ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN``
 414
 415 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN``
 416
 417 - ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT``
 418
 419 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT``
 420
 421 - ``RTE_BBDEV_TURBO_MAP_DEC``
 422
 423 Example:
 424
 425     .. parsed-literal::
 426
 427         op_flags =
 428         RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE, RTE_BBDEV_TURBO_EQUALIZER,
 429         RTE_BBDEV_TURBO_SOFT_OUTPUT
 430
 431 Chain of operation statuses that are expected after operation is performed.
 432 Following statuses can be used:
 433
 434 - ``DMA``
 435
 436 - ``FCW``
 437
 438 - ``CRC``
 439
 440 - ``OK``
 441
 442 ``OK`` means no errors are expected. Cannot be used with other values.
 443
 444 .. parsed-literal::
 445
 446     expected_status =
 447     FCW, CRC
 448
 449
 450 Turbo encoder test vectors template
 451 -----------------------------------
 452
 453 For turbo encoder it has to be always set to ``RTE_BBDEV_OP_TURBO_ENC``
 454
 455 .. parsed-literal::
 456
 457     op_type =
 458     RTE_BBDEV_OP_TURBO_ENC
 459
 460 Chain of uint32_t values
 461
 462 .. parsed-literal::
 463
 464     input0 =
 465     0x11d2bcac, 0x4d
 466
 467 Chain of uint32_t values
 468
 469 .. parsed-literal::
 470
 471     output0 =
 472     0xd2399179, 0x640eb999, 0x2cbaf577, 0xaf224ae2, 0x9d139927, 0xe6909b29,
 473     0xa25b7f47, 0x2aa224ce, 0x79f2
 474
 475 uint32_t value
 476
 477 .. parsed-literal::
 478
 479     e =
 480     272
 481
 482 uint16_t value
 483
 484 .. parsed-literal::
 485
 486     k =
 487     40
 488
 489 uint16_t value
 490
 491 .. parsed-literal::
 492
 493     ncb =
 494     192
 495
 496 uint8_t value
 497
 498 .. parsed-literal::
 499
 500     rv_index =
 501     0
 502
 503 Chain of flags for turbo encoder operation. Following flags can be used:
 504
 505 - ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS``
 506
 507 - ``RTE_BBDEV_TURBO_RATE_MATCH``
 508
 509 - ``RTE_BBDEV_TURBO_CRC_24B_ATTACH``
 510
 511 - ``RTE_BBDEV_TURBO_CRC_24A_ATTACH``
 512
 513 - ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER``
 514
 515 ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` is used to indicate the parser to
 516 force the input data to be memory split and formed as a segmented mbuf.
 517
 518
 519 .. parsed-literal::
 520
 521     op_flags =
 522     RTE_BBDEV_TURBO_RATE_MATCH
 523
 524 Chain of operation statuses that are expected after operation is performed.
 525 Following statuses can be used:
 526
 527 - ``DMA``
 528
 529 - ``FCW``
 530
 531 - ``OK``
 532
 533 ``OK`` means no errors are expected. Cannot be used with other values.
 534
 535 .. parsed-literal::
 536
 537     expected_status =
 538     OK