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 (**turbo_sw**) provides a poll mode bbdev driver that utilizes
   8 Intel optimized libraries for LTE Layer 1 workloads acceleration. This PMD
   9 supports the functions: Turbo FEC, Rate Matching and CRC functions.
  10
  11 Features
  12 --------
  13
  14 SW Turbo PMD has support for the following capabilities:
  15
  16 For the encode operation:
  17
  18 * ``RTE_BBDEV_TURBO_CRC_24A_ATTACH``
  19 * ``RTE_BBDEV_TURBO_CRC_24B_ATTACH``
  20 * ``RTE_BBDEV_TURBO_RATE_MATCH``
  21 * ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS``
  22
  23 For the decode operation:
  24
  25 * ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE``
  26 * ``RTE_BBDEV_TURBO_CRC_TYPE_24B``
  27 * ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN``
  28 * ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN``
  29
  30
  31 Limitations
  32 -----------
  33
  34 * In-place operations for Turbo encode and decode are not supported
  35
  36 Installation
  37 ------------
  38
  39 FlexRAN SDK Download
  40 ~~~~~~~~~~~~~~~~~~~~
  41
  42 To build DPDK with the *turbo_sw* PMD the user is required to download
  43 the export controlled ``FlexRAN SDK`` Libraries. An account at `Intel Resource
  44 Design Center <https://www.intel.com/content/www/us/en/design/resource-design-center.html>`_
  45 needs to be registered.
  46
  47 Once registered, the user needs to log in, and look for
  48 *Intel FlexRAN Software Release Package 1_4_0* to download or directly through
  49 this `link <https://cdrdv2.intel.com/v1/dl/getContent/576288>`_.
  50
  51 After download is complete, the user needs to unpack and compile on their
  52 system before building DPDK.
  53
  54 The following table maps DPDK versions with past FlexRAN SDK releases:
  55
  56 .. _table_flexran_releases:
  57
  58 .. table:: DPDK and FlexRAN SDK releases compliance
  59
  60    =====================  ============================
  61    DPDK version           FlexRAN SDK release
  62    =====================  ============================
  63    18.02                  1.3.0
  64    18.05                  1.4.0
  65    =====================  ============================
  66
  67 FlexRAN SDK Installation
  68 ~~~~~~~~~~~~~~~~~~~~~~~~
  69
  70 The following are pre-requisites for building FlexRAN SDK Libraries:
  71  (a) An AVX2 supporting machine
  72  (b) Windriver TS 2 or CentOS 7 operating systems
  73  (c) Intel ICC 17.0.3 compiler installed
  74
  75 The following instructions should be followed in this exact order:
  76
  77 #. Set the environment variables:
  78
  79     .. code-block:: console
  80
  81         source <path-to-icc-compiler-install-folder>/linux/bin/compilervars.sh intel64 -platform linux
  82
  83
  84 #. Extract the ``576288-576288-intel-swa-sw-flexran-release-package-r1-4-0.zip``
  85    package, then run the SDK extractor script and accept the license:
  86
  87     .. code-block:: console
  88
  89         cd <path-to-workspace>/FlexRAN-1.4.0/
  90         ./SDK-R1.4.0.sh
  91
  92 #. Generate makefiles based on system configuration:
  93
  94     .. code-block:: console
  95
  96         cd <path-to-workspace>/FlexRAN-1.4.0/SDK-R1.4.0/sdk/
  97         ./create-makefiles-linux.sh
  98
  99 #. A build folder is generated in this form ``build-<ISA>-<CC>``, enter that
 100    folder and install:
 101
 102     .. code-block:: console
 103
 104         cd build-avx2-icc/
 105         make install
 106
 107
 108 Initialization
 109 --------------
 110
 111 In order to enable this virtual bbdev PMD, the user must:
 112
 113 * Build the ``FLEXRAN SDK`` libraries (explained in Installation section).
 114
 115 * Export the environmental variables ``FLEXRAN_SDK`` to the path where the
 116   FlexRAN SDK libraries were installed. And ``DIR_WIRELESS_SDK`` to the path
 117   where the libraries were extracted.
 118
 119 Example:
 120
 121 .. code-block:: console
 122
 123     export FLEXRAN_SDK=<path-to-workspace>/FlexRAN-1.4.0/SDK-R1.4.0/sdk/build-avx2-icc/install
 124     export DIR_WIRELESS_SDK=<path-to-workspace>/FlexRAN-1.4.0/SDK-R1.4.0/sdk/
 125
 126
 127 * Set ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y`` in DPDK common configuration
 128   file ``config/common_base``.
 129
 130 To use the PMD in an application, user must:
 131
 132 - Call ``rte_vdev_init("turbo_sw")`` within the application.
 133
 134 - Use ``--vdev="turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally.
 135
 136 The following parameters (all optional) can be provided in the previous two calls:
 137
 138 * ``socket_id``: Specify the socket where the memory for the device is going to be allocated
 139   (by default, *socket_id* will be the socket where the core that is creating the PMD is running on).
 140
 141 * ``max_nb_queues``: Specify the maximum number of queues in the device (default is ``RTE_MAX_LCORE``).
 142
 143 Example:
 144 ~~~~~~~~
 145
 146 .. code-block:: console
 147
 148     ./test-bbdev.py -e="--vdev=turbo_sw,socket_id=0,max_nb_queues=8" \
 149     -c validation -v ./test_vectors/bbdev_vector_t?_default.data