[PATCH] ethdev: fix mbuf fast release requirements description

[PATCH] ethdev: fix mbuf fast release requirements description

[Morten Brørup]

It was unclear if mbuf fast release could support segmented packets, or if
mbuf fast release required non-segmented packets.
This has now been investigated in detail, and it was concluded that
segmented packets can be supported with mbuf fast release still achieving
the enhanced performance.
So the description of the mbuf fast release Tx offload flag was fixed.

Furthermore, the general descriptions of the Rx and Tx offloads were
improved, to reflect that they are not only for device capability
reporting, but also for device and queue configuration purposes.

NB: If a driver does not support segmented packets with mbuf fast release,
it can check the multi segment send flag when selecting transmit function.

Fixes: 55624173bacb ("mbuf: add raw free and alloc bulk functions")
Cc: stable@dpdk.org

Signed-off-by: Morten Brørup <mb@smartsharesystems.com>
---
The other description improvements were taken from patch-155635 ("[v3,2/3]
ethdev: Improve descriptions of RX and TX offloads").
---
 lib/ethdev/rte_ethdev.h | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
index a66c2abbdb..0d8e2d0236 100644
--- a/lib/ethdev/rte_ethdev.h
+++ b/lib/ethdev/rte_ethdev.h
@@ -1578,7 +1578,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)
@@ -1613,12 +1613,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)
@@ -1639,39 +1639,39 @@ 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. */
 #define RTE_ETH_TX_OFFLOAD_MULTI_SEGS       RTE_BIT64(15)
 /**
- * Device supports optimization for fast release of mbufs.
+ * Optimization for fast release of mbufs.
  * When set application must guarantee that per-queue all mbufs come from the same mempool,
- * are direct, have refcnt=1, next=NULL and nb_segs=1, as done by rte_pktmbuf_prefree_seg().
+ * have refcnt=1, and are direct.
  *
  * @see rte_mbuf_raw_free_bulk()
  */
 #define RTE_ETH_TX_OFFLOAD_MBUF_FAST_FREE   RTE_BIT64(16)
 #define RTE_ETH_TX_OFFLOAD_SECURITY         RTE_BIT64(17)
 /**
- * Device supports generic UDP tunneled packet TSO.
+ * Generic UDP tunneled packet TSO.
  * Application must set RTE_MBUF_F_TX_TUNNEL_UDP and other mbuf fields required
  * for tunnel TSO.
  */
 #define RTE_ETH_TX_OFFLOAD_UDP_TNL_TSO      RTE_BIT64(18)
 /**
- * Device supports generic IP tunneled packet TSO.
+ * Generic IP tunneled packet TSO.
  * Application must set RTE_MBUF_F_TX_TUNNEL_IP and other mbuf fields required
  * for tunnel TSO.
  */
 #define RTE_ETH_TX_OFFLOAD_IP_TNL_TSO       RTE_BIT64(19)
-/** Device supports outer UDP checksum */
+/** Outer UDP checksum. Used for tunneling packet. */
 #define RTE_ETH_TX_OFFLOAD_OUTER_UDP_CKSUM  RTE_BIT64(20)
 /**
- * Device sends on time read from RTE_MBUF_DYNFIELD_TIMESTAMP_NAME
+ * Send on time read from RTE_MBUF_DYNFIELD_TIMESTAMP_NAME
  * if RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME is set in ol_flags.
  * The mbuf field and flag are registered when the offload is configured.
  */
 #define RTE_ETH_TX_OFFLOAD_SEND_ON_TIMESTAMP RTE_BIT64(21)
 /*
- * If new Tx offload capabilities are defined, they also must be
+ * If new Tx offloads are defined, they also must be
  * mentioned in rte_tx_offload_names in rte_ethdev.c file.
  */
 
-- 
2.43.0

Re: [PATCH] ethdev: fix mbuf fast release requirements description

[Stephen Hemminger]

On Thu,  5 Feb 2026 09:28:48 +0000
Morten Brørup <mb@smartsharesystems.com> wrote:

> It was unclear if mbuf fast release could support segmented packets, or if
> mbuf fast release required non-segmented packets.
> This has now been investigated in detail, and it was concluded that
> segmented packets can be supported with mbuf fast release still achieving
> the enhanced performance.
> So the description of the mbuf fast release Tx offload flag was fixed.
> 
> Furthermore, the general descriptions of the Rx and Tx offloads were
> improved, to reflect that they are not only for device capability
> reporting, but also for device and queue configuration purposes.
> 
> NB: If a driver does not support segmented packets with mbuf fast release,
> it can check the multi segment send flag when selecting transmit function.
> 
> Fixes: 55624173bacb ("mbuf: add raw free and alloc bulk functions")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Morten Brørup <mb@smartsharesystems.com>
> ---
> The other description improvements were taken from patch-155635 ("[v3,2/3]
> ethdev: Improve descriptions of RX and TX offloads").
> ---

Acked-by: Stephen Hemminger <stephen@networkplumber.org>

I wonder if it would be good to point the AI documentation review
tool at the docbook comments in ethdev. There are some grammar
and clarity errors there.

Re: [PATCH] ethdev: fix mbuf fast release requirements description

[Stephen Hemminger]

On Thu,  5 Feb 2026 09:28:48 +0000
Morten Brørup <mb@smartsharesystems.com> wrote:

> It was unclear if mbuf fast release could support segmented packets, or if
> mbuf fast release required non-segmented packets.
> This has now been investigated in detail, and it was concluded that
> segmented packets can be supported with mbuf fast release still achieving
> the enhanced performance.
> So the description of the mbuf fast release Tx offload flag was fixed.
> 
> Furthermore, the general descriptions of the Rx and Tx offloads were
> improved, to reflect that they are not only for device capability
> reporting, but also for device and queue configuration purposes.
> 
> NB: If a driver does not support segmented packets with mbuf fast release,
> it can check the multi segment send flag when selecting transmit function.
> 
> Fixes: 55624173bacb ("mbuf: add raw free and alloc bulk functions")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Morten Brørup <mb@smartsharesystems.com>
> ---

Queued to next-net

Re: [PATCH] ethdev: fix mbuf fast release requirements description

[Andrew Rybchenko]

On 2/5/26 8:41 PM, Stephen Hemminger wrote:
> On Thu,  5 Feb 2026 09:28:48 +0000
> Morten Brørup <mb@smartsharesystems.com> wrote:
> 
>> It was unclear if mbuf fast release could support segmented packets, or if
>> mbuf fast release required non-segmented packets.
>> This has now been investigated in detail, and it was concluded that
>> segmented packets can be supported with mbuf fast release still achieving
>> the enhanced performance.
>> So the description of the mbuf fast release Tx offload flag was fixed.
>>
>> Furthermore, the general descriptions of the Rx and Tx offloads were
>> improved, to reflect that they are not only for device capability
>> reporting, but also for device and queue configuration purposes.
>>
>> NB: If a driver does not support segmented packets with mbuf fast release,
>> it can check the multi segment send flag when selecting transmit function.
>>
>> Fixes: 55624173bacb ("mbuf: add raw free and alloc bulk functions")
>> Cc: stable@dpdk.org
>>
>> Signed-off-by: Morten Brørup <mb@smartsharesystems.com>
>> ---
>> The other description improvements were taken from patch-155635 ("[v3,2/3]
>> ethdev: Improve descriptions of RX and TX offloads").
>> ---
> 
> Acked-by: Stephen Hemminger <stephen@networkplumber.org>
> 
> I wonder if it would be good to point the AI documentation review
> tool at the docbook comments in ethdev. There are some grammar
> and clarity errors there.

Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>