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