> -----Original Message----- > From: dev [mailto:dev-boun...@dpdk.org] On Behalf Of Amr Mokhtar > Sent: Thursday, December 7, 2017 9:41 PM > To: dev@dpdk.org > Cc: tho...@monjalon.net; Burakov, Anatoly <anatoly.bura...@intel.com>; De > Lara Guarch, Pablo <pablo.de.lara.gua...@intel.com>; Power, Niall > <niall.po...@intel.com>; Macnamara, Chris <chris.macnam...@intel.com>; > Mokhtar, Amr <amr.mokh...@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.mokh...@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
