FIFO Item Buffer

Data Structures
struct	item_buffer_t

Functions
bool	PushItem (item_buffer_t *buffer, uint16_t *data)
void	PopItem (item_buffer_t *buffer, uint16_t *data)
uint16_t	ItemBufferGetSize (item_buffer_t *buffer)
void	ItemBufferInit (item_buffer_t *buffer, uint16_t *data_array, uint16_t max_size, uint8_t type_size)
void	ItemBufferSetCallback (item_buffer_t *buffer, void(*Callback)(item_buffer_t *buffer))
void	ItemBufferClearCallback (item_buffer_t *buffer)

Detailed Description

Author

Anthony Merlino

Function Documentation

void ItemBufferClearCallback

(

item_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

uint16_t ItemBufferGetSize

(

item_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

void ItemBufferInit	(	item_buffer_t *	buffer,
		uint16_t *	data_array,
		uint16_t	max_size,
		uint8_t	type_size
	)

Initialize a FIFO buffer

Example code:

#define TX_BUFFER_LENGTH 512
buffer_t tx; // transmit buffer
item_t 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 item_t data to implement the actual buffer
max_size	Maximum size of the buffer (should be the same length as the array)
type_size	Size of the item

void ItemBufferSetCallback	(	item_buffer_t *	buffer,
		void(*)(item_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
item_t 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.

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.

void PopItem	(	item_buffer_t *	buffer,
		uint16_t *	data
	)

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

[in]	buffer	Pointer to the buffer_t data structure holding the buffer info
[out]	data	Data from the front of the buffer copied to the location pointed to

Warning

Pop is not yet interrupt safe

bool PushItem	(	item_buffer_t *	buffer,
		uint16_t *	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	item_t data to be added to the rear of the FIFO buffer

Warning

Push is not yet interrupt safe