1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Intel Corporation 3 4SW Turbo Poll Mode Driver 5========================= 6 7The SW Turbo PMD (**baseband_turbo_sw**) provides a software only poll mode bbdev 8driver that can optionally utilize Intel optimized libraries for LTE and 5GNR 9Layer 1 workloads acceleration. 10 11Note that the driver can also be built without any dependency with reduced 12functionality for maintenance purpose. 13 14To enable linking to the SDK libraries see detailed installation section below. 15Two flags can be enabled depending on whether the target machine can support 16AVX2 and AVX512 instructions sets and the related SDK libraries for vectorized 17signal processing functions are installed : 18- CONFIG_RTE_BBDEV_SDK_AVX2 19- CONFIG_RTE_BBDEV_SDK_AVX512 20By default these 2 flags are disabled by default. For AVX2 machine and SDK 21library installed then the first flag can be enabled. For AVX512 machine and 22SDK library installed then both flags can be enabled for full real time capability. 23 24This PMD supports the functions: FEC, Rate Matching and CRC functions detailed 25in the Features section. 26 27Features 28-------- 29 30SW Turbo PMD can support for the following capabilities when the SDK libraries 31are used: 32 33For the LTE encode operation: 34 35* ``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` 36* ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` 37* ``RTE_BBDEV_TURBO_RATE_MATCH`` 38* ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS`` 39 40For the LTE decode operation: 41 42* ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` 43* ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` 44* ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN`` 45* ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` 46* ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` 47* ``RTE_BBDEV_TURBO_EARLY_TERMINATION`` 48 49For the 5G NR LDPC encode operation: 50 51* ``RTE_BBDEV_LDPC_RATE_MATCH`` 52* ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` 53* ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` 54 55For the 5G NR LDPC decode operation: 56 57* ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` 58* ``RTE_BBDEV_LDPC_CRC_TYPE_24A_CHECK`` 59* ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` 60* ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE`` 61* ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE`` 62* ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE`` 63 64Limitations 65----------- 66 67* In-place operations for encode and decode are not supported 68 69Installation 70------------ 71 72FlexRAN SDK Download 73~~~~~~~~~~~~~~~~~~~~ 74 75As an option it is possible to link this driver with FleXRAN SDK libraries 76which can enable real time signal processing using AVX instructions. 77 78These libraries are available through this `link <https://software.intel.com/en-us/articles/flexran-lte-and-5g-nr-fec-software-development-kit-modules>`_. 79 80After download is complete, the user needs to unpack and compile on their 81system before building DPDK. 82 83The following table maps DPDK versions with past FlexRAN SDK releases: 84 85.. _table_flexran_releases: 86 87.. table:: DPDK and FlexRAN FEC SDK releases compliance 88 89 ===================== ============================ 90 DPDK version FlexRAN FEC SDK release 91 ===================== ============================ 92 19.08 19.04 93 ===================== ============================ 94 95FlexRAN SDK Installation 96~~~~~~~~~~~~~~~~~~~~~~~~ 97 98Note that the installation of these libraries is optional. 99 100The following are pre-requisites for building FlexRAN SDK Libraries: 101 (a) An AVX2 or AVX512 supporting machine 102 (b) CentOS Linux release 7.2.1511 (Core) operating system is advised 103 (c) Intel ICC 18.0.1 20171018 compiler or more recent and related libraries 104 ICC is `available with a free community license <https://software.intel.com/en-us/system-studio/choose-download#technical>`_. 105 106The following instructions should be followed in this exact order: 107 108#. Set the environment variables: 109 110 .. code-block:: console 111 112 source <path-to-icc-compiler-install-folder>/linux/bin/compilervars.sh intel64 -platform linux 113 114#. Run the SDK extractor script and accept the license: 115 116 .. code-block:: console 117 118 cd <path-to-workspace> 119 ./FlexRAN-FEC-SDK-19-04.sh 120 121#. Generate makefiles based on system configuration: 122 123 .. code-block:: console 124 125 cd <path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/ 126 ./create-makefiles-linux.sh 127 128#. A build folder is generated in this form ``build-<ISA>-<CC>``, enter that 129 folder and install: 130 131 .. code-block:: console 132 133 cd build-avx512-icc/ 134 make && make install 135 136Initialization 137-------------- 138 139In order to enable this virtual bbdev PMD, the user may: 140 141* Build the ``FLEXRAN SDK`` libraries (explained in Installation section). 142 143* Export the environmental variables ``FLEXRAN_SDK`` to the path where the 144 FlexRAN SDK libraries were installed. And ``DIR_WIRELESS_SDK`` to the path 145 where the libraries were extracted. 146 147Example: 148 149.. code-block:: console 150 151 export FLEXRAN_SDK=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/install 152 export DIR_WIRELESS_SDK=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/ 153 154* Set ``CONFIG_RTE_BBDEV_SDK_AVX2=y`` and ``CONFIG_RTE_BBDEV_SDK_AVX512=y`` 155 in DPDK common configuration file ``config/common_base`` to be able to use 156 the SDK libraries as mentioned above. 157 For AVX2 machine it is possible to only enable CONFIG_RTE_BBDEV_SDK_AVX2 158 for limited 4G functionality. 159 If no flag are set the PMD driver will still build but its capabilities 160 will be limited accordingly. 161 162To use the PMD in an application, user must: 163 164- Call ``rte_vdev_init("baseband_turbo_sw")`` within the application. 165 166- Use ``--vdev="baseband_turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally. 167 168The following parameters (all optional) can be provided in the previous two calls: 169 170* ``socket_id``: Specify the socket where the memory for the device is going to be allocated 171 (by default, *socket_id* will be the socket where the core that is creating the PMD is running on). 172 173* ``max_nb_queues``: Specify the maximum number of queues in the device (default is ``RTE_MAX_LCORE``). 174 175Example: 176~~~~~~~~ 177 178.. code-block:: console 179 180 ./test-bbdev.py -e="--vdev=baseband_turbo_sw,socket_id=0,max_nb_queues=8" \ 181 -c validation -v ./turbo_*_default.data 182