2  * Copyright (c) 2018-2024 Nordic Semiconductor ASA
4  * SPDX-License-Identifier: Apache-2.0
8  * Memory FIFO permitting enqueue at tail (last) and dequeue from head (first).
14  * buffer yet to be committed, exists in a limbo state - until committed.
17  * Invariant: last-index refers to the buffer that is safe to write while in
18  * limbo-state. Outside limbo state, last-index refers one buffer ahead of what
21  * There are essentially two APIs, distinguished by the buffer-type:
22  *  API 1 Value-type   : MFIFO_DEFINE(name1, sizeof(struct foo), cnt1);
23  *  API 2 Pointer-type : MFIFO_DEFINE(name2, sizeof(void *),     cnt2);
27  *   ------+------------------------+----------------------
31  * TODO: Reduce size: All functions except mfifo_enqueue should not be inline
35  * @brief   Define a Memory FIFO implemented as a circular queue.
37  *   Contains one-more buffer than needed.
39  * TODO: We can avoid string-concat macros below by setting type in
40  *       MFIFO_DEFINE struct or use a typedef. Yes the size of field 'm' may be
66  * @brief   Non-destructive: Allocate buffer from the queue's tail, by index
72  *   Allocation is non-destructive as operations are performed on index copies,
75  *   un-committed allocations returns the same buffer index.
83 	/* Non-destructive: Advance write-index modulo 'count' */  in mfifo_enqueue_idx_get()
91 	 * first == last, but we just advanced a copy of the write-index before  in mfifo_enqueue_idx_get()
104  * @brief   Non-destructive: Allocate buffer from named queue
114  * @brief   Commit a previously allocated buffer (=void-ptr)
117 static inline void mfifo_by_idx_enqueue(uint8_t *fifo, uint8_t size,  in mfifo_by_idx_enqueue()  argument
120 	/* API 2: fifo is array of void-ptrs */  in mfifo_by_idx_enqueue()
121 	void **p = (void **)(fifo + (*last) * size); /* buffer preceding idx */  in mfifo_by_idx_enqueue()
122 	*p = mem; /* store the payload which for API 2 is only a void-ptr */  in mfifo_by_idx_enqueue()
129  * @brief   Commit a previously allocated buffer (=void-ptr)
137  * @brief   Non-destructive: Allocate buffer from named queue
143 static inline uint8_t mfifo_enqueue_get(uint8_t *fifo, uint8_t size,  in mfifo_enqueue_get()  argument
156 	/* We keep idx as the always-one-free, so we return preceding  in mfifo_enqueue_get()
160 	*mem = (void *)(fifo + last * size); /* preceding buffer */  in mfifo_enqueue_get()
166  * @brief   Non-destructive: Allocate buffer from named queue
171  * @return Index to the buffer one-ahead of allocated buffer
182  *   limbo state -- thus completing its enqueue.
187  * @param idx[in]   Index one-ahead of previously allocated buffer
188  * @param last[out] Write-index
200  * @param idx[in]  Index one-ahead of previously allocated buffer
214 		return last - first;  in mfifo_avail_count_get()
216 		return count - first + last;  in mfifo_avail_count_get()
229  * @brief Non-destructive peek
232 static inline void *mfifo_dequeue_get(uint8_t *fifo, uint8_t size,  in mfifo_dequeue_get()  argument
239 	/* API 1: fifo is array of some value type */  in mfifo_dequeue_get()
240 	return (void *)(fifo + first * size);  in mfifo_dequeue_get()
251  * @brief Non-destructive: Peek at head (oldest) buffer
254 static inline void *mfifo_dequeue_peek(uint8_t *fifo, uint8_t size,  in mfifo_dequeue_peek()  argument
261 	/* API 2: fifo is array of void-ptrs */  in mfifo_dequeue_peek()
262 	return *((void **)(fifo + first * size));  in mfifo_dequeue_peek()
266  * @brief Non-destructive: Peek at head (oldest) buffer
273 static inline void *mfifo_dequeue_iter_get(uint8_t *fifo, uint8_t size,  in mfifo_dequeue_iter_get()  argument
293 	p = (void *)(fifo + (*idx) * size);  in mfifo_dequeue_iter_get()
306  * @brief Dequeue head-buffer from queue of buffers
308  * @param fifo[in]      Contiguous memory holding the circular queue
309  * @param size[in]      Size of each buffer in circular queue
311  * @param last[in]      Tail index, Span: [0 .. count-1]
312  * @param first[in,out] Head index, Span: [0 .. count-1]. Will be updated
315 static inline void *mfifo_dequeue(uint8_t *fifo, uint8_t size, uint8_t count,  in mfifo_dequeue()  argument
318 	uint8_t _first = *first; /* Copy read-index */  in mfifo_dequeue()
327 	 * API 2: fifo is array of void-ptrs  in mfifo_dequeue()
329 	mem = *((void **)(fifo + _first * size));  in mfifo_dequeue()
331 	/* Circular buffer increment read-index modulo 'count' */  in mfifo_dequeue()
337 	*first = _first; /* Write back read-index */  in mfifo_dequeue()
343  * @brief   Dequeue head-buffer from named queue of buffers
345  * @param name[in]  Name-fragment of circular queue