[dpdk-dev] [PATCH v3 5/5] bbdev: documentation
Kovacevic, Marko
marko.kovacevic at intel.com
Mon Dec 18 15:26:25 CET 2017
> -----Original Message-----
> From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Amr Mokhtar
> Sent: Thursday, December 7, 2017 9:41 PM
> To: dev at dpdk.org
> Cc: thomas at monjalon.net; Burakov, Anatoly <anatoly.burakov at intel.com>; De
> Lara Guarch, Pablo <pablo.de.lara.guarch at intel.com>; Power, Niall
> <niall.power at intel.com>; Macnamara, Chris <chris.macnamara at intel.com>;
> Mokhtar, Amr <amr.mokhtar at 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 at 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
More information about the dev
mailing list