Merge remote-tracking branch 'origin/develop' into main

Author: zigam

README.md

@@ -21,18 +21,18 @@ use those two get functionalities simultaniously.
 
 Function "ring_buffer_get_by_index" supports two kind of access types:
 
-1. NORMAL ACCESS: 	classical aproach, where index is a positive
+1. **NORMAL ACCESS: 	classical aproach**, where index is a positive
 						number and simple represants buffer index. This approach
 						has no information about time stamps of values inside buffer.
 						Range: [0, size)
 
-2. INVERS ACCESS: 	chronologically aproach, where index is a negative number.
+2. **INVERS ACCESS: 	chronologically aproach**, where index is a negative number.
 						Meaning that "-1" value will always returns latest value in
 						buffer and "-size" index value will return oldest value
-						in buffer. This feature becomes very handy when performing
-						digital filtering where ring buffer can represants sample
+						in buffer. ***This feature becomes very handy when performing
+						digital filtering (convolution) where ring buffer can represants sample
 						window and thus easy access from oldest to latest sample
-						can be achieved with invers access.
+						can be achieved with invers access.***
 						Range of index: [-size, -1]
 
 
@@ -41,21 +41,28 @@ Function "ring_buffer_get_by_index" supports two kind of access types:
 
 This module needs only ANSI C standard libraries. 
 
-## API
+## Multientry Limitations
+
+Guidance for multi-entry usage: 
+ - **It is recomented to use ring_buffer between two task/interrupts/cores in provider/consumer manner.** Meaning one task/interrupt/core is writing to ring_buffer and other task/interrupt/core is reading from it.
+ - **It is not recommended for two or more task/interrupt/core to read/write to same ring_buffer instance!**
 
- - ring_buffer_status_t 	**ring_buffer_init**			(p_ring_buffer_t * p_ring_buffer, const uint32_t size, const ring_buffer_attr_t * const p_attr);
- - ring_buffer_status_t	**ring_buffer_is_init**			(p_ring_buffer_t buf_inst, bool * const p_is_init);
 
- - ring_buffer_status_t	**ring_buffer_add** 			(p_ring_buffer_t buf_inst, const void * const p_item);
- - ring_buffer_status_t	**ring_buffer_get** 			(p_ring_buffer_t buf_inst, void * const p_item);
- - ring_buffer_status_t	**ring_buffer_get_by_index**	(p_ring_buffer_t buf_inst, void * const p_item, const int32_t idx);
- - ring_buffer_status_t	**ring_buffer_reset**			(p_ring_buffer_t buf_inst);
+## API
 
- - ring_buffer_status_t	**ring_buffer_get_name**		(p_ring_buffer_t buf_inst, char * const p_name);
- - ring_buffer_status_t	**ring_buffer_get_taken**		(p_ring_buffer_t buf_inst, uint32_t * const p_taken);
- - ring_buffer_status_t	**ring_buffer_get_free**		(p_ring_buffer_t buf_inst, uint32_t * const p_free);
- - ring_buffer_status_t	**ring_buffer_get_size**		(p_ring_buffer_t buf_inst, uint32_t * const p_size);
- - ring_buffer_status_t	**ring_buffer_get_item_size**	(p_ring_buffer_t buf_inst, uint32_t * const p_item_size);
+| API Functions | Description | Prototype |
+| --- | ----------- | ----- |
+| **ring_buffer_init** | Initialization of ring buffer | ring_buffer_status_t ring_buffer_init(p_ring_buffer_t * p_ring_buffer, const uint32_t size, const ring_buffer_attr_t * const p_attr) |
+| **ring_buffer_is_init** | Get initialization flag | ring_buffer_status_t ring_buffer_is_init(p_ring_buffer_t buf_inst, bool * const p_is_init) |
+| **ring_buffer_add** | Add element to ring buffer in FIFO form | ring_buffer_status_t ring_buffer_add(p_ring_buffer_t buf_inst, const void * const p_item) |
+| **ring_buffer_get** | Get element from ring buffer in FIFO form | ring_buffer_status_t ring_buffer_get(p_ring_buffer_t buf_inst, void * const p_item) |
+| **ring_buffer_get_by_index** | Get element from ring buffer without any side effects. Access by index. | ring_buffer_status_t	ring_buffer_get_by_index(p_ring_buffer_t buf_inst, void * const p_item, const int32_t idx) |
+| **ring_buffer_reset** | Reset ring buffer | ring_buffer_status_t	ring_buffer_reset(p_ring_buffer_t buf_inst) |
+| **ring_buffer_get_name** | Get ring buffer name | ring_buffer_status_t ring_buffer_get_name(p_ring_buffer_t buf_inst, char * const p_name)|
+| **ring_buffer_get_taken** | Get number of taken space of elements inside a buffer | ring_buffer_status_t	ring_buffer_get_taken(p_ring_buffer_t buf_inst, uint32_t * const p_taken)|
+| **ring_buffer_get_free** | Get number of free space of elements inside a buffer | ring_buffer_status_t ring_buffer_get_free(p_ring_buffer_t buf_inst, uint32_t * const p_free)|
+| **ring_buffer_get_size** | Get size of all items inside ring buffer | ring_buffer_status_t ring_buffer_get_size(p_ring_buffer_t buf_inst, uint32_t * const p_size)|
+| **ring_buffer_get_item_size** | Get item size in bytes | ring_buffer_status_t ring_buffer_get_item_size(p_ring_buffer_t buf_inst, uint32_t * const p_item_size)|
 
 
 NOTE: Detailed description of functions can be found in doxygen (doc/**ring_buffer_Vx_x_x.zip**)!

src/ring_buffer.c

@@ -7,7 +7,7 @@
 *@brief     Ring (circular) buffer for general use
 *@author    Ziga Miklosic
 *@date      03.02.2021
-*@version   V2.0.1
+*@version   V2.0.2
 *
 *@section Description
 *
@@ -435,39 +435,50 @@ ring_buffer_status_t ring_buffer_init(p_ring_buffer_t * p_ring_buffer, const uin
 
 	if ( NULL != p_ring_buffer )
 	{
-		// Allocate ring buffer instance space
-		*p_ring_buffer = malloc( sizeof( ring_buffer_t ));
+		// Check if that instance is already allocated
+		// By meaning that this buffer instance was initialised before...
+		if ( NULL == *p_ring_buffer )
+		{
+			// Allocate ring buffer instance space
+			*p_ring_buffer = malloc( sizeof( ring_buffer_t ));
 
-		// Allocation success
-		if ( NULL != *p_ring_buffer )
-		{	
-			(*p_ring_buffer)->size_of_buffer = size;
-			(*p_ring_buffer)->head = 0;
-			(*p_ring_buffer)->tail = 0;
-			(*p_ring_buffer)->is_full = false;
-			(*p_ring_buffer)->is_empty = true;
-
-			// Default setup
-			if ( NULL == p_attr )
+			// Allocation success
+			if ( NULL != *p_ring_buffer )
 			{
-				status = ring_buffer_default_setup( *p_ring_buffer, size );
-			}
+				(*p_ring_buffer)->size_of_buffer = size;
+				(*p_ring_buffer)->head = 0;
+				(*p_ring_buffer)->tail = 0;
+				(*p_ring_buffer)->is_full = false;
+				(*p_ring_buffer)->is_empty = true;
+
+				// Default setup
+				if ( NULL == p_attr )
+				{
+					status = ring_buffer_default_setup( *p_ring_buffer, size );
+				}
 
-			// Customize setup
-			else
-			{
-				status = ring_buffer_custom_setup( *p_ring_buffer, size, p_attr );
-			}
+				// Customize setup
+				else
+				{
+					status = ring_buffer_custom_setup( *p_ring_buffer, size, p_attr );
+				}
 
-			// Setup success
-			if ( eRING_BUFFER_OK == status )
+				// Setup success
+				if ( eRING_BUFFER_OK == status )
+				{
+					(*p_ring_buffer)->is_init = true;
+				}
+			}
+			else
 			{
-				(*p_ring_buffer)->is_init = true;
+				status = eRING_BUFFER_ERROR_MEM;
 			}
 		}
+
+		// Already initialised
 		else
 		{
-			status = eRING_BUFFER_ERROR_MEM;
+			status = eRING_BUFFER_ERROR_INIT;
 		}
 	}
 	else

src/ring_buffer.h

@@ -7,7 +7,7 @@
 *@brief     Ring (circular) buffer for general use
 *@author    Ziga Miklosic
 *@date      03.02.2021
-*@version   V2.0.1
+*@version   V2.0.2
 */
 ////////////////////////////////////////////////////////////////////////////////
 /**
@@ -37,7 +37,7 @@
  */
 #define RING_BUFFER_VER_MAJOR		( 2 )
 #define RING_BUFFER_VER_MINOR		( 0 )
-#define RING_BUFFER_VER_DEVELOP		( 1 )
+#define RING_BUFFER_VER_DEVELOP		( 2 )
 
 /**
  * 	Status

version.txt

@@ -1,3 +1,16 @@
+============================================================
+ Version 2.0.2 (23.06.2022)
+============================================================
+ 
+ Features/Changes:
+ - Added protection for multiple init calls
+ - Added detailed description about module limitations
+   
+ Todo:
+  - 
+
+============================================================
+
 ============================================================
  Version 2.0.1 (25.05.2022)
 ============================================================