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 #define RTE_BBDEV_MAX_CODE_BLOCKS 64
30 extern int bbdev_logtype;
33 * Helper macro for logging
36 * Log level: EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, or DEBUG
38 * The format string, as in printf(3).
40 * The variable arguments required by the format string.
46 #define rte_bbdev_log(level, fmt, ...) \
47 rte_log(RTE_LOG_ ## level, bbdev_logtype, fmt "\n", ##__VA_ARGS__)
50 * Helper macro for debug logging with extra source info
53 * The format string, as in printf(3).
55 * The variable arguments required by the format string.
61 #define rte_bbdev_log_debug(fmt, ...) \
62 rte_bbdev_log(DEBUG, RTE_STR(__LINE__) ":%s() " fmt, __func__, \
66 * Helper macro for extra conditional logging from datapath
69 * The format string, as in printf(3).
71 * The variable arguments required by the format string.
77 #define rte_bbdev_log_verbose(fmt, ...) \
78 (void)((RTE_LOG_DEBUG <= RTE_LOG_DP_LEVEL) ? \
79 rte_log(RTE_LOG_DEBUG, \
80 bbdev_logtype, ": " fmt "\n", ##__VA_ARGS__) : 0)
82 /** Flags for turbo decoder operation and capability structure */
83 enum rte_bbdev_op_td_flag_bitmasks {
84 /**< If sub block de-interleaving is to be performed. */
85 RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE = (1ULL << 0),
86 /**< To use CRC Type 24B (otherwise use CRC Type 24A). */
87 RTE_BBDEV_TURBO_CRC_TYPE_24B = (1ULL << 1),
88 /**< If turbo equalization is to be performed. */
89 RTE_BBDEV_TURBO_EQUALIZER = (1ULL << 2),
90 /**< If set, saturate soft output to +/-127 */
91 RTE_BBDEV_TURBO_SOFT_OUT_SATURATE = (1ULL << 3),
92 /**< Set to 1 to start iteration from even, else odd; one iteration =
95 RTE_BBDEV_TURBO_HALF_ITERATION_EVEN = (1ULL << 4),
96 /**< If 0, TD stops after CRC matches; else if 1, runs to end of next
97 * odd iteration after CRC matches
99 RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH = (1ULL << 5),
100 /**< Set if soft output is required to be output */
101 RTE_BBDEV_TURBO_SOFT_OUTPUT = (1ULL << 6),
102 /**< Set to enable early termination mode */
103 RTE_BBDEV_TURBO_EARLY_TERMINATION = (1ULL << 7),
104 /**< Set if a device supports decoder dequeue interrupts */
105 RTE_BBDEV_TURBO_DEC_INTERRUPTS = (1ULL << 9),
106 /**< Set if positive LLR encoded input is supported. Positive LLR value
107 * represents the level of confidence for bit '1', and vice versa for
109 * This is mutually exclusive with RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN
110 * when used to formalize the input data format.
112 RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN = (1ULL << 10),
113 /**< Set if negative LLR encoded input is supported. Negative LLR value
114 * represents the level of confidence for bit '1', and vice versa for
116 * This is mutually exclusive with RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN
117 * when used to formalize the input data format.
119 RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN = (1ULL << 11),
120 /**< Set if positive LLR soft output is supported. Positive LLR value
121 * represents the level of confidence for bit '1', and vice versa for
123 * This is mutually exclusive with
124 * RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT when used to formalize
125 * the input data format.
127 RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT = (1ULL << 12),
128 /**< Set if negative LLR soft output is supported. Negative LLR value
129 * represents the level of confidence for bit '1', and vice versa for
131 * This is mutually exclusive with
132 * RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT when used to formalize the
135 RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT = (1ULL << 13),
136 /**< Set if driver supports flexible parallel MAP engine decoding. If
137 * not supported, num_maps (number of MAP engines) argument is unusable.
139 RTE_BBDEV_TURBO_MAP_DEC = (1ULL << 14),
140 /**< Set if a device supports scatter-gather functionality */
141 RTE_BBDEV_TURBO_DEC_SCATTER_GATHER = (1ULL << 15)
144 /** Flags for turbo encoder operation and capability structure */
145 enum rte_bbdev_op_te_flag_bitmasks {
146 /**< Ignore rv_index and set K0 = 0 */
147 RTE_BBDEV_TURBO_RV_INDEX_BYPASS = (1ULL << 0),
148 /**< If rate matching is to be performed */
149 RTE_BBDEV_TURBO_RATE_MATCH = (1ULL << 1),
150 /**< This bit must be set to enable CRC-24B generation */
151 RTE_BBDEV_TURBO_CRC_24B_ATTACH = (1ULL << 2),
152 /**< This bit must be set to enable CRC-24A generation */
153 RTE_BBDEV_TURBO_CRC_24A_ATTACH = (1ULL << 3),
154 /**< Set if a device supports encoder dequeue interrupts */
155 RTE_BBDEV_TURBO_ENC_INTERRUPTS = (1ULL << 4),
156 /**< Set if a device supports scatter-gather functionality */
157 RTE_BBDEV_TURBO_ENC_SCATTER_GATHER = (1ULL << 5)
160 /**< Data input and output buffer for BBDEV operations */
161 struct rte_bbdev_op_data {
162 /**< The mbuf data structure representing the data for BBDEV operation.
164 * This mbuf pointer can point to one Code Block (CB) data buffer or
165 * multiple CBs contiguously located next to each other.
166 * A Transport Block (TB) represents a whole piece of data that is
167 * divided into one or more CBs. Maximum number of CBs can be contained
168 * in one TB is defined by RTE_BBDEV_MAX_CODE_BLOCKS.
170 * An mbuf data structure cannot represent more than one TB. The
171 * smallest piece of data that can be contained in one mbuf is one CB.
172 * An mbuf can include one contiguous CB, subset of contiguous CBs that
173 * are belonging to one TB, or all contiguous CBs that are belonging to
176 * If a BBDEV PMD supports the extended capability "Scatter-Gather",
177 * then it is capable of collecting (gathering) non-contiguous
178 * (scattered) data from multiple locations in the memory.
179 * This capability is reported by the capability flags:
180 * - RTE_BBDEV_TURBO_ENC_SCATTER_GATHER and
181 * - RTE_BBDEV_TURBO_DEC_SCATTER_GATHER.
182 * Only if a BBDEV PMD supports this feature, chained mbuf data
183 * structures are accepted. A chained mbuf can represent one
184 * non-contiguous CB or multiple non-contiguous CBs.
185 * If BBDEV PMD does not support this feature, it will assume inbound
186 * mbuf data contains one segment.
188 * The output mbuf data though is always one segment, even if the input
189 * was a chained mbuf.
191 struct rte_mbuf *data;
192 /**< The starting point of the BBDEV (encode/decode) operation,
195 * BBDEV starts to read data past this offset.
196 * In case of chained mbuf, this offset applies only to the first mbuf
200 /**< The total data length to be processed in one operation, in bytes.
202 * In case the mbuf data is representing one CB, this is the length of
203 * the CB undergoing the operation.
204 * If it's for multiple CBs, this is the total length of those CBs
205 * undergoing the operation.
206 * If it's for one TB, this is the total length of the TB under
209 * In case of chained mbuf, this data length includes the lengths of the
210 * "scattered" data segments undergoing the operation.
215 struct rte_bbdev_op_dec_cb_params {
216 /**< The K size of the input CB, in bits [40:6144], as specified in
218 * This size is inclusive of CRC bits, regardless whether it was
219 * pre-calculated by the application or not.
222 /**< The E length of the CB rate matched LLR output, in bytes, as in
228 struct rte_bbdev_op_dec_tb_params {
229 /**< The K- size of the input CB, in bits [40:6144], that is in the
230 * Turbo operation when r < C-, as in 3GPP TS 36.212.
233 /**< The K+ size of the input CB, in bits [40:6144], that is in the
234 * Turbo operation when r >= C-, as in 3GPP TS 36.212.
237 /**< The number of CBs that have K- size, [0:63] */
239 /**< The total number of CBs in the TB, [1:RTE_BBDEV_MAX_CODE_BLOCKS] */
241 /**< The number of CBs that uses Ea before switching to Eb, [0:63] */
243 /**< The E size of the CB rate matched output to use in the Turbo
244 * operation when r < cab
247 /**< The E size of the CB rate matched output to use in the Turbo
248 * operation when r >= cab
253 /**< Operation structure for Turbo decode.
254 * An operation can perform on one CB at a time "CB-mode".
255 * An operation can perform on one or multiple CBs that are logically belonging
256 * to one TB "TB-mode".
257 * The provided K size parameter of the CB is its size out coming from the
259 * CRC24A/B check is requested by the application by setting the flag
260 * RTE_BBDEV_TURBO_CRC_TYPE_24B for CRC24B check or CRC24A otherwise.
261 * In TB-mode, BBDEV concatenates the decoded CBs one next to the other with
262 * relevant CRC24B in between.
264 * The input encoded CB data is the Virtual Circular Buffer data stream, wk,
265 * with the null padding included as described in 3GPP TS 36.212
266 * section 5.1.4.1.2 and shown in 3GPP TS 36.212 section 5.1.4.1 Figure 5.1.4-1.
267 * The size of the virtual circular buffer is 3*Kpi, where Kpi is the 32 byte
268 * aligned value of K, as specified in 3GPP TS 36.212 section 5.1.4.1.1.
270 * Each byte in the input circular buffer is the LLR value of each bit of the
273 * Hard output is a mandatory capability that all BBDEV PMDs support. This is
274 * the decoded CBs of K sizes (CRC24A/B is the last 24-bit in each decoded CB).
275 * Soft output is an optional capability for BBDEV PMDs. If supported, an LLR
276 * rate matched output is computed in the soft_output buffer structure.
278 * The output mbuf data structure is expected to be allocated by the
279 * application with enough room for the output data.
281 struct rte_bbdev_op_turbo_dec {
282 /**< The Virtual Circular Buffer, wk, size 3*Kpi for each CB */
283 struct rte_bbdev_op_data input;
284 /**< The hard decisions buffer for the decoded output,
287 struct rte_bbdev_op_data hard_output;
288 /**< The soft LLR output buffer - optional */
289 struct rte_bbdev_op_data soft_output;
291 uint32_t op_flags; /**< Flags from rte_bbdev_op_td_flag_bitmasks */
292 uint8_t rv_index; /**< Rv index for rate matching [0:3] */
293 /**< The minimum number of iterations to perform in decoding all CBs in
294 * this operation - input
297 /**< The maximum number of iterations to perform in decoding all CBs in
298 * this operation - input
301 /**< The maximum number of iterations that were perform in decoding all
302 * CBs in this decode operation - output
305 /**< 5 bit extrinsic scale (scale factor on extrinsic info) */
307 /**< Number of MAP engines to use in decode,
308 * must be power of 2 (or 0 to auto-select)
312 uint8_t code_block_mode; /**< [0 - TB : 1 - CB] */
314 /**< Struct which stores Code Block specific parameters */
315 struct rte_bbdev_op_dec_cb_params cb_params;
316 /**< Struct which stores Transport Block specific parameters */
317 struct rte_bbdev_op_dec_tb_params tb_params;
321 struct rte_bbdev_op_enc_cb_params {
322 /**< The K size of the input CB, in bits [40:6144], as specified in
324 * This size is inclusive of CRC24A, regardless whether it was
325 * pre-calculated by the application or not.
328 /**< The E length of the CB rate matched output, in bits, as in
332 /**< The Ncb soft buffer size of the CB rate matched output [K:3*Kpi],
333 * in bits, as specified in 3GPP TS 36.212.
338 struct rte_bbdev_op_enc_tb_params {
339 /**< The K- size of the input CB, in bits [40:6144], that is in the
340 * Turbo operation when r < C-, as in 3GPP TS 36.212.
341 * This size is inclusive of CRC24B, regardless whether it was
342 * pre-calculated and appended by the application or not.
345 /**< The K+ size of the input CB, in bits [40:6144], that is in the
346 * Turbo operation when r >= C-, as in 3GPP TS 36.212.
347 * This size is inclusive of CRC24B, regardless whether it was
348 * pre-calculated and appended by the application or not.
351 /**< The number of CBs that have K- size, [0:63] */
353 /**< The total number of CBs in the TB, [1:RTE_BBDEV_MAX_CODE_BLOCKS] */
355 /**< The number of CBs that uses Ea before switching to Eb, [0:63] */
357 /**< The E size of the CB rate matched output to use in the Turbo
358 * operation when r < cab
361 /**< The E size of the CB rate matched output to use in the Turbo
362 * operation when r >= cab
365 /**< The Ncb soft buffer size for the rate matched CB that is used in
366 * the Turbo operation when r < C-, [K:3*Kpi]
369 /**< The Ncb soft buffer size for the rate matched CB that is used in
370 * the Turbo operation when r >= C-, [K:3*Kpi]
373 /**< The index of the first CB in the inbound mbuf data, default is 0 */
377 /**< Operation structure for Turbo encode.
378 * An operation can perform on one CB at a time "CB-mode".
379 * An operation can perform on one or multiple CBs that are logically
380 * belonging to one TB "TB-mode".
382 * In CB-mode, CRC24A/B is an optional operation. K size parameter is not
383 * affected by CRC24A/B inclusion, this only affects the inbound mbuf data
384 * length. Not all BBDEV PMDs are capable of CRC24A/B calculation. Flags
385 * RTE_BBDEV_TURBO_CRC_24A_ATTACH and RTE_BBDEV_TURBO_CRC_24B_ATTACH informs
386 * the application with relevant capability. These flags can be set in the
387 * op_flags parameter to indicate BBDEV to calculate and append CRC24A to CB
388 * before going forward with Turbo encoding.
390 * In TB-mode, CRC24A is assumed to be pre-calculated and appended to the
391 * inbound TB mbuf data buffer.
393 * The output mbuf data structure is expected to be allocated by the
394 * application with enough room for the output data.
396 struct rte_bbdev_op_turbo_enc {
397 /**< The input CB or TB data */
398 struct rte_bbdev_op_data input;
399 /**< The rate matched CB or TB output buffer */
400 struct rte_bbdev_op_data output;
402 uint32_t op_flags; /**< Flags from rte_bbdev_op_te_flag_bitmasks */
403 uint8_t rv_index; /**< Rv index for rate matching [0:3] */
405 uint8_t code_block_mode; /**< [0 - TB : 1 - CB] */
407 /**< Struct which stores Code Block specific parameters */
408 struct rte_bbdev_op_enc_cb_params cb_params;
409 /**< Struct which stores Transport Block specific parameters */
410 struct rte_bbdev_op_enc_tb_params tb_params;
414 /**< List of the capabilities for the Turbo Decoder */
415 struct rte_bbdev_op_cap_turbo_dec {
416 /**< Flags from rte_bbdev_op_td_flag_bitmasks */
417 uint32_t capability_flags;
418 uint8_t num_buffers_src; /**< Num input code block buffers */
419 /**< Num hard output code block buffers */
420 uint8_t num_buffers_hard_out;
421 /**< Num soft output code block buffers if supported by the driver */
422 uint8_t num_buffers_soft_out;
425 /**< List of the capabilities for the Turbo Encoder */
426 struct rte_bbdev_op_cap_turbo_enc {
427 /**< Flags from rte_bbdev_op_te_flag_bitmasks */
428 uint32_t capability_flags;
429 uint8_t num_buffers_src; /**< Num input code block buffers */
430 uint8_t num_buffers_dst; /**< Num output code block buffers */
433 /** Different operation types supported by the device */
434 enum rte_bbdev_op_type {
435 RTE_BBDEV_OP_NONE, /**< Dummy operation that does nothing */
436 RTE_BBDEV_OP_TURBO_DEC, /**< Turbo decode */
437 RTE_BBDEV_OP_TURBO_ENC, /**< Turbo encode */
438 RTE_BBDEV_OP_TYPE_COUNT, /**< Count of different op types */
441 /**< Bit indexes of possible errors reported through status field */
444 RTE_BBDEV_DATA_ERROR,
448 /**< Structure specifying a single encode operation */
449 struct rte_bbdev_enc_op {
450 int status; /**< Status of operation that was performed */
451 struct rte_mempool *mempool; /**< Mempool which op instance is in */
452 void *opaque_data; /**< Opaque pointer for user data */
453 /**< Contains encoder specific parameters */
454 struct rte_bbdev_op_turbo_enc turbo_enc;
457 /**< Structure specifying a single decode operation */
458 struct rte_bbdev_dec_op {
459 int status; /**< Status of operation that was performed */
460 struct rte_mempool *mempool; /**< Mempool which op instance is in */
461 void *opaque_data; /**< Opaque pointer for user data */
462 /**< Contains decoder specific parameters */
463 struct rte_bbdev_op_turbo_dec turbo_dec;
466 /**< Operation capabilities supported by a device */
467 struct rte_bbdev_op_cap {
468 enum rte_bbdev_op_type type; /**< Type of operation */
470 struct rte_bbdev_op_cap_turbo_dec turbo_dec;
471 struct rte_bbdev_op_cap_turbo_enc turbo_enc;
472 } cap; /**< Operation-type specific capabilities */
475 /**< @internal Private data structure stored with operation pool. */
476 struct rte_bbdev_op_pool_private {
477 enum rte_bbdev_op_type type; /**< Type of operations in a pool */
481 * Converts queue operation type from enum to string
484 * Operation type as enum
487 * Operation type as string or NULL if op_type is invalid
491 rte_bbdev_op_type_str(enum rte_bbdev_op_type op_type);
494 * Creates a bbdev operation mempool
499 * Operation type, use RTE_BBDEV_OP_NONE for a pool which supports all
501 * @param num_elements
502 * Number of elements in the pool.
504 * Number of elements to cache on an lcore, see rte_mempool_create() for
505 * further details about cache size.
507 * Socket to allocate memory on.
510 * - Pointer to a mempool on success,
511 * - NULL pointer on failure.
514 rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type,
515 unsigned int num_elements, unsigned int cache_size,
519 * Bulk allocate encode operations from a mempool with parameter defaults reset.
522 * Operation mempool, created by rte_bbdev_op_pool_create().
524 * Output array to place allocated operations
526 * Number of operations to allocate
530 * - EINVAL if invalid mempool is provided
533 rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool,
534 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
536 struct rte_bbdev_op_pool_private *priv;
540 priv = (struct rte_bbdev_op_pool_private *)
541 rte_mempool_get_priv(mempool);
542 if (unlikely(priv->type != RTE_BBDEV_OP_TURBO_ENC))
546 ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
547 if (unlikely(ret < 0))
550 rte_bbdev_log_verbose("%u encode ops allocated from %s\n",
551 num_ops, mempool->name);
557 * Bulk allocate decode operations from a mempool with parameter defaults reset.
560 * Operation mempool, created by rte_bbdev_op_pool_create().
562 * Output array to place allocated operations
564 * Number of operations to allocate
568 * - EINVAL if invalid mempool is provided
571 rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool,
572 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
574 struct rte_bbdev_op_pool_private *priv;
578 priv = (struct rte_bbdev_op_pool_private *)
579 rte_mempool_get_priv(mempool);
580 if (unlikely(priv->type != RTE_BBDEV_OP_TURBO_DEC))
584 ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
585 if (unlikely(ret < 0))
588 rte_bbdev_log_verbose("%u encode ops allocated from %s\n",
589 num_ops, mempool->name);
595 * Free decode operation structures that were allocated by
596 * rte_bbdev_dec_op_alloc_bulk().
597 * All structures must belong to the same mempool.
600 * Operation structures
602 * Number of structures
605 rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops, unsigned int num_ops)
608 rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
609 rte_bbdev_log_verbose("%u decode ops freed to %s\n", num_ops,
610 ops[0]->mempool->name);
615 * Free encode operation structures that were allocated by
616 * rte_bbdev_enc_op_alloc_bulk().
617 * All structures must belong to the same mempool.
620 * Operation structures
622 * Number of structures
625 rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops, unsigned int num_ops)
628 rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
629 rte_bbdev_log_verbose("%u encode ops freed to %s\n", num_ops,
630 ops[0]->mempool->name);
638 #endif /* _RTE_BBDEV_OP_H_ */