1 /* ring_buffer.h: Simple ring buffer API */
2 
3 /*
4  * Copyright (c) 2015 Intel Corporation
5  *
6  * SPDX-License-Identifier: Apache-2.0
7  */
8 /** @file */
9 
10 #ifndef ZEPHYR_INCLUDE_SYS_RING_BUFFER_H_
11 #define ZEPHYR_INCLUDE_SYS_RING_BUFFER_H_
12 
13 #include <zephyr/kernel.h>
14 #include <zephyr/sys/util.h>
15 #include <errno.h>
16 
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20 
21 /* The limit is used by algorithm for distinguishing between empty and full
22  * state.
23  */
24 #define RING_BUFFER_MAX_SIZE 0x80000000U
25 
26 #define RING_BUFFER_SIZE_ASSERT_MSG \
27 	"Size too big"
28 
29 /**
30  * @brief A structure to represent a ring buffer
31  */
32 struct ring_buf {
33 	uint8_t *buffer;
34 	int32_t put_head;
35 	int32_t put_tail;
36 	int32_t put_base;
37 	int32_t get_head;
38 	int32_t get_tail;
39 	int32_t get_base;
40 	uint32_t size;
41 };
42 
43 /**
44  * @brief Function to force ring_buf internal states to given value
45  *
46  * Any value other than 0 makes sense only in validation testing context.
47  */
ring_buf_internal_reset(struct ring_buf * buf,int32_t value)48 static inline void ring_buf_internal_reset(struct ring_buf *buf, int32_t value)
49 {
50 	buf->put_head = buf->put_tail = buf->put_base = value;
51 	buf->get_head = buf->get_tail = buf->get_base = value;
52 }
53 
54 /**
55  * @defgroup ring_buffer_apis Ring Buffer APIs
56  * @ingroup datastructure_apis
57  * @{
58  */
59 
60 /**
61  * @brief Define and initialize a ring buffer for byte data.
62  *
63  * This macro establishes a ring buffer of an arbitrary size.
64  * The basic storage unit is a byte.
65  *
66  * The ring buffer can be accessed outside the module where it is defined
67  * using:
68  *
69  * @code extern struct ring_buf <name>; @endcode
70  *
71  * @param name  Name of the ring buffer.
72  * @param size8 Size of ring buffer (in bytes).
73  */
74 #define RING_BUF_DECLARE(name, size8) \
75 	BUILD_ASSERT(size8 < RING_BUFFER_MAX_SIZE,\
76 		RING_BUFFER_SIZE_ASSERT_MSG); \
77 	static uint8_t __noinit _ring_buffer_data_##name[size8]; \
78 	struct ring_buf name = { \
79 		.buffer = _ring_buffer_data_##name, \
80 		.size = size8 \
81 	}
82 
83 /**
84  * @brief Define and initialize an "item based" ring buffer.
85  *
86  * This macro establishes an "item based" ring buffer. Each data item is
87  * an array of 32-bit words (from zero to 1020 bytes in length), coupled
88  * with a 16-bit type identifier and an 8-bit integer value.
89  *
90  * The ring buffer can be accessed outside the module where it is defined
91  * using:
92  *
93  * @code extern struct ring_buf <name>; @endcode
94  *
95  * @param name Name of the ring buffer.
96  * @param size32 Size of ring buffer (in 32-bit words).
97  */
98 #define RING_BUF_ITEM_DECLARE(name, size32) \
99 	BUILD_ASSERT((size32) < RING_BUFFER_MAX_SIZE / 4,\
100 		RING_BUFFER_SIZE_ASSERT_MSG); \
101 	static uint32_t __noinit _ring_buffer_data_##name[size32]; \
102 	struct ring_buf name = { \
103 		.buffer = (uint8_t *) _ring_buffer_data_##name, \
104 		.size = 4 * (size32) \
105 	}
106 
107 /**
108  * @brief Define and initialize an "item based" ring buffer.
109  *
110  * This exists for backward compatibility reasons. @ref RING_BUF_ITEM_DECLARE
111  * should be used instead.
112  *
113  * @param name Name of the ring buffer.
114  * @param size32 Size of ring buffer (in 32-bit words).
115  */
116 #define RING_BUF_ITEM_DECLARE_SIZE(name, size32) \
117 	RING_BUF_ITEM_DECLARE(name, size32)
118 
119 /**
120  * @brief Define and initialize a power-of-2 sized "item based" ring buffer.
121  *
122  * This macro establishes an "item based" ring buffer by specifying its
123  * size using a power of 2. This exists mainly for backward compatibility
124  * reasons. @ref RING_BUF_ITEM_DECLARE should be used instead.
125  *
126  * @param name Name of the ring buffer.
127  * @param pow Ring buffer size exponent.
128  */
129 #define RING_BUF_ITEM_DECLARE_POW2(name, pow) \
130 	RING_BUF_ITEM_DECLARE(name, BIT(pow))
131 
132 /**
133  * @brief Compute the ring buffer size in 32-bit needed to store an element
134  *
135  * The argument can be a type or an expression.
136  * Note: rounds up if the size is not a multiple of 32 bits.
137  *
138  * @param expr Expression or type to compute the size of
139  */
140 #define RING_BUF_ITEM_SIZEOF(expr) DIV_ROUND_UP(sizeof(expr), sizeof(uint32_t))
141 
142 /**
143  * @brief Initialize a ring buffer for byte data.
144  *
145  * This routine initializes a ring buffer, prior to its first use. It is only
146  * used for ring buffers not defined using RING_BUF_DECLARE.
147  *
148  * @param buf Address of ring buffer.
149  * @param size Ring buffer size (in bytes).
150  * @param data Ring buffer data area (uint8_t data[size]).
151  */
ring_buf_init(struct ring_buf * buf,uint32_t size,uint8_t * data)152 static inline void ring_buf_init(struct ring_buf *buf,
153 				 uint32_t size,
154 				 uint8_t *data)
155 {
156 	__ASSERT(size < RING_BUFFER_MAX_SIZE, RING_BUFFER_SIZE_ASSERT_MSG);
157 
158 	buf->size = size;
159 	buf->buffer = data;
160 	ring_buf_internal_reset(buf, 0);
161 }
162 
163 /**
164  * @brief Initialize an "item based" ring buffer.
165  *
166  * This routine initializes a ring buffer, prior to its first use. It is only
167  * used for ring buffers not defined using RING_BUF_ITEM_DECLARE.
168  *
169  * Each data item is an array of 32-bit words (from zero to 1020 bytes in
170  * length), coupled with a 16-bit type identifier and an 8-bit integer value.
171  *
172  * Each data item is an array of 32-bit words (from zero to 1020 bytes in
173  * length), coupled with a 16-bit type identifier and an 8-bit integer value.
174  *
175  * @param buf Address of ring buffer.
176  * @param size Ring buffer size (in 32-bit words)
177  * @param data Ring buffer data area (uint32_t data[size]).
178  */
ring_buf_item_init(struct ring_buf * buf,uint32_t size,uint32_t * data)179 static inline void ring_buf_item_init(struct ring_buf *buf,
180 				      uint32_t size,
181 				      uint32_t *data)
182 {
183 	__ASSERT(size < RING_BUFFER_MAX_SIZE / 4, RING_BUFFER_SIZE_ASSERT_MSG);
184 	ring_buf_init(buf, 4 * size, (uint8_t *)data);
185 }
186 
187 /**
188  * @brief Determine if a ring buffer is empty.
189  *
190  * @param buf Address of ring buffer.
191  *
192  * @return true if the ring buffer is empty, or false if not.
193  */
ring_buf_is_empty(struct ring_buf * buf)194 static inline bool ring_buf_is_empty(struct ring_buf *buf)
195 {
196 	return buf->get_head == buf->put_tail;
197 }
198 
199 /**
200  * @brief Reset ring buffer state.
201  *
202  * @param buf Address of ring buffer.
203  */
ring_buf_reset(struct ring_buf * buf)204 static inline void ring_buf_reset(struct ring_buf *buf)
205 {
206 	ring_buf_internal_reset(buf, 0);
207 }
208 
209 /**
210  * @brief Determine free space in a ring buffer.
211  *
212  * @param buf Address of ring buffer.
213  *
214  * @return Ring buffer free space (in bytes).
215  */
ring_buf_space_get(struct ring_buf * buf)216 static inline uint32_t ring_buf_space_get(struct ring_buf *buf)
217 {
218 	return buf->size - (buf->put_head - buf->get_tail);
219 }
220 
221 /**
222  * @brief Determine free space in an "item based" ring buffer.
223  *
224  * @param buf Address of ring buffer.
225  *
226  * @return Ring buffer free space (in 32-bit words).
227  */
ring_buf_item_space_get(struct ring_buf * buf)228 static inline uint32_t ring_buf_item_space_get(struct ring_buf *buf)
229 {
230 	return ring_buf_space_get(buf) / 4;
231 }
232 
233 /**
234  * @brief Return ring buffer capacity.
235  *
236  * @param buf Address of ring buffer.
237  *
238  * @return Ring buffer capacity (in bytes).
239  */
ring_buf_capacity_get(struct ring_buf * buf)240 static inline uint32_t ring_buf_capacity_get(struct ring_buf *buf)
241 {
242 	return buf->size;
243 }
244 
245 /**
246  * @brief Determine used space in a ring buffer.
247  *
248  * @param buf Address of ring buffer.
249  *
250  * @return Ring buffer space used (in bytes).
251  */
ring_buf_size_get(struct ring_buf * buf)252 static inline uint32_t ring_buf_size_get(struct ring_buf *buf)
253 {
254 	return buf->put_tail - buf->get_head;
255 }
256 
257 /**
258  * @brief Allocate buffer for writing data to a ring buffer.
259  *
260  * With this routine, memory copying can be reduced since internal ring buffer
261  * can be used directly by the user. Once data is written to allocated area
262  * number of bytes written must be confirmed (see @ref ring_buf_put_finish).
263  *
264  * @warning
265  * Use cases involving multiple writers to the ring buffer must prevent
266  * concurrent write operations, either by preventing all writers from
267  * being preempted or by using a mutex to govern writes to the ring buffer.
268  *
269  * @warning
270  * Ring buffer instance should not mix byte access and item access
271  * (calls prefixed with ring_buf_item_).
272  *
273  * @param[in]  buf  Address of ring buffer.
274  * @param[out] data Pointer to the address. It is set to a location within
275  *		    ring buffer.
276  * @param[in]  size Requested allocation size (in bytes).
277  *
278  * @return Size of allocated buffer which can be smaller than requested if
279  *	   there is not enough free space or buffer wraps.
280  */
281 uint32_t ring_buf_put_claim(struct ring_buf *buf,
282 			    uint8_t **data,
283 			    uint32_t size);
284 
285 /**
286  * @brief Indicate number of bytes written to allocated buffers.
287  *
288  * The number of bytes must be equal to or lower than the sum corresponding
289  * to all preceding @ref ring_buf_put_claim invocations (or even 0). Surplus
290  * bytes will be returned to the available free buffer space.
291  *
292  * @warning
293  * Use cases involving multiple writers to the ring buffer must prevent
294  * concurrent write operations, either by preventing all writers from
295  * being preempted or by using a mutex to govern writes to the ring buffer.
296  *
297  * @warning
298  * Ring buffer instance should not mix byte access and item access
299  * (calls prefixed with ring_buf_item_).
300  *
301  * @param  buf  Address of ring buffer.
302  * @param  size Number of valid bytes in the allocated buffers.
303  *
304  * @retval 0 Successful operation.
305  * @retval -EINVAL Provided @a size exceeds free space in the ring buffer.
306  */
307 int ring_buf_put_finish(struct ring_buf *buf, uint32_t size);
308 
309 /**
310  * @brief Write (copy) data to a ring buffer.
311  *
312  * This routine writes data to a ring buffer @a buf.
313  *
314  * @warning
315  * Use cases involving multiple writers to the ring buffer must prevent
316  * concurrent write operations, either by preventing all writers from
317  * being preempted or by using a mutex to govern writes to the ring buffer.
318  *
319  * @warning
320  * Ring buffer instance should not mix byte access and item access
321  * (calls prefixed with ring_buf_item_).
322  *
323  * @param buf Address of ring buffer.
324  * @param data Address of data.
325  * @param size Data size (in bytes).
326  *
327  * @retval Number of bytes written.
328  */
329 uint32_t ring_buf_put(struct ring_buf *buf, const uint8_t *data, uint32_t size);
330 
331 /**
332  * @brief Get address of a valid data in a ring buffer.
333  *
334  * With this routine, memory copying can be reduced since internal ring buffer
335  * can be used directly by the user. Once data is processed it must be freed
336  * using @ref ring_buf_get_finish.
337  *
338  * @warning
339  * Use cases involving multiple reads of the ring buffer must prevent
340  * concurrent read operations, either by preventing all readers from
341  * being preempted or by using a mutex to govern reads to the ring buffer.
342  *
343  * @warning
344  * Ring buffer instance should not mix byte access and item access
345  * (calls prefixed with ring_buf_item_).
346  *
347  * @param[in]  buf  Address of ring buffer.
348  * @param[out] data Pointer to the address. It is set to a location within
349  *		    ring buffer.
350  * @param[in]  size Requested size (in bytes).
351  *
352  * @return Number of valid bytes in the provided buffer which can be smaller
353  *	   than requested if there is not enough free space or buffer wraps.
354  */
355 uint32_t ring_buf_get_claim(struct ring_buf *buf,
356 			    uint8_t **data,
357 			    uint32_t size);
358 
359 /**
360  * @brief Indicate number of bytes read from claimed buffer.
361  *
362  * The number of bytes must be equal or lower than the sum corresponding to
363  * all preceding @ref ring_buf_get_claim invocations (or even 0). Surplus
364  * bytes will remain available in the buffer.
365  *
366  * @warning
367  * Use cases involving multiple reads of the ring buffer must prevent
368  * concurrent read operations, either by preventing all readers from
369  * being preempted or by using a mutex to govern reads to the ring buffer.
370  *
371  * @warning
372  * Ring buffer instance should not mix byte access and  item mode
373  * (calls prefixed with ring_buf_item_).
374  *
375  * @param  buf  Address of ring buffer.
376  * @param  size Number of bytes that can be freed.
377  *
378  * @retval 0 Successful operation.
379  * @retval -EINVAL Provided @a size exceeds valid bytes in the ring buffer.
380  */
381 int ring_buf_get_finish(struct ring_buf *buf, uint32_t size);
382 
383 /**
384  * @brief Read data from a ring buffer.
385  *
386  * This routine reads data from a ring buffer @a buf.
387  *
388  * @warning
389  * Use cases involving multiple reads of the ring buffer must prevent
390  * concurrent read operations, either by preventing all readers from
391  * being preempted or by using a mutex to govern reads to the ring buffer.
392  *
393  * @warning
394  * Ring buffer instance should not mix byte access and  item mode
395  * (calls prefixed with ring_buf_item_).
396  *
397  * @param buf  Address of ring buffer.
398  * @param data Address of the output buffer. Can be NULL to discard data.
399  * @param size Data size (in bytes).
400  *
401  * @retval Number of bytes written to the output buffer.
402  */
403 uint32_t ring_buf_get(struct ring_buf *buf, uint8_t *data, uint32_t size);
404 
405 /**
406  * @brief Peek at data from a ring buffer.
407  *
408  * This routine reads data from a ring buffer @a buf without removal.
409  *
410  * @warning
411  * Use cases involving multiple reads of the ring buffer must prevent
412  * concurrent read operations, either by preventing all readers from
413  * being preempted or by using a mutex to govern reads to the ring buffer.
414  *
415  * @warning
416  * Ring buffer instance should not mix byte access and  item mode
417  * (calls prefixed with ring_buf_item_).
418  *
419  * @warning
420  * Multiple calls to peek will result in the same data being 'peeked'
421  * multiple times. To remove data, use either @ref ring_buf_get or
422  * @ref ring_buf_get_claim followed by @ref ring_buf_get_finish with a
423  * non-zero `size`.
424  *
425  * @param buf  Address of ring buffer.
426  * @param data Address of the output buffer. Cannot be NULL.
427  * @param size Data size (in bytes).
428  *
429  * @retval Number of bytes written to the output buffer.
430  */
431 uint32_t ring_buf_peek(struct ring_buf *buf, uint8_t *data, uint32_t size);
432 
433 /**
434  * @brief Write a data item to a ring buffer.
435  *
436  * This routine writes a data item to ring buffer @a buf. The data item
437  * is an array of 32-bit words (from zero to 1020 bytes in length),
438  * coupled with a 16-bit type identifier and an 8-bit integer value.
439  *
440  * @warning
441  * Use cases involving multiple writers to the ring buffer must prevent
442  * concurrent write operations, either by preventing all writers from
443  * being preempted or by using a mutex to govern writes to the ring buffer.
444  *
445  * @param buf Address of ring buffer.
446  * @param type Data item's type identifier (application specific).
447  * @param value Data item's integer value (application specific).
448  * @param data Address of data item.
449  * @param size32 Data item size (number of 32-bit words).
450  *
451  * @retval 0 Data item was written.
452  * @retval -EMSGSIZE Ring buffer has insufficient free space.
453  */
454 int ring_buf_item_put(struct ring_buf *buf, uint16_t type, uint8_t value,
455 		      uint32_t *data, uint8_t size32);
456 
457 /**
458  * @brief Read a data item from a ring buffer.
459  *
460  * This routine reads a data item from ring buffer @a buf. The data item
461  * is an array of 32-bit words (up to 1020 bytes in length),
462  * coupled with a 16-bit type identifier and an 8-bit integer value.
463  *
464  * @warning
465  * Use cases involving multiple reads of the ring buffer must prevent
466  * concurrent read operations, either by preventing all readers from
467  * being preempted or by using a mutex to govern reads to the ring buffer.
468  *
469  * @param buf Address of ring buffer.
470  * @param type Area to store the data item's type identifier.
471  * @param value Area to store the data item's integer value.
472  * @param data Area to store the data item. Can be NULL to discard data.
473  * @param size32 Size of the data item storage area (number of 32-bit chunks).
474  *
475  * @retval 0 Data item was fetched; @a size32 now contains the number of
476  *         32-bit words read into data area @a data.
477  * @retval -EAGAIN Ring buffer is empty.
478  * @retval -EMSGSIZE Data area @a data is too small; @a size32 now contains
479  *         the number of 32-bit words needed.
480  */
481 int ring_buf_item_get(struct ring_buf *buf, uint16_t *type, uint8_t *value,
482 		      uint32_t *data, uint8_t *size32);
483 
484 /**
485  * @}
486  */
487 
488 #ifdef __cplusplus
489 }
490 #endif
491 
492 #endif /* ZEPHYR_INCLUDE_SYS_RING_BUFFER_H_ */
493