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

[Morten Brørup]

> From: Stephen Hemminger [mailto:stephen at networkplumber.org]
> Sent: Wednesday, 18 February 2026 18.13
> 
> 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.

I agree.
But this API is for applications, so its documentation should be written for application developers.

Drivers are doing it wrong because driver APIs are largely undocumented, e.g. [2] and [3].
[2]: https://elixir.bootlin.com/dpdk/v25.11/source/lib/ethdev/rte_ethdev_core.h#L33
[3]: https://elixir.bootlin.com/dpdk/v25.11/source/lib/mempool/rte_mempool.h#L478

It would be an improvement if driver API documentation at least referred to the application APIs that wrap them.

> 
> > 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#L
> 273
> 
> 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