diff --git a/drivers/include/net/netdev.h b/drivers/include/net/netdev.h index 3d201d13f0f284ff9c3bc2fd54c6e6039133ecac..cdaeba365dc59771ccf7e17090588573c2e06119 100644 --- a/drivers/include/net/netdev.h +++ b/drivers/include/net/netdev.h @@ -310,19 +310,26 @@ typedef struct netdev_driver { int (*send)(netdev_t *dev, const iolist_t *iolist); /** - * @brief Get a received frame + * @brief Drop a received frame, **OR** get the length of a received frame, + * **OR** get a received frame. * * @pre `(dev != NULL)` - * @pre `(buf != NULL) && (len > 0)` * * Supposed to be called from * @ref netdev_t::event_callback "netdev->event_callback()" * - * If @p buf == NULL and @p len == 0, returns the packet size without - * dropping it. + * If @p buf == NULL and @p len == 0, returns the packet size -- or an upper + * bound estimation of the size -- without dropping the packet. * If @p buf == NULL and @p len > 0, drops the packet and returns the packet * size. * + * If called with @p buf != NULL and @p len is smaller than the received + * packet: + * - The received packet is dropped + * - The content in @p buf becomes invalid. (The driver may use the memory + * to implement the dropping - or may not change it.) + * - `-ENOBUFS` is returned + * * @param[in] dev network device descriptor. Must not be NULL. * @param[out] buf buffer to write into or NULL to return the packet * size. @@ -335,7 +342,7 @@ typedef struct netdev_driver { * * @return `-ENOBUFS` if supplied buffer is too small * @return number of bytes read if buf != NULL - * @return packet size if buf == NULL + * @return packet size (or upper bound estimation) if buf == NULL */ int (*recv)(netdev_t *dev, void *buf, size_t len, void *info);