Re: [PATCH v2 1/5] bbdev: add operation type for MLDTS procession

[Maxime Coquelin <maxime.coquelin@redhat.com>]

On 6/15/23 18:48, Nicolas Chautru wrote:
> Extended bbdev operations to support MLDTS based operations.
> 
> Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>
> ---
>   doc/guides/prog_guide/bbdev.rst |  53 +++++++++++++++
>   lib/bbdev/rte_bbdev.c           |  11 ++-
>   lib/bbdev/rte_bbdev.h           |  76 +++++++++++++++++++++
>   lib/bbdev/rte_bbdev_op.h        | 116 +++++++++++++++++++++++++++++++-
>   lib/bbdev/version.map           |   5 ++
>   5 files changed, 259 insertions(+), 2 deletions(-)
> 
> diff --git a/doc/guides/prog_guide/bbdev.rst b/doc/guides/prog_guide/bbdev.rst
> index 549f1d002a..8e384015ee 100644
> --- a/doc/guides/prog_guide/bbdev.rst
> +++ b/doc/guides/prog_guide/bbdev.rst
> @@ -1165,6 +1165,59 @@ either as 2 INT16 or as 2 FP16 based when the option supported.
>   The data layout is based on contiguous concatenation of output data
>   first by cyclic shift then by antenna.
>   
> +BBDEV MLD-TS Operation
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +This operation allows to run the Tree Search (TS) portion of a Maximum Likelihood processing (MLD).
> +
> +This alternate equalization option accelerates the exploration of the best combination of
> +transmitted symbols across layers minimizing the Euclidean distance between the received and
> +reconstructed signal, then generates the LLRs to be used by the LDPC Decoder.
> +The input is the results of the Q R decomposition: Q^Hy signal and R matrix.
> +
> +The structure passed for each MLD-TS operation is given below,
> +with the operation flags forming a bitmask in the ``op_flags`` field.
> +
> +  **NOTE:** The actual operation flags that may be used with a specific
> +  bbdev PMD are dependent on the driver capabilities as reported via
> +  ``rte_bbdev_info_get()``, and may be a subset of those below.
> +
> +.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h
> +   :language: c
> +   :start-after: Structure rte_bbdev_op_mldts 8<
> +   :end-before: >8 End of structure rte_bbdev_op_mldts.
> +
> ++--------------------------------------------------------------------+
> +|Description of MLD-TS capability flags                              |
> ++====================================================================+
> +|RTE_BBDEV_MLDTS_REP                                                 |
> +| Set if the option to use repeated data from R channel is supported |
> ++--------------------------------------------------------------------+
> +
> +The MLD-TS parameters are set out in the table below.
> +
> ++-------------------------+--------------------------------------------------------------+
> +|Parameter                |Description                                                   |
> ++=========================+==============================================================+
> +|qhy_input                |input data qHy                                                |
> ++-------------------------+--------------------------------------------------------------+
> +|r_input                  |input data R triangular matrix                                |
> ++-------------------------+--------------------------------------------------------------+
> +|output                   |output data (LLRs)                                            |
> ++-------------------------+--------------------------------------------------------------+
> +|op_flags                 |bitmask of all active operation capabilities                  |
> ++-------------------------+--------------------------------------------------------------+
> +|num_rbs                  |number of Resource Blocks                                     |
> ++-------------------------+--------------------------------------------------------------+
> +|num_layers               |number of overlapping layers                                  |
> ++-------------------------+--------------------------------------------------------------+
> +|q_m                      |array of modulation order for each layer                      |
> ++-------------------------+--------------------------------------------------------------+
> +|r_rep                    |optional row repetition for the R matrix (subcarriers)        |
> ++-------------------------+--------------------------------------------------------------+
> +|c_rep                    |optional column repetition for the R matrix (symbols)         |
> ++-------------------------+--------------------------------------------------------------+
> +
>   Sample code
>   -----------
>   
> diff --git a/lib/bbdev/rte_bbdev.c b/lib/bbdev/rte_bbdev.c
> index 1521cdbc53..26fc077bdc 100644
> --- a/lib/bbdev/rte_bbdev.c
> +++ b/lib/bbdev/rte_bbdev.c
> @@ -24,7 +24,7 @@
>   #define DEV_NAME "BBDEV"
>   
>   /* Number of supported operation types in *rte_bbdev_op_type*. */
> -#define BBDEV_OP_TYPE_COUNT 6
> +#define BBDEV_OP_TYPE_COUNT 7
>   
>   /* BBDev library logging ID */
>   RTE_LOG_REGISTER_DEFAULT(bbdev_logtype, NOTICE);
> @@ -857,6 +857,9 @@ get_bbdev_op_size(enum rte_bbdev_op_type type)
>   	case RTE_BBDEV_OP_FFT:
>   		result = sizeof(struct rte_bbdev_fft_op);
>   		break;
> +	case RTE_BBDEV_OP_MLDTS:
> +		result = sizeof(struct rte_bbdev_mldts_op);
> +		break;
>   	default:
>   		break;
>   	}
> @@ -884,6 +887,10 @@ bbdev_op_init(struct rte_mempool *mempool, void *arg, void *element,
>   		struct rte_bbdev_fft_op *op = element;
>   		memset(op, 0, mempool->elt_size);
>   		op->mempool = mempool;
> +	} else if (type == RTE_BBDEV_OP_MLDTS) {
> +		struct rte_bbdev_mldts_op *op = element;
> +		memset(op, 0, mempool->elt_size);
> +		op->mempool = mempool;
>   	}
>   }
>   
> @@ -1135,6 +1142,7 @@ rte_bbdev_op_type_str(enum rte_bbdev_op_type op_type)
>   		"RTE_BBDEV_OP_LDPC_DEC",
>   		"RTE_BBDEV_OP_LDPC_ENC",
>   		"RTE_BBDEV_OP_FFT",
> +		"RTE_BBDEV_OP_MLDTS",
>   	};
>   
>   	if (op_type < BBDEV_OP_TYPE_COUNT)
> @@ -1184,3 +1192,4 @@ rte_bbdev_enqueue_status_str(enum rte_bbdev_enqueue_status status)
>   	rte_bbdev_log(ERR, "Invalid enqueue status");
>   	return NULL;
>   }
> +
> diff --git a/lib/bbdev/rte_bbdev.h b/lib/bbdev/rte_bbdev.h
> index 52f6ed9b01..a5bcc09f10 100644
> --- a/lib/bbdev/rte_bbdev.h
> +++ b/lib/bbdev/rte_bbdev.h
> @@ -438,6 +438,12 @@ typedef uint16_t (*rte_bbdev_enqueue_fft_ops_t)(
>   		struct rte_bbdev_fft_op **ops,
>   		uint16_t num);
>   
> +/** @internal Enqueue MLD-TS operations for processing on queue of a device. */
> +typedef uint16_t (*rte_bbdev_enqueue_mldts_ops_t)(
> +		struct rte_bbdev_queue_data *q_data,
> +		struct rte_bbdev_mldts_op **ops,
> +		uint16_t num);
> +
>   /** @internal Dequeue encode operations from a queue of a device. */
>   typedef uint16_t (*rte_bbdev_dequeue_enc_ops_t)(
>   		struct rte_bbdev_queue_data *q_data,
> @@ -453,6 +459,11 @@ typedef uint16_t (*rte_bbdev_dequeue_fft_ops_t)(
>   		struct rte_bbdev_queue_data *q_data,
>   		struct rte_bbdev_fft_op **ops, uint16_t num);
>   
> +/** @internal Dequeue MLDTS operations from a queue of a device. */
> +typedef uint16_t (*rte_bbdev_dequeue_mldts_ops_t)(
> +		struct rte_bbdev_queue_data *q_data,
> +		struct rte_bbdev_mldts_op **ops, uint16_t num);
> +
>   #define RTE_BBDEV_NAME_MAX_LEN  64  /**< Max length of device name */
>   
>   /**
> @@ -512,6 +523,10 @@ struct __rte_cache_aligned rte_bbdev {
>   	/** User application callback for interrupts if present */
>   	struct rte_bbdev_cb_list list_cbs;
>   	struct rte_intr_handle *intr_handle; /**< Device interrupt handle */
> +	/** Enqueue MLD-TS function */
> +	rte_bbdev_enqueue_mldts_ops_t enqueue_mldts_ops;
> +	/** Dequeue MLD-TS function */
> +	rte_bbdev_dequeue_mldts_ops_t dequeue_mldts_ops;
>   };
>   
>   /** @internal array of all devices */
> @@ -668,6 +683,36 @@ rte_bbdev_enqueue_fft_ops(uint16_t dev_id, uint16_t queue_id,
>   	return dev->enqueue_fft_ops(q_data, ops, num_ops);
>   }
>   
> +/**
> + * Enqueue a burst of MLDTS operations to a queue of the device.
> + * This functions only enqueues as many operations as currently possible and
> + * does not block until @p num_ops entries in the queue are available.
> + * This function does not provide any error notification to avoid the
> + * corresponding overhead.
> + *
> + * @param dev_id
> + *   The identifier of the device.
> + * @param queue_id
> + *   The index of the queue.
> + * @param ops
> + *   Pointer array containing operations to be enqueued Must have at least
> + *   @p num_ops entries
> + * @param num_ops
> + *   The maximum number of operations to enqueue.
> + *
> + * @return
> + *   The number of operations actually enqueued (this is the number of processed
> + *   entries in the @p ops array).
> + */
> +static inline uint16_t
> +rte_bbdev_enqueue_mldts_ops(uint16_t dev_id, uint16_t queue_id,
> +		struct rte_bbdev_mldts_op **ops, uint16_t num_ops)
> +{
> +	struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
> +	struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
> +	return dev->enqueue_mldts_ops(q_data, ops, num_ops);
> +}
> +
>   /**
>    * Dequeue a burst of processed encode operations from a queue of the device.
>    * This functions returns only the current contents of the queue,
> @@ -823,6 +868,37 @@ rte_bbdev_dequeue_fft_ops(uint16_t dev_id, uint16_t queue_id,
>   	return dev->dequeue_fft_ops(q_data, ops, num_ops);
>   }
>   
> +/**
> + * Dequeue a burst of MLDTS operations from a queue of the device.
> + * This functions returns only the current contents of the queue, and does not
> + * block until @p num_ops is available.
> + * This function does not provide any error notification to avoid the
> + * corresponding overhead.
> + *
> + * @param dev_id
> + *   The identifier of the device.
> + * @param queue_id
> + *   The index of the queue.
> + * @param ops
> + *   Pointer array where operations will be dequeued to. Must have at least
> + *   @p num_ops entries
> + * @param num_ops
> + *   The maximum number of operations to dequeue.
> + *
> + * @return
> + *   The number of operations actually dequeued (this is the number of entries
> + *   copied into the @p ops array).
> + */
> +__rte_experimental
> +static inline uint16_t
> +rte_bbdev_dequeue_mldts_ops(uint16_t dev_id, uint16_t queue_id,
> +		struct rte_bbdev_mldts_op **ops, uint16_t num_ops)
> +{
> +	struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
> +	struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
> +	return dev->dequeue_mldts_ops(q_data, ops, num_ops);
> +}
> +
>   /** Definitions of device event types */
>   enum rte_bbdev_event_type {
>   	RTE_BBDEV_EVENT_UNKNOWN,  /**< unknown event type */
> diff --git a/lib/bbdev/rte_bbdev_op.h b/lib/bbdev/rte_bbdev_op.h
> index 96a390cd9b..990d110fa7 100644
> --- a/lib/bbdev/rte_bbdev_op.h
> +++ b/lib/bbdev/rte_bbdev_op.h
> @@ -50,6 +50,10 @@ extern "C" {
>   #define RTE_BBDEV_LDPC_MAX_CODE_BLOCKS (256)
>   /* 12 CS maximum */
>   #define RTE_BBDEV_MAX_CS_2 (6)
> +/* MLD-TS up to 4 layers */
> +#define RTE_BBDEV_MAX_MLD_LAYERS (4)
> +/* 12 SB per RB */
> +#define RTE_BBDEV_SCPERRB (12)
>   
>   /*
>    * Maximum size to be used to manage the enum rte_bbdev_op_type
> @@ -241,6 +245,12 @@ enum rte_bbdev_op_fft_flag_bitmasks {
>   	RTE_BBDEV_FFT_FP16_OUTPUT = (1ULL << 7)
>   };
>   
> +/** Flags for MLDTS operation and capability structure */
> +enum rte_bbdev_op_mldts_flag_bitmasks {
> +	/**  Set if the device supports C/R repetition options.  */
> +	RTE_BBDEV_MLDTS_REP = (1ULL << 0),
> +};
> +
>   /** Flags for the Code Block/Transport block mode  */
>   enum rte_bbdev_op_cb_mode {
>   	/** One operation is one or fraction of one transport block  */
> @@ -783,6 +793,36 @@ struct rte_bbdev_op_fft {
>   };
>   /* >8 End of structure rte_bbdev_op_fft. */
>   
> +/** Operation structure for MLDTS processing.
> + *
> + * The output mbuf data structure is expected to be allocated by the
> + * application with enough room for the output data.
> + */
> +
> +/* Structure rte_bbdev_op_mldts 8< */
> +struct rte_bbdev_op_mldts {
> +	/** Input data QHy from QR decomposition. */
> +	struct rte_bbdev_op_data qhy_input;
> +	/** Input data R from QR decomposition. */
> +	struct rte_bbdev_op_data r_input;
> +	/** Output data post MLD-TS. */
> +	struct rte_bbdev_op_data output;
> +	/** Flags from *rte_bbdev_op_MLDTS_flag_bitmasks*. */
> +	uint32_t op_flags;
> +	/** Number of RBs. */
> +	uint16_t num_rbs;
> +	/** Number of layers 2->4. */
> +	uint16_t num_layers;
> +	/** Modulation order (2->8 QPSK to 256QAM). */
> +	uint8_t q_m[RTE_BBDEV_MAX_MLD_LAYERS];
> +	/** Row repetition for the same R matrix - subcarriers. */
> +	uint8_t r_rep;
> +	/** Column repetition for the same R matrix - symbols. */
> +	uint8_t c_rep;
> +};
> +/* >8 End of structure rte_bbdev_op_mldts. */
> +
> +
>   /** List of the capabilities for the Turbo Decoder */
>   struct rte_bbdev_op_cap_turbo_dec {
>   	/** Flags from rte_bbdev_op_td_flag_bitmasks */
> @@ -839,6 +879,16 @@ struct rte_bbdev_op_cap_ldpc_enc {
>   struct rte_bbdev_op_cap_fft {
>   	/** Flags from *rte_bbdev_op_fft_flag_bitmasks*. */
>   	uint32_t capability_flags;
> +	/** Num input code block buffers. */
> +	uint16_t num_buffers_src;
> +	/** Num output code block buffers. */
> +	uint16_t num_buffers_dst;
> +};
> +
> +/** List of the capabilities for the MLD */
> +struct rte_bbdev_op_cap_mld {
> +	/** Flags from rte_bbdev_op_mldts_flag_bitmasks */
> +	uint32_t capability_flags;
>   	/** Number of input code block buffers. */
>   	uint16_t num_buffers_src;
>   	/** Number of output code block buffers. */
> @@ -856,6 +906,7 @@ enum rte_bbdev_op_type {
>   	RTE_BBDEV_OP_LDPC_DEC,  /**< LDPC decode */
>   	RTE_BBDEV_OP_LDPC_ENC,  /**< LDPC encode */
>   	RTE_BBDEV_OP_FFT,  /**< FFT */
> +	RTE_BBDEV_OP_MLDTS,  /**< MLD-TS */
>   	/* Note: RTE_BBDEV_OP_TYPE_SIZE_MAX must be larger or equal to maximum enum value */
>   };
>   
> @@ -864,7 +915,8 @@ enum {
>   	RTE_BBDEV_DRV_ERROR,
>   	RTE_BBDEV_DATA_ERROR,
>   	RTE_BBDEV_CRC_ERROR,
> -	RTE_BBDEV_SYNDROME_ERROR
> +	RTE_BBDEV_SYNDROME_ERROR,
> +	RTE_BBDEV_ENGINE_ERROR
>   };
>   
>   /** Structure specifying a single encode operation */
> @@ -911,6 +963,18 @@ struct rte_bbdev_fft_op {
>   	struct rte_bbdev_op_fft fft;
>   };
>   
> +/** Structure specifying a single mldts operation */
> +struct rte_bbdev_mldts_op {
> +	/** Status of operation that was performed. */
> +	int status;
> +	/** Mempool which op instance is in. */
> +	struct rte_mempool *mempool;
> +	/** Opaque pointer for user data. */
> +	void *opaque_data;
> +	/** Contains turbo decoder specific parameters. */
> +	struct rte_bbdev_op_mldts mldts;
> +};
> +
>   /** Operation capabilities supported by a device */
>   struct rte_bbdev_op_cap {
>   	enum rte_bbdev_op_type type;  /**< Type of operation */
> @@ -920,6 +984,7 @@ struct rte_bbdev_op_cap {
>   		struct rte_bbdev_op_cap_ldpc_dec ldpc_dec;
>   		struct rte_bbdev_op_cap_ldpc_enc ldpc_enc;
>   		struct rte_bbdev_op_cap_fft fft;
> +		struct rte_bbdev_op_cap_mld mld;
>   	} cap;  /**< Operation-type specific capabilities */
>   };
>   
> @@ -1058,6 +1123,36 @@ rte_bbdev_fft_op_alloc_bulk(struct rte_mempool *mempool,
>   	return rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
>   }
>   
> +/**
> + * Bulk allocate MLD 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.
> + */
> +__rte_experimental
> +static inline int
> +rte_bbdev_mldts_op_alloc_bulk(struct rte_mempool *mempool,
> +		struct rte_bbdev_mldts_op **ops, uint16_t num_ops)
> +{
> +	struct rte_bbdev_op_pool_private *priv;
> +
> +	/* Check type */
> +	priv = (struct rte_bbdev_op_pool_private *)rte_mempool_get_priv(mempool);
> +	if (unlikely(priv->type != RTE_BBDEV_OP_MLDTS))
> +		return -EINVAL;
> +
> +	/* Get elements */
> +	return rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
> +}
> +
>   /**
>    * Free decode operation structures that were allocated by
>    * rte_bbdev_dec_op_alloc_bulk().
> @@ -1110,6 +1205,25 @@ rte_bbdev_fft_op_free_bulk(struct rte_bbdev_fft_op **ops, unsigned int num_ops)
>   		rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
>   }
>   
> +/**
> + * Free encode operation structures that were allocated by
> + * rte_bbdev_mldts_op_alloc_bulk().
> + * All structures must belong to the same mempool.
> + *
> + * @param ops
> + *   Operation structures
> + * @param num_ops
> + *   Number of structures
> + */
> +__rte_experimental
> +static inline void
> +rte_bbdev_mldts_op_free_bulk(struct rte_bbdev_mldts_op **ops, unsigned int num_ops)
> +{
> +	if (num_ops > 0)
> +		rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
> +}
> +
> +
>   #ifdef __cplusplus
>   }
>   #endif
> diff --git a/lib/bbdev/version.map b/lib/bbdev/version.map
> index d0bb835255..8f28ae7c68 100644
> --- a/lib/bbdev/version.map
> +++ b/lib/bbdev/version.map
> @@ -50,4 +50,9 @@ EXPERIMENTAL {
>   	rte_bbdev_enqueue_status_str;
>   	rte_bbdev_fft_op_alloc_bulk;
>   	rte_bbdev_fft_op_free_bulk;
> +	#added in 23.11
> +	rte_bbdev_dequeue_mldts_ops;
> +	rte_bbdev_enqueue_mldts_ops;
> +	rte_bbdev_mldts_op_alloc_bulk;
> +	rte_bbdev_mldts_op_free_bulk;
>   };

Reviewed-by: Maxime Coquelin <maxime.coquelin@redhat.com>