doc/guides/bbdevs/turbo_sw.rst

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