From 9584008d9f14e63687148ccf07fab9591e3a2780 Mon Sep 17 00:00:00 2001
From: Henrik Brix Andersen <henrik@brixandersen.dk>
Date: Fri, 28 Jun 2024 19:45:38 +0000
Subject: [PATCH] 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
3d306c181f0d75c5765f80fdfbee614e1e3f191d, 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 | 13 +++++------
 doc/releases/release-notes-4.0.rst          |  3 +++
 include/zephyr/net/buf.h                    | 24 +++++++--------------
 3 files changed, 16 insertions(+), 24 deletions(-)

diff --git a/doc/connectivity/networking/api/net_buf.rst b/doc/connectivity/networking/api/net_buf.rst
index 1210fbc6ca0..88948ac8007 100644
--- a/doc/connectivity/networking/api/net_buf.rst
+++ b/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
-passed from one thread to another. However, since a net_buf may have a
-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
-:c:func:`net_buf_get` APIs must be used when passing buffers through
-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`
+objects. Use :c:func:`k_fifo_put` and :c:func:`k_fifo_get` to pass buffer
+from one thread to another.
+
+Special functions exist for dealing with buffers in single linked lists,
+where 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`.
 
diff --git a/doc/releases/release-notes-4.0.rst b/doc/releases/release-notes-4.0.rst
index aeb0b5306c5..24bc0df1b06 100644
--- a/doc/releases/release-notes-4.0.rst
+++ b/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
 *************
 
diff --git a/include/zephyr/net/buf.h b/include/zephyr/net/buf.h
index 66ff8d83b75..9b1d5af16b3 100644
--- a/include/zephyr/net/buf.h
+++ b/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
- * fragments.
+ * @deprecated Use @a k_fifo_get() instead.
  *
  * @param fifo Which FIFO to take the buffer from.
  * @param timeout Affects the action taken should the FIFO be empty.
@@ -1448,14 +1447,14 @@ 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,
-						k_timeout_t timeout,
-						const char *func, int line);
+__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,
-					  k_timeout_t timeout);
+__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
- * inserting them as well into the FIFO.
+ * @deprecated Use @a k_fifo_put() instead.
  *
  * @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.