> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Amr Mokhtar
> Sent: Thursday, December 7, 2017 9:41 PM
> To: dev@dpdk.org
> Cc: thomas@monjalon.net; Burakov, Anatoly <anatoly.burakov@intel.com>; De
> Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>; Power, Niall
> <niall.power@intel.com>; Macnamara, Chris <chris.macnamara@intel.com>;
> Mokhtar, Amr <amr.mokhtar@intel.com>
> Subject: [dpdk-dev] [PATCH v3 5/5] bbdev: documentation
>
> - Wireless Baseband Device Library Programmer’s Guide
> - test-bbdev User Guide
> - BBDEV Sample Application User Guides
> - Baseband Device Drivers Guides
> - Doxygen API
>
> Signed-off-by: Amr Mokhtar <amr.mokhtar@intel.com>
> ---
> doc/api/doxy-api-index.md | 1 +
> doc/api/doxy-api.conf | 1 +
> doc/guides/bbdevs/index.rst | 40 +++
> doc/guides/bbdevs/null.rst | 77 +++++
> doc/guides/bbdevs/turbo_sw.rst | 175 ++++++++++
> doc/guides/index.rst | 1 +
> doc/guides/prog_guide/bbdev.rst | 613
> +++++++++++++++++++++++++++++++++
> doc/guides/prog_guide/index.rst | 1 +
> doc/guides/sample_app_ug/bbdev_app.rst | 160 +++++++++
> doc/guides/sample_app_ug/index.rst | 1 +
> doc/guides/tools/index.rst | 1 +
> doc/guides/tools/testbbdev.rst | 600
> ++++++++++++++++++++++++++++++++
> 12 files changed, 1671 insertions(+)
> create mode 100644 doc/guides/bbdevs/index.rst
> create mode 100644 doc/guides/bbdevs/null.rst
> create mode 100644 doc/guides/bbdevs/turbo_sw.rst
> create mode 100644 doc/guides/prog_guide/bbdev.rst
> create mode 100644 doc/guides/sample_app_ug/bbdev_app.rst
> create mode 100644 doc/guides/tools/testbbdev.rst
>
> diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
> index 3492702..8d7ff89 100644
> --- a/doc/api/doxy-api-index.md
> +++ b/doc/api/doxy-api-index.md
> @@ -50,6 +50,7 @@ The public API headers are grouped by topics:
> [bitrate] (@ref rte_bitrate.h),
> [latency] (@ref rte_latencystats.h),
> [devargs] (@ref rte_devargs.h),
> + [bbdev] (@ref rte_bbdev.h),
> [PCI] (@ref rte_pci.h)
>
> - **device specific**:
> diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf
> index b2cbe94..241cae3 100644
> --- a/doc/api/doxy-api.conf
> +++ b/doc/api/doxy-api.conf
> @@ -39,6 +39,7 @@ INPUT = doc/api/doxy-api-index.md \
> lib/librte_eal/common/include \
> lib/librte_eal/common/include/generic \
> lib/librte_acl \
> + lib/librte_bbdev \
> lib/librte_bitratestats \
> lib/librte_cfgfile \
> lib/librte_cmdline \
> diff --git a/doc/guides/bbdevs/index.rst b/doc/guides/bbdevs/index.rst
> new file mode 100644
> index 0000000..c9aa1b0
> --- /dev/null
> +++ b/doc/guides/bbdevs/index.rst
> @@ -0,0 +1,40 @@
> +..
> + BSD LICENSE
> +
> + Copyright(c) 2017 Intel Corporation. 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.
> +
> +Baseband Device Drivers
> +=======================
> +
> +.. toctree::
> + :maxdepth: 2
> + :numbered:
> +
> + null
> + turbo_sw
> diff --git a/doc/guides/bbdevs/null.rst b/doc/guides/bbdevs/null.rst
> new file mode 100644
> index 0000000..0f40232
> --- /dev/null
> +++ b/doc/guides/bbdevs/null.rst
> @@ -0,0 +1,77 @@
> +..
> + BSD LICENSE
> +
> + Copyright(c) 2017 Intel Corporation. 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.
> +
> +BBDEV null Poll Mode Driver
> +============================
> +
> +The (**bbdev_null**) is a bbdev poll mode driver which provides a minimal
> +implementation of a software bbdev device. As a null device it does not modify
> +the data in the mbuf on which the bbdev operation is to operate and it only
> +works for operation type ``RTE_BBDEV_OP_NONE``.
> +
> +When a burst of mbufs is submitted to a *bbdev null PMD* for processing then
> +each mbuf in the burst will be enqueued in an internal buffer ring to be
> +collected on a dequeue call.
> +
> +
> +Limitations
> +-----------
> +
> +* In-place operations for Turbo encode and decode are not supported
> +
> +Installation
> +------------
> +
> +The *bbdev null PMD* is enabled and built by default in both the Linux and
> +FreeBSD builds.
> +
> +Initialization
> +--------------
> +
> +To use the PMD in an application, user must:
> +
> +- Call ``rte_vdev_init("bbdev_null")`` within the application.
> +
> +- Use ``--vdev="bbdev_null"`` in the EAL options, which will call
> ``rte_vdev_init()`` internally.
> +
> +The following parameters (all optional) can be provided in the previous two
> calls:
> +
> +* ``socket_id``: Specify the socket where the memory for the device is going to
> be allocated
> + (by default, *socket_id* will be the socket where the core that is creating the
> PMD is running on).
> +
> +* ``max_nb_queues``: Specify the maximum number of queues in the device
> (default is ``RTE_MAX_LCORE``).
> +
> +Example:
> +~~~~~~~~
> +
> +.. code-block:: console
> +
> + ./test-bbdev.py -e="--vdev=bbdev_null,socket_id=0,max_nb_queues=8"
> diff --git a/doc/guides/bbdevs/turbo_sw.rst b/doc/guides/bbdevs/turbo_sw.rst
> new file mode 100644
> index 0000000..b34d8a5
> --- /dev/null
> +++ b/doc/guides/bbdevs/turbo_sw.rst
> @@ -0,0 +1,175 @@
> +..
> + BSD LICENSE
> +
> + Copyright(c) 2017 Intel Corporation. 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.
> +
> +SW Turbo Poll Mode Driver
> +=========================
> +
> +The SW Turbo PMD (**turbo_sw**) provides a poll mode bbdev driver that
> utilizes
> +Intel optimized libraries for LTE Layer 1 workloads acceleration. This PMD
> +supports the functions: Turbo FEC, Rate Matching and CRC functions.
> +
> +Features
> +--------
> +
> +SW Turbo PMD has support for the following capabilities:
> +
> +For the encode operation:
> +
> +* ``RTE_BBDEV_TURBO_CRC_24A_ATTACH``
> +* ``RTE_BBDEV_TURBO_CRC_24B_ATTACH``
> +* ``RTE_BBDEV_TURBO_RATE_MATCH``
> +* ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS``
> +
> +For the decode operation:
> +
> +* ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE``
> +* ``RTE_BBDEV_TURBO_CRC_TYPE_24B``
> +* ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN``
> +* ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN``
> +
> +
> +Limitations
> +-----------
> +
> +* In-place operations for Turbo encode and decode are not supported
> +
> +Installation
> +------------
> +
> +FlexRAN SDK Download
> +~~~~~~~~~~~~~~~~~~~~
> +
> +To build DPDK with the *turbo_sw* PMD the user is required to download
> +the export controlled ``FlexRAN SDK`` Libraries. An account at Intel Resource
> +Design Center needs to be registered from
> +`<https://www.intel.com/content/www/us/en/design/resource-design-
> center.html>`_.
> +
> +Once registered, the user needs to log in, and look for
> +*Intel SWA_SW_FlexRAN_Release_Package R1_3_0* and click for download.
> Or use
> +this direct download link
> `<https://cdrd.intel.com/v1/dl/getContent/575367>`_.
> +
> +After download is complete, the user needs to unpack and compile on their
> +system before building DPDK.
> +
> +FlexRAN SDK Installation
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The following are pre-requisites for building FlexRAN SDK Libraries:
> + (a) An AVX2 supporting machine
> + (b) Windriver TS 2 or CentOS 7 operating systems
> + (c) Intel ICC compiler installed
> +
> +The following instructions should be followed in this exact order:
> +
> +#. Set the environment variables:
> +
> + .. code-block:: console
> +
> + source <path-to-icc-compiler-install-folder>/linux/bin/compilervars.sh
> intel64 -platform linux
> +
> +
> +#. Extract the ``FlexRAN-1.3.0.tar.gz.zip`` package, then run the SDK extractor
> + script and accept the license:
> +
> + .. code-block:: console
> +
> + cd <path-to-workspace>/FlexRAN-1.3.0/
> + ./SDK-R1.3.0.sh
> +
> +#. To allow ``FlexRAN SDK R1.3.0`` to work with bbdev properly, the following
> + hotfix is required. Change the return of function
> ``rate_matching_turbo_lte_avx2()``
> + located in file
> + ``<path-to-workspace>/FlexRAN-1.3.0/SDK-
> R1.3.0/sdk/source/phy/lib_rate_matching/phy_rate_match_avx2.cpp``
> + to return 0 instead of 1.
> +
> + .. code-block:: c
> +
> + - return 1;
> + + return 0;
> +
> +#. Generate makefiles based on system configuration:
> +
> + .. code-block:: console
> +
> + cd <path-to-workspace>/FlexRAN-1.3.0/SDK-R1.3.0/sdk/
> + ./create-makefiles-linux.sh
> +
> +#. A build folder is generated in this form ``build-<ISA>-<CC>``, enter that
> + folder and install:
> +
> + .. code-block:: console
> +
> + cd build-avx2-icc/
> + make install
> +
> +
> +Initialization
> +--------------
> +
> +In order to enable this virtual bbdev PMD, the user must:
> +
> +* Build the ``FLEXRAN SDK`` libraries (explained in Installation section).
> +
> +* Export the environmental variables ``FLEXRAN_SDK`` to the path where the
> + FlexRAN SDK libraries were installed. And ``DIR_WIRELESS_SDK`` to the path
> + where the librararies were extracted.
Typo above librararies/ libraries
> +Input and output data buffers are identified by ``rte_bbdev_op_data``
> structure.
> +This strucutre has three elements:
Typo above strucutre / structure
> +Limitations
> +-----------
> +
> +* Although, the baseband sample application is designed to work in full-duplex
> + mode, but due to theplain format of the received packets from pkt-gen, the
> + Turbo decode (uplink) is not operable. Only the Turbo encode direction
> + (downlink) is currently supported in the bbdev sample application.
Small space required theplain/ the plain
> +where, NIC0PCIADDR is the PCI addresse of the Rx port
Typo addresse/ address
> +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 systax of the test vector files is in the following section.
Typo systax/ syntax
Marko Kovacevic
@@ -50,6 +50,7 @@ The public API headers are grouped by topics:
[bitrate] (@ref rte_bitrate.h),
[latency] (@ref rte_latencystats.h),
[devargs] (@ref rte_devargs.h),
+ [bbdev] (@ref rte_bbdev.h),
[PCI] (@ref rte_pci.h)
- **device specific**:
@@ -39,6 +39,7 @@ INPUT = doc/api/doxy-api-index.md \
lib/librte_eal/common/include \
lib/librte_eal/common/include/generic \
lib/librte_acl \
+ lib/librte_bbdev \
lib/librte_bitratestats \
lib/librte_cfgfile \
lib/librte_cmdline \
new file mode 100644
@@ -0,0 +1,40 @@
+..
+ BSD LICENSE
+
+ Copyright(c) 2017 Intel Corporation. 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.
+
+Baseband Device Drivers
+=======================
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ null
+ turbo_sw
new file mode 100644
@@ -0,0 +1,77 @@
+..
+ BSD LICENSE
+
+ Copyright(c) 2017 Intel Corporation. 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.
+
+BBDEV null Poll Mode Driver
+============================
+
+The (**bbdev_null**) is a bbdev poll mode driver which provides a minimal
+implementation of a software bbdev device. As a null device it does not modify
+the data in the mbuf on which the bbdev operation is to operate and it only
+works for operation type ``RTE_BBDEV_OP_NONE``.
+
+When a burst of mbufs is submitted to a *bbdev null PMD* for processing then
+each mbuf in the burst will be enqueued in an internal buffer ring to be
+collected on a dequeue call.
+
+
+Limitations
+-----------
+
+* In-place operations for Turbo encode and decode are not supported
+
+Installation
+------------
+
+The *bbdev null PMD* is enabled and built by default in both the Linux and
+FreeBSD builds.
+
+Initialization
+--------------
+
+To use the PMD in an application, user must:
+
+- Call ``rte_vdev_init("bbdev_null")`` within the application.
+
+- Use ``--vdev="bbdev_null"`` in the EAL options, which will call ``rte_vdev_init()`` internally.
+
+The following parameters (all optional) can be provided in the previous two calls:
+
+* ``socket_id``: Specify the socket where the memory for the device is going to be allocated
+ (by default, *socket_id* will be the socket where the core that is creating the PMD is running on).
+
+* ``max_nb_queues``: Specify the maximum number of queues in the device (default is ``RTE_MAX_LCORE``).
+
+Example:
+~~~~~~~~
+
+.. code-block:: console
+
+ ./test-bbdev.py -e="--vdev=bbdev_null,socket_id=0,max_nb_queues=8"
new file mode 100644
@@ -0,0 +1,175 @@
+..
+ BSD LICENSE
+
+ Copyright(c) 2017 Intel Corporation. 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.
+
+SW Turbo Poll Mode Driver
+=========================
+
+The SW Turbo PMD (**turbo_sw**) provides a poll mode bbdev driver that utilizes
+Intel optimized libraries for LTE Layer 1 workloads acceleration. This PMD
+supports the functions: Turbo FEC, Rate Matching and CRC functions.
+
+Features
+--------
+
+SW Turbo PMD has support for the following capabilities:
+
+For the encode operation:
+
+* ``RTE_BBDEV_TURBO_CRC_24A_ATTACH``
+* ``RTE_BBDEV_TURBO_CRC_24B_ATTACH``
+* ``RTE_BBDEV_TURBO_RATE_MATCH``
+* ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS``
+
+For the decode operation:
+
+* ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE``
+* ``RTE_BBDEV_TURBO_CRC_TYPE_24B``
+* ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN``
+* ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN``
+
+
+Limitations
+-----------
+
+* In-place operations for Turbo encode and decode are not supported
+
+Installation
+------------
+
+FlexRAN SDK Download
+~~~~~~~~~~~~~~~~~~~~
+
+To build DPDK with the *turbo_sw* PMD the user is required to download
+the export controlled ``FlexRAN SDK`` Libraries. An account at Intel Resource
+Design Center needs to be registered from
+`<https://www.intel.com/content/www/us/en/design/resource-design-center.html>`_.
+
+Once registered, the user needs to log in, and look for
+*Intel SWA_SW_FlexRAN_Release_Package R1_3_0* and click for download. Or use
+this direct download link `<https://cdrd.intel.com/v1/dl/getContent/575367>`_.
+
+After download is complete, the user needs to unpack and compile on their
+system before building DPDK.
+
+FlexRAN SDK Installation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following are pre-requisites for building FlexRAN SDK Libraries:
+ (a) An AVX2 supporting machine
+ (b) Windriver TS 2 or CentOS 7 operating systems
+ (c) Intel ICC compiler installed
+
+The following instructions should be followed in this exact order:
+
+#. Set the environment variables:
+
+ .. code-block:: console
+
+ source <path-to-icc-compiler-install-folder>/linux/bin/compilervars.sh intel64 -platform linux
+
+
+#. Extract the ``FlexRAN-1.3.0.tar.gz.zip`` package, then run the SDK extractor
+ script and accept the license:
+
+ .. code-block:: console
+
+ cd <path-to-workspace>/FlexRAN-1.3.0/
+ ./SDK-R1.3.0.sh
+
+#. To allow ``FlexRAN SDK R1.3.0`` to work with bbdev properly, the following
+ hotfix is required. Change the return of function ``rate_matching_turbo_lte_avx2()``
+ located in file
+ ``<path-to-workspace>/FlexRAN-1.3.0/SDK-R1.3.0/sdk/source/phy/lib_rate_matching/phy_rate_match_avx2.cpp``
+ to return 0 instead of 1.
+
+ .. code-block:: c
+
+ - return 1;
+ + return 0;
+
+#. Generate makefiles based on system configuration:
+
+ .. code-block:: console
+
+ cd <path-to-workspace>/FlexRAN-1.3.0/SDK-R1.3.0/sdk/
+ ./create-makefiles-linux.sh
+
+#. A build folder is generated in this form ``build-<ISA>-<CC>``, enter that
+ folder and install:
+
+ .. code-block:: console
+
+ cd build-avx2-icc/
+ make install
+
+
+Initialization
+--------------
+
+In order to enable this virtual bbdev PMD, the user must:
+
+* Build the ``FLEXRAN SDK`` libraries (explained in Installation section).
+
+* Export the environmental variables ``FLEXRAN_SDK`` to the path where the
+ FlexRAN SDK libraries were installed. And ``DIR_WIRELESS_SDK`` to the path
+ where the librararies were extracted.
+
+Example:
+
+.. code-block:: console
+
+ export FLEXRAN_SDK=<path-to-workspace>/FlexRAN-1.3.0/SDK-R1.3.0/sdk/build-avx2-icc/install
+ export DIR_WIRELESS_SDK=<path-to-workspace>/FlexRAN-1.3.0/SDK-R1.3.0/sdk/
+
+
+* Set ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y`` in DPDK common configuration
+ file ``config/common_base``.
+
+To use the PMD in an application, user must:
+
+- Call ``rte_vdev_init("turbo_sw")`` within the application.
+
+- Use ``--vdev="turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally.
+
+The following parameters (all optional) can be provided in the previous two calls:
+
+* ``socket_id``: Specify the socket where the memory for the device is going to be allocated
+ (by default, *socket_id* will be the socket where the core that is creating the PMD is running on).
+
+* ``max_nb_queues``: Specify the maximum number of queues in the device (default is ``RTE_MAX_LCORE``).
+
+Example:
+~~~~~~~~
+
+.. code-block:: console
+
+ ./test-bbdev.py -e="--vdev=turbo_sw,socket_id=0,max_nb_queues=8" \
+ -c validation -v ./test_vectors/bbdev_vector_t?_default.data
@@ -44,6 +44,7 @@ DPDK documentation
nics/index
cryptodevs/index
eventdevs/index
+ bbdevs/index
mempool/index
platform/index
contributing/index
new file mode 100644
@@ -0,0 +1,613 @@
+..
+ BSD LICENSE
+
+ Copyright(c) 2017 Intel Corporation. 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.
+
+Wireless Baseband Device Library
+================================
+
+The Wireless Baseband library provides a common programming framework that
+abstracts HW accelerators based on FPGA and/or Fixed Function Accelerators that
+assist with 3gpp Physical Layer processing. Furthermore, it decouples the
+application from the compute-intensive wireless functions by abstracting their
+optimized libraries to appear as virtual bbdev devices.
+
+The functional scope of the BBDEV library are those functions in relation to
+the 3gpp Layer 1 signal processing (channel coding, modulation, ...).
+
+The framework currently only supports Turbo Code FEC function.
+
+
+Design Principles
+-----------------
+
+The Wireless Baseband library follows the same ideology of DPDK's Ethernet
+Device and Crypto Device frameworks. Wireless Baseband provides a generic
+acceleration abstraction framework which supports both physical (hardware) and
+virtual (software) wireless acceleration functions.
+
+Device Management
+-----------------
+
+Device Creation
+~~~~~~~~~~~~~~~
+
+Physical bbdev devices are discovered during the PCI probe/enumeration of the
+EAL function which is executed at DPDK initialization, based on
+their PCI device identifier, each unique PCI BDF (bus/bridge, device,
+function).
+
+Virtual devices can be created by two mechanisms, either using the EAL command
+line options or from within the application using an EAL API directly.
+
+From the command line using the --vdev EAL option
+
+.. code-block:: console
+
+ --vdev 'turbo_sw,max_nb_queues=8,socket_id=0'
+
+Our using the rte_vdev_init API within the application code.
+
+.. code-block:: c
+
+ rte_vdev_init("turbo_sw", "max_nb_queues=2,socket_id=0")
+
+All virtual bbdev devices support the following initialization parameters:
+
+- ``max_nb_queues`` - maximum number of queues supported by the device.
+
+- ``socket_id`` - socket on which to allocate the device resources on.
+
+
+Device Identification
+~~~~~~~~~~~~~~~~~~~~~
+
+Each device, whether virtual or physical is uniquely designated by two
+identifiers:
+
+- A unique device index used to designate the bbdev device in all functions
+ exported by the bbdev API.
+
+- A device name used to designate the bbdev device in console messages, for
+ administration or debugging purposes. For ease of use, the port name includes
+ the port index.
+
+
+Device Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+From the application point of view, each instance of a bbdev device consists of
+one or more queues identified by queue IDs. While different devices may have
+different capabilities (e.g. support different operation types), all queues on
+a device support identical configuration possibilities. A queue is configured
+for only one type of operation and is configured at initializations time.
+When an operation is enqueued to a specific queue ID, the result is dequeued
+from the same queue ID.
+
+Configuration of a device has two different levels: configuration that applies
+to the whole device, and configuration that applies to a single queue.
+
+Device configuration is applied with
+``rte_bbdev_setup_queues(dev_id,num_queues,socket_id)``
+and queue configuration is applied with
+``rte_bbdev_queue_configure(dev_id,queue_id,conf)``. Note that, although all
+queues on a device support same capabilities, they can be configured differently
+and will then behave differently.
+Devices supporting interrupts can enable them by using
+``rte_bbdev_intr_enable(dev_id)``.
+
+The configuration of each bbdev device includes the following operations:
+
+- Allocation of resources, including hardware resources if a physical device.
+- Resetting the device into a well-known default state.
+- Initialization of statistics counters.
+
+The ``rte_bbdev_setup_queues`` API is used to setup queues for a bbdev device.
+
+.. code-block:: c
+
+ int rte_bbdev_setup_queues(uint16_t dev_id, uint16_t num_queues,
+ int socket_id);
+
+- ``num_queues`` argument identifies the total number of queues to setup for
+ this device.
+
+- ``socket_id`` specifies which socket will be used to allocate the memory.
+
+
+The ``rte_bbdev_intr_enable`` API is used to enable interrupts for a bbdev
+device, if supported by the driver. Should be called before starting the device.
+
+.. code-block:: c
+
+ int rte_bbdev_intr_enable(uint16_t dev_id);
+
+
+Queues Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+Each bbdev devices queue is individually configured through the
+``rte_bbdev_queue_configure()`` API.
+Each queue resources may be allocated on a specified socket.
+
+.. code-block:: c
+
+ struct rte_bbdev_queue_conf {
+ int socket;
+ uint32_t queue_size;
+ uint8_t priority;
+ bool deferred_start;
+ enum rte_bbdev_op_type op_type;
+ };
+
+Device & Queues Management
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After initialization, devices are in a stopped state, so must be started by the
+application. If an application is finished using a device it can close the
+device. Once closed, it cannot be restarted.
+
+.. code-block:: c
+
+ int rte_bbdev_start(uint16_t dev_id)
+ int rte_bbdev_stop(uint16_t dev_id)
+ int rte_bbdev_close(uint16_t dev_id)
+ int rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id)
+ int rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id)
+
+
+By default, all queues are started when the device is started, but they can be
+stopped individually.
+
+.. code-block:: c
+
+ int rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id)
+ int rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id)
+
+
+Logical Cores, Memory and Queues Relationships
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The bbdev device Library as the Poll Mode Driver library support NUMA for when
+a processor’s logical cores and interfaces utilize its local memory. Therefore
+baseband operations, the mbuf being operated on should be allocated from memory
+pools created in the local memory. The buffers should, if possible, remain on
+the local processor to obtain the best performance results and buffer
+descriptors should be populated with mbufs allocated from a mempool allocated
+from local memory.
+
+The run-to-completion model also performs better, especially in the case of
+virtual bbdev devices, if the baseband operation and data buffers are in local
+memory instead of a remote processor's memory. This is also true for the
+pipe-line model provided all logical cores used are located on the same processor.
+
+Multiple logical cores should never share the same queue for enqueuing
+operations or dequeuing operations on the same bbdev device since this would
+require global locks and hinder performance. It is however possible to use a
+different logical core to dequeue an operation on a queue pair from the logical
+core which it was enqueued on. This means that a baseband burst enqueue/dequeue
+APIs are a logical place to transition from one logical core to another in a
+packet processing pipeline.
+
+
+Device Operation Capabilities
+-----------------------------
+
+Capabilities (in terms of operations supported, max number of queues, etc.)
+identify what a bbdev is capable of performing that differs from one device to
+another. For the full scope of the bbdev capability see the definition of the
+structure in the *DPDK API Reference*.
+
+.. code-block:: c
+
+ struct rte_bbdev_op_cap;
+
+A device reports its capabilities when registering itself in the bbdev framework.
+With the aid of this capabilities mechanism, an application can query devices to
+discover which operations within the 3gpp physical layer they are capable of
+performing. Below is an example of the capabilities for a PMD it supports in
+relation to Turbo Encoding and Decoding operations.
+
+.. code-block:: c
+
+ static const struct rte_bbdev_op_cap bbdev_capabilities[] = {
+ {
+ .type = RTE_BBDEV_OP_TURBO_DEC,
+ .cap.turbo_dec = {
+ .capability_flags =
+ RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE |
+ RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN |
+ RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN |
+ RTE_BBDEV_TURBO_CRC_TYPE_24B,
+ .num_buffers_src = RTE_BBDEV_MAX_CODE_BLOCKS,
+ .num_buffers_hard_out =
+ RTE_BBDEV_MAX_CODE_BLOCKS,
+ .num_buffers_soft_out = 0,
+ }
+ },
+ {
+ .type = RTE_BBDEV_OP_TURBO_ENC,
+ .cap.turbo_enc = {
+ .capability_flags =
+ RTE_BBDEV_TURBO_CRC_24B_ATTACH |
+ RTE_BBDEV_TURBO_RATE_MATCH |
+ RTE_BBDEV_TURBO_RV_INDEX_BYPASS,
+ .num_buffers_src = RTE_BBDEV_MAX_CODE_BLOCKS,
+ .num_buffers_dst = RTE_BBDEV_MAX_CODE_BLOCKS,
+ }
+ },
+ RTE_BBDEV_END_OF_CAPABILITIES_LIST()
+ };
+
+Capabilities Discovery
+~~~~~~~~~~~~~~~~~~~~~~
+
+Discovering the features and capabilities of a bbdev device poll mode driver
+is achieved through the ``rte_bbdev_info_get()`` function.
+
+.. code-block:: c
+
+ int rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info)
+
+This allows the user to query a specific bbdev PMD and get all the device
+capabilities. The ``rte_bbdev_info`` structure provides two levels of
+information:
+
+- Device relevant information, like: name and related rte_bus.
+
+- Driver specific information, as defined by the ``struct rte_bbdev_driver_info``
+ structure, this is where capabilities reside along with other specifics like:
+ maximum queue sizes and priority level.
+
+.. code-block:: c
+
+ struct rte_bbdev_info {
+ int socket_id;
+ const char *dev_name;
+ const struct rte_bus *bus;
+ uint16_t num_queues;
+ bool started;
+ struct rte_bbdev_driver_info drv;
+ };
+
+Operation Processing
+--------------------
+
+Scheduling of baseband operations on DPDK's application data path is
+performed using a burst oriented asynchronous API set. A queue on a bbdev
+device accepts a burst of baseband operations using enqueue burst API. On physical
+bbdev devices the enqueue burst API will place the operations to be processed
+on the device's hardware input queue, for virtual devices the processing of the
+baseband operations is usually completed during the enqueue call to the bbdev
+device. The dequeue burst API will retrieve any processed operations available
+from the queue on the bbdev device, from physical devices this is usually
+directly from the device's processed queue, and for virtual device's from a
+``rte_ring`` where processed operations are place after being processed on the
+enqueue call.
+
+
+Enqueue / Dequeue Burst APIs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The burst enqueue API uses a bbdev device identifier and a queue
+identifier to specify the bbdev device queue to schedule the processing on.
+The ``num_ops`` parameter is the number of operations to process which are
+supplied in the ``ops`` array of ``rte_bbdev_*_op`` structures.
+The enqueue function returns the number of operations it actually enqueued for
+processing, a return value equal to ``num_ops`` means that all packets have been
+enqueued.
+
+.. code-block:: c
+
+ uint16_t rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id,
+ struct rte_bbdev_enc_op **ops, uint16_t num_ops)
+
+ uint16_t rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id,
+ struct rte_bbdev_dec_op **ops, uint16_t num_ops)
+
+The dequeue API uses the same format as the enqueue API of processed but
+the ``num_ops`` and ``ops`` parameters are now used to specify the max processed
+operations the user wishes to retrieve and the location in which to store them.
+The API call returns the actual number of processed operations returned, this
+can never be larger than ``num_ops``.
+
+.. code-block:: c
+
+ uint16_t rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id,
+ struct rte_bbdev_enc_op **ops, uint16_t num_ops)
+
+ uint16_t rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id,
+ struct rte_bbdev_dec_op **ops, uint16_t num_ops)
+
+Operation Representation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+An encode bbdev operation is represented by ``rte_bbdev_enc_op`` structure,
+and by ``rte_bbdev_dec_op`` for decode. These structures act as metadata
+containers for all necessary information required for the bbdev operation to be
+processed on a particular bbdev device poll mode driver.
+
+.. code-block:: c
+
+ struct rte_bbdev_enc_op {
+ int status;
+ struct rte_mempool *mempool;
+ void *opaque_data;
+ struct rte_bbdev_op_turbo_enc turbo_enc;
+ };
+
+ struct rte_bbdev_dec_op {
+ int status;
+ struct rte_mempool *mempool;
+ void *opaque_data;
+ struct rte_bbdev_op_turbo_dec turbo_dec;
+ };
+
+The operation structure by itself defines the operation type. It includes an
+operation status, a reference to the operation specific data, which can vary in
+size and content depending on the operation being provisioned. It also contains
+the source mempool for the operation, if it is allocated from a mempool.
+
+If bbdev operations are allocated from a bbdev operation mempool, see next
+section, there is also the ability to allocate private memory with the
+operation for applications purposes.
+
+Application software is responsible for specifying all the operation specific
+fields in the ``rte_bbdev_*_op`` structure which are then used by the bbdev PMD
+to process the requested operation.
+
+
+Operation Management and Allocation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The bbdev library provides an API set for managing bbdev operations which
+utilize the Mempool Library to allocate operation buffers. Therefore, it ensures
+that the bbdev operation is interleaved optimally across the channels and
+ranks for optimal processing.
+
+.. code-block:: c
+
+ struct rte_mempool *
+ rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type,
+ unsigned int num_elements, unsigned int cache_size,
+ int socket_id)
+
+``rte_bbdev_*_op_alloc_bulk()`` and ``rte_bbdev_*_op_free_bulk()`` are used to
+allocate bbdev operations of a specific type from a given bbdev operation mempool.
+
+.. code-block:: c
+
+ int rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool,
+ struct rte_bbdev_enc_op **ops, uint16_t num_ops)
+
+ int rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool,
+ struct rte_bbdev_dec_op **ops, uint16_t num_ops)
+
+``rte_bbdev_*_op_free_bulk()`` is called by the application to return an
+operation to its allocating pool.
+
+.. code-block:: c
+
+ void rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops,
+ unsigned int num_ops)
+ void rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops,
+ unsigned int num_ops)
+
+BBDEV Operations
+~~~~~~~~~~~~~~~~
+
+The bbdev operation structure contains all the mutable data relating to
+performing Turbo code processing on a referenced mbuf data buffer. It is used
+for either encode or decode operations.
+
+Turbo Encode operation accepts one input and one output.
+
+Turbo Decode operation accepts one input and two outputs, called *hard-decision*
+and *soft-decision* outputs. *Soft-decision* output is optional.
+
+It is expected that the application provides input and output ``mbuf`` pointers
+allocated and ready to use. The baseband framework supports turbo coding on
+Code Blocks (CB) and Transport Blocks (TB).
+
+For the output buffer(s), the application needs only to provide an allocated and
+free mbuf (containing only one mbuf segment), so that bbdev can write the
+operation outcome.
+
+**Turbo Encode Op structure**
+
+.. code-block:: c
+
+ struct rte_bbdev_op_turbo_enc {
+ struct rte_bbdev_op_data input;
+ struct rte_bbdev_op_data output;
+
+ uint32_t op_flags;
+ uint8_t rv_index;
+ uint8_t code_block_mode;
+ union {
+ struct rte_bbdev_op_enc_cb_params cb_params;
+ struct rte_bbdev_op_enc_tb_params tb_params;
+ };
+ };
+
+
+**Turbo Decode Op structure**
+
+.. code-block:: c
+
+ struct rte_bbdev_op_turbo_dec {
+ struct rte_bbdev_op_data input;
+ struct rte_bbdev_op_data hard_output;
+ struct rte_bbdev_op_data soft_output;
+
+ uint32_t op_flags;
+ uint8_t rv_index;
+ uint8_t iter_min:4;
+ uint8_t iter_max:4;
+ uint8_t iter_count;
+ uint8_t ext_scale;
+ uint8_t num_maps;
+ uint8_t code_block_mode;
+ union {
+ struct rte_bbdev_op_dec_cb_params cb_params;
+ struct rte_bbdev_op_dec_tb_params tb_params;
+ };
+ };
+
+Input and output data buffers are identified by ``rte_bbdev_op_data`` structure.
+This strucutre has three elements:
+
+- ``data`` - This is the mbuf reference
+
+- ``offset`` - The starting point for the Turbo input/output, in bytes, from the
+ start of the data in the data buffer. It must be smaller than data_len of the
+ mbuf's first segment
+
+- ``length`` - The length, in bytes, of the buffer on which the Turbo operation
+ will or has been computed. For the input, the length is set by the application.
+ For the output(s), the length is computed by the bbdev PMD driver.
+
+Sample code
+-----------
+
+The baseband device sample application gives an introduction on how to use the
+bbdev framework, by giving a sample code performing a loop-back operation with a
+baseband processor capable of transceiving data packets.
+
+The following sample C-like pseudo-code shows the basic steps to encode several
+buffers using (**sw_trubo**) bbdev PMD.
+
+.. code-block:: c
+
+ /* EAL Init */
+ ret = rte_eal_init(argc, argv);
+ if (ret < 0)
+ rte_exit(EXIT_FAILURE, "Invalid EAL arguments\n");
+
+ /* Get number of available bbdev devices */
+ nb_bbdevs = rte_bbdev_count();
+ if (nb_bbdevs == 0)
+ rte_exit(EXIT_FAILURE, "No bbdevs detected!\n");
+
+ /* Create bbdev op pools */
+ bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC] =
+ rte_bbdev_op_pool_create("bbdev_op_pool_enc",
+ RTE_BBDEV_OP_TURBO_ENC, NB_MBUF, 128, rte_socket_id());
+
+ /* Get information for this device */
+ rte_bbdev_info_get(dev_id, &info);
+
+ /* Setup BBDEV device queues */
+ ret = rte_bbdev_setup_queues(dev_id, qs_nb, info.socket_id);
+ if (ret < 0)
+ rte_exit(EXIT_FAILURE,
+ "ERROR(%d): BBDEV %u not configured properly\n",
+ ret, dev_id);
+
+ /* setup device queues */
+ qconf.socket = info.socket_id;
+ qconf.queue_size = info.drv.queue_size_lim;
+ qconf.op_type = RTE_BBDEV_OP_TURBO_ENC;
+
+ for (q_id = 0; q_id < qs_nb; q_id++) {
+ /* Configure all queues belonging to this bbdev device */
+ ret = rte_bbdev_queue_configure(dev_id, q_id, &qconf);
+ if (ret < 0)
+ rte_exit(EXIT_FAILURE,
+ "ERROR(%d): BBDEV %u queue %u not configured properly\n",
+ ret, dev_id, q_id);
+ }
+
+ /* Start bbdev device */
+ ret = rte_bbdev_start(dev_id);
+
+ /* Create the mbuf mempool for pkts */
+ mbuf_pool = rte_pktmbuf_pool_create("bbdev_mbuf_pool",
+ NB_MBUF, MEMPOOL_CACHE_SIZE, 0,
+ RTE_MBUF_DEFAULT_BUF_SIZE, rte_socket_id());
+ if (mbuf_pool == NULL)
+ rte_exit(EXIT_FAILURE,
+ "Unable to create '%s' pool\n", pool_name);
+
+ while (!global_exit_flag) {
+
+ /* Allocate burst of op structures in preparation for enqueue */
+ if (rte_bbdev_enc_op_alloc_bulk(bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC],
+ ops_burst, op_num) != 0)
+ continue;
+
+ /* Allocate input mbuf pkts */
+ ret = rte_pktmbuf_alloc_bulk(mbuf_pool, input_pkts_burst, MAX_PKT_BURST);
+ if (ret < 0)
+ continue;
+
+ /* Allocate output mbuf pkts */
+ ret = rte_pktmbuf_alloc_bulk(mbuf_pool, output_pkts_burst, MAX_PKT_BURST);
+ if (ret < 0)
+ continue;
+
+ for (j = 0; j < op_num; j++) {
+ /* Append the size of the ethernet header */
+ rte_pktmbuf_append(input_pkts_burst[j],
+ sizeof(struct ether_hdr));
+
+ /* set op */
+
+ ops_burst[j]->turbo_enc.input.offset =
+ sizeof(struct ether_hdr);
+
+ ops_burst[j]->turbo_enc->input.length =
+ rte_pktmbuf_pkt_len(bbdev_pkts[j]);
+
+ ops_burst[j]->turbo_enc->input.data =
+ input_pkts_burst[j];
+
+ ops_burst[j]->turbo_enc->output.offset =
+ sizeof(struct ether_hdr);
+
+ ops_burst[j]->turbo_enc->output.data =
+ output_pkts_burst[j];
+ }
+
+ /* Enqueue packets on BBDEV device */
+ op_num = rte_bbdev_enqueue_enc_ops(qconf->bbdev_id,
+ qconf->bbdev_qs[q], ops_burst,
+ MAX_PKT_BURST);
+
+ /* Dequeue packets from BBDEV device*/
+ op_num = rte_bbdev_dequeue_enc_ops(qconf->bbdev_id,
+ qconf->bbdev_qs[q], ops_burst,
+ MAX_PKT_BURST);
+ }
+
+
+BBDEV Device API
+~~~~~~~~~~~~~~~~
+
+The bbdev Library API is described in the *DPDK API Reference* document.
@@ -66,6 +66,7 @@ Programmer's Guide
kernel_nic_interface
thread_safety_dpdk_functions
eventdev
+ bbdev
event_ethernet_rx_adapter
qos_framework
power_man
new file mode 100644
@@ -0,0 +1,160 @@
+.. BSD LICENSE
+ Copyright(c) 2017 Intel Corporation. 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.
+
+.. bbdev_app:
+
+Loop-back Sample Application using Baseband Device (bbdev)
+==========================================================
+
+The baseband sample application is a simple example of packet processing using
+the Data Plane Development Kit (DPDK) for baseband workloads using the bbdev
+library.
+
+Overview
+--------
+
+The Baseband device sample application performs a loop-back operation using a
+baseband device capable of transceiving data packets.
+A packet is received on a DOWNLINK_RX_PORT or UPLINK_RX_PORTS -> enqueued for
+baseband operation -> dequeued from the baseband device then looped back to
+DOWNLINK_TX_PORTS or UPLINK_TX_PORTS, respectively.
+
+* The source MAC address is replaced by the TX_PORT MAC address
+
+* The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID
+
+Limitations
+-----------
+
+* Although, the baseband sample application is designed to work in full-duplex
+ mode, but due to theplain format of the received packets from pkt-gen, the
+ Turbo decode (uplink) is not operable. Only the Turbo encode direction
+ (downlink) is currently supported in the bbdev sample application.
+
+Compiling the Application
+-------------------------
+
+#. DPDK needs to be built with ``turbo_sw`` PMD driver enabled along with
+ ``FLEXRAN SDK`` Libraries. Refer to *SW Turbo Poll Mode Driver*
+ documentation for more details on this.
+
+#. Go to the example directory:
+
+ .. code-block:: console
+
+ export RTE_SDK=/path/to/rte_sdk
+ cd ${RTE_SDK}/examples/bbdev_app
+
+#. Set the target (a default target is used if not specified). For example:
+
+ .. code-block:: console
+
+ export RTE_TARGET=x86_64-native-linuxapp-gcc
+
+ See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
+
+#. Build the application:
+
+ .. code-block:: console
+
+ make
+
+Running the Application
+-----------------------
+
+The application requires a number of command line options:
+
+.. code-block:: console
+
+ $ ./build/bbdev [EAL options] -- [-r DOWNLINK_RX_PORTS] [-R UPLINK_RX_PORTS] /
+ [-t DOWNLINK_TX_PORTS ] [-T UPLINK_TX_PORTS] /
+ [-c DOWNLINK_CORES] [-C UPLINK_CORES]
+
+where:
+
+* ``r DOWNLINK_RX_PORTS``: hexmask for downlink receiver ports number
+* ``R UPLINK_RX_PORTS``: hexmask for uplink receiver ports number
+* ``t DOWNLINK_TX_PORTS``: hexmask for downlink transceiver ports number
+* ``T UPLINK_TX_PORTS``: hexmask for uplink transceiver ports number
+* ``c DOWNLINK_CORES``: hexmask for downlink cores number
+* ``C UPLINK_CORES``: hexmask for uplink cores number
+
+The application requires that baseband devices is capable of performing
+the specified baseband operation are available on application initialization.
+This means that HW baseband device/s must be bound to a DPDK driver or
+a SW baseband device/s (virtual BBdev) must be created (using --vdev).
+
+To run the application in linuxapp environment with one baseband device for
+uplink, running on 1 port and 2 logical cores, issue the command:
+
+.. code-block:: console
+
+ $ ./build/bbdev --vdev='turbo_sw' -w <NIC0PCIADDR> -c 0x38 --socket-mem=2,2 \
+ --file-prefix=bbdev -- -r 0x1 -t 0x1 -c 0x30
+
+where, NIC0PCIADDR is the PCI addresse of the Rx port
+
+This command creates one virtual bbdev devices ``turbo_sw`` where the device
+gets linked to a corresponding ethernet port as whitelisted by the parameter -w.
+3 cores are allocated to the application, and assigned as:
+
+ - core 3 is the master and used to print the stats live on screen,
+
+ - cores 4 & 5 are the downlink cores, Tx & Rx
+
+
+Refer to the *DPDK Getting Started Guide* for general information on running
+applications and the Environment Abstraction Layer (EAL) options.
+
+Using Packet Generator with baseband device sample application
+--------------------------------------------------------------
+
+To allow the bbdev sample app to do the loopback, an influx of traffic is required.
+This can be done by using DPDK Pktgen to burst traffic on two ethernet ports, and
+it will print the transmitted along with the looped-back traffic on Rx ports.
+Executing the command below will generate traffic on the two whitelisted ethernet
+ports.
+
+.. code-block:: console
+
+ $ ./pktgen-3.4.0/app/x86_64-native-linuxapp-gcc/pktgen -c 0x3 \
+ --socket-mem=1,1 --file-prefix=pg -w <NIC1PCIADDR> -- -m 1.0 -P
+
+where:
+
+* ``-c COREMASK``: A hexadecimal bitmask of cores to run on
+* ``--socket-mem``: Memory to allocate on specific sockets (use comma separated values)
+* ``--file-prefix``: Prefix for hugepage filenames
+* ``-w <NIC1PCIADDR>``: Add a PCI device in white list. The argument format is <[domain:]bus:devid.func>.
+* ``-m <string>``: Matrix for mapping ports to logical cores.
+* ``-P``: PROMISCUOUS mode
+
+
+Refer to *The Pktgen Application* documents for general information on running
+Pktgen with DPDK applications.
@@ -81,6 +81,7 @@ Sample Applications User Guides
ptpclient
performance_thread
ipsec_secgw
+ bbdev_app
**Figures**
@@ -41,3 +41,4 @@ DPDK Tools User Guides
devbind
cryptoperf
testeventdev
+ testbbdev
new file mode 100644
@@ -0,0 +1,600 @@
+..
+ BSD LICENSE
+
+ Copyright(c) 2017 Intel Corporation. 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.
+
+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_<name>=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_2CB.data``
+
+- ``bbdev_vector_td_CRC24B.data``
+
+- ``bbdev_vector_td_bypassSbd.data``
+
+- ``bbdev_vector_td_default.data``
+
+- ``bbdev_vector_td_deint.data``
+
+- ``bbdev_vector_td_pos_llr_1_bit_input.data``
+
+- ``bbdev_vector_td_pos_llr_1_bit_input_soft_output.data``
+
+- ``bbdev_vector_td_pos_llr_1_bit_soft_output.data``
+
+- ``bbdev_vector_te_2CB.data``
+
+- ``bbdev_vector_te_CRC24A.data``
+
+- ``bbdev_vector_te_CRC24B.data``
+
+- ``bbdev_vector_te_TB.data``
+
+- ``bbdev_vector_te_bypassRM.data``
+
+- ``bbdev_vector_te_bypassRM2.data``
+
+- ``bbdev_vector_te_bypassRvidx.data``
+
+- ``bbdev_vector_te_default.data``
+
+- ``bbdev_vector_te_partialTB.data``
+
+- ``bbdev_vector_te_splitCB.data``
+
+- ``bbdev_vector_te_splitTB.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 systax 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