1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2017 Intel Corporation
4 dpdk-test-bbdev Application
5 ===========================
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.
13 Compiling the Application
14 -------------------------
16 **Step 1: PMD setting**
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
22 ``CONFIG_RTE_LIBRTE_PMD_<name>=y``
24 Setting example for (*turbo_sw*) PMD
26 ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y``
28 **Step 2: Build the application**
30 Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the
31 ``dpdk-test-bbdev`` application.
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.
39 Running the Application
40 -----------------------
42 The tool application has a number of command line options:
44 .. code-block:: console
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]
54 The following are the command-line options:
57 Shows help message and exit.
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*".
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.
67 ``-t TIMEOUT, --timeout TIMEOUT``
68 Specifies timeout in seconds. If not specified timeout is set to 300 seconds.
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.
73 The following tests can be run:
76 Small unit tests witch check basic functionality of bbdev library.
78 Test calculates three latency metrics:
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.
89 Test do enqueue on given vector and compare output after dequeueing.
91 Test measures the achieved throughput on the available lcores.
92 Results are printed in million operations per second and million bits per second.
94 The same test as 'throughput' but uses interrupts instead of PMD to perform
99 ``./test-bbdev.py -c validation``
100 Runs validation test suite
102 ``./test-bbdev.py -c latency throughput``
103 Runs latency and throughput test suites
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
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
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.
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.
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)
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.
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.
142 .. code-block:: console
144 ./test-bbdev.py -v app/test-bbdev/test_vectors/turbo_<enc/dec>_c<c>_k<k>_r<r>_e<e>_<extra-info>.data
146 It runs all tests with following vectors:
148 - ``bbdev_null.data``
150 - ``turbo_dec_c1_k6144_r0_e34560_sbd_negllr.data``
152 - ``turbo_enc_c1_k40_r0_e1196_rm.data``
154 - ``turbo_enc_c2_k5952_r0_e17868_crc24b.data``
156 - ``turbo_dec_c1_k40_r0_e17280_sbd_negllr.data``
158 - ``turbo_dec_c1_k6144_r0_e34560_sbd_posllr.data``
160 - ``turbo_enc_c1_k40_r0_e272_rm.data``
162 - ``turbo_enc_c3_k4800_r2_e14412_crc24b.data``
164 - ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data``
166 - ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr_crc24b.data``
168 - ``turbo_enc_c1_k6144_r0_e120_rm_rvidx.data``
170 - ``turbo_enc_c4_k4800_r2_e14412_crc24b.data``
172 - ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_low_snr.data``
174 - ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr.data``
176 - ``turbo_enc_c1_k6144_r0_e18444.data``
178 - ``turbo_dec_c1_k6144_r0_e34560_negllr.data``
180 - ``turbo_enc_c1_k40_r0_e1190_rm.data``
182 - ``turbo_enc_c1_k6144_r0_e18448_crc24a.data``
184 - ``turbo_dec_c1_k6144_r0_e34560_posllr.data``
186 - ``turbo_enc_c1_k40_r0_e1194_rm.data``
188 - ``turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data``
190 .. code-block:: console
192 ./test-bbdev.py -v app/test-bbdev/turbo_*_default.data
194 It runs all tests with "default" vectors.
196 * ``turbo_dec_default.data`` is a soft link to
197 ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data``
199 * ``turbo_enc_default.data`` is a soft link to
200 ``turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data``
206 Shortened tree of isg_cid-wireless_dpdk_ae with dpdk compiled for
207 x86_64-native-linuxapp-icc target:
215 |-- turbo_dec_c1_k6144_r0_e34560_sbd_negllr.data
216 |-- turbo_enc_c1_k40_r0_e1196_rm.data
217 |-- turbo_enc_c2_k5952_r0_e17868_crc24b.data
218 |-- turbo_dec_c1_k40_r0_e17280_sbd_negllr.data
219 |-- turbo_dec_c1_k6144_r0_e34560_sbd_posllr.data
220 |-- turbo_enc_c1_k40_r0_e272_rm.data
221 |-- turbo_enc_c3_k4800_r2_e14412_crc24b.data
222 |-- turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data
223 |-- turbo_dec_c2_k3136_r0_e4920_sbd_negllr_crc24b.data
224 |-- turbo_enc_c1_k6144_r0_e120_rm_rvidx.data
225 |-- turbo_enc_c4_k4800_r2_e14412_crc24b.data
226 |-- turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_low_snr.data
227 |-- turbo_dec_c2_k3136_r0_e4920_sbd_negllr.data
228 |-- turbo_enc_c1_k6144_r0_e18444.data
229 |-- turbo_dec_c1_k6144_r0_e34560_negllr.data
230 |-- turbo_enc_c1_k40_r0_e1190_rm.data
231 |-- turbo_enc_c1_k6144_r0_e18448_crc24a.data
232 |-- turbo_dec_c1_k6144_r0_e34560_posllr.data
233 |-- turbo_enc_c1_k40_r0_e1194_rm.data
234 |-- turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data
236 |-- x86_64-native-linuxapp-icc
243 .. code-block:: console
245 ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev
246 -v turbo_dec_default.data
248 It runs all available tests using the test vector filled based on
249 *turbo_dec_default.data* file.
250 By default number of operations to process on device is set to 32, timeout is
251 set to 300s and operations enqueue/dequeue burst size is set to 32.
252 Moreover a bbdev (*bbdev_null*) device will be created.
254 bbdev turbo_sw device
255 ~~~~~~~~~~~~~~~~~~~~~
257 .. code-block:: console
259 ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev
260 -e="--vdev=turbo_sw" -t 120 -c validation
261 -v ./test_vectors/turbo_* -n 64 -b 8 32
263 It runs **validation** test for each vector file that matches the given pattern.
264 Number of operations to process on device is set to 64 and operations timeout is
265 set to 120s and enqueue/dequeue burst size is set to 8 and to 32.
266 Moreover a bbdev (*turbo_sw*) device will be created.
272 Executing bbdev null device with *bbdev_null.data* helps in measuring the
273 overhead introduced by the bbdev framework.
275 .. code-block:: console
277 ./test-bbdev.py -e="--vdev=bbdev_null0"
278 -v ./test_vectors/bbdev_null.data
282 bbdev_null device does not have to be defined explicitly as it is created by default.
289 Test Vector files contain the data which is used to set turbo decoder/encoder
290 parameters and buffers for validation purpose. New test vector files should be
291 stored in ``app/test-bbdev/test_vectors/`` directory. Detailed description of
292 the syntax of the test vector files is in the following section.
295 Basic principles for test vector files
296 --------------------------------------
297 Line started with ``#`` is treated as a comment and is ignored.
299 If variable is a chain of values, values should be separated by a comma. If
300 assignment is split into several lines, each line (except the last one) has to
301 be ended with a comma.
302 There is no comma after last value in last line. Correct assignment should
303 look like the following:
308 value, value, value, value,
311 In case where variable is a single value correct assignment looks like the
319 Length of chain variable is calculated by parser. Can not be defined
322 Variable op_type has to be defined as a first variable in file. It specifies
323 what type of operations will be executed. For decoder op_type has to be set to
324 ``RTE_BBDEV_OP_TURBO_DEC`` and for encoder to ``RTE_BBDEV_OP_TURBO_ENC``.
326 Full details of the meaning and valid values for the below fields are
327 documented in *rte_bbdev_op.h*
330 Turbo decoder test vectors template
331 -----------------------------------
333 For turbo decoder it has to be always set to ``RTE_BBDEV_OP_TURBO_DEC``
338 RTE_BBDEV_OP_TURBO_DEC
340 Chain of uint32_t values. Note that it is possible to define more than one
341 input/output entries which will result in chaining two or more data structures
342 for *segmented Transport Blocks*
347 0x00000000, 0x7f817f00, 0x7f7f8100, 0x817f8100, 0x81008100, 0x7f818100, 0x81817f00, 0x7f818100,
348 0x81007f00, 0x7f818100, 0x817f8100, 0x81817f00, 0x81008100, 0x817f7f00, 0x7f7f8100, 0x81817f00
350 Chain of uint32_t values
355 0x7f7f0000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
356 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000
358 Chain of uint32_t values
363 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
364 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000
366 Chain of uint32_t values
373 Chain of uint32_t values
380 Chain of uint32_t values
385 0x817f817f, 0x7f817f7f, 0x81818181, 0x817f7f81, 0x7f818181, 0x8181817f, 0x817f817f, 0x8181817f
387 Chain of uint32_t values
392 0x817f7f81, 0x7f7f7f81, 0x7f7f8181
433 expected_iter_count =
450 Chain of flags for turbo decoder operation. Following flags can be used:
452 - ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE``
454 - ``RTE_BBDEV_TURBO_CRC_TYPE_24B``
456 - ``RTE_BBDEV_TURBO_EQUALIZER``
458 - ``RTE_BBDEV_TURBO_SOFT_OUT_SATURATE``
460 - ``RTE_BBDEV_TURBO_HALF_ITERATION_EVEN``
462 - ``RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH``
464 - ``RTE_BBDEV_TURBO_SOFT_OUTPUT``
466 - ``RTE_BBDEV_TURBO_EARLY_TERMINATION``
468 - ``RTE_BBDEV_TURBO_DEC_INTERRUPTS``
470 - ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN``
472 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN``
474 - ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT``
476 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT``
478 - ``RTE_BBDEV_TURBO_MAP_DEC``
485 RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE, RTE_BBDEV_TURBO_EQUALIZER,
486 RTE_BBDEV_TURBO_SOFT_OUTPUT
488 Chain of operation statuses that are expected after operation is performed.
489 Following statuses can be used:
499 ``OK`` means no errors are expected. Cannot be used with other values.
507 Turbo encoder test vectors template
508 -----------------------------------
510 For turbo encoder it has to be always set to ``RTE_BBDEV_OP_TURBO_ENC``
515 RTE_BBDEV_OP_TURBO_ENC
517 Chain of uint32_t values
524 Chain of uint32_t values
529 0xd2399179, 0x640eb999, 0x2cbaf577, 0xaf224ae2, 0x9d139927, 0xe6909b29,
530 0xa25b7f47, 0x2aa224ce, 0x79f2
560 Chain of flags for turbo encoder operation. Following flags can be used:
562 - ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS``
564 - ``RTE_BBDEV_TURBO_RATE_MATCH``
566 - ``RTE_BBDEV_TURBO_CRC_24B_ATTACH``
568 - ``RTE_BBDEV_TURBO_CRC_24A_ATTACH``
570 - ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER``
572 ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` is used to indicate the parser to
573 force the input data to be memory split and formed as a segmented mbuf.
579 RTE_BBDEV_TURBO_RATE_MATCH
581 Chain of operation statuses that are expected after operation is performed.
582 Following statuses can be used:
590 ``OK`` means no errors are expected. Cannot be used with other values.