4  * SPDX-License-Identifier: Apache-2.0
25 	"Size too big"
30  * @defgroup ring_buffer_apis Ring Buffer APIs
33  * @brief Simple ring buffer implementation.
39  * @brief A structure to represent a ring buffer
43 	uint8_t *buffer;  member
50 	uint32_t size;  member
61 	buf->put_head = buf->put_tail = buf->put_base = value;  in ring_buf_internal_reset()
62 	buf->get_head = buf->get_tail = buf->get_base = value;  in ring_buf_internal_reset()
66  * @brief Define and initialize a ring buffer for byte data.
68  * This macro establishes a ring buffer of an arbitrary size.
71  * The ring buffer can be accessed outside the module where it is defined
76  * @param name  Name of the ring buffer.
77  * @param size8 Size of ring buffer (in bytes).
84 		.buffer = _ring_buffer_data_##name, \
85 		.size = size8 \
89  * @brief Define and initialize an "item based" ring buffer.
91  * This macro establishes an "item based" ring buffer. Each data item is
92  * an array of 32-bit words (from zero to 1020 bytes in length), coupled
93  * with a 16-bit type identifier and an 8-bit integer value.
95  * The ring buffer can be accessed outside the module where it is defined
100  * @param name Name of the ring buffer.
101  * @param size32 Size of ring buffer (in 32-bit words).
108 		.buffer = (uint8_t *) _ring_buffer_data_##name, \
109 		.size = 4 * (size32) \
113  * @brief Define and initialize an "item based" ring buffer.
118  * @param name Name of the ring buffer.
119  * @param size32 Size of ring buffer (in 32-bit words).
125  * @brief Define and initialize a power-of-2 sized "item based" ring buffer.
127  * This macro establishes an "item based" ring buffer by specifying its
128  * size using a power of 2. This exists mainly for backward compatibility
131  * @param name Name of the ring buffer.
132  * @param pow Ring buffer size exponent.
138  * @brief Compute the ring buffer size in 32-bit needed to store an element
141  * Note: rounds up if the size is not a multiple of 32 bits.
143  * @param expr Expression or type to compute the size of
148  * @brief Initialize a ring buffer for byte data.
150  * This routine initializes a ring buffer, prior to its first use. It is only
153  * @param buf Address of ring buffer.
154  * @param size Ring buffer size (in bytes).
155  * @param data Ring buffer data area (uint8_t data[size]).
158 				 uint32_t size,  in ring_buf_init()  argument
161 	__ASSERT(size < RING_BUFFER_MAX_SIZE, RING_BUFFER_SIZE_ASSERT_MSG);  in ring_buf_init()
163 	buf->size = size;  in ring_buf_init()
164 	buf->buffer = data;  in ring_buf_init()
169  * @brief Initialize an "item based" ring buffer.
171  * This routine initializes a ring buffer, prior to its first use. It is only
174  * Each data item is an array of 32-bit words (from zero to 1020 bytes in
175  * length), coupled with a 16-bit type identifier and an 8-bit integer value.
177  * @param buf Address of ring buffer.
178  * @param size Ring buffer size (in 32-bit words)
179  * @param data Ring buffer data area (uint32_t data[size]).
182 				      uint32_t size,  in ring_buf_item_init()  argument
185 	__ASSERT(size < RING_BUFFER_MAX_SIZE / 4, RING_BUFFER_SIZE_ASSERT_MSG);  in ring_buf_item_init()
186 	ring_buf_init(buf, 4 * size, (uint8_t *)data);  in ring_buf_item_init()
190  * @brief Determine if a ring buffer is empty.
192  * @param buf Address of ring buffer.
194  * @return true if the ring buffer is empty, or false if not.
198 	return buf->get_head == buf->put_tail;  in ring_buf_is_empty()
202  * @brief Reset ring buffer state.
204  * @param buf Address of ring buffer.
212  * @brief Determine free space in a ring buffer.
214  * @param buf Address of ring buffer.
216  * @return Ring buffer free space (in bytes).
220 	return buf->size - (buf->put_head - buf->get_tail);  in ring_buf_space_get()
224  * @brief Determine free space in an "item based" ring buffer.
226  * @param buf Address of ring buffer.
228  * @return Ring buffer free space (in 32-bit words).
236  * @brief Return ring buffer capacity.
238  * @param buf Address of ring buffer.
240  * @return Ring buffer capacity (in bytes).
244 	return buf->size;  in ring_buf_capacity_get()
248  * @brief Determine used space in a ring buffer.
250  * @param buf Address of ring buffer.
252  * @return Ring buffer space used (in bytes).
256 	return buf->put_tail - buf->get_head;  in ring_buf_size_get()
260  * @brief Allocate buffer for writing data to a ring buffer.
262  * With this routine, memory copying can be reduced since internal ring buffer
267  * Use cases involving multiple writers to the ring buffer must prevent
269  * being preempted or by using a mutex to govern writes to the ring buffer.
272  * Ring buffer instance should not mix byte access and item access
275  * @param[in]  buf  Address of ring buffer.
277  *		    ring buffer.
278  * @param[in]  size Requested allocation size (in bytes).
280  * @return Size of allocated buffer which can be smaller than requested if
281  *	   there is not enough free space or buffer wraps.
285 			    uint32_t size);
292  * bytes will be returned to the available free buffer space.
295  * Use cases involving multiple writers to the ring buffer must prevent
297  * being preempted or by using a mutex to govern writes to the ring buffer.
300  * Ring buffer instance should not mix byte access and item access
303  * @param  buf  Address of ring buffer.
304  * @param  size Number of valid bytes in the allocated buffers.
307  * @retval -EINVAL Provided @a size exceeds free space in the ring buffer.
309 int ring_buf_put_finish(struct ring_buf *buf, uint32_t size);
312  * @brief Write (copy) data to a ring buffer.
314  * This routine writes data to a ring buffer @a buf.
317  * Use cases involving multiple writers to the ring buffer must prevent
319  * being preempted or by using a mutex to govern writes to the ring buffer.
322  * Ring buffer instance should not mix byte access and item access
325  * @param buf Address of ring buffer.
327  * @param size Data size (in bytes).
331 uint32_t ring_buf_put(struct ring_buf *buf, const uint8_t *data, uint32_t size);
334  * @brief Get address of a valid data in a ring buffer.
336  * With this routine, memory copying can be reduced since internal ring buffer
341  * Use cases involving multiple reads of the ring buffer must prevent
343  * being preempted or by using a mutex to govern reads to the ring buffer.
346  * Ring buffer instance should not mix byte access and item access
349  * @param[in]  buf  Address of ring buffer.
351  *		    ring buffer.
352  * @param[in]  size Requested size (in bytes).
354  * @return Number of valid bytes in the provided buffer which can be smaller
355  *	   than requested if there is not enough free space or buffer wraps.
359 			    uint32_t size);
362  * @brief Indicate number of bytes read from claimed buffer.
366  * bytes will remain available in the buffer.
369  * Use cases involving multiple reads of the ring buffer must prevent
371  * being preempted or by using a mutex to govern reads to the ring buffer.
374  * Ring buffer instance should not mix byte access and  item mode
377  * @param  buf  Address of ring buffer.
378  * @param  size Number of bytes that can be freed.
381  * @retval -EINVAL Provided @a size exceeds valid bytes in the ring buffer.
383 int ring_buf_get_finish(struct ring_buf *buf, uint32_t size);
386  * @brief Read data from a ring buffer.
388  * This routine reads data from a ring buffer @a buf.
391  * Use cases involving multiple reads of the ring buffer must prevent
393  * being preempted or by using a mutex to govern reads to the ring buffer.
396  * Ring buffer instance should not mix byte access and  item mode
399  * @param buf  Address of ring buffer.
400  * @param data Address of the output buffer. Can be NULL to discard data.
401  * @param size Data size (in bytes).
403  * @retval Number of bytes written to the output buffer.
405 uint32_t ring_buf_get(struct ring_buf *buf, uint8_t *data, uint32_t size);
408  * @brief Peek at data from a ring buffer.
410  * This routine reads data from a ring buffer @a buf without removal.
413  * Use cases involving multiple reads of the ring buffer must prevent
415  * being preempted or by using a mutex to govern reads to the ring buffer.
418  * Ring buffer instance should not mix byte access and  item mode
425  * non-zero `size`.
427  * @param buf  Address of ring buffer.
428  * @param data Address of the output buffer. Cannot be NULL.
429  * @param size Data size (in bytes).
431  * @retval Number of bytes written to the output buffer.
433 uint32_t ring_buf_peek(struct ring_buf *buf, uint8_t *data, uint32_t size);
436  * @brief Write a data item to a ring buffer.
438  * This routine writes a data item to ring buffer @a buf. The data item
439  * is an array of 32-bit words (from zero to 1020 bytes in length),
440  * coupled with a 16-bit type identifier and an 8-bit integer value.
443  * Use cases involving multiple writers to the ring buffer must prevent
445  * being preempted or by using a mutex to govern writes to the ring buffer.
447  * @param buf Address of ring buffer.
451  * @param size32 Data item size (number of 32-bit words).
454  * @retval -EMSGSIZE Ring buffer has insufficient free space.
460  * @brief Read a data item from a ring buffer.
462  * This routine reads a data item from ring buffer @a buf. The data item
463  * is an array of 32-bit words (up to 1020 bytes in length),
464  * coupled with a 16-bit type identifier and an 8-bit integer value.
467  * Use cases involving multiple reads of the ring buffer must prevent
469  * being preempted or by using a mutex to govern reads to the ring buffer.
471  * @param buf Address of ring buffer.
475  * @param size32 Size of the data item storage area (number of 32-bit chunks).
478  *         32-bit words read into data area @a data.
479  * @retval -EAGAIN Ring buffer is empty.
480  * @retval -EMSGSIZE Data area @a data is too small; @a size32 now contains
481  *         the number of 32-bit words needed.