From ca33590b6af032bff57d9cc70455660466a654b2 Mon Sep 17 00:00:00 2001 From: Luca Boccassi Date: Mon, 19 Feb 2018 11:16:57 +0000 Subject: New upstream version 18.02 Change-Id: I89ed24cb2a49b78fe5be6970b99dd46c1499fcc3 Signed-off-by: Luca Boccassi --- doc/guides/tools/cryptoperf.rst | 45 +- doc/guides/tools/img/eventdev_order_atq_test.svg | 34 +- doc/guides/tools/img/eventdev_order_queue_test.svg | 34 +- doc/guides/tools/img/eventdev_perf_atq_test.svg | 34 +- doc/guides/tools/img/eventdev_perf_queue_test.svg | 34 +- .../img/eventdev_pipeline_atq_test_generic.svg | 3263 +++++++++++++++++ .../img/eventdev_pipeline_atq_test_lockfree.svg | 3344 +++++++++++++++++ .../img/eventdev_pipeline_queue_test_generic.svg | 3548 ++++++++++++++++++ .../img/eventdev_pipeline_queue_test_lockfree.svg | 3826 ++++++++++++++++++++ doc/guides/tools/index.rst | 1 + doc/guides/tools/pdump.rst | 31 +- doc/guides/tools/proc_info.rst | 47 +- doc/guides/tools/testbbdev.rst | 540 +++ doc/guides/tools/testeventdev.rst | 237 +- 14 files changed, 14773 insertions(+), 245 deletions(-) create mode 100644 doc/guides/tools/img/eventdev_pipeline_atq_test_generic.svg create mode 100644 doc/guides/tools/img/eventdev_pipeline_atq_test_lockfree.svg create mode 100644 doc/guides/tools/img/eventdev_pipeline_queue_test_generic.svg create mode 100644 doc/guides/tools/img/eventdev_pipeline_queue_test_lockfree.svg create mode 100644 doc/guides/tools/testbbdev.rst (limited to 'doc/guides/tools') diff --git a/doc/guides/tools/cryptoperf.rst b/doc/guides/tools/cryptoperf.rst index 7e126770..3c0e7d94 100644 --- a/doc/guides/tools/cryptoperf.rst +++ b/doc/guides/tools/cryptoperf.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2016 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016 Intel Corporation. dpdk-test-crypto-perf Application ================================= @@ -171,6 +144,20 @@ The following are the appication command-line options: is the maximum size (i.e. ``--buffer-sz 16:2:32``) * List of values, up to 32 values, separated in commas (i.e. ``--buffer-sz 32,64,128``) +* ``--imix `` + + Set the distribution of packet sizes. + + A list of weights must be passed, containing the same number of items than buffer-sz, + so each item in this list will be the weight of the packet size on the same position + in the buffer-sz parameter (a list have to be passed in that parameter). + + Example: + + To test a distribution of 20% packets of 64 bytes, 40% packets of 100 bytes and 40% packets + of 256 bytes, the command line would be: ``--buffer-sz 64,100,256 --imix 20,40,40``. + Note that the weights do not have to be percentages, so using ``--imix 1,2,2`` would result + in the same distribution * ``--segment-sz `` diff --git a/doc/guides/tools/img/eventdev_order_atq_test.svg b/doc/guides/tools/img/eventdev_order_atq_test.svg index a36eafa7..5acd8ea3 100644 --- a/doc/guides/tools/img/eventdev_order_atq_test.svg +++ b/doc/guides/tools/img/eventdev_order_atq_test.svg @@ -2,39 +2,9 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + +   + + + + worker 0 + worker 1 + worker n + port 0 + port 1 + port n + + producer 0 + + q0 + + port n+2 + + test: pipeline_atq + + producer 1 + qs + + port n+3 + + + producer m-1 + q2s + + port n+m + + + + + total queues = number of ethernet dev + 1 + All workers are linked to all stage queues + eth port 1 Rxq 0 + eth port q Rxq 0 + eth port 0 Rxq 0 + + + + eth port 1 Txq 0 + + + + eth port 0 Txq 0 + + + + eth port q Txq 0 + + Event ethRx adptr 0 + Event ethRx adptr 1 + Event ethRx adptr q + + + Tx Serviceport n + 1 + + + + + + + + + + + Single Link Q + + + + (Tx Generic) + + diff --git a/doc/guides/tools/img/eventdev_pipeline_atq_test_lockfree.svg b/doc/guides/tools/img/eventdev_pipeline_atq_test_lockfree.svg new file mode 100644 index 00000000..d7f10de3 --- /dev/null +++ b/doc/guides/tools/img/eventdev_pipeline_atq_test_lockfree.svg @@ -0,0 +1,3344 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + +   + + + + worker 0 + worker 1 + worker n + port 0 + port 1 + port n + + producer 0 + + q0 + + port n+1 + + test: pipeline_atq + + producer 1 + qs + + port n+2 + + + producer m-1 + q2s + + port n+m + + + + + total queues = number of ethernet dev + All workers are linked to all queues + eth port 1 Rxq 0 + eth port q Rxq 0 + eth port 0 Rxq 0 + + + + eth port 1 Txq 0 + + + + eth port 0 Txq 0 + + + + eth port q Txq 0 + + Event ethRx adptr 0 + Event ethRx adptr 1 + Event ethRx adptr q + + + + + + + + + + + + + + (Tx Lock free) + + diff --git a/doc/guides/tools/img/eventdev_pipeline_queue_test_generic.svg b/doc/guides/tools/img/eventdev_pipeline_queue_test_generic.svg new file mode 100644 index 00000000..732d4886 --- /dev/null +++ b/doc/guides/tools/img/eventdev_pipeline_queue_test_generic.svg @@ -0,0 +1,3548 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + producer 0 + + q0 + q1 + qs-1 + + port n+2 + + + test: pipeline_queue + + + + producer 1 + qs + qs+1 + q2s-1 + + port n+3 + + + + + + + producer m-1 + q2s + q2s+1 + q3s-1 + + port n+m + + + + + + total queues = (number of stages * number of ethernet dev) + 1 + All workers are linked to all stage queues + eth port 1 Rxq 0 + eth port q Rxq 0 + eth port 0 Rxq 0 + Event ethRx adptr 0 + Event ethRx adptr 1 + Event ethRx adptr q + + + + worker 0 + worker 1 + worker n + port 0 + port 1 + port n + + + eth port 1 Txq 0 + + + + eth port 0 Txq 0 + + + + eth port q Txq 0 + + + + Tx Serviceport n + 1 + + + + + + SingleLink Q + + + + + + + + (Tx Generic) + + diff --git a/doc/guides/tools/img/eventdev_pipeline_queue_test_lockfree.svg b/doc/guides/tools/img/eventdev_pipeline_queue_test_lockfree.svg new file mode 100644 index 00000000..c0a365c7 --- /dev/null +++ b/doc/guides/tools/img/eventdev_pipeline_queue_test_lockfree.svg @@ -0,0 +1,3826 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + producer 0 + + q0 + q1 + qs-2 + + port n+1 + + + test: pipeline_queue + + + + producer 1 + qs + qs+1 + q2s-2 + + port n+2 + + + + + + + producer m-1 + q2s + q2s+1 + q3s-2 + + port n+m + + + + + + total queues = (number of stages * number of ethernet dev) + number of ethernet dev + eth port 1 Rxq 0 + eth port q Rxq 0 + eth port 0 Rxq 0 + Event ethRx adptr 0 + Event ethRx adptr 1 + Event ethRx adptr q + + + + worker 0 + worker 1 + worker n + port 0 + port 1 + port n + + + eth port 1 Txq 0 + + + + eth port 0 Txq 0 + + + + eth port q Txq 0 + + + + + + + + + + + + + + qs-1 + q2s-1 + q3s-1 + Atomic Q + Atomic Q + Atomic Q + Stage0 Q + Stage1 Q + Stage2 Q + + + + + + + (Tx Lock free) + All workers are linked to all queues + + diff --git a/doc/guides/tools/index.rst b/doc/guides/tools/index.rst index c9133ec8..a6e2c4c7 100644 --- a/doc/guides/tools/index.rst +++ b/doc/guides/tools/index.rst @@ -39,5 +39,6 @@ DPDK Tools User Guides pdump pmdinfo devbind + testbbdev cryptoperf testeventdev diff --git a/doc/guides/tools/pdump.rst b/doc/guides/tools/pdump.rst index 16502f7a..5168c81a 100644 --- a/doc/guides/tools/pdump.rst +++ b/doc/guides/tools/pdump.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2016 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016 Intel Corporation. .. _pdump_tool: diff --git a/doc/guides/tools/proc_info.rst b/doc/guides/tools/proc_info.rst index fd17e278..d5b5ed6a 100644 --- a/doc/guides/tools/proc_info.rst +++ b/doc/guides/tools/proc_info.rst @@ -1,33 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2015 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2015 Intel Corporation. dpdk-procinfo Application ========================= @@ -68,3 +40,18 @@ The xstats-reset parameter controls the resetting of extended port statistics. If no port mask is specified xstats are reset for all DPDK ports. **-m**: Print DPDK memory information. + +Limitations +----------- + +* dpdk-procinfo should run alongside primary process with same DPDK version. + +* When running ``dpdk-procinfo`` with shared library mode, it is required to + pass the same NIC PMD libraries as used for the primary application. Any + mismatch in PMD library arguments can lead to undefined behaviour and results + affecting primary application too. + +* Stats retrieval using ``dpdk-procinfo`` is not supported for virtual devices like PCAP and TAP. + +* Since default DPDK EAL arguments for ``dpdk-procinfo`` are ``-c1, -n4 & --proc-type=secondary``, + It is not expected that the user passes any EAL arguments. diff --git a/doc/guides/tools/testbbdev.rst b/doc/guides/tools/testbbdev.rst new file mode 100644 index 00000000..5c7112de --- /dev/null +++ b/doc/guides/tools/testbbdev.rst @@ -0,0 +1,540 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017 Intel Corporation + +dpdk-test-bbdev Application +=========================== + +The ``dpdk-test-bbdev`` tool is a Data Plane Development Kit (DPDK) utility that +allows measuring performance parameters of PMDs available in the bbdev framework. +Available tests available for execution are: latency, throughput, validation and +sanity tests. Execution of tests can be customized using various parameters +passed to a python running script. + +Compiling the Application +------------------------- + +**Step 1: PMD setting** + +The ``dpdk-test-bbdev`` tool depends on crypto device drivers PMD which +are disabled by default in the build configuration file ``common_base``. +The bbdevice drivers PMD which should be tested can be enabled by setting + + ``CONFIG_RTE_LIBRTE_PMD_=y`` + +Setting example for (*turbo_sw*) PMD + + ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y`` + +**Step 2: Build the application** + +Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the +``dpdk-test-bbdev`` application. + +Initially, the user must select a DPDK target to choose the correct target type +and compiler options to use when building the libraries. +The user must have all libraries, modules, updates and compilers installed +in the system prior to this, as described in the earlier chapters in this +Getting Started Guide. + +Running the Application +----------------------- + +The tool application has a number of command line options: + +.. code-block:: console + + python test-bbdev.py [-h] [-p TESTAPP_PATH] [-e EAL_PARAMS] [-t TIMEOUT] + [-c TEST_CASE [TEST_CASE ...]] + [-v TEST_VECTOR [TEST_VECTOR...]] [-n NUM_OPS] + [-b BURST_SIZE [BURST_SIZE ...]] [-l NUM_LCORES] + +command-line Options +~~~~~~~~~~~~~~~~~~~~ + +The following are the command-line options: + +``-h, --help`` + Shows help message and exit. + +``-p TESTAPP_PATH, --testapp_path TESTAPP_PATH`` + Indicates the path to the bbdev test app. If not specified path is set based + on *$RTE_SDK* environment variable concatenated with "*/build/app/testbbdev*". + +``-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. + +``-t TIMEOUT, --timeout TIMEOUT`` + Specifies timeout in seconds. If not specified timeout is set to 300 seconds. + +``-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`` + Runs validation test suite + + ``./test-bbdev.py -c latency throughput`` + Runs latency and throughput test suites + +``-v TEST_VECTOR [TEST_VECTOR ...], --test_vector TEST_VECTOR [TEST_VECTOR ...]`` + Specifies paths to the test vector files. If not specified path is set based + on *$RTE_SDK* environment variable concatenated with + "*/app/test-bbdev/test_vectors/bbdev_vector_null.data*" and indicates default + data file. + + **Example usage:** + + ``./test-bbdev.py -v app/test-bbdev/test_vectors/bbdev_vector_td_test1.data`` + Fills vector based on bbdev_vector_td_test1.data file and runs all tests + + ``./test-bbdev.py -v bbdev_vector_td_test1.data bbdev_vector_te_test2.data`` + The bbdev test app is executed twice. First time vector is filled based on + *bbdev_vector_td_test1.data* file and second time based on + *bbdev_vector_te_test2.data* file. For both executions all tests are run. + +``-n NUM_OPS, --num_ops NUM_OPS`` + Specifies number of operations to process on device. If not specified num_ops + is set to 32 operations. + +``-l NUM_LCORES, --num_lcores NUM_LCORES`` + Specifies number of lcores to run. If not specified num_lcores is set + according to value from RTE configuration (EAL coremask) + +``-b BURST_SIZE [BURST_SIZE ...], --burst-size BURST_SIZE [BURST_SIZE ...]`` + Specifies operations enqueue/dequeue burst size. If not specified burst_size is + set to 32. Maximum is 512. + + +Parameter globbing +~~~~~~~~~~~~~~~~~~ + +Thanks to the globbing functionality in python test-bbdev.py script allows to +run tests with different set of vector files without giving all of them explicitly. + +**Example usage:** + +.. code-block:: console + + ./test-bbdev.py -v app/test-bbdev/test_vectors/bbdev_vector_*.data + +It runs all tests with following vectors: + +- ``bbdev_vector_null.data`` + +- ``bbdev_vector_td_default.data`` + +- ``bbdev_vector_te_default.data`` + + +.. code-block:: console + + ./test-bbdev.py -v app/test-bbdev/test_vectors/bbdev_vector_t?_default.data + +It runs all tests with "default" vectors: + +- ``bbdev_vector_te_default.data`` + +- ``bbdev_vector_td_default.data`` + + +Running Tests +------------- + +Shortened tree of isg_cid-wireless_dpdk_ae with dpdk compiled for +x86_64-native-linuxapp-icc target: + +:: + + |-- app + |-- test-bbdev + |-- test_vectors + |-- bbdev_vector_null.data + |-- bbdev_vector_td_default.data + |-- bbdev_vector_te_default.data + + |-- x86_64-native-linuxapp-icc + |-- app + |-- testbbdev + +All bbdev devices +~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev + -v ./test_vectors/bbdev_vector_td_default.data + +It runs all available tests using the test vector filled based on +*bbdev_vector_td_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. + +bbdev 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 + -v ./test_vectors/bbdev_vector_t?_default.data -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. + + +bbdev null device +~~~~~~~~~~~~~~~~~ + +Executing bbdev null device with *bbdev_vector_null.data* helps in measuring the +overhead introduced by the bbdev framework. + +.. code-block:: console + + ./test-bbdev.py -e="--vdev=bbdev_null0" + -v ./test_vectors/bbdev_vector_null.data + +**Note:** + +bbdev_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 +stored in ``app/test-bbdev/test_vectors/`` directory. Detailed description of +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 +assignment is split into several lines, each line (except the last one) has to +be ended with a comma. +There is no comma after last value in last line. Correct assignment should +look like the following: + +.. parsed-literal:: + + variable = + value, value, value, value, + value, value + +In case where variable is a single value correct assignment looks like the +following: + +.. parsed-literal:: + + variable = + value + +Length of chain variable is calculated by parser. Can not be defined +explicitly. + +Variable op_type has to be defined as a first variable in file. It specifies +what type of operations will be executed. For decoder op_type has to be set to +``RTE_BBDEV_OP_TURBO_DEC`` and for encoder to ``RTE_BBDEV_OP_TURBO_ENC``. + +Full details of the meaning and valid values for the below fields are +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`` + +.. parsed-literal:: + + op_type = + RTE_BBDEV_OP_TURBO_DEC + +Chain of uint32_t values. Note that it is possible to define more than one +input/output entries which will result in chaining two or more data structures +for *segmented Transport Blocks* + +.. parsed-literal:: + + input0 = + 0x00000000, 0x7f817f00, 0x7f7f8100, 0x817f8100, 0x81008100, 0x7f818100, 0x81817f00, 0x7f818100, + 0x81007f00, 0x7f818100, 0x817f8100, 0x81817f00, 0x81008100, 0x817f7f00, 0x7f7f8100, 0x81817f00 + +Chain of uint32_t values + +.. parsed-literal:: + + input1 = + 0x7f7f0000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, + 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000 + +Chain of uint32_t values + +.. parsed-literal:: + + input2 = + 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, + 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000 + +Chain of uint32_t values + +.. parsed-literal:: + + hard_output0 = + 0xa7d6732e + +Chain of uint32_t values + +.. parsed-literal:: + + hard_output1 = + 0xa61 + +Chain of uint32_t values + +.. parsed-literal:: + + soft_output0 = + 0x817f817f, 0x7f817f7f, 0x81818181, 0x817f7f81, 0x7f818181, 0x8181817f, 0x817f817f, 0x8181817f + +Chain of uint32_t values + +.. parsed-literal:: + + soft_output1 = + 0x817f7f81, 0x7f7f7f81, 0x7f7f8181 + +uint32_t value + +.. parsed-literal:: + + e = + 44 + +uint16_t value + +.. parsed-literal:: + + k = + 40 + +uint8_t value + +.. parsed-literal:: + + rv_index = + 0 + +uint8_t value + +.. parsed-literal:: + + iter_max = + 8 + +uint8_t value + +.. parsed-literal:: + + iter_min = + 4 + +uint8_t value + +.. parsed-literal:: + + expected_iter_count = + 8 + +uint8_t value + +.. parsed-literal:: + + ext_scale = + 15 + +uint8_t value + +.. parsed-literal:: + + num_maps = + 0 + +Chain of flags for turbo decoder operation. Following flags can be used: + +- ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` + +- ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` + +- ``RTE_BBDEV_TURBO_EQUALIZER`` + +- ``RTE_BBDEV_TURBO_SOFT_OUT_SATURATE`` + +- ``RTE_BBDEV_TURBO_HALF_ITERATION_EVEN`` + +- ``RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH`` + +- ``RTE_BBDEV_TURBO_SOFT_OUTPUT`` + +- ``RTE_BBDEV_TURBO_EARLY_TERMINATION`` + +- ``RTE_BBDEV_TURBO_DEC_INTERRUPTS`` + +- ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN`` + +- ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` + +- ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT`` + +- ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT`` + +- ``RTE_BBDEV_TURBO_MAP_DEC`` + +Example: + + .. parsed-literal:: + + op_flags = + RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE, RTE_BBDEV_TURBO_EQUALIZER, + RTE_BBDEV_TURBO_SOFT_OUTPUT + +Chain of operation statuses that are expected after operation is performed. +Following statuses can be used: + +- ``DMA`` + +- ``FCW`` + +- ``CRC`` + +- ``OK`` + +``OK`` means no errors are expected. Cannot be used with other values. + +.. parsed-literal:: + + expected_status = + FCW, CRC + + +Turbo encoder test vectors template +----------------------------------- + +For turbo encoder it has to be always set to ``RTE_BBDEV_OP_TURBO_ENC`` + +.. parsed-literal:: + + op_type = + RTE_BBDEV_OP_TURBO_ENC + +Chain of uint32_t values + +.. parsed-literal:: + + input0 = + 0x11d2bcac, 0x4d + +Chain of uint32_t values + +.. parsed-literal:: + + output0 = + 0xd2399179, 0x640eb999, 0x2cbaf577, 0xaf224ae2, 0x9d139927, 0xe6909b29, + 0xa25b7f47, 0x2aa224ce, 0x79f2 + +uint32_t value + +.. parsed-literal:: + + e = + 272 + +uint16_t value + +.. parsed-literal:: + + k = + 40 + +uint16_t value + +.. parsed-literal:: + + ncb = + 192 + +uint8_t value + +.. parsed-literal:: + + rv_index = + 0 + +Chain of flags for turbo encoder operation. Following flags can be used: + +- ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS`` + +- ``RTE_BBDEV_TURBO_RATE_MATCH`` + +- ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` + +- ``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` + +- ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` + +``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` is used to indicate the parser to +force the input data to be memory split and formed as a segmented mbuf. + + +.. parsed-literal:: + + op_flags = + RTE_BBDEV_TURBO_RATE_MATCH + +Chain of operation statuses that are expected after operation is performed. +Following statuses can be used: + +- ``DMA`` + +- ``FCW`` + +- ``OK`` + +``OK`` means no errors are expected. Cannot be used with other values. + +.. parsed-literal:: + + expected_status = + OK diff --git a/doc/guides/tools/testeventdev.rst b/doc/guides/tools/testeventdev.rst index 5aa2237b..77480ffe 100644 --- a/doc/guides/tools/testeventdev.rst +++ b/doc/guides/tools/testeventdev.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2017 Cavium, Inc. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Cavium, Inc nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017 Cavium, Inc dpdk-test-eventdev Application ============================== @@ -146,6 +119,9 @@ The following are the application command-line options: Enable queue priority. +* ``--prod_type_ethdev`` + + Use ethernet device as producer. Eventdev Tests -------------- @@ -348,6 +324,10 @@ the timestamp in the event on the first stage and then on termination, it updates the number of cycles to forward a packet. The application uses this value to compute the average latency to a forward packet. +When ``--prod_type_ethdev`` command line option is selected, the application +uses the probed ethernet devices as producers by configuring them as Rx +adapters instead of using synthetic producers. + Application options ^^^^^^^^^^^^^^^^^^^ @@ -366,6 +346,7 @@ Supported application command line options are following:: --worker_deq_depth --fwd_latency --queue_priority + --prod_type_ethdev Example ^^^^^^^ @@ -377,6 +358,12 @@ Example command to run perf queue test: sudo build/app/dpdk-test-eventdev -c 0xf -s 0x1 --vdev=event_sw0 -- \ --test=perf_queue --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0 +Example command to run perf queue test with ethernet ports: + +.. code-block:: console + + sudo build/app/dpdk-test-eventdev --vdev=event_sw0 -- \ + --test=perf_queue --plcores=2 --wlcore=3 --stlist=p --prod_type_ethdev PERF_ATQ Test ~~~~~~~~~~~~~~~ @@ -443,6 +430,7 @@ Supported application command line options are following:: --nb_pkts --worker_deq_depth --fwd_latency + --prod_type_ethdev Example ^^^^^^^ @@ -453,3 +441,194 @@ Example command to run perf ``all types queue`` test: sudo build/app/dpdk-test-eventdev --vdev=event_octeontx -- \ --test=perf_atq --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0 + + +PIPELINE_QUEUE Test +~~~~~~~~~~~~~~~~~~~ + +This is a pipeline test case that aims at testing the following: + +#. Measure the end-to-end performance of an event dev with a ethernet dev. +#. Maintain packet ordering from Rx to Tx. + +.. _table_eventdev_pipeline_queue_test: + +.. table:: Pipeline queue test eventdev configuration. + + +---+--------------+----------------+-----------------------------------------+ + | # | Items | Value | Comments | + | | | | | + +===+==============+================+=========================================+ + | 1 | nb_queues | (nb_producers | Queues will be configured based on the | + | | | * nb_stages) + | user requested sched type list(--stlist)| + | | | x | Here value of x is 1 in generic pipeline| + | | | | and nb_producers in lockfree pipeline | + +---+--------------+----------------+-----------------------------------------+ + | 2 | nb_producers | >= 1 | Producers will be configured based on | + | | | | the number of detected ethernet devices.| + | | | | Each ethdev will be configured as an Rx | + | | | | adapter. | + +---+--------------+----------------+-----------------------------------------+ + | 3 | nb_workers | >= 1 | Selected through --wlcores command line | + | | | | argument | + +---+--------------+----------------+-----------------------------------------+ + | 4 | nb_ports | nb_workers + | Workers use port 0 to port n. | + | | | nb_producers | Producers use port n+1 to port n+m, | + | | | | depending on the Rx adapter capability. | + +---+--------------+----------------+-----------------------------------------+ + +.. _figure_eventdev_pipeline_queue_test_generic: + +.. figure:: img/eventdev_pipeline_queue_test_generic.* + +.. _figure_eventdev_pipeline_queue_test_lockfree: + +.. figure:: img/eventdev_pipeline_queue_test_lockfree.* + + pipeline queue test operation. + +The pipeline queue test configures the eventdev with Q queues and P ports, +where Q and P is a function of the number of workers, the number of producers +and number of stages as mentioned in :numref:`table_eventdev_pipeline_queue_test`. + +The user can choose the number of workers and number of stages through the +``--wlcores`` and the ``--stlist`` application command line arguments +respectively. + +The number of producers depends on the number of ethernet devices detected and +each ethernet device is configured as a event_eth_rx_adapter that acts as a +producer. + +The producer(s) injects the events to eventdev based the first stage sched type +list requested by the user through ``--stlist`` the command line argument. + +Based on the number of stages to process(selected through ``--stlist``), +The application forwards the event to next upstream queue and when it reaches +the last stage in the pipeline if the event type is ``atomic`` it is enqueued +onto ethdev Tx queue else to maintain ordering the event type is set to +``atomic`` and enqueued onto the last stage queue. + +If the ethernet has ``DEV_TX_OFFLOAD_MT_LOCKFREE`` capability then the worker +cores transmit the packets directly. Else the worker cores enqueue the packet +onto the ``SINGLE_LINK_QUEUE`` that is managed by a Tx service. The Tx service +dequeues the packet and transmits it. + +On packet Tx, application increments the number events processed and print +periodically in one second to get the number of events processed in one +second. + + +Application options +^^^^^^^^^^^^^^^^^^^ + +Supported application command line options are following:: + + --verbose + --dev + --test + --socket_id + --pool_sz + --wlcores + --stlist + --worker_deq_depth + --prod_type_ethdev + + +.. Note:: + + * The ``--prod_type_ethdev`` is mandatory for running this test. + +Example +^^^^^^^ + +Example command to run pipeline queue test: + +.. code-block:: console + + sudo build/app/dpdk-test-eventdev -c 0xf -s 0x8 --vdev=event_sw0 -- \ + --test=pipeline_queue --wlcore=1 --prod_type_ethdev --stlist=a + + +PIPELINE_ATQ Test +~~~~~~~~~~~~~~~~~~~ + +This is a pipeline test case that aims at testing the following with +``all types queue`` eventdev scheme. + +#. Measure the end-to-end performance of an event dev with a ethernet dev. +#. Maintain packet ordering from Rx to Tx. + +.. _table_eventdev_pipeline_atq_test: + +.. table:: Pipeline atq test eventdev configuration. + + +---+--------------+----------------+-----------------------------------------+ + | # | Items | Value | Comments | + | | | | | + +===+==============+================+=========================================+ + | 1 | nb_queues | nb_producers + | Queues will be configured based on the | + | | | x | user requested sched type list(--stlist)| + | | | | where x = 1 in generic pipeline and 0 | + | | | | in lockfree pipeline | + +---+--------------+----------------+-----------------------------------------+ + | 2 | nb_producers | >= 1 | Producers will be configured based on | + | | | | the number of detected ethernet devices.| + | | | | Each ethdev will be configured as an Rx | + | | | | adapter. | + +---+--------------+----------------+-----------------------------------------+ + | 3 | nb_workers | >= 1 | Selected through --wlcores command line | + | | | | argument | + +---+--------------+----------------+-----------------------------------------+ + | 4 | nb_ports | nb_workers + | Workers use port 0 to port n. | + | | | nb_producers | Producers use port n+1 to port n+m, | + | | | | depending on the Rx adapter capability. | + +---+--------------+----------------+-----------------------------------------+ + +.. _figure_eventdev_pipeline_atq_test_generic: + +.. figure:: img/eventdev_pipeline_atq_test_generic.* + +.. _figure_eventdev_pipeline_atq_test_lockfree: + +.. figure:: img/eventdev_pipeline_atq_test_lockfree.* + + pipeline atq test operation. + +The pipeline atq test configures the eventdev with Q queues and P ports, +where Q and P is a function of the number of workers, the number of producers +and number of stages as mentioned in :numref:`table_eventdev_pipeline_atq_test`. + +The atq queue test functions as same as ``pipeline_queue`` test. The difference +is, It uses, ``all type queue scheme`` instead of separate queues for each +stage and thus reduces the number of queues required to realize the use case. + + +Application options +^^^^^^^^^^^^^^^^^^^ + +Supported application command line options are following:: + + --verbose + --dev + --test + --socket_id + --pool_sz + --wlcores + --stlist + --worker_deq_depth + --prod_type_ethdev + + +.. Note:: + + * The ``--prod_type_ethdev`` is mandatory for running this test. + +Example +^^^^^^^ + +Example command to run pipeline queue test: + +.. code-block:: console + + sudo build/app/dpdk-test-eventdev -c 0xf -s 0x8 --vdev=event_sw0 -- \ + --test=pipeline_atq --wlcore=1 --prod_type_ethdev --stlist=a -- cgit 1.2.3-korg