-----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 <redacted>; De
Lara Guarch, Pablo [off-list ref]; Power, Niall
[off-list ref]; Macnamara, Chris [off-list ref];
Mokhtar, Amr [off-list ref]
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 <redacted>
---
 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.