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

[Stephen Hemminger]

On Wed, 18 Feb 2026 09:48:04 +0100
Morten Brørup <mb at smartsharesystems.com> wrote:

> > + *
> > + * A return value equal to *nb_pkts* means that all packets have been
> > + * consumed, and this is likely to signify that other output packets
> >   * could be immediately transmitted again. Applications that implement
> > a
> >   * "send as many packets to transmit as possible" policy can check
> > this
> >   * specific case and keep invoking the rte_eth_tx_burst() function
> > until
> >   * a value less than *nb_pkts* is returned.
> >   *
> > + * If a packet cannot be transmitted due to an error (for example, an
> > + * invalid offload flag), the driver must still consume it and free
> > the
> > + * mbuf, rather than stopping at that point. Such packets should be
> > + * counted in the *tx_errors* port statistic.  
> 
> The above paragraph is driver centric, it should be application centric.

Most of the applications are doing it right already since everybody
starts with l2fwd, or l3fwd. The problem I see is buggy drivers.

> Suggest rephrasing as:
> 
> If a packet cannot be transmitted due to an error (for example, an invalid offload flag), the rte_eth_tx_burst() function will still consume it, rather than stopping at that point.
> Such packets are counted in the *oerrors* port statistic.
> 
> NB: In struct rte_eth_stats [1], the error counter is named "oerrors", not "tx_errors".
> 
> [1]: https://elixir.bootlin.com/dpdk/v25.11/source/lib/ethdev/rte_ethdev.h#L273

Good point, I was thinking of the per-queue stats and xstats.

> While discussing details...
> Let's say a packet has 4 segments, and the driver only has 2 descriptors remaining available.
> In that case, I think the driver should not consume the packet, but leave it for the application to either drop it or retry transmitting it later.
> Do we want to mention this case too, or is it a semi-obvious case of the descriptor ring having no more room?

There are also other cases of backpressure like when driver talks to kernel and gets EAGAIN or EBUSY