[dpdk-dev] [v1] ethdev: support Tx queue used count

[Andrew Rybchenko]

On 1/11/24 18:17, jerinj at marvell.com wrote:
> From: Jerin Jacob <jerinj at marvell.com>
> 
> Introduce a new API to retrieve the number of used descriptors
> in a Tx queue. Applications can leverage this API in the fast path to
> inspect the Tx queue occupancy and take appropriate actions based on the
> available free descriptors.
> 
> A notable use case could be implementing Random Early Discard (RED)
> in software based on Tx queue occupancy.
> 
> Signed-off-by: Jerin Jacob <jerinj at marvell.com>

with few nits below
Reviewed-by: Andrew Rybchenko <andrew.rybchenko at oktetlabs.ru>

[snip]

> diff --git a/doc/guides/nics/features.rst b/doc/guides/nics/features.rst
> index f7d9980849..0d5a8733fc 100644
> --- a/doc/guides/nics/features.rst
> +++ b/doc/guides/nics/features.rst
> @@ -962,6 +962,16 @@ management (see :doc:`../prog_guide/power_man` for more details).
>   
>   * **[implements] eth_dev_ops**: ``get_monitor_addr``
>   
> +.. _nic_features_tx_queue_used_count:

I'd stick to shorter version _nic_features_tx_queue_count to match API
naming and feature title below.

> +
> +Tx queue count
> +--------------
> +
> +Supports to get the number of used descriptors of a Tx queue.
> +
> +* **[implements] eth_dev_ops**: ``tx_queue_count``.
> +* **[related] API**: ``rte_eth_tx_queue_count()``.
> +
>   .. _nic_features_other:
>   
>   Other dev ops not represented by a Feature

[snip]

> diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
> index 21e3a21903..af59da9652 100644
> --- a/lib/ethdev/rte_ethdev.h
> +++ b/lib/ethdev/rte_ethdev.h
> @@ -6803,6 +6803,80 @@ rte_eth_recycle_mbufs(uint16_t rx_port_id, uint16_t rx_queue_id,
>   __rte_experimental
>   int rte_eth_buffer_split_get_supported_hdr_ptypes(uint16_t port_id, uint32_t *ptypes, int num);
>   
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
> + *
> + * Get the number of used descriptors of a Tx queue
> + *
> + * This function retrieves the number of used descriptors of a transmit queue.
> + * Applications can use this API in the fast path to inspect Tx queue occupancy and take
> + * appropriate actions based on the available free descriptors.
> + * An example action could be implementing the Random Early Discard (RED).
> + *
> + * Since it's a fast-path function, no check is performed on port_id and
> + * tx_queue_id. The caller must therefore ensure that the port is enabled
> + * and the queue is configured and running.
> + *
> + * @param port_id
> + *   The port identifier of the device.
> + * @param tx_queue_id
> + *   The index of the transmit queue.
> + *   The value must be in the range [0, nb_tx_queue - 1] previously supplied
> + *   to rte_eth_dev_configure().
> + * @return
> + *  The number of used descriptors in the specific queue, or:
> + *   - (-ENODEV) if *port_id* is invalid. Enabled only when RTE_ETHDEV_DEBUG_TX is enabled
> + *   - (-EINVAL) if *queue_id* is invalid. Enabled only when RTE_ETHDEV_DEBUG_TX is enabled
> + *   - (-ENOTSUP) if the device does not support this function.
> + *
> + * @note This function is designed for fast-path use.
> + */
> +__rte_experimental
> +static inline int
> +rte_eth_tx_queue_count(uint16_t port_id, uint16_t tx_queue_id)
> +{
> +	struct rte_eth_fp_ops *fops;
> +	void *qd;
> +	int rc;
> +
> +#ifdef RTE_ETHDEV_DEBUG_TX
> +	if (port_id >= RTE_MAX_ETHPORTS || !rte_eth_dev_is_valid_port(port_id)) {
> +		RTE_ETHDEV_LOG_LINE(ERR, "Invalid port_id=%u", port_id);
> +		rc = -ENODEV;
> +		rte_eth_trace_tx_queue_count(port_id, tx_queue_id, rc);
> +		return rc;
> +	}
> +
> +	rc = -EINVAL;

Since it is a debug, IMHO it is better to keep the code simple and init
rc in two below if bodies separately rather than relying on shared init
here.

> +	if (tx_queue_id >= RTE_MAX_QUEUES_PER_PORT) {
> +		RTE_ETHDEV_LOG_LINE(ERR, "Invalid Tx queue_id=%u for port_id=%u",
> +				    tx_queue_id, port_id);
> +		rte_eth_trace_tx_queue_count(port_id, tx_queue_id, rc);
> +		return rc;
> +	}
> +#endif
> +
> +	/* Fetch pointer to Tx queue data */
> +	fops = &rte_eth_fp_ops[port_id];
> +	qd = fops->txq.data[tx_queue_id];
> +
> +#ifdef RTE_ETHDEV_DEBUG_TX
> +	if (qd == NULL) {
> +		RTE_ETHDEV_LOG_LINE(ERR, "Invalid Tx queue_id=%u for port_id=%u",
> +				    tx_queue_id, port_id);
> +		rte_eth_trace_tx_queue_count(port_id, tx_queue_id, rc);
> +		return rc;
> +	}
> +#endif
> +	if (fops->tx_queue_count == NULL)

Don't we need trace here? (no strong opinion, just trying to understand
why it is missing here)

> +		return -ENOTSUP;
> +
> +	rc = fops->tx_queue_count(qd);
> +	rte_eth_trace_tx_queue_count(port_id, tx_queue_id, rc);
> +
> +	return rc;
> +}
>   #ifdef __cplusplus
>   }
>   #endif

[snip]