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