From ac3dcc1106e775fb74eab2e615154a0888ef33e2 Mon Sep 17 00:00:00 2001 From: Andrew Boie Date: Mon, 1 Apr 2019 12:28:03 -0700 Subject: [PATCH] doc: clarify k_queue_alloc_append and related APIs The data isn't copied, there's just an additional implicit allocation. Fixes: #15090 Signed-off-by: Andrew Boie --- include/kernel.h | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/include/kernel.h b/include/kernel.h index dcf649366d3..5ec9585fb5a 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -1812,9 +1812,10 @@ extern void k_queue_append(struct k_queue *queue, void *data); /** * @brief Append an element to a queue. * - * This routine appends a data item to @a queue. There is an implicit - * memory allocation from the calling thread's resource pool, which is - * automatically freed when the item is removed from the queue. + * This routine appends a data item to @a queue. There is an implicit memory + * allocation to create an additional temporary bookkeeping data structure from + * the calling thread's resource pool, which is automatically freed when the + * item is removed. The data itself is not copied. * * @note Can be called by ISRs. * @@ -1845,9 +1846,10 @@ extern void k_queue_prepend(struct k_queue *queue, void *data); /** * @brief Prepend an element to a queue. * - * This routine prepends a data item to @a queue. There is an implicit - * memory allocation from the calling thread's resource pool, which is - * automatically freed when the item is removed from the queue. + * This routine prepends a data item to @a queue. There is an implicit memory + * allocation to create an additional temporary bookkeeping data structure from + * the calling thread's resource pool, which is automatically freed when the + * item is removed. The data itself is not copied. * * @note Can be called by ISRs. * @@ -2117,9 +2119,10 @@ struct k_fifo { /** * @brief Add an element to a FIFO queue. * - * This routine adds a data item to @a fifo. There is an implicit - * memory allocation from the calling thread's resource pool, which is - * automatically freed when the item is removed. + * This routine adds a data item to @a fifo. There is an implicit memory + * allocation to create an additional temporary bookkeeping data structure from + * the calling thread's resource pool, which is automatically freed when the + * item is removed. The data itself is not copied. * * @note Can be called by ISRs. * @@ -2316,9 +2319,10 @@ struct k_lifo { /** * @brief Add an element to a LIFO queue. * - * This routine adds a data item to @a lifo. There is an implicit - * memory allocation from the calling thread's resource pool, which is - * automatically freed when the item is removed. + * This routine adds a data item to @a lifo. There is an implicit memory + * allocation to create an additional temporary bookkeeping data structure from + * the calling thread's resource pool, which is automatically freed when the + * item is removed. The data itself is not copied. * * @note Can be called by ISRs. *