Re: [PATCH v2] ethdev: clarify rte_eth_tx_burst() return value and ownership semantics

[Stephen Hemminger <stephen@networkplumber.org>]

On Wed, 18 Feb 2026 16:44:49 -0800
Stephen Hemminger <stephen@networkplumber.org> wrote:

> The documentation for rte_eth_tx_burst() uses the word "sent" to
> describe the return value, which is misleading. Packets returned as
> consumed may not have been transmitted yet; they have been accepted
> by the driver and are no longer the caller's responsibility.
> 
> This matters because the common usage pattern is:
> 
>     n = rte_eth_tx_burst(port, txq, mbufs, nb_pkts);
>     for (i = n; i < nb_pkts; i++)
>         rte_pktmbuf_free(mbufs[i]);
> 
> For this to work correctly, the contract must be:
>  - tx_pkts[0..n-1]: ownership transferred to the driver.
>  - tx_pkts[n..nb_pkts-1]: untouched, still owned by the caller.
> 
> Several drivers (and AI-assisted reviews) misinterpret the current
> wording and treat packets with errors as unconsumed, returning a
> short count. This causes callers to retry those packets indefinitely.
> The correct behavior is that the driver must consume (and free)
> erroneous packets, counting them via oerrors.
> 
> Replace "sent" with "consumed" in the return value description,
> spell out the mbuf ownership contract, clarify the error handling
> expectation, and update the @return block to match.
> 
> Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
> ---

FYI - many, many drivers got this wrong. Only a few seem to get
it right.