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 uint8_t num_buffers_src; /**< Num input code block buffers */
383 /**< Num hard output code block buffers */
384 uint8_t num_buffers_hard_out;
385 /**< Num soft output code block buffers if supported by the driver */
386 uint8_t num_buffers_soft_out;
389 /**< List of the capabilities for the Turbo Encoder */
390 struct rte_bbdev_op_cap_turbo_enc {
391 /**< Flags from rte_bbdev_op_te_flag_bitmasks */
392 uint32_t capability_flags;
393 uint8_t num_buffers_src; /**< Num input code block buffers */
394 uint8_t num_buffers_dst; /**< Num output code block buffers */
397 /** Different operation types supported by the device */
398 enum rte_bbdev_op_type {
399 RTE_BBDEV_OP_NONE, /**< Dummy operation that does nothing */
400 RTE_BBDEV_OP_TURBO_DEC, /**< Turbo decode */
401 RTE_BBDEV_OP_TURBO_ENC, /**< Turbo encode */
402 RTE_BBDEV_OP_TYPE_COUNT, /**< Count of different op types */
405 /**< Bit indexes of possible errors reported through status field */
408 RTE_BBDEV_DATA_ERROR,
412 /**< Structure specifying a single encode operation */
413 struct rte_bbdev_enc_op {
414 int status; /**< Status of operation that was performed */
415 struct rte_mempool *mempool; /**< Mempool which op instance is in */
416 void *opaque_data; /**< Opaque pointer for user data */
417 /**< Contains encoder specific parameters */
418 struct rte_bbdev_op_turbo_enc turbo_enc;
421 /**< Structure specifying a single decode operation */
422 struct rte_bbdev_dec_op {
423 int status; /**< Status of operation that was performed */
424 struct rte_mempool *mempool; /**< Mempool which op instance is in */
425 void *opaque_data; /**< Opaque pointer for user data */
426 /**< Contains decoder specific parameters */
427 struct rte_bbdev_op_turbo_dec turbo_dec;
430 /**< Operation capabilities supported by a device */
431 struct rte_bbdev_op_cap {
432 enum rte_bbdev_op_type type; /**< Type of operation */
434 struct rte_bbdev_op_cap_turbo_dec turbo_dec;
435 struct rte_bbdev_op_cap_turbo_enc turbo_enc;
436 } cap; /**< Operation-type specific capabilities */
439 /**< @internal Private data structure stored with operation pool. */
440 struct rte_bbdev_op_pool_private {
441 enum rte_bbdev_op_type type; /**< Type of operations in a pool */
445 * Converts queue operation type from enum to string
448 * Operation type as enum
451 * Operation type as string or NULL if op_type is invalid
455 rte_bbdev_op_type_str(enum rte_bbdev_op_type op_type);
458 * Creates a bbdev operation mempool
463 * Operation type, use RTE_BBDEV_OP_NONE for a pool which supports all
465 * @param num_elements
466 * Number of elements in the pool.
468 * Number of elements to cache on an lcore, see rte_mempool_create() for
469 * further details about cache size.
471 * Socket to allocate memory on.
474 * - Pointer to a mempool on success,
475 * - NULL pointer on failure.
478 rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type,
479 unsigned int num_elements, unsigned int cache_size,
483 * Bulk allocate encode operations from a mempool with parameter defaults reset.
486 * Operation mempool, created by rte_bbdev_op_pool_create().
488 * Output array to place allocated operations
490 * Number of operations to allocate
494 * - EINVAL if invalid mempool is provided
497 rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool,
498 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
500 struct rte_bbdev_op_pool_private *priv;
504 priv = (struct rte_bbdev_op_pool_private *)
505 rte_mempool_get_priv(mempool);
506 if (unlikely(priv->type != RTE_BBDEV_OP_TURBO_ENC))
510 ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
511 if (unlikely(ret < 0))
518 * Bulk allocate decode operations from a mempool with parameter defaults reset.
521 * Operation mempool, created by rte_bbdev_op_pool_create().
523 * Output array to place allocated operations
525 * Number of operations to allocate
529 * - EINVAL if invalid mempool is provided
532 rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool,
533 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
535 struct rte_bbdev_op_pool_private *priv;
539 priv = (struct rte_bbdev_op_pool_private *)
540 rte_mempool_get_priv(mempool);
541 if (unlikely(priv->type != RTE_BBDEV_OP_TURBO_DEC))
545 ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
546 if (unlikely(ret < 0))
553 * Free decode operation structures that were allocated by
554 * rte_bbdev_dec_op_alloc_bulk().
555 * All structures must belong to the same mempool.
558 * Operation structures
560 * Number of structures
563 rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops, unsigned int num_ops)
566 rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
570 * Free encode operation structures that were allocated by
571 * rte_bbdev_enc_op_alloc_bulk().
572 * All structures must belong to the same mempool.
575 * Operation structures
577 * Number of structures
580 rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops, unsigned int num_ops)
583 rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
590 #endif /* _RTE_BBDEV_OP_H_ */