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