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

[Jerin Jacob]

On Fri, Jan 12, 2024 at 5:04 PM Ferruh Yigit <ferruh.yigit at amd.com> wrote:
>
> On 1/11/2024 3:17 PM, 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>
> > ---

> >
>
> As we are adding a new API and dev_ops, is a driver implementation and
> testpmd/example implementation planned for this release?

Yes.

>
>
> > rfc..v1:
> > - Updated API similar to rte_eth_rx_queue_count() where it returns
> > "used" count instead of "free" count
> >
> > 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:
> > +
> > +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()``.
> > +
> >
>
> Can you please keep the order same with 'default.ini' file,
> I recognized there is already some mismatch in order but we can fix them
> later.

Ack

>
> >  .. _nic_features_other:
> >
> >  Other dev ops not represented by a Feature
> > diff --git a/doc/guides/nics/features/default.ini b/doc/guides/nics/features/default.ini
> > index 806cb033ff..3ef6d45c0e 100644
> > --- a/doc/guides/nics/features/default.ini
> > +++ b/doc/guides/nics/features/default.ini
> > @@ -59,6 +59,7 @@ Packet type parsing  =
> >  Timesync             =
> >  Rx descriptor status =
> >  Tx descriptor status =
> > +Tx queue count       =
> >
>
> Existing Rx queue count is not documented, if we are documenting this,
> can you please add "Rx queue count" in a separate patch?

I will do.


>
> >  Basic stats          =
> >  Extended stats       =
> >  Stats per queue      =
> > diff --git a/lib/ethdev/ethdev_driver.h b/lib/ethdev/ethdev_driver.h
> > index b482cd12bb..f05f68a67c 100644
> > --- a/lib/ethdev/ethdev_driver.h
> > +++ b/lib/ethdev/ethdev_driver.h
> > @@ -58,6 +58,8 @@ struct rte_eth_dev {
> >       eth_rx_queue_count_t rx_queue_count;
> >       /** Check the status of a Rx descriptor */
> >       eth_rx_descriptor_status_t rx_descriptor_status;
> > +     /** Get the number of used Tx descriptors */
> > +     eth_tx_queue_count_t tx_queue_count;
> >       /** Check the status of a Tx descriptor */
> >       eth_tx_descriptor_status_t tx_descriptor_status;
> >       /** Pointer to PMD transmit mbufs reuse function */
> > diff --git a/lib/ethdev/ethdev_private.c b/lib/ethdev/ethdev_private.c
> > index a656df293c..626524558a 100644
> > --- a/lib/ethdev/ethdev_private.c
> > +++ b/lib/ethdev/ethdev_private.c
> > @@ -273,6 +273,7 @@ eth_dev_fp_ops_setup(struct rte_eth_fp_ops *fpo,
> >       fpo->tx_pkt_prepare = dev->tx_pkt_prepare;
> >       fpo->rx_queue_count = dev->rx_queue_count;
> >       fpo->rx_descriptor_status = dev->rx_descriptor_status;
> > +     fpo->tx_queue_count = dev->tx_queue_count;
> >       fpo->tx_descriptor_status = dev->tx_descriptor_status;
> >       fpo->recycle_tx_mbufs_reuse = dev->recycle_tx_mbufs_reuse;
> >       fpo->recycle_rx_descriptors_refill = dev->recycle_rx_descriptors_refill;
> > diff --git a/lib/ethdev/ethdev_trace_points.c b/lib/ethdev/ethdev_trace_points.c
> > index 91f71d868b..e618414392 100644
> > --- a/lib/ethdev/ethdev_trace_points.c
> > +++ b/lib/ethdev/ethdev_trace_points.c
> > @@ -481,6 +481,9 @@ RTE_TRACE_POINT_REGISTER(rte_eth_trace_count_aggr_ports,
> >  RTE_TRACE_POINT_REGISTER(rte_eth_trace_map_aggr_tx_affinity,
> >       lib.ethdev.map_aggr_tx_affinity)
> >
> > +RTE_TRACE_POINT_REGISTER(rte_eth_trace_tx_queue_count,
> > +     lib.ethdev.tx_queue_count)
> > +
>
> Can you please group this with 'tx_burst' & 'call_tx_callbacks' above?

Ack


>
> >  RTE_TRACE_POINT_REGISTER(rte_flow_trace_copy,
> >       lib.ethdev.flow.copy)
> >
> > 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).
> >
>
> Above is good, but do you think does it help to mention that intended
> usacase is QoS, to address the risk Bruce mentioned?

I will add following notes in next version.

 * @note There is no requirement to call this function before
rte_eth_tx_burst() invocation.
 * @note Utilize this function exclusively when the caller needs to
determine the used queue count
 * across all descriptors of a Tx queue. If the use case only involves
checking the status of a
 * specific descriptor slot, opt for rte_eth_tx_descriptor_status() instead.



>
>
> > + *
> > + * 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;
> > +     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)
> > +             return -ENOTSUP;
> > +
> > +     rc = fops->tx_queue_count(qd);
> >
>
> Can you please put an empty line here to have a separate block for trace
> code?

Ack


>
> > +     rte_eth_trace_tx_queue_count(port_id, tx_queue_id, rc);
> > +
> > +     return rc;
> > +}
> >  #ifdef __cplusplus
> >  }
> >  #endif
> > diff --git a/lib/ethdev/rte_ethdev_core.h b/lib/ethdev/rte_ethdev_core.h
> > index 4bfaf79c6c..d3f09f390d 100644
> > --- a/lib/ethdev/rte_ethdev_core.h
> > +++ b/lib/ethdev/rte_ethdev_core.h
> > @@ -60,6 +60,9 @@ typedef uint16_t (*eth_recycle_tx_mbufs_reuse_t)(void *txq,
> >  /** @internal Refill Rx descriptors with the recycling mbufs */
> >  typedef void (*eth_recycle_rx_descriptors_refill_t)(void *rxq, uint16_t nb);
> >
> > +/** @internal Get number of used descriptors on a transmit queue. */
> > +typedef int (*eth_tx_queue_count_t)(void *txq);
> > +
>
> Can you please move it above 'tx_descriptor_status', to keep same order
> kept in many other locations:
> rx_queue_count
> rx_descriptor_status
> tx_queue_count
> tx_descriptor_status

Ack


>
>
> >  /**
> >   * @internal
> >   * Structure used to hold opaque pointers to internal ethdev Rx/Tx
> > @@ -116,7 +119,9 @@ struct rte_eth_fp_ops {
> >       eth_tx_descriptor_status_t tx_descriptor_status;
> >       /** Copy used mbufs from Tx mbuf ring into Rx. */
> >       eth_recycle_tx_mbufs_reuse_t recycle_tx_mbufs_reuse;
> > -     uintptr_t reserved2[2];
> > +     /** Get the number of used Tx descriptors. */
> > +     eth_tx_queue_count_t tx_queue_count;
> >
>
> Similarly, can you please move it above 'tx_descriptor_status'?

Ack


>
>
> > +     uintptr_t reserved2[1];
> >       /**@}*/
> >
> >  } __rte_cache_aligned;
> > diff --git a/lib/ethdev/rte_ethdev_trace_fp.h b/lib/ethdev/rte_ethdev_trace_fp.h
> > index 186271c9ff..c98c488433 100644
> > --- a/lib/ethdev/rte_ethdev_trace_fp.h
> > +++ b/lib/ethdev/rte_ethdev_trace_fp.h
> > @@ -73,6 +73,14 @@ RTE_TRACE_POINT_FP(
> >       rte_trace_point_emit_u64(count);
> >  )
> >
> > +RTE_TRACE_POINT_FP(
> > +     rte_eth_trace_tx_queue_count,
> > +     RTE_TRACE_POINT_ARGS(uint16_t port_id, uint16_t tx_queue_id, int rc),
> > +     rte_trace_point_emit_u16(port_id);
> > +     rte_trace_point_emit_u16(tx_queue_id);
> > +     rte_trace_point_emit_int(rc);
> > +)
> > +
>
> Existing 'rx_queue_count' is missing tracepoints, for consistency, can
> you please add that too in a separate patch?

I will do.

>
>
> >  #ifdef __cplusplus
> >  }
> >  #endif
> > diff --git a/lib/ethdev/version.map b/lib/ethdev/version.map
> > index 5c4917c020..e03830902a 100644
> > --- a/lib/ethdev/version.map
> > +++ b/lib/ethdev/version.map
> > @@ -316,6 +316,9 @@ EXPERIMENTAL {
> >       rte_eth_recycle_rx_queue_info_get;
> >       rte_flow_group_set_miss_actions;
> >       rte_flow_calc_table_hash;
> > +
> > +     # added in 24.03
> > +     rte_eth_tx_queue_count;
> >  };
> >
> >  INTERNAL {
>