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.
+The SW Turbo PMD (**baseband_turbo_sw**) provides a software only poll mode bbdev
+driver that can optionally utilize Intel optimized libraries for LTE and 5GNR
+Layer 1 workloads acceleration.
+
+Note that the driver can also be built without any dependency with reduced
+functionality for maintenance purpose.
+
+To enable linking to the SDK libraries see detailed installation section below.
+
+This PMD supports the functions: FEC, Rate Matching and CRC functions detailed
+in the Features section.
Features
--------
-SW Turbo PMD has support for the following capabilities:
+SW Turbo PMD can support for the following capabilities when the SDK libraries
+are used:
-For the encode operation:
+For the LTE 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:
+For the LTE decode operation:
* ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE``
* ``RTE_BBDEV_TURBO_CRC_TYPE_24B``
* ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP``
* ``RTE_BBDEV_TURBO_EARLY_TERMINATION``
+For the 5G NR LDPC encode operation:
+
+* ``RTE_BBDEV_LDPC_RATE_MATCH``
+* ``RTE_BBDEV_LDPC_CRC_24A_ATTACH``
+* ``RTE_BBDEV_LDPC_CRC_24B_ATTACH``
+
+For the 5G NR LDPC decode operation:
+
+* ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK``
+* ``RTE_BBDEV_LDPC_CRC_TYPE_24A_CHECK``
+* ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP``
+* ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE``
+* ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE``
+* ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE``
Limitations
-----------
-* In-place operations for Turbo encode and decode are not supported
+* In-place operations for 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 <https://www.intel.com/content/www/us/en/design/resource-design-center.html>`_
-needs to be registered.
+As an option it is possible to link this driver with FleXRAN SDK libraries
+which can enable real time signal processing using AVX instructions.
-Once registered, the user needs to log in, and look for
-*Intel FlexRAN Software Release Package 1_4_0* to download or directly through
-this `link <https://cdrdv2.intel.com/v1/dl/getContent/576288>`_.
+These libraries are available through this `link <https://software.intel.com/en-us/articles/flexran-lte-and-5g-nr-fec-software-development-kit-modules>`_.
After download is complete, the user needs to unpack and compile on their
system before building DPDK.
.. _table_flexran_releases:
-.. table:: DPDK and FlexRAN SDK releases compliance
+.. table:: DPDK and FlexRAN FEC SDK releases compliance
===================== ============================
- DPDK version FlexRAN SDK release
+ DPDK version FlexRAN FEC SDK release
===================== ============================
- 18.02 1.3.0
- 18.05 1.4.0
+ 19.08 19.04
===================== ============================
FlexRAN SDK Installation
~~~~~~~~~~~~~~~~~~~~~~~~
+Note that the installation of these libraries is optional.
+
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 17.0.3 compiler installed
+ (a) An AVX2 or AVX512 supporting machine
+ (b) CentOS Linux release 7.2.1511 (Core) operating system is advised
+ (c) Intel ICC 18.0.1 20171018 compiler or more recent and related libraries
+ ICC is `available with a free community license <https://software.intel.com/en-us/system-studio/choose-download#technical>`_.
The following instructions should be followed in this exact order:
source <path-to-icc-compiler-install-folder>/linux/bin/compilervars.sh intel64 -platform linux
-
-#. Extract the ``576288-576288-intel-swa-sw-flexran-release-package-r1-4-0.zip``
- package, then run the SDK extractor script and accept the license:
+#. Run the SDK extractor script and accept the license:
.. code-block:: console
- cd <path-to-workspace>/FlexRAN-1.4.0/
- ./SDK-R1.4.0.sh
+ cd <path-to-workspace>
+ ./FlexRAN-FEC-SDK-19-04.sh
#. Generate makefiles based on system configuration:
.. code-block:: console
- cd <path-to-workspace>/FlexRAN-1.4.0/SDK-R1.4.0/sdk/
+ cd <path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/
./create-makefiles-linux.sh
-#. If build as a shared library is required, then add ``"-fPIC"`` option to file
- ``<path-to-workspace>/FlexRAN-1.4.0/SDK-R1.4.0/sdk/cmake/intel-compile-options.cmake``
- as follows:
-
- .. code-block:: console
-
- add_compile_options("-fPIC")
-
#. 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
-
+ cd build-avx512-icc/
+ make && make install
Initialization
--------------
-In order to enable this virtual bbdev PMD, the user must:
+In order to enable this virtual bbdev PMD, the user may:
* Build the ``FLEXRAN SDK`` libraries (explained in Installation section).
FlexRAN SDK libraries were installed. And ``DIR_WIRELESS_SDK`` to the path
where the libraries were extracted.
+* Tune the meson build option pointing the location of the FlexRAN SDK libraries ``flexran_sdk``
+
Example:
.. code-block:: console
- export FLEXRAN_SDK=<path-to-workspace>/FlexRAN-1.4.0/SDK-R1.4.0/sdk/build-avx2-icc/install
- export DIR_WIRELESS_SDK=<path-to-workspace>/FlexRAN-1.4.0/SDK-R1.4.0/sdk/
+ export FLEXRAN_SDK=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/install
+ export DIR_WIRELESS_SDK=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/
+ cd build
+ meson configure -Dflexran_sdk=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx512-icc/install
+* For AVX512 machines with SDK libraries installed then both 4G and 5G can be enabled for full real time FEC capability.
+ For AVX2 machines it is possible to only enable the 4G libraries and the PMD capabilities will be limited to 4G FEC.
+ If no library is present then the PMD driver will still build but its capabilities will be limited accordingly.
-* 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.
+- Call ``rte_vdev_init("baseband_turbo_sw")`` within the application.
-- Use ``--vdev="turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally.
+- Use ``--vdev="baseband_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:
.. 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
+ ./test-bbdev.py -e="--vdev=baseband_turbo_sw,socket_id=0,max_nb_queues=8" \
+ -c validation -v ./turbo_*_default.data