net: buf: document fragment limitations

Document limitations on the FIFO queuing functions when fragments are
used. Namely that the `get` functions are not thread-safe when fragments
are present.

This is due to multiple independent calls to `k_fifo_get/sys_slist_get`.
A second thread can interrupt the retrieval before all fragments have
been removed. The second thread can then read from the FIFO, obtaining
the trailing fragments as a 'new' `net_buf`. The first thread will then
either assert or pull in the next `net_buf` on the queue as part of the
first `net_buf`.

Fixes #28355

Signed-off-by: Jordan Yates <[email protected]>

Author: Jordan Yates

include/net/buf.h

@@ -1131,6 +1131,9 @@ struct net_buf *net_buf_alloc_with_data(struct net_buf_pool *pool,
 /**
  * @brief Get a buffer from a FIFO.
  *
+ * This function is NOT thread-safe if the buffers in the FIFO contain
+ * fragments.
+ *
  * @param fifo Which FIFO to take the buffer from.
  * @param timeout Affects the action taken should the FIFO be empty.
  *        If K_NO_WAIT, then return immediately. If K_FOREVER, then wait as
@@ -1197,7 +1200,8 @@ void net_buf_slist_put(sys_slist_t *list, struct net_buf *buf);
  * @brief Get a buffer from a list.
  *
  * If the buffer had any fragments, these will automatically be recovered from
- * the list as well and be placed to the buffer's fragment list.
+ * the list as well and be placed to the buffer's fragment list. This function
+ * is NOT thread-safe when recovering fragments.
  *
  * @param list Which list to take the buffer from.
  *