X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Ftools%2Ftestbbdev.rst;h=7e956966097b199e74363ada359be70100fd57f3;hb=64edb05e29c82260a0bd1000a20023d20c123e41;hp=5997d3667e292183bef734bd0d5380d99b56c47e;hpb=43b767f6bb1209a7577f48bb4a9485352d5240a8;p=dpdk.git diff --git a/doc/guides/tools/testbbdev.rst b/doc/guides/tools/testbbdev.rst index 5997d3667e..7e95696609 100644 --- a/doc/guides/tools/testbbdev.rst +++ b/doc/guides/tools/testbbdev.rst @@ -21,7 +21,7 @@ The bbdevice drivers PMD which should be tested can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_=y`` -Setting example for (*turbo_sw*) PMD +Setting example for (*baseband_turbo_sw*) PMD ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y`` @@ -62,7 +62,7 @@ The following are the command-line options: ``-e EAL_PARAMS, --eal_params EAL_PARAMS`` Specifies EAL arguments which are passed to the test app. For more details, - refer to DPDK documentation at http://dpdk.org/doc. + refer to DPDK documentation at :doc:`../linux_gsg/linux_eal_parameters`. ``-t TIMEOUT, --timeout TIMEOUT`` Specifies timeout in seconds. If not specified timeout is set to 300 seconds. @@ -70,30 +70,6 @@ The following are the command-line options: ``-c TEST_CASE [TEST_CASE ...], --test_cases TEST_CASE [TEST_CASE ...]`` Defines test cases to run. If not specified all available tests are run. - The following tests can be run: - - * unittest - Small unit tests witch check basic functionality of bbdev library. - * latency - Test calculates three latency metrics: - - * offload_latency_tc - measures the cost of offloading enqueue and dequeue operations. - * offload_latency_empty_q_tc - measures the cost of offloading a dequeue operation from an empty queue. - checks how long last dequeueing if there is no operations to dequeue - * operation_latency_tc - measures the time difference from the first attempt to enqueue till the - first successful dequeue. - * validation - Test do enqueue on given vector and compare output after dequeueing. - * throughput - Test measures the achieved throughput on the available lcores. - Results are printed in million operations per second and million bits per second. - * interrupt - The same test as 'throughput' but uses interrupts instead of PMD to perform - the dequeue. - **Example usage:** ``./test-bbdev.py -c validation`` @@ -130,8 +106,54 @@ The following are the command-line options: Specifies operations enqueue/dequeue burst size. If not specified burst_size is set to 32. Maximum is 512. - -Parameter globbing +Test Cases +~~~~~~~~~~ + +There are 6 main test cases that can be executed using testbbdev tool: + +* Sanity checks [-c unittest] + - Performs sanity checks on BBDEV interface, validating basic functionality + +* Validation tests [-c validation] + - Performs full operation of enqueue and dequeue + - Compares the dequeued data buffer with a expected values in the test + vector (TV) being used + - Fails if any dequeued value does not match the data in the TV + +* Offload Cost measurement [-c offload] + - Measures the CPU cycles consumed from the receipt of a user enqueue + until it is put on the device queue + - The test measures 4 metrics + (a) *SW Enq Offload Cost*: Software only enqueue offload cost, the cycle + counts and time (us) from the point the enqueue API is called until + the point the operation is put on the accelerator queue. + (b) *Acc Enq Offload Cost*: The cycle count and time (us) from the + point the operation is put on the accelerator queue until the return + from enqueue. + (c) *SW Deq Offload Cost*: Software dequeue cost, the cycle counts and + time (us) consumed to dequeue one operation. + (d) *Empty Queue Enq Offload Cost*: The cycle count and time (us) + consumed to dequeue from an empty queue. + +* Latency measurement [-c latency] + - Measures the time consumed from the first enqueue until the first + appearance of a dequeued result + - This measurement represents the full latency of a bbdev operation + (encode or decode) to execute + +* Poll-mode Throughput measurement [-c throughput] + - Performs full operation of enqueue and dequeue + - Executes in poll mode + - Measures the achieved throughput on a subset or all available CPU cores + - Dequeued data is not validated against expected values stored in TV + - Results are printed in million operations per second and million bits + per second + +* Interrupt-mode Throughput [-c interrupt] + - Similar to Throughput test case, but using interrupts. No polling. + + +Parameter Globbing ~~~~~~~~~~~~~~~~~~ Thanks to the globbing functionality in python test-bbdev.py script allows to @@ -204,7 +226,7 @@ Running Tests ------------- Shortened tree of isg_cid-wireless_dpdk_ae with dpdk compiled for -x86_64-native-linuxapp-icc target: +x86_64-native-linux-icc target: :: @@ -233,7 +255,7 @@ x86_64-native-linuxapp-icc target: |-- turbo_enc_c1_k40_r0_e1194_rm.data |-- turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data - |-- x86_64-native-linuxapp-icc + |-- x86_64-native-linux-icc |-- app |-- testbbdev @@ -242,28 +264,28 @@ All bbdev devices .. code-block:: console - ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev + ./test-bbdev.py -p ../../x86_64-native-linux-icc/app/testbbdev -v turbo_dec_default.data It runs all available tests using the test vector filled based on *turbo_dec_default.data* file. By default number of operations to process on device is set to 32, timeout is set to 300s and operations enqueue/dequeue burst size is set to 32. -Moreover a bbdev (*bbdev_null*) device will be created. +Moreover a bbdev (*baseband_null*) device will be created. -bbdev turbo_sw device -~~~~~~~~~~~~~~~~~~~~~ +baseband turbo_sw device +~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: console - ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev - -e="--vdev=turbo_sw" -t 120 -c validation + ./test-bbdev.py -p ../../x86_64-native-linux-icc/app/testbbdev + -e="--vdev=baseband_turbo_sw" -t 120 -c validation -v ./test_vectors/turbo_* -n 64 -b 8 32 It runs **validation** test for each vector file that matches the given pattern. Number of operations to process on device is set to 64 and operations timeout is set to 120s and enqueue/dequeue burst size is set to 8 and to 32. -Moreover a bbdev (*turbo_sw*) device will be created. +Moreover a bbdev (*baseband_turbo_sw*) device will be created. bbdev null device @@ -274,17 +296,17 @@ overhead introduced by the bbdev framework. .. code-block:: console - ./test-bbdev.py -e="--vdev=bbdev_null0" + ./test-bbdev.py -e="--vdev=baseband_null0" -v ./test_vectors/bbdev_null.data **Note:** -bbdev_null device does not have to be defined explicitly as it is created by default. +baseband_null device does not have to be defined explicitly as it is created by default. Test Vector files -================= +----------------- Test Vector files contain the data which is used to set turbo decoder/encoder parameters and buffers for validation purpose. New test vector files should be @@ -293,7 +315,7 @@ the syntax of the test vector files is in the following section. Basic principles for test vector files --------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Line started with ``#`` is treated as a comment and is ignored. If variable is a chain of values, values should be separated by a comma. If @@ -328,7 +350,7 @@ documented in *rte_bbdev_op.h* Turbo decoder test vectors template ------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For turbo decoder it has to be always set to ``RTE_BBDEV_OP_TURBO_DEC`` @@ -505,7 +527,7 @@ Following statuses can be used: Turbo encoder test vectors template ------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For turbo encoder it has to be always set to ``RTE_BBDEV_OP_TURBO_ENC``