[PATCH v3 2/3] ethdev: Improve descriptions of RX and TX offloads

[Stephen Hemminger]

On Sun,  3 Aug 2025 19:42:17 +0000
Morten Brørup <mb at smartsharesystems.com> wrote:

> The descriptions of the RX and TX offloads have been improved, to
> reflect that they are not only for device capability reporting, but
> also for device and queue configuration purposes.
> 
> Signed-off-by: Morten Brørup <mb at smartsharesystems.com>
> Acked-by: Bruce Richardson <bruce.richardson at intel.com>
> Acked-by: Andrew Rybchenko <andrew.rybchenko at oktetlabs.ru>
> Acked-by: Konstantin Ananyev <konstantin.ananyev at huawei.com>
> ---
> v3:
> * Add notes about conflicts between fast mbuf release and
>   multi segment send. (Stephen Hemminger)
> ---
>  lib/ethdev/rte_ethdev.h | 34 ++++++++++++++++++++++++----------
>  1 file changed, 24 insertions(+), 10 deletions(-)
> 
> diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
> index f9fb6ae549..724b2b149c 100644
> --- a/lib/ethdev/rte_ethdev.h
> +++ b/lib/ethdev/rte_ethdev.h
> @@ -1550,7 +1550,7 @@ struct rte_eth_conf {
>  };
>  
>  /**
> - * Rx offload capabilities of a device.
> + * Rx offload capabilities/configuration of a device or queue.
>   */
>  #define RTE_ETH_RX_OFFLOAD_VLAN_STRIP       RTE_BIT64(0)
>  #define RTE_ETH_RX_OFFLOAD_IPV4_CKSUM       RTE_BIT64(1)
> @@ -1585,12 +1585,12 @@ struct rte_eth_conf {
>  			     RTE_ETH_RX_OFFLOAD_QINQ_STRIP)
>  
>  /*
> - * If new Rx offload capabilities are defined, they also must be
> + * If new Rx offloads are defined, they also must be
>   * mentioned in rte_rx_offload_names in rte_ethdev.c file.
>   */
>  
>  /**
> - * Tx offload capabilities of a device.
> + * Tx offload capabilities/configuration of a device or queue.
>   */
>  #define RTE_ETH_TX_OFFLOAD_VLAN_INSERT      RTE_BIT64(0)
>  #define RTE_ETH_TX_OFFLOAD_IPV4_CKSUM       RTE_BIT64(1)
> @@ -1611,39 +1611,53 @@ struct rte_eth_conf {
>   * Tx queue without SW lock.
>   */
>  #define RTE_ETH_TX_OFFLOAD_MT_LOCKFREE      RTE_BIT64(14)
> -/** Device supports multi segment send. */
> +/**
> + * Multi segment send.
> + *
> + * Note: If a port is configured for fast release of mbufs, the driver is expected to use an
> + * optimized Tx burst function relying on the preconditions for fast release of mbufs, which
> + * prohibits segmented packets, and thus multi segment send is unavailable.
> + * Note: If configuring a port for multi segment send, support for configuring a Tx queue for
> + * fast release of mbufs depends on the driver.
> + */

Wording is still a bit awkward. But many of the offload comments are a problem.

All the comments for offloads probably need rewording to be consistent.
Editors always like when all items in a list use same tense and subject/object wording.

I am lazy, sounds like a good job for AI to do.

Chatgpt says:
Here’s a clearer and more concise version:

Note: When a port is configured for fast mbuf release, the driver must use an optimized Tx burst function. This requires fast mbuf release preconditions, which prevent segmented packets and disable multi-segment send.

Note: When enabling multi-segment send, Tx queue configuration for fast mbuf release depends on the driver support.

Should also be careful to use RFC style keywords (see RFC 2119) related
to MUST, SHOULD, MAY. For example, driver should use optimized release function.