net: buf: deprecate special putter and getter functions

Deprecate the net_buf_put() and net_buf_get() functions.

Special handling of net_bufs in k_fifos is no longer needed after commit
3d306c181f, since these actions are now
atomic regardless of any net_buf fragments.

Signed-off-by: Henrik Brix Andersen <henrik@brixandersen.dk>

doc/connectivity/networking/api/net_buf.rst

@@ -50,14 +50,11 @@ Both the maximum data and user data capacity of the buffers is
 compile-time defined when declaring the buffer pool.
 
 The buffers have native support for being passed through k_fifo kernel
-objects. This is a very practical feature when the buffers need to be
+objects. Use :c:func:`k_fifo_put` and :c:func:`k_fifo_get` to pass buffer
-passed from one thread to another. However, since a net_buf may have a
+from one thread to another.
-fragment chain attached to it, instead of using the :c:func:`k_fifo_put`
+
-and :c:func:`k_fifo_get` APIs, special :c:func:`net_buf_put` and
+Special functions exist for dealing with buffers in single linked lists,
-:c:func:`net_buf_get` APIs must be used when passing buffers through
+where the :c:func:`net_buf_slist_put` and :c:func:`net_buf_slist_get`
-FIFOs. These APIs ensure that the buffer chains stay intact. The same
-applies for passing buffers through a singly linked list, in which case
-the :c:func:`net_buf_slist_put` and :c:func:`net_buf_slist_get`
 functions must be used instead of :c:func:`sys_slist_append` and
 :c:func:`sys_slist_get`.
 

doc/releases/release-notes-4.0.rst

@@ -30,6 +30,9 @@ Removed APIs in this release
 Deprecated in this release
 ==========================
 
+* Deprecated the :c:func:`net_buf_put` and :c:func:`net_buf_get` API functions in favor of
+  :c:func:`k_fifo_put` and :c:func:`k_fifo_get`.
+
 Architectures
 *************
 

include/zephyr/net/buf.h

@@ -1437,8 +1437,7 @@ struct net_buf * __must_check 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
+ * @deprecated Use @a k_fifo_get() instead.
- * fragments.
  *
  * @param fifo Which FIFO to take the buffer from.
  * @param timeout Affects the action taken should the FIFO be empty.
@@ -1448,13 +1447,13 @@ struct net_buf * __must_check net_buf_alloc_with_data(struct net_buf_pool *pool,
  * @return New buffer or NULL if the FIFO is empty.
  */
 #if defined(CONFIG_NET_BUF_LOG)
-struct net_buf * __must_check net_buf_get_debug(struct k_fifo *fifo,
+__deprecated struct net_buf * __must_check net_buf_get_debug(struct k_fifo *fifo,
 							     k_timeout_t timeout,
 							     const char *func, int line);
 #define	net_buf_get(_fifo, _timeout) \
 	net_buf_get_debug(_fifo, _timeout, __func__, __LINE__)
 #else
-struct net_buf * __must_check net_buf_get(struct k_fifo *fifo,
+__deprecated struct net_buf * __must_check net_buf_get(struct k_fifo *fifo,
 						       k_timeout_t timeout);
 #endif
 
@@ -1503,9 +1502,6 @@ void net_buf_simple_reserve(struct net_buf_simple *buf, size_t reserve);
 /**
  * @brief Put a buffer into a list
  *
- * If the buffer contains follow-up fragments this function will take care of
- * inserting them as well into the list.
- *
  * @param list Which list to append the buffer to.
  * @param buf Buffer.
  */
@@ -1514,9 +1510,6 @@ 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.
- *
  * @param list Which list to take the buffer from.
  *
  * @return New buffer or NULL if the FIFO is empty.
@@ -1526,13 +1519,12 @@ struct net_buf * __must_check net_buf_slist_get(sys_slist_t *list);
 /**
  * @brief Put a buffer to the end of a FIFO.
  *
- * If the buffer contains follow-up fragments this function will take care of
+ * @deprecated Use @a k_fifo_put() instead.
- * inserting them as well into the FIFO.
  *
  * @param fifo Which FIFO to put the buffer to.
  * @param buf Buffer.
  */
-void net_buf_put(struct k_fifo *fifo, struct net_buf *buf);
+__deprecated void net_buf_put(struct k_fifo *fifo, struct net_buf *buf);
 
 /**
  * @brief Decrements the reference count of a buffer.