FIFO Byte Buffer

Modules
	printf Functionality for Buffer Module

Data Structures
struct	buffer_t

Macros
#define	BUFFER_PUSH_FAILED   1
	push failed (return value of PushData() )
#define	BUFFER_PUSH_SUCCEEDED   0
	push succeeded (return value of PushData() )

Functions
void	Push (buffer_t *buffer, char data)
char	Pop (buffer_t *buffer)
uint16_t	GetSize (buffer_t *buffer)
void	BufferInit (buffer_t *buffer, char *data_array, uint16_t max_size)
void	BufferSetCallback (buffer_t *buffer, void(*Callback)(buffer_t *buffer))
void	BufferClearCallback (buffer_t *buffer)
char	PushData (buffer_t *buffer, char *data, uint16_t length)

Detailed Description

This module implements a software FIFO buffer of bytes. It provides methods Push() and Pop() to add and remove bytes from the buffer.

The user is responsible for allocating the structure used to manage the buffer, buffer_t, as well as the actual byte array which will be used to implement the buffer. These are then passed to BufferInit() which must be called prior to any attempts to Push or Pop.

There is also a PushData() method which allows multiple bytes to be added to the buffer at once.

An alternative to this FIFO byte buffer is the Item Buffer module which works the same except with items of any size instead of being limited to bytes only.

Author

Michael Muhlbaier

Anthony Merlino

Version

0.1 Initial implementation

1.0 Made Push and Pop interrupt safe

1.1 Added PushData

1.2 Added and corrected documentation, removed include "system.h"

Function Documentation

void BufferClearCallback

(

buffer_t *

buffer

)

Clear/remove the callback function for 'buffer'

Parameters

buffer

Pointer to the buffer_t data structure whose callback function is to be cleared

void BufferInit	(	buffer_t *	buffer,
		char *	data_array,
		uint16_t	max_size
	)

Initialize a FIFO buffer

Example code:

#define TX_BUFFER_LENGTH 512
buffer_t tx; // transmit buffer
char tx_buffer_array[TX_BUFFER_LENGTH]
...
BufferInit(&tx, &tx_buffer_array[0], TX_BUFFER_LENGTH);

Parameters

buffer	Pointer to the buffer_t data structure to be initialized
data_array	Array of char data to implement the actual buffer
max_size	Maximum size of the buffer (should be the same length as the array)

void BufferSetCallback	(	buffer_t *	buffer,
		void(*)(buffer_t *buffer)	Callback
	)

Set Callback function for buffer to be called after items are Push'd to the buffer

The callback function will be called after anything is Push'd to the buffer. The function will be called with a pointer to the buffer which had an item pushed onto it.

Example:

void TxCallback(buffer_t * buf);
#define TX_BUFFER_LENGTH 512
buffer_t tx; // transmit buffer
char tx_buffer_array[TX_BUFFER_LENGTH]
...
BufferInit(&tx, &tx_buffer_array[0], TX_BUFFER_LENGTH);
BufferSetCallback(&tx, TxCallback);
...
void TxCallback(buffer_t * buf) {
        SET_UART_TX_IE();
}

This example is useful for a uC which has a hardware Tx interrupt flag which is set whenever there is room in the hardware Tx FIFO buffer. When done transmitting the interrupt must be disabled to avoid getting stuck in the ISR. When data needs to be sent the interrupt must be enabled again, thus the need for the callback.

Another usage could be to handle received data on a receive buffer.

Warning

many applications may use the Push method in a ISR which means the Callback would be called from a ISR. Thus care should be taken to ensure callbacks are both fast and interrupt safe

Parameters

buffer	Pointer to the buffer_t data structure whose callback function is to be set
Callback	Function pointer to a callback function with no return value and a buffer_t pointer input.

uint16_t GetSize

(

buffer_t *

buffer

)

GetSize returns the number of items in the FIFO buffer

BufferInit() should be used to initialize the buffer otherwise the return value will be meaningless

Parameters

buffer

Pointer to the buffer_t data structure holding the buffer info

Returns

Number of items in the buffer

char Pop

(

buffer_t *

buffer

)

Pop will return one item from the front of the FIFO buffer

Pop will return the item at the front of the FIFO buffer then increment (and wrap as needed) the front. If the buffer is empty it will return 0.

BufferInit() must be used to initialize the buffer prior to calling Pop and passing it a pointer to the buffer.

Parameters

buffer

Pointer to the buffer_t data structure holding the buffer info

Returns

Data of type char from the front of the buffer

Warning

is only interrupt safe if EnableInterrupts() and DisableInterrupts() are defined by hal_general.h

void Push	(	buffer_t *	buffer,
		char	data
	)

Push will add one item, data, to the FIFO buffer

Push will add one item to the rear of the data buffer then increment (and wrap is needed) the rear. If the buffer is full it will overwrite the data at the front of the buffer and increment the front.

BufferInit() must be used to initialize the buffer prior to calling Push and passing it a pointer to the buffer.

Parameters

buffer	Pointer to the buffer_t data structure holding the buffer info
data	char data to be added to the rear of the FIFO buffer

Warning

Push is only interrupt safe if EnableInterrupts() and DisableInterrupts() are defined by hal_general.h

char PushData	(	buffer_t *	buffer,
		char *	data,
		uint16_t	length
	)

Push a array of data to the buffer

Warning

PushData will disable interrupts while writing to the buffer. If length is long this could interfere with time sensitive ISRs. Consider using Push() if this is an issue.

PushData will add an array of items to the rear of the data buffer and increment (and wrap if needed) the rear. If the buffer does not have room none of the data will be pushed to the buffer.

BufferInit() must be used to initialize the buffer prior to calling PushData and passing it a pointer to the buffer.

Parameters

buffer	Pointer to the buffer_t data structure holding the buffer info
data	char pointer to data array to be added to the rear of the FIFO buffer
length	the number of items in the data array

Returns

0 if succeeded, 1 if no room in buffer