1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017 Intel Corporation
5 #ifndef _RTE_BBDEV_OP_H_
6 #define _RTE_BBDEV_OP_H_
11 * Defines wireless base band layer 1 operations and capabilities
14 * @b EXPERIMENTAL: this API may change without prior notice
23 #include <rte_common.h>
25 #include <rte_memory.h>
26 #include <rte_mempool.h>
28 /* Number of columns in sub-block interleaver (36.212, section 5.1.4.1.1) */
29 #define RTE_BBDEV_C_SUBBLOCK (32)
30 /* Maximum size of Transport Block (36.213, Table, Table 7.1.7.2.5-1) */
31 #define RTE_BBDEV_MAX_TB_SIZE (391656)
32 /* Maximum size of Code Block (36.212, Table 5.1.3-3) */
33 #define RTE_BBDEV_MAX_CB_SIZE (6144)
34 /* Minimum size of Code Block (36.212, Table 5.1.3-3) */
35 #define RTE_BBDEV_MIN_CB_SIZE (40)
36 /* Maximum size of circular buffer */
37 #define RTE_BBDEV_MAX_KW (18528)
39 * Maximum number of Code Blocks in Transport Block. It is calculated based on
40 * maximum size of one Code Block and one Transport Block (considering CRC24A
42 * (391656 + 24) / (6144 - 24) = 64
44 #define RTE_BBDEV_MAX_CODE_BLOCKS (64)
46 /** Flags for turbo decoder operation and capability structure */
47 enum rte_bbdev_op_td_flag_bitmasks {
48 /**< If sub block de-interleaving is to be performed. */
49 RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE = (1ULL << 0),
50 /**< To use CRC Type 24B (otherwise use CRC Type 24A). */
51 RTE_BBDEV_TURBO_CRC_TYPE_24B = (1ULL << 1),
52 /**< If turbo equalization is to be performed. */
53 RTE_BBDEV_TURBO_EQUALIZER = (1ULL << 2),
54 /**< If set, saturate soft output to +/-127 */
55 RTE_BBDEV_TURBO_SOFT_OUT_SATURATE = (1ULL << 3),
56 /**< Set to 1 to start iteration from even, else odd; one iteration =
59 RTE_BBDEV_TURBO_HALF_ITERATION_EVEN = (1ULL << 4),
60 /**< If 0, TD stops after CRC matches; else if 1, runs to end of next
61 * odd iteration after CRC matches
63 RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH = (1ULL << 5),
64 /**< Set if soft output is required to be output */
65 RTE_BBDEV_TURBO_SOFT_OUTPUT = (1ULL << 6),
66 /**< Set to enable early termination mode */
67 RTE_BBDEV_TURBO_EARLY_TERMINATION = (1ULL << 7),
68 /**< Set if a device supports decoder dequeue interrupts */
69 RTE_BBDEV_TURBO_DEC_INTERRUPTS = (1ULL << 9),
70 /**< Set if positive LLR encoded input is supported. Positive LLR value
71 * represents the level of confidence for bit '1', and vice versa for
73 * This is mutually exclusive with RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN
74 * when used to formalize the input data format.
76 RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN = (1ULL << 10),
77 /**< Set if negative LLR encoded input is supported. Negative LLR value
78 * represents the level of confidence for bit '1', and vice versa for
80 * This is mutually exclusive with RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN
81 * when used to formalize the input data format.
83 RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN = (1ULL << 11),
84 /**< Set if positive LLR soft output is supported. Positive LLR value
85 * represents the level of confidence for bit '1', and vice versa for
87 * This is mutually exclusive with
88 * RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT when used to formalize
89 * the input data format.
91 RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT = (1ULL << 12),
92 /**< Set if negative LLR soft output is supported. Negative LLR value
93 * represents the level of confidence for bit '1', and vice versa for
95 * This is mutually exclusive with
96 * RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT when used to formalize the
99 RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT = (1ULL << 13),
100 /**< Set if driver supports flexible parallel MAP engine decoding. If
101 * not supported, num_maps (number of MAP engines) argument is unusable.
103 RTE_BBDEV_TURBO_MAP_DEC = (1ULL << 14),
104 /**< Set if a device supports scatter-gather functionality */
105 RTE_BBDEV_TURBO_DEC_SCATTER_GATHER = (1ULL << 15)
108 /** Flags for turbo encoder operation and capability structure */
109 enum rte_bbdev_op_te_flag_bitmasks {
110 /**< Ignore rv_index and set K0 = 0 */
111 RTE_BBDEV_TURBO_RV_INDEX_BYPASS = (1ULL << 0),
112 /**< If rate matching is to be performed */
113 RTE_BBDEV_TURBO_RATE_MATCH = (1ULL << 1),
114 /**< This bit must be set to enable CRC-24B generation */
115 RTE_BBDEV_TURBO_CRC_24B_ATTACH = (1ULL << 2),
116 /**< This bit must be set to enable CRC-24A generation */
117 RTE_BBDEV_TURBO_CRC_24A_ATTACH = (1ULL << 3),
118 /**< Set if a device supports encoder dequeue interrupts */
119 RTE_BBDEV_TURBO_ENC_INTERRUPTS = (1ULL << 4),
120 /**< Set if a device supports scatter-gather functionality */
121 RTE_BBDEV_TURBO_ENC_SCATTER_GATHER = (1ULL << 5)
124 /**< Data input and output buffer for BBDEV operations */
125 struct rte_bbdev_op_data {
126 /**< The mbuf data structure representing the data for BBDEV operation.
128 * This mbuf pointer can point to one Code Block (CB) data buffer or
129 * multiple CBs contiguously located next to each other.
130 * A Transport Block (TB) represents a whole piece of data that is
131 * divided into one or more CBs. Maximum number of CBs can be contained
132 * in one TB is defined by RTE_BBDEV_MAX_CODE_BLOCKS.
134 * An mbuf data structure cannot represent more than one TB. The
135 * smallest piece of data that can be contained in one mbuf is one CB.
136 * An mbuf can include one contiguous CB, subset of contiguous CBs that
137 * are belonging to one TB, or all contiguous CBs that are belonging to
140 * If a BBDEV PMD supports the extended capability "Scatter-Gather",
141 * then it is capable of collecting (gathering) non-contiguous
142 * (scattered) data from multiple locations in the memory.
143 * This capability is reported by the capability flags:
144 * - RTE_BBDEV_TURBO_ENC_SCATTER_GATHER and
145 * - RTE_BBDEV_TURBO_DEC_SCATTER_GATHER.
146 * Only if a BBDEV PMD supports this feature, chained mbuf data
147 * structures are accepted. A chained mbuf can represent one
148 * non-contiguous CB or multiple non-contiguous CBs.
149 * If BBDEV PMD does not support this feature, it will assume inbound
150 * mbuf data contains one segment.
152 * The output mbuf data though is always one segment, even if the input
153 * was a chained mbuf.
155 struct rte_mbuf *data;
156 /**< The starting point of the BBDEV (encode/decode) operation,
159 * BBDEV starts to read data past this offset.
160 * In case of chained mbuf, this offset applies only to the first mbuf
164 /**< The total data length to be processed in one operation, in bytes.
166 * In case the mbuf data is representing one CB, this is the length of
167 * the CB undergoing the operation.
168 * If it's for multiple CBs, this is the total length of those CBs
169 * undergoing the operation.
170 * If it's for one TB, this is the total length of the TB under
173 * In case of chained mbuf, this data length includes the lengths of the
174 * "scattered" data segments undergoing the operation.
179 struct rte_bbdev_op_dec_cb_params {
180 /**< The K size of the input CB, in bits [40:6144], as specified in
182 * This size is inclusive of CRC bits, regardless whether it was
183 * pre-calculated by the application or not.
186 /**< The E length of the CB rate matched LLR output, in bytes, as in
192 struct rte_bbdev_op_dec_tb_params {
193 /**< The K- size of the input CB, in bits [40:6144], that is in the
194 * Turbo operation when r < C-, as in 3GPP TS 36.212.
197 /**< The K+ size of the input CB, in bits [40:6144], that is in the
198 * Turbo operation when r >= C-, as in 3GPP TS 36.212.
201 /**< The number of CBs that have K- size, [0:63] */
203 /**< The total number of CBs in the TB, [1:RTE_BBDEV_MAX_CODE_BLOCKS] */
205 /**< The number of CBs that uses Ea before switching to Eb, [0:63] */
207 /**< The E size of the CB rate matched output to use in the Turbo
208 * operation when r < cab
211 /**< The E size of the CB rate matched output to use in the Turbo
212 * operation when r >= cab
217 /**< Operation structure for Turbo decode.
218 * An operation can perform on one CB at a time "CB-mode".
219 * An operation can perform on one or multiple CBs that are logically belonging
220 * to one TB "TB-mode".
221 * The provided K size parameter of the CB is its size out coming from the
223 * CRC24A/B check is requested by the application by setting the flag
224 * RTE_BBDEV_TURBO_CRC_TYPE_24B for CRC24B check or CRC24A otherwise.
225 * In TB-mode, BBDEV concatenates the decoded CBs one next to the other with
226 * relevant CRC24B in between.
228 * The input encoded CB data is the Virtual Circular Buffer data stream, wk,
229 * with the null padding included as described in 3GPP TS 36.212
230 * section 5.1.4.1.2 and shown in 3GPP TS 36.212 section 5.1.4.1 Figure 5.1.4-1.
231 * The size of the virtual circular buffer is 3*Kpi, where Kpi is the 32 byte
232 * aligned value of K, as specified in 3GPP TS 36.212 section 5.1.4.1.1.
234 * Each byte in the input circular buffer is the LLR value of each bit of the
237 * Hard output is a mandatory capability that all BBDEV PMDs support. This is
238 * the decoded CBs of K sizes (CRC24A/B is the last 24-bit in each decoded CB).
239 * Soft output is an optional capability for BBDEV PMDs. If supported, an LLR
240 * rate matched output is computed in the soft_output buffer structure.
242 * The output mbuf data structure is expected to be allocated by the
243 * application with enough room for the output data.
245 struct rte_bbdev_op_turbo_dec {
246 /**< The Virtual Circular Buffer, wk, size 3*Kpi for each CB */
247 struct rte_bbdev_op_data input;
248 /**< The hard decisions buffer for the decoded output,
251 struct rte_bbdev_op_data hard_output;
252 /**< The soft LLR output buffer - optional */
253 struct rte_bbdev_op_data soft_output;
255 uint32_t op_flags; /**< Flags from rte_bbdev_op_td_flag_bitmasks */
256 uint8_t rv_index; /**< Rv index for rate matching [0:3] */
257 /**< The minimum number of iterations to perform in decoding all CBs in
258 * this operation - input
261 /**< The maximum number of iterations to perform in decoding all CBs in
262 * this operation - input
265 /**< The maximum number of iterations that were perform in decoding all
266 * CBs in this decode operation - output
269 /**< 5 bit extrinsic scale (scale factor on extrinsic info) */
271 /**< Number of MAP engines to use in decode,
272 * must be power of 2 (or 0 to auto-select)
276 uint8_t code_block_mode; /**< [0 - TB : 1 - CB] */
278 /**< Struct which stores Code Block specific parameters */
279 struct rte_bbdev_op_dec_cb_params cb_params;
280 /**< Struct which stores Transport Block specific parameters */
281 struct rte_bbdev_op_dec_tb_params tb_params;
285 struct rte_bbdev_op_enc_cb_params {
286 /**< The K size of the input CB, in bits [40:6144], as specified in
288 * This size is inclusive of CRC24A, regardless whether it was
289 * pre-calculated by the application or not.
292 /**< The E length of the CB rate matched output, in bits, as in
296 /**< The Ncb soft buffer size of the CB rate matched output [K:3*Kpi],
297 * in bits, as specified in 3GPP TS 36.212.
302 struct rte_bbdev_op_enc_tb_params {
303 /**< The K- size of the input CB, in bits [40:6144], that is in the
304 * Turbo operation when r < C-, as in 3GPP TS 36.212.
305 * This size is inclusive of CRC24B, regardless whether it was
306 * pre-calculated and appended by the application or not.
309 /**< The K+ size of the input CB, in bits [40:6144], that is in the
310 * Turbo operation when r >= C-, as in 3GPP TS 36.212.
311 * This size is inclusive of CRC24B, regardless whether it was
312 * pre-calculated and appended by the application or not.
315 /**< The number of CBs that have K- size, [0:63] */
317 /**< The total number of CBs in the TB, [1:RTE_BBDEV_MAX_CODE_BLOCKS] */
319 /**< The number of CBs that uses Ea before switching to Eb, [0:63] */
321 /**< The E size of the CB rate matched output to use in the Turbo
322 * operation when r < cab
325 /**< The E size of the CB rate matched output to use in the Turbo
326 * operation when r >= cab
329 /**< The Ncb soft buffer size for the rate matched CB that is used in
330 * the Turbo operation when r < C-, [K:3*Kpi]
333 /**< The Ncb soft buffer size for the rate matched CB that is used in
334 * the Turbo operation when r >= C-, [K:3*Kpi]
337 /**< The index of the first CB in the inbound mbuf data, default is 0 */
341 /**< Operation structure for Turbo encode.
342 * An operation can perform on one CB at a time "CB-mode".
343 * An operation can perform on one or multiple CBs that are logically
344 * belonging to one TB "TB-mode".
346 * In CB-mode, CRC24A/B is an optional operation. K size parameter is not
347 * affected by CRC24A/B inclusion, this only affects the inbound mbuf data
348 * length. Not all BBDEV PMDs are capable of CRC24A/B calculation. Flags
349 * RTE_BBDEV_TURBO_CRC_24A_ATTACH and RTE_BBDEV_TURBO_CRC_24B_ATTACH informs
350 * the application with relevant capability. These flags can be set in the
351 * op_flags parameter to indicate BBDEV to calculate and append CRC24A to CB
352 * before going forward with Turbo encoding.
354 * In TB-mode, CRC24A is assumed to be pre-calculated and appended to the
355 * inbound TB mbuf data buffer.
357 * The output mbuf data structure is expected to be allocated by the
358 * application with enough room for the output data.
360 struct rte_bbdev_op_turbo_enc {
361 /**< The input CB or TB data */
362 struct rte_bbdev_op_data input;
363 /**< The rate matched CB or TB output buffer */
364 struct rte_bbdev_op_data output;
366 uint32_t op_flags; /**< Flags from rte_bbdev_op_te_flag_bitmasks */
367 uint8_t rv_index; /**< Rv index for rate matching [0:3] */
369 uint8_t code_block_mode; /**< [0 - TB : 1 - CB] */
371 /**< Struct which stores Code Block specific parameters */
372 struct rte_bbdev_op_enc_cb_params cb_params;
373 /**< Struct which stores Transport Block specific parameters */
374 struct rte_bbdev_op_enc_tb_params tb_params;
378 /**< List of the capabilities for the Turbo Decoder */
379 struct rte_bbdev_op_cap_turbo_dec {
380 /**< Flags from rte_bbdev_op_td_flag_bitmasks */
381 uint32_t capability_flags;
382 /** Maximal LLR absolute value. Acceptable LLR values lie in range
383 * [-max_llr_modulus, max_llr_modulus].
385 int8_t max_llr_modulus;
386 uint8_t num_buffers_src; /**< Num input code block buffers */
387 /**< Num hard output code block buffers */
388 uint8_t num_buffers_hard_out;
389 /**< Num soft output code block buffers if supported by the driver */
390 uint8_t num_buffers_soft_out;
393 /**< List of the capabilities for the Turbo Encoder */
394 struct rte_bbdev_op_cap_turbo_enc {
395 /**< Flags from rte_bbdev_op_te_flag_bitmasks */
396 uint32_t capability_flags;
397 uint8_t num_buffers_src; /**< Num input code block buffers */
398 uint8_t num_buffers_dst; /**< Num output code block buffers */
401 /** Different operation types supported by the device */
402 enum rte_bbdev_op_type {
403 RTE_BBDEV_OP_NONE, /**< Dummy operation that does nothing */
404 RTE_BBDEV_OP_TURBO_DEC, /**< Turbo decode */
405 RTE_BBDEV_OP_TURBO_ENC, /**< Turbo encode */
406 RTE_BBDEV_OP_TYPE_COUNT, /**< Count of different op types */
409 /**< Bit indexes of possible errors reported through status field */
412 RTE_BBDEV_DATA_ERROR,
416 /**< Structure specifying a single encode operation */
417 struct rte_bbdev_enc_op {
418 int status; /**< Status of operation that was performed */
419 struct rte_mempool *mempool; /**< Mempool which op instance is in */
420 void *opaque_data; /**< Opaque pointer for user data */
421 /**< Contains encoder specific parameters */
422 struct rte_bbdev_op_turbo_enc turbo_enc;
425 /**< Structure specifying a single decode operation */
426 struct rte_bbdev_dec_op {
427 int status; /**< Status of operation that was performed */
428 struct rte_mempool *mempool; /**< Mempool which op instance is in */
429 void *opaque_data; /**< Opaque pointer for user data */
430 /**< Contains decoder specific parameters */
431 struct rte_bbdev_op_turbo_dec turbo_dec;
434 /**< Operation capabilities supported by a device */
435 struct rte_bbdev_op_cap {
436 enum rte_bbdev_op_type type; /**< Type of operation */
438 struct rte_bbdev_op_cap_turbo_dec turbo_dec;
439 struct rte_bbdev_op_cap_turbo_enc turbo_enc;
440 } cap; /**< Operation-type specific capabilities */
443 /**< @internal Private data structure stored with operation pool. */
444 struct rte_bbdev_op_pool_private {
445 enum rte_bbdev_op_type type; /**< Type of operations in a pool */
449 * Converts queue operation type from enum to string
452 * Operation type as enum
455 * Operation type as string or NULL if op_type is invalid
459 rte_bbdev_op_type_str(enum rte_bbdev_op_type op_type);
462 * Creates a bbdev operation mempool
467 * Operation type, use RTE_BBDEV_OP_NONE for a pool which supports all
469 * @param num_elements
470 * Number of elements in the pool.
472 * Number of elements to cache on an lcore, see rte_mempool_create() for
473 * further details about cache size.
475 * Socket to allocate memory on.
478 * - Pointer to a mempool on success,
479 * - NULL pointer on failure.
482 rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type,
483 unsigned int num_elements, unsigned int cache_size,
487 * Bulk allocate encode operations from a mempool with parameter defaults reset.
490 * Operation mempool, created by rte_bbdev_op_pool_create().
492 * Output array to place allocated operations
494 * Number of operations to allocate
498 * - EINVAL if invalid mempool is provided
501 rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool,
502 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
504 struct rte_bbdev_op_pool_private *priv;
508 priv = (struct rte_bbdev_op_pool_private *)
509 rte_mempool_get_priv(mempool);
510 if (unlikely(priv->type != RTE_BBDEV_OP_TURBO_ENC))
514 ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
515 if (unlikely(ret < 0))
522 * Bulk allocate decode operations from a mempool with parameter defaults reset.
525 * Operation mempool, created by rte_bbdev_op_pool_create().
527 * Output array to place allocated operations
529 * Number of operations to allocate
533 * - EINVAL if invalid mempool is provided
536 rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool,
537 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
539 struct rte_bbdev_op_pool_private *priv;
543 priv = (struct rte_bbdev_op_pool_private *)
544 rte_mempool_get_priv(mempool);
545 if (unlikely(priv->type != RTE_BBDEV_OP_TURBO_DEC))
549 ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
550 if (unlikely(ret < 0))
557 * Free decode operation structures that were allocated by
558 * rte_bbdev_dec_op_alloc_bulk().
559 * All structures must belong to the same mempool.
562 * Operation structures
564 * Number of structures
567 rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops, unsigned int num_ops)
570 rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
574 * Free encode operation structures that were allocated by
575 * rte_bbdev_enc_op_alloc_bulk().
576 * All structures must belong to the same mempool.
579 * Operation structures
581 * Number of structures
584 rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops, unsigned int num_ops)
587 rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
594 #endif /* _RTE_BBDEV_OP_H_ */