larshei / lovelybuffer

A FIFO and ring buffer implementation in C with custom data type and multiple buffers for e.g. double buffering or buffering multiple interfaces on embedded devices.

FIFO and ring buffer in C

This is an implementation of a buffer in C, with the following attributes:

• Buffer with user defined data type.
• Manages read/write and mutliple buffer instances.
• FIFO or ring buffer mode for each buffer instance.
• Buffer instances / slots can be claimed and returned for repeated use.
• The buffer struct is hidden to the user.
• The buffer struct is managing data, not storing tha data itself.
• Memory usage and execution time not known yet, both expected to be very low.

Unit tests in Ceedling are included.

The Buffer System

The buffer system is designed to provide multiple FIFO-buffers and allow asynchronous data collection / data processing.

After initialization, a buffer handle for each buffer is put on a stack and can be claimed by the users program. The buffer can later be returned to the system and claimed again.

Example Usage

Configuration

Lets assume you have an SPI driver, that requires a buffer for both input and output, and communication is based on exchanging bytes (= 8 bit length).

Configure the buffer system in buf_buffer_config.h like so:

#define DATA_TYPE          uint8_t
#define BUF_BUFFER_COUNT   2

System Init

At startup, the buffer system needs to be initialized, using

if (buf_init_system() != BUF_OK) {
    // handle error
}

Buffer Init

System init prepares the buffer system itself, not a specific buffer.

Each buffer must be initialized by itself. The buffers only manage data and dont contain the data themselves, so the user needs to provide memory for storage. Buffers will be used in the application based on their handle/pointer.

DATA_TYPE     buffer_array[100];
buf_buffer_t  buffer_handle;

To give the data storage information to the buffer system, create a buf_data_info_t structure:

buf_data_info_t             buffer_config;
buffer_config.array         = (DATA_TYPE*) buffer_array;
buffer_config.element_count = BUFFER_SIZE;
buffer_config.element_size  = sizeof(DATA_TYPE);

and pass it to the system to retrieve and initialize a buffer:

buffer_handle = buf_claim_and_init_buffer((buf_data_info_t*)&buffer_config);

Make sure to not claim more buffers than you have configured in BUF_BUFFER_COUNT, otherwise this function will return NULL instead of a buffer handle.

Buffer Mode

After buffer initialization, a buffer is used in FIFO mode. Users might want to switch to ring buffer mode. The difference is:

• FIFO: A FIFO blocks further write access when the buffer is full, making sure all data that was put in the buffer is taken out.
• Ring Buffer: A ring buffer always allows write access, overwriting old data after a wrap around. Oftentimes, a ring buffer does not have a dedicated read pointer (but we do!)

uint8_t  result1 = buf_fifo_buffer_mode(buffer_handle);
uint8_t  result2 = buf_ring_buffer_mode(buffer_handle);

The functions change the internal state of the buffer. It may be changed at any time. Returns BUF_OK.

Get the current buffer mode of either BUF_RINGBUF or BUF_FIFOBUF using

uint8_t  mode =  buf_get_buffer_mode(buffer_handle);

Buffer Usage

Using a buffer is pretty straight forward adding and reading values, using

uint8_t    result = buf_add_element (buffer_handle, value);
DATA_TYPE  value  = buf_read_element(buffer_handle);

buf_add_element returns BUF_OK or BUF_FULL. buf_read_element returns value or NULL.

The functions can be guarded by using

uint8_t  is_empty = buf_is_empty(buffer_handle);
uint8_t  is_full  = buf_is_full (buffer_handle);

Returning Buffers that are no longer used

In a scenario with continuous data collection and asynchronous data processing it may be a good idea to have the data collection task claim a buffer, fill it and then pass it on to one of many other tasks. These tasks can then return the buffer once its content has been processed.

uint8_t  result = buf_return_buffer(buffer_handle);

The function automtically checks, if the buffer_handle is a valid buffer address and if the buffer is already on the stack or not. The return values are BUF_OK, BUF_DUPLICATE (buffer already on stack), BUF_NULL (invalid handle).

Changelog

2020-05-12: Initial Version

lovelybuffer's Issues

Warn or block usage of the same data array in multiple buffers.

Right now, multiple buffers can be assigned to the same data array.
This means data might be manipulated from multiple sources and is therefore not safe.

Add units tests for writing to/reading from multiple buffers.

Currently, only one array and therefore buffer is read from and written to.

Add Unit Tests for Ring Buffer Mode

As part of PR #6 ring buffer mode was added.
Write units tests for this mode.
blocks #6