[RFC] ethdev: clarify rte_eth_tx_burst() return value and ownership semantics

[Stephen Hemminger]

On Tue, 17 Feb 2026 09:41:07 +0300
Andrew Rybchenko <andrew.rybchenko at oktetlabs.ru> wrote:

> On 2/16/26 9:00 PM, Stephen Hemminger 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 tx_errors.
> > 
> > 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 at networkplumber.org>  
> 
> Acked-by: Andrew Rybchenko <andrew.rybchenko at oktetlabs.ru>
> 
> Thanks for the clarification. I really like it.
> 

I haven't reviewed all drivers but have found bugs related to this
in tap, af_packet and likely other software drivers. The hardware
drivers seem to be modeled after ixgbe and get it right.