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 needs to be registered from
  45 `<https://www.intel.com/content/www/us/en/design/resource-design-center.html>`_.
  46
  47 Once registered, the user needs to log in, and look for
  48 *Intel SWA_SW_FlexRAN_Release_Package R1_3_0* and click for download. Or use
  49 this direct download link `<https://cdrd.intel.com/v1/dl/getContent/575367>`_.
  50
  51 After download is complete, the user needs to unpack and compile on their
  52 system before building DPDK.
  53
  54 FlexRAN SDK Installation
  55 ~~~~~~~~~~~~~~~~~~~~~~~~
  56
  57 The following are pre-requisites for building FlexRAN SDK Libraries:
  58  (a) An AVX2 supporting machine
  59  (b) Windriver TS 2 or CentOS 7 operating systems
  60  (c) Intel ICC compiler installed
  61
  62 The following instructions should be followed in this exact order:
  63
  64 #. Set the environment variables:
  65
  66     .. code-block:: console
  67
  68         source <path-to-icc-compiler-install-folder>/linux/bin/compilervars.sh intel64 -platform linux
  69
  70
  71 #. Extract the ``FlexRAN-1.3.0.tar.gz.zip`` package, then run the SDK extractor
  72    script and accept the license:
  73
  74     .. code-block:: console
  75
  76         cd <path-to-workspace>/FlexRAN-1.3.0/
  77         ./SDK-R1.3.0.sh
  78
  79 #. To allow ``FlexRAN SDK R1.3.0`` to work with bbdev properly, the following
  80    hotfix is required. Change the return of function ``rate_matching_turbo_lte_avx2()``
  81    located in file
  82    ``<path-to-workspace>/FlexRAN-1.3.0/SDK-R1.3.0/sdk/source/phy/lib_rate_matching/phy_rate_match_avx2.cpp``
  83    to return 0 instead of 1.
  84
  85     .. code-block:: c
  86
  87         -  return 1;
  88         +  return 0;
  89
  90 #. Generate makefiles based on system configuration:
  91
  92     .. code-block:: console
  93
  94         cd <path-to-workspace>/FlexRAN-1.3.0/SDK-R1.3.0/sdk/
  95         ./create-makefiles-linux.sh
  96
  97 #. A build folder is generated in this form ``build-<ISA>-<CC>``, enter that
  98    folder and install:
  99
 100     .. code-block:: console
 101
 102         cd build-avx2-icc/
 103         make install
 104
 105
 106 Initialization
 107 --------------
 108
 109 In order to enable this virtual bbdev PMD, the user must:
 110
 111 * Build the ``FLEXRAN SDK`` libraries (explained in Installation section).
 112
 113 * Export the environmental variables ``FLEXRAN_SDK`` to the path where the
 114   FlexRAN SDK libraries were installed. And ``DIR_WIRELESS_SDK`` to the path
 115   where the libraries were extracted.
 116
 117 Example:
 118
 119 .. code-block:: console
 120
 121     export FLEXRAN_SDK=<path-to-workspace>/FlexRAN-1.3.0/SDK-R1.3.0/sdk/build-avx2-icc/install
 122     export DIR_WIRELESS_SDK=<path-to-workspace>/FlexRAN-1.3.0/SDK-R1.3.0/sdk/
 123
 124
 125 * Set ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y`` in DPDK common configuration
 126   file ``config/common_base``.
 127
 128 To use the PMD in an application, user must:
 129
 130 - Call ``rte_vdev_init("turbo_sw")`` within the application.
 131
 132 - Use ``--vdev="turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally.
 133
 134 The following parameters (all optional) can be provided in the previous two calls:
 135
 136 * ``socket_id``: Specify the socket where the memory for the device is going to be allocated
 137   (by default, *socket_id* will be the socket where the core that is creating the PMD is running on).
 138
 139 * ``max_nb_queues``: Specify the maximum number of queues in the device (default is ``RTE_MAX_LCORE``).
 140
 141 Example:
 142 ~~~~~~~~
 143
 144 .. code-block:: console
 145
 146     ./test-bbdev.py -e="--vdev=turbo_sw,socket_id=0,max_nb_queues=8" \
 147     -c validation -v ./test_vectors/bbdev_vector_t?_default.data