Skip to content

Commit cdf500e

Browse files
author
zigam
committed
- removed unneeded code
- updated readme
1 parent 617b77b commit cdf500e

2 files changed

Lines changed: 172 additions & 25 deletions

File tree

‎README.md‎

Lines changed: 172 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,43 @@
11
# Ring buffer
2-
Ring buffer modules is implemented for general used in embedded C code. It support three data types: uint32_t, int32_t and float32_t. Data type is not importatn at initialization point as it is only how stored information are interpreted by C compiler.
2+
This module constains ring buffer implementation for general purpose usage.
3+
It can work with simple byte size item or larger size items. Module is
4+
written in such a way that all details are hidden from user. Additionally
5+
buffers are created as individual, separated instances so different
6+
instances of buffer can be configured differently in order to addopt application needs.
37

4-
Ring buffer memory space is dynamically allocated and success of allocation is taken into consideration before using that instance. Deallocation on exsisting ring buffer instance is not supported as it's not good practice to free memory in C world.
8+
Override mode is supported where buffer is never full and new values are
9+
always overriding old values regarding of reading rate. This functionality
10+
is very usefull for filter sampling storage purposes.
511

6-
#### Dependencies
12+
Additionally buffers data storage can be allocated statically if dynamic
13+
allocation is not perfered by application. Look at the example of
14+
static allocation of memory.
15+
16+
There are two distinct get functions: "ring_buffer_get" and "ring_buffer_get_by_index".
17+
First one returns oldest item in buffer and acts as a FIFO, meaning that tail increments
18+
at every call of it. On the other side "ring_buffer_get_by_index" returns value relative
19+
to input argument value and does not increment tail pointer! It is important not to
20+
use those two get functionalities simultaniously.
21+
22+
Function "ring_buffer_get_by_index" supports two kind of access types:
23+
24+
1. NORMAL ACCESS: classical aproach, where index is a positive
25+
number and simple represants buffer index. This approach
26+
has no information about time stamps of values inside buffer.
27+
Range: [0, size)
28+
29+
2. INVERS ACCESS: chronologically aproach, where index is a negative number.
30+
Meaning that "-1" value will always returns latest value in
31+
buffer and "-size" index value will return oldest value
32+
in buffer. This feature becomes very handy when performing
33+
digital filtering where ring buffer can represants sample
34+
window and thus easy access from oldest to latest sample
35+
can be achieved with invers access.
36+
Range of index: [-size, -1]
37+
38+
39+
40+
## Dependencies
741

842
Definition of flaot32_t must be provided by user. In current implementation it is defined in "*project_config.h*". Just add following statement to your code where it suits the best.
943

@@ -12,19 +46,144 @@ Definition of flaot32_t must be provided by user. In current implementation it i
1246
typedef float float32_t;
1347
```
1448

15-
#### API
49+
## API
1650

1751
API of ring buffer constist of three blocks, those are: initialization, add element to buffer and get element from buffer. Note that getting element from buffer intakes intiger parameter as support normal and invers access. Invers access meas that get function will return time related element from ring buffer. This feature is specially handy when comes to digital filter calculations.
1852

19-
#### List of functions:
20-
- ring_buffer_status_t **ring_buffer_init** (p_ring_buffer_t * p_ring_buffer, const uint32_t size);
53+
#### List of API functions:
54+
- 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);
55+
- ring_buffer_status_t **ring_buffer_is_init** (p_ring_buffer_t buf_inst, bool * const p_is_init);
56+
57+
- ring_buffer_status_t **ring_buffer_add** (p_ring_buffer_t buf_inst, const void * const p_item);
58+
- ring_buffer_status_t **ring_buffer_get** (p_ring_buffer_t buf_inst, void * const p_item);
59+
- ring_buffer_status_t **ring_buffer_get_by_index** (p_ring_buffer_t buf_inst, void * const p_item, const int32_t idx);
60+
- ring_buffer_status_t **ring_buffer_reset** (p_ring_buffer_t buf_inst);
61+
62+
- ring_buffer_status_t **ring_buffer_get_name** (p_ring_buffer_t buf_inst, char * const p_name);
63+
- ring_buffer_status_t **ring_buffer_get_taken** (p_ring_buffer_t buf_inst, uint32_t * const p_taken);
64+
- ring_buffer_status_t **ring_buffer_get_free** (p_ring_buffer_t buf_inst, uint32_t * const p_free);
65+
- ring_buffer_status_t **ring_buffer_get_size** (p_ring_buffer_t buf_inst, uint32_t * const p_size);
66+
- ring_buffer_status_t **ring_buffer_get_item_size** (p_ring_buffer_t buf_inst, uint32_t * const p_item_size);
67+
68+
69+
NOTE: Detailed description of functions can be found in doxygen (doc/**ring_buffer_Vx_x_x.zip**)!
70+
71+
## Usage
72+
73+
### Initialization examples
74+
75+
```C
76+
// My ring buffer instance
77+
p_ring_buffer_t my_ringbuffer = NULL;
78+
79+
// Initialization as default buffer with size of 10 items + Dynamica allocation of memory
80+
if ( eRING_BUFFER_OK != ring_buffer_init( &my_ringbuffer, 10, NULL ))
81+
{
82+
// Init failed...
83+
}
84+
85+
86+
// My second ring buffer instance
87+
p_ring_buffer_t my_ringbuffer_2 = NULL;
88+
ring_buffer_attr_t my_ringbuffer_2_attr;
89+
90+
// Customize ring buffer:
91+
my_ring_buffer_2_attr.name = "Dynamic allocated buffer";
92+
my_ring_buffer_2_attr.p_mem = NULL;
93+
my_ring_buffer_2_attr.item_size = sizeof(float32_t);
94+
my_ring_buffer_2_attr.override = true;
95+
96+
// Initialization as customized buffer with size of 32 items + Dynamic allocation of memory
97+
if ( eRING_BUFFER_OK != ring_buffer_init( &my_ringbuffer_2, 32, &my_ring_buffer_2_attr ))
98+
{
99+
// Init failed...
100+
}
101+
102+
103+
// My third ring buffer instance
104+
p_ring_buffer_t my_ringbuffer_3 = NULL;
105+
ring_buffer_attr_t my_ringbuffer_3_attr;
106+
uint8_t buf_mem[128];
107+
108+
// Customize ring buffer:
109+
my_ring_buffer_3_attr.name = "Static allocated buffer";
110+
my_ring_buffer_3_attr.p_mem = &buf_mem;
111+
my_ring_buffer_3_attr.item_size = sizeof(float32_t);
112+
my_ring_buffer_3_attr.override = true;
113+
114+
// Initialization as customised buffer with size of 32 items + Static allocation of memory
115+
if ( eRING_BUFFER_OK != ring_buffer_init( &my_ringbuffer_2, 32, &my_ring_buffer_2_attr ))
116+
{
117+
// Init failed...
118+
}
119+
120+
```
121+
122+
### Get items out of buffer examples
123+
124+
```C
125+
// My ring buffer is initialized for byte items
126+
uint8_t item;
127+
128+
// =============================================================
129+
// GETTING VALUE
130+
// =============================================================
131+
132+
// Pump all items out of buffer
133+
ring_buffer_get_taken( my_ring_buffer, &taken );
134+
135+
for ( i = 0; i < taken; i++ )
136+
{
137+
ring_buffer_get( my_ring_buffer, &item );
138+
139+
// So something with "item" value here...
140+
}
141+
142+
// OR equivalent
143+
144+
while( eRING_BUFFER_EMPTY != ring_buffer_get( my_ring_buffer, &item ))
145+
{
146+
// So something with "item" value here...
147+
}
148+
149+
150+
// =============================================================
151+
// GETTING VALUE BY INDEX
152+
// =============================================================
153+
154+
// Get value at index 0 from ring buffer - classic access
155+
ring_buffer_get_by_index( my_ringbuffer, &item, 0 );
21156

22-
- ring_buffer_status_t **ring_buffer_add_u32** (p_ring_buffer_t buf_inst, const uint32_t data);
23-
- ring_buffer_status_t **ring_buffer_add_i32** (p_ring_buffer_t buf_inst, const int32_t data );
24-
- ring_buffer_status_t **ring_buffer_add_f** (p_ring_buffer_t buf_inst, const float32_t data);
25-
- uint32_t **ring_buffer_get_u32** (p_ring_buffer_t buf_inst, const int32_t idx);
26-
- int32_t **ring_buffer_get_i32** (p_ring_buffer_t buf_inst, const int32_t idx);
27-
- float32_t **ring_buffer_get_f** (p_ring_buffer_t buf_inst, const int32_t idx);
157+
// Get latest value from ring buffer - inverted access
158+
ring_buffer_get_by_index( my_ringbuffer, &item, -1 );
28159

29-
NOTE: Detailed description of fucntion can be found in doxygen!
160+
// Get oldest value from ring buffer - inverted access
161+
ring_buffer_get_by_index( my_ringbuffer, &item, -10 );
162+
163+
164+
// ***** Example of filter usage of getting value by index ****
165+
166+
float32_t sample;
167+
168+
// Make convolution
169+
for ( i = 0; i < filter_inst -> order; i++ )
170+
{
171+
// Get sample
172+
ring_buffer_get_by_index( filter_inst->p_x, &sample, (( -i ) - 1 ));
173+
174+
// Convolve
175+
y += ( filter_inst->p_a[i] * sample );
176+
}
177+
178+
```
179+
180+
### Add item to buffer examples
181+
182+
```C
183+
// My ring buffer is initialized for byte items
184+
uint8_t item;
185+
186+
// Add value to buffer
187+
ring_buffer_add( my_ringbuffer, &item );
188+
```
30189

‎src/ring_buffer.h‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -95,18 +95,6 @@ ring_buffer_status_t ring_buffer_get_free (p_ring_buffer_t buf_inst, uint32_t *
9595
ring_buffer_status_t ring_buffer_get_size (p_ring_buffer_t buf_inst, uint32_t * const p_size);
9696
ring_buffer_status_t ring_buffer_get_item_size (p_ring_buffer_t buf_inst, uint32_t * const p_item_size);
9797

98-
99-
100-
#if (0) // OBSOLETE
101-
ring_buffer_status_t ring_buffer_add_u32 (p_ring_buffer_t buf_inst, const uint32_t data);
102-
ring_buffer_status_t ring_buffer_add_i32 (p_ring_buffer_t buf_inst, const int32_t data );
103-
ring_buffer_status_t ring_buffer_add_f (p_ring_buffer_t buf_inst, const float32_t data);
104-
uint32_t ring_buffer_get_u32 (p_ring_buffer_t buf_inst, const int32_t idx);
105-
int32_t ring_buffer_get_i32 (p_ring_buffer_t buf_inst, const int32_t idx);
106-
float32_t ring_buffer_get_f (p_ring_buffer_t buf_inst, const int32_t idx);
107-
#endif
108-
109-
11098
#endif // __RING_BUFFER_H
11199

112100
////////////////////////////////////////////////////////////////////////////////

0 commit comments

Comments
 (0)