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