New upstream version 18.02
[deb_dpdk.git] / lib / librte_bbdev / rte_bbdev_op.h
diff --git a/lib/librte_bbdev/rte_bbdev_op.h b/lib/librte_bbdev/rte_bbdev_op.h
new file mode 100644 (file)
index 0000000..9a80c64
--- /dev/null
@@ -0,0 +1,574 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2017 Intel Corporation
+ */
+
+#ifndef _RTE_BBDEV_OP_H_
+#define _RTE_BBDEV_OP_H_
+
+/**
+ * @file rte_bbdev_op.h
+ *
+ * Defines wireless base band layer 1 operations and capabilities
+ *
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+
+#include <rte_common.h>
+#include <rte_mbuf.h>
+#include <rte_memory.h>
+#include <rte_mempool.h>
+
+#define RTE_BBDEV_MAX_CODE_BLOCKS 64
+
+/** Flags for turbo decoder operation and capability structure */
+enum rte_bbdev_op_td_flag_bitmasks {
+       /**< If sub block de-interleaving is to be performed. */
+       RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE = (1ULL << 0),
+       /**< To use CRC Type 24B (otherwise use CRC Type 24A). */
+       RTE_BBDEV_TURBO_CRC_TYPE_24B = (1ULL << 1),
+       /**< If turbo equalization is to be performed. */
+       RTE_BBDEV_TURBO_EQUALIZER = (1ULL << 2),
+       /**< If set, saturate soft output to +/-127 */
+       RTE_BBDEV_TURBO_SOFT_OUT_SATURATE = (1ULL << 3),
+       /**< Set to 1 to start iteration from even, else odd; one iteration =
+        * max_iteration + 0.5
+        */
+       RTE_BBDEV_TURBO_HALF_ITERATION_EVEN = (1ULL << 4),
+       /**< If 0, TD stops after CRC matches; else if 1, runs to end of next
+        * odd iteration after CRC matches
+        */
+       RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH = (1ULL << 5),
+       /**< Set if soft output is required to be output  */
+       RTE_BBDEV_TURBO_SOFT_OUTPUT = (1ULL << 6),
+       /**< Set to enable early termination mode */
+       RTE_BBDEV_TURBO_EARLY_TERMINATION = (1ULL << 7),
+       /**< Set if a device supports decoder dequeue interrupts */
+       RTE_BBDEV_TURBO_DEC_INTERRUPTS = (1ULL << 9),
+       /**< Set if positive LLR encoded input is supported. Positive LLR value
+        * represents the level of confidence for bit '1', and vice versa for
+        * bit '0'.
+        * This is mutually exclusive with RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN
+        * when used to formalize the input data format.
+        */
+       RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN = (1ULL << 10),
+       /**< Set if negative LLR encoded input is supported. Negative LLR value
+        * represents the level of confidence for bit '1', and vice versa for
+        * bit '0'.
+        * This is mutually exclusive with RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN
+        * when used to formalize the input data format.
+        */
+       RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN = (1ULL << 11),
+       /**< Set if positive LLR soft output is supported. Positive LLR value
+        * represents the level of confidence for bit '1', and vice versa for
+        * bit '0'.
+        * This is mutually exclusive with
+        * RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT when used to formalize
+        * the input data format.
+        */
+       RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT = (1ULL << 12),
+       /**< Set if negative LLR soft output is supported. Negative LLR value
+        * represents the level of confidence for bit '1', and vice versa for
+        * bit '0'.
+        * This is mutually exclusive with
+        * RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT when used to formalize the
+        * input data format.
+        */
+       RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT = (1ULL << 13),
+       /**< Set if driver supports flexible parallel MAP engine decoding. If
+        * not supported, num_maps (number of MAP engines) argument is unusable.
+        */
+       RTE_BBDEV_TURBO_MAP_DEC = (1ULL << 14),
+       /**< Set if a device supports scatter-gather functionality */
+       RTE_BBDEV_TURBO_DEC_SCATTER_GATHER = (1ULL << 15)
+};
+
+/** Flags for turbo encoder operation and capability structure */
+enum rte_bbdev_op_te_flag_bitmasks {
+       /**< Ignore rv_index and set K0 = 0 */
+       RTE_BBDEV_TURBO_RV_INDEX_BYPASS = (1ULL << 0),
+       /**< If rate matching is to be performed */
+       RTE_BBDEV_TURBO_RATE_MATCH = (1ULL << 1),
+       /**< This bit must be set to enable CRC-24B generation */
+       RTE_BBDEV_TURBO_CRC_24B_ATTACH = (1ULL << 2),
+       /**< This bit must be set to enable CRC-24A generation */
+       RTE_BBDEV_TURBO_CRC_24A_ATTACH = (1ULL << 3),
+       /**< Set if a device supports encoder dequeue interrupts */
+       RTE_BBDEV_TURBO_ENC_INTERRUPTS = (1ULL << 4),
+       /**< Set if a device supports scatter-gather functionality */
+       RTE_BBDEV_TURBO_ENC_SCATTER_GATHER = (1ULL << 5)
+};
+
+/**< Data input and output buffer for BBDEV operations */
+struct rte_bbdev_op_data {
+       /**< The mbuf data structure representing the data for BBDEV operation.
+        *
+        * This mbuf pointer can point to one Code Block (CB) data buffer or
+        * multiple CBs contiguously located next to each other.
+        * A Transport Block (TB) represents a whole piece of data that is
+        * divided into one or more CBs. Maximum number of CBs can be contained
+        * in one TB is defined by RTE_BBDEV_MAX_CODE_BLOCKS.
+        *
+        * An mbuf data structure cannot represent more than one TB. The
+        * smallest piece of data that can be contained in one mbuf is one CB.
+        * An mbuf can include one contiguous CB, subset of contiguous CBs that
+        * are belonging to one TB, or all contiguous CBs that are belonging to
+        * one TB.
+        *
+        * If a BBDEV PMD supports the extended capability "Scatter-Gather",
+        * then it is capable of collecting (gathering) non-contiguous
+        * (scattered) data from multiple locations in the memory.
+        * This capability is reported by the capability flags:
+        * - RTE_BBDEV_TURBO_ENC_SCATTER_GATHER and
+        * - RTE_BBDEV_TURBO_DEC_SCATTER_GATHER.
+        * Only if a BBDEV PMD supports this feature, chained mbuf data
+        * structures are accepted. A chained mbuf can represent one
+        * non-contiguous CB or multiple non-contiguous CBs.
+        * If BBDEV PMD does not support this feature, it will assume inbound
+        * mbuf data contains one segment.
+        *
+        * The output mbuf data though is always one segment, even if the input
+        * was a chained mbuf.
+        */
+       struct rte_mbuf *data;
+       /**< The starting point of the BBDEV (encode/decode) operation,
+        * in bytes.
+        *
+        * BBDEV starts to read data past this offset.
+        * In case of chained mbuf, this offset applies only to the first mbuf
+        * segment.
+        */
+       uint32_t offset;
+       /**< The total data length to be processed in one operation, in bytes.
+        *
+        * In case the mbuf data is representing one CB, this is the length of
+        * the CB undergoing the operation.
+        * If it's for multiple CBs, this is the total length of those CBs
+        * undergoing the operation.
+        * If it's for one TB, this is the total length of the TB under
+        * operation.
+        *
+        * In case of chained mbuf, this data length includes the lengths of the
+        * "scattered" data segments undergoing the operation.
+        */
+       uint32_t length;
+};
+
+struct rte_bbdev_op_dec_cb_params {
+       /**< The K size of the input CB, in bits [40:6144], as specified in
+        * 3GPP TS 36.212.
+        * This size is inclusive of CRC bits, regardless whether it was
+        * pre-calculated by the application or not.
+        */
+       uint16_t k;
+       /**< The E length of the CB rate matched LLR output, in bytes, as in
+        * 3GPP TS 36.212.
+        */
+       uint32_t e;
+};
+
+struct rte_bbdev_op_dec_tb_params {
+       /**< The K- size of the input CB, in bits [40:6144], that is in the
+        * Turbo operation when r < C-, as in 3GPP TS 36.212.
+        */
+       uint16_t k_neg;
+       /**< The K+ size of the input CB, in bits [40:6144], that is in the
+        * Turbo operation when r >= C-, as in 3GPP TS 36.212.
+        */
+       uint16_t k_pos;
+       /**< The number of CBs that have K- size, [0:63] */
+       uint8_t c_neg;
+       /**< The total number of CBs in the TB, [1:RTE_BBDEV_MAX_CODE_BLOCKS] */
+       uint8_t c;
+       /**< The number of CBs that uses Ea before switching to Eb, [0:63] */
+       uint8_t cab;
+       /**< The E size of the CB rate matched output to use in the Turbo
+        * operation when r < cab
+        */
+       uint32_t ea;
+       /**< The E size of the CB rate matched output to use in the Turbo
+        * operation when r >= cab
+        */
+       uint32_t eb;
+};
+
+/**< Operation structure for Turbo decode.
+ * An operation can perform on one CB at a time "CB-mode".
+ * An operation can perform on one or multiple CBs that are logically belonging
+ * to one TB "TB-mode".
+ * The provided K size parameter of the CB is its size out coming from the
+ * decode operation.
+ * CRC24A/B check is requested by the application by setting the flag
+ * RTE_BBDEV_TURBO_CRC_TYPE_24B for CRC24B check or CRC24A otherwise.
+ * In TB-mode, BBDEV concatenates the decoded CBs one next to the other with
+ * relevant CRC24B in between.
+ *
+ * The input encoded CB data is the Virtual Circular Buffer data stream, wk,
+ * with the null padding included as described in 3GPP TS 36.212
+ * section 5.1.4.1.2 and shown in 3GPP TS 36.212 section 5.1.4.1 Figure 5.1.4-1.
+ * The size of the virtual circular buffer is 3*Kpi, where Kpi is the 32 byte
+ * aligned value of K, as specified in 3GPP TS 36.212 section 5.1.4.1.1.
+ *
+ * Each byte in the input circular buffer is the LLR value of each bit of the
+ * original CB.
+ *
+ * Hard output is a mandatory capability that all BBDEV PMDs support. This is
+ * the decoded CBs of K sizes (CRC24A/B is the last 24-bit in each decoded CB).
+ * Soft output is an optional capability for BBDEV PMDs. If supported, an LLR
+ * rate matched output is computed in the soft_output buffer structure.
+ *
+ * The output mbuf data structure is expected to be allocated by the
+ * application with enough room for the output data.
+ */
+struct rte_bbdev_op_turbo_dec {
+       /**< The Virtual Circular Buffer, wk, size 3*Kpi for each CB */
+       struct rte_bbdev_op_data input;
+       /**< The hard decisions buffer for the decoded output,
+        * size K for each CB
+        */
+       struct rte_bbdev_op_data hard_output;
+       /**< The soft LLR output buffer - optional */
+       struct rte_bbdev_op_data soft_output;
+
+       uint32_t op_flags;  /**< Flags from rte_bbdev_op_td_flag_bitmasks */
+       uint8_t rv_index;  /**< Rv index for rate matching [0:3] */
+       /**< The minimum number of iterations to perform in decoding all CBs in
+        * this operation - input
+        */
+       uint8_t iter_min:4;
+       /**< The maximum number of iterations to perform in decoding all CBs in
+        * this operation - input
+        */
+       uint8_t iter_max:4;
+       /**< The maximum number of iterations that were perform in decoding all
+        * CBs in this decode operation - output
+        */
+       uint8_t iter_count;
+       /**< 5 bit extrinsic scale (scale factor on extrinsic info) */
+       uint8_t ext_scale;
+       /**< Number of MAP engines to use in decode,
+        * must be power of 2 (or 0 to auto-select)
+        */
+       uint8_t num_maps;
+
+       uint8_t code_block_mode; /**< [0 - TB : 1 - CB] */
+       union {
+               /**< Struct which stores Code Block specific parameters */
+               struct rte_bbdev_op_dec_cb_params cb_params;
+               /**< Struct which stores Transport Block specific parameters */
+               struct rte_bbdev_op_dec_tb_params tb_params;
+       };
+};
+
+struct rte_bbdev_op_enc_cb_params {
+       /**< The K size of the input CB, in bits [40:6144], as specified in
+        * 3GPP TS 36.212.
+        * This size is inclusive of CRC24A, regardless whether it was
+        * pre-calculated by the application or not.
+        */
+       uint16_t k;
+       /**< The E length of the CB rate matched output, in bits, as in
+        * 3GPP TS 36.212.
+        */
+       uint32_t e;
+       /**< The Ncb soft buffer size of the CB rate matched output [K:3*Kpi],
+        * in bits, as specified in 3GPP TS 36.212.
+        */
+       uint16_t ncb;
+};
+
+struct rte_bbdev_op_enc_tb_params {
+       /**< The K- size of the input CB, in bits [40:6144], that is in the
+        * Turbo operation when r < C-, as in 3GPP TS 36.212.
+        * This size is inclusive of CRC24B, regardless whether it was
+        * pre-calculated and appended by the application or not.
+        */
+       uint16_t k_neg;
+       /**< The K+ size of the input CB, in bits [40:6144], that is in the
+        * Turbo operation when r >= C-, as in 3GPP TS 36.212.
+        * This size is inclusive of CRC24B, regardless whether it was
+        * pre-calculated and appended by the application or not.
+        */
+       uint16_t k_pos;
+       /**< The number of CBs that have K- size, [0:63] */
+       uint8_t c_neg;
+       /**< The total number of CBs in the TB, [1:RTE_BBDEV_MAX_CODE_BLOCKS] */
+       uint8_t c;
+       /**< The number of CBs that uses Ea before switching to Eb, [0:63] */
+       uint8_t cab;
+       /**< The E size of the CB rate matched output to use in the Turbo
+        * operation when r < cab
+        */
+       uint32_t ea;
+       /**< The E size of the CB rate matched output to use in the Turbo
+        * operation when r >= cab
+        */
+       uint32_t eb;
+       /**< The Ncb soft buffer size for the rate matched CB that is used in
+        * the Turbo operation when r < C-, [K:3*Kpi]
+        */
+       uint16_t ncb_neg;
+       /**< The Ncb soft buffer size for the rate matched CB that is used in
+        * the Turbo operation when r >= C-, [K:3*Kpi]
+        */
+       uint16_t ncb_pos;
+       /**< The index of the first CB in the inbound mbuf data, default is 0 */
+       uint8_t r;
+};
+
+/**< Operation structure for Turbo encode.
+ * An operation can perform on one CB at a time "CB-mode".
+ * An operation can perform on one or multiple CBs that are logically
+ * belonging to one TB "TB-mode".
+ *
+ * In CB-mode, CRC24A/B is an optional operation. K size parameter is not
+ * affected by CRC24A/B inclusion, this only affects the inbound mbuf data
+ * length. Not all BBDEV PMDs are capable of CRC24A/B calculation. Flags
+ * RTE_BBDEV_TURBO_CRC_24A_ATTACH and RTE_BBDEV_TURBO_CRC_24B_ATTACH informs
+ * the application with relevant capability. These flags can be set in the
+ * op_flags parameter to indicate BBDEV to calculate and append CRC24A to CB
+ * before going forward with Turbo encoding.
+ *
+ * In TB-mode, CRC24A is assumed to be pre-calculated and appended to the
+ * inbound TB mbuf data buffer.
+ *
+ * The output mbuf data structure is expected to be allocated by the
+ * application with enough room for the output data.
+ */
+struct rte_bbdev_op_turbo_enc {
+       /**< The input CB or TB data */
+       struct rte_bbdev_op_data input;
+       /**< The rate matched CB or TB output buffer */
+       struct rte_bbdev_op_data output;
+
+       uint32_t op_flags;  /**< Flags from rte_bbdev_op_te_flag_bitmasks */
+       uint8_t rv_index;  /**< Rv index for rate matching [0:3] */
+
+       uint8_t code_block_mode; /**< [0 - TB : 1 - CB] */
+       union {
+               /**< Struct which stores Code Block specific parameters */
+               struct rte_bbdev_op_enc_cb_params cb_params;
+               /**< Struct which stores Transport Block specific parameters */
+               struct rte_bbdev_op_enc_tb_params tb_params;
+       };
+};
+
+/**< List of the capabilities for the Turbo Decoder */
+struct rte_bbdev_op_cap_turbo_dec {
+       /**< Flags from rte_bbdev_op_td_flag_bitmasks */
+       uint32_t capability_flags;
+       uint8_t num_buffers_src;  /**< Num input code block buffers */
+       /**< Num hard output code block buffers */
+       uint8_t num_buffers_hard_out;
+       /**< Num soft output code block buffers if supported by the driver */
+       uint8_t num_buffers_soft_out;
+};
+
+/**< List of the capabilities for the Turbo Encoder */
+struct rte_bbdev_op_cap_turbo_enc {
+       /**< Flags from rte_bbdev_op_te_flag_bitmasks */
+       uint32_t capability_flags;
+       uint8_t num_buffers_src;  /**< Num input code block buffers */
+       uint8_t num_buffers_dst;  /**< Num output code block buffers */
+};
+
+/** Different operation types supported by the device */
+enum rte_bbdev_op_type {
+       RTE_BBDEV_OP_NONE,  /**< Dummy operation that does nothing */
+       RTE_BBDEV_OP_TURBO_DEC,  /**< Turbo decode */
+       RTE_BBDEV_OP_TURBO_ENC,  /**< Turbo encode */
+       RTE_BBDEV_OP_TYPE_COUNT,  /**< Count of different op types */
+};
+
+/**< Bit indexes of possible errors reported through status field */
+enum {
+       RTE_BBDEV_DRV_ERROR,
+       RTE_BBDEV_DATA_ERROR,
+       RTE_BBDEV_CRC_ERROR,
+};
+
+/**< Structure specifying a single encode operation */
+struct rte_bbdev_enc_op {
+       int status;  /**< Status of operation that was performed */
+       struct rte_mempool *mempool;  /**< Mempool which op instance is in */
+       void *opaque_data;  /**< Opaque pointer for user data */
+       /**< Contains encoder specific parameters */
+       struct rte_bbdev_op_turbo_enc turbo_enc;
+};
+
+/**< Structure specifying a single decode operation */
+struct rte_bbdev_dec_op {
+       int status;  /**< Status of operation that was performed */
+       struct rte_mempool *mempool;  /**< Mempool which op instance is in */
+       void *opaque_data;  /**< Opaque pointer for user data */
+       /**< Contains decoder specific parameters */
+       struct rte_bbdev_op_turbo_dec turbo_dec;
+};
+
+/**< Operation capabilities supported by a device */
+struct rte_bbdev_op_cap {
+       enum rte_bbdev_op_type type;  /**< Type of operation */
+       union {
+               struct rte_bbdev_op_cap_turbo_dec turbo_dec;
+               struct rte_bbdev_op_cap_turbo_enc turbo_enc;
+       } cap;  /**< Operation-type specific capabilities */
+};
+
+/**< @internal Private data structure stored with operation pool. */
+struct rte_bbdev_op_pool_private {
+       enum rte_bbdev_op_type type;  /**< Type of operations in a pool */
+};
+
+/**
+ * Converts queue operation type from enum to string
+ *
+ * @param op_type
+ *   Operation type as enum
+ *
+ * @returns
+ *   Operation type as string or NULL if op_type is invalid
+ *
+ */
+const char*
+rte_bbdev_op_type_str(enum rte_bbdev_op_type op_type);
+
+/**
+ * Creates a bbdev operation mempool
+ *
+ * @param name
+ *   Pool name.
+ * @param type
+ *   Operation type, use RTE_BBDEV_OP_NONE for a pool which supports all
+ *   operation types.
+ * @param num_elements
+ *   Number of elements in the pool.
+ * @param cache_size
+ *   Number of elements to cache on an lcore, see rte_mempool_create() for
+ *   further details about cache size.
+ * @param socket_id
+ *   Socket to allocate memory on.
+ *
+ * @return
+ *   - Pointer to a mempool on success,
+ *   - NULL pointer on failure.
+ */
+struct rte_mempool *
+rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type,
+               unsigned int num_elements, unsigned int cache_size,
+               int socket_id);
+
+/**
+ * Bulk allocate encode operations from a mempool with parameter defaults reset.
+ *
+ * @param mempool
+ *   Operation mempool, created by rte_bbdev_op_pool_create().
+ * @param ops
+ *   Output array to place allocated operations
+ * @param num_ops
+ *   Number of operations to allocate
+ *
+ * @returns
+ *   - 0 on success
+ *   - EINVAL if invalid mempool is provided
+ */
+static inline int
+rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool,
+               struct rte_bbdev_enc_op **ops, uint16_t num_ops)
+{
+       struct rte_bbdev_op_pool_private *priv;
+       int ret;
+
+       /* Check type */
+       priv = (struct rte_bbdev_op_pool_private *)
+                       rte_mempool_get_priv(mempool);
+       if (unlikely(priv->type != RTE_BBDEV_OP_TURBO_ENC))
+               return -EINVAL;
+
+       /* Get elements */
+       ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
+       if (unlikely(ret < 0))
+               return ret;
+
+       return 0;
+}
+
+/**
+ * Bulk allocate decode operations from a mempool with parameter defaults reset.
+ *
+ * @param mempool
+ *   Operation mempool, created by rte_bbdev_op_pool_create().
+ * @param ops
+ *   Output array to place allocated operations
+ * @param num_ops
+ *   Number of operations to allocate
+ *
+ * @returns
+ *   - 0 on success
+ *   - EINVAL if invalid mempool is provided
+ */
+static inline int
+rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool,
+               struct rte_bbdev_dec_op **ops, uint16_t num_ops)
+{
+       struct rte_bbdev_op_pool_private *priv;
+       int ret;
+
+       /* Check type */
+       priv = (struct rte_bbdev_op_pool_private *)
+                       rte_mempool_get_priv(mempool);
+       if (unlikely(priv->type != RTE_BBDEV_OP_TURBO_DEC))
+               return -EINVAL;
+
+       /* Get elements */
+       ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
+       if (unlikely(ret < 0))
+               return ret;
+
+       return 0;
+}
+
+/**
+ * Free decode operation structures that were allocated by
+ * rte_bbdev_dec_op_alloc_bulk().
+ * All structures must belong to the same mempool.
+ *
+ * @param ops
+ *   Operation structures
+ * @param num_ops
+ *   Number of structures
+ */
+static inline void
+rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops, unsigned int num_ops)
+{
+       if (num_ops > 0)
+               rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
+}
+
+/**
+ * Free encode operation structures that were allocated by
+ * rte_bbdev_enc_op_alloc_bulk().
+ * All structures must belong to the same mempool.
+ *
+ * @param ops
+ *   Operation structures
+ * @param num_ops
+ *   Number of structures
+ */
+static inline void
+rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops, unsigned int num_ops)
+{
+       if (num_ops > 0)
+               rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _RTE_BBDEV_OP_H_ */