@miri64: We had a discussion on what this size should be in an issue. This interpretation is different to what most drivers implement (in the send(), not the confirm_send() function), but as porting would result in work anyway, I figured we should rather go for the best solution than the lazy solution.

IMO there is little reason to just return the result of iolist_size(iolist) on what was passed in send(), as the upper layer could just call iolist_size() directly to get this. So if we really want additional data for statistics, it should be IMO a value that has the most value when the value of iolist_size(iolist) is known anyway. And to me this is the number of bytes physically transmitted; as this would allow to calculate the layer 2 throughput, while iolist_size(iolist) can provide the layer 2 goodput.

The last sentence is wrong. The netif can easily calculate the sizes needed for goodput calculation, but it would need to make sure to call iolist_size(iolist) prior to adding the L2 header (and trailer, if applicable). But the reasoning should still be valid.

Note this change. Previously the API doc read as if a driver would need to expect elements in the iolist that have iolist_t::iol_data == NULL but iolist_t::iol_size > 0. I think this was just a mistake in formulation and not intentionally.

Shoudln't NOACK and TX_MEDIUM_BUSY be included as well? They are resolved at the same time

Done. I changed the return values to have -EGAIN in confirm_send() when called to early. This matches the semantics of the error code better. And this allows to return -EBUSY when the medium was busy; which is consistent with the interpretation of the same error code issued by send().

Who is going to call that function and what are they going to do with the number of bytes sent?

The 802.15.4 sub-mac will call a callback on TX done, can we do this here too?

Who is going to call that function

E.g. in the current GNRC network stack, I would implement this in the gnrc_netif. That way the gnrc_netif could turn the asynchronous non-blocking API into a "blocking" API. (I'm not sure if blocking is the right word, but the gnrc_netif will only act upon a message when the transmission is fully complete. That way if e.g. the 6lowpan implementation would send 3 frames as fragments of a single IPv6 packet, the gnrc_netif would send them one by one. That way the driver does no longer need to block on send() for link layer fragmentation to work.)

and what are they going to do with the number of bytes sent?

The number of bytes sent is only useful to gather L2 stats IMO. So unless the l2 stats module is used, the caller will only check for the return value to be non-negative.

The 802.15.4 sub-mac will call a callback on TX done, can we do this here too?

In the long term I would like to adopt those ideas of the 802.15.4 radio HAL that can be generically applied to all network devices for the netdev API. As said, my personal goal is that in the end a compatible subset of the radio HAL becomes the "generic network HAL". That way code duplication between different network technologies could be avoided, while still being able to exploit technology specific features through the technology specific API additions on top of the "generic network HAL".

But I think it would be better to change the netdev API in small steps.

So would this do

    dev->send();
    while (dev->confirm_send() == -EAGAIN) {}

?

Yes. But more likely you want to block until NETDEV_EVENT_TX_COMPLETE is issued.

When would we get NETDEV_EVENT_TX_COMPLETE but have confirm_send() return -EAGAIN?

Shouldn’t one be enough?
I see also have .confirm_tx in the radio HAL.
I’d like to have @jia200x‘s 2 ct on this so we don’t end up with two slightly incompatible mechanisms for the same thing.

The only mechanism that tells the upper layer that a packet was received is when confirm_transmit() returns 0.
The thing is, some radios have an "TX DONE" IRQ (and impressively, some like CC2420 don't). If the cap IEEE802154_CAP_IRQ_TX_DONE is available, the upper layer knows that it can e.g lock a mutex and unlock it on IEEE802154_CONFIRM_TX_DONE. But e.g for CC2420 the lower layer needs to poll until confirm_transmit return 0.

So in the Radio HAL officially there's only one mechanism (the confirm function).

Maybe we should update the documentation of NETDEV_EVENT_TX_COMPLETE to reflect that's not a mandatory event.

Couldn't we instead use a timer in the CC2420 driver and keep the API easier instead? At least the driver should be in an excellent position to optimize the timeout duration.

Nothing blocks the driver to implement such a feature. however, the timeout should make sure that confirm_send returns 0. Otherwise the API is not respected