Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
First-In-First-Out Buffer (FIFO)

See Quick start guide for First-In-First-Out Buffer (FIFO).

These functions manages FIFOs thanks to simple a API. The FIFO can be 100% full thanks to a double-index range implementation. For example, a FIFO of 4 elements can be implemented: the FIFO can really hold up to 4 elements. This is particularly well suited for any kind of application needing a lot of small FIFO. The maximum fifo size is 128 items (uint8, uint16 or uint32). Note that the driver, thanks to its conception, does not use interrupt protection.

Modules

 Quick Start Guide(s)
 In this section you can find a list of all Quick Start guides related to the First-In-First-Out Buffer (FIFO).
 

Data Structures

struct  fifo_desc
 FIFO descriptor used by FIFO driver. More...
 

Typedefs

typedef struct fifo_desc fifo_desc_t
 

Enumerations

enum  {
  FIFO_OK = 0,
  FIFO_ERROR_OVERFLOW,
  FIFO_ERROR_UNDERFLOW,
  FIFO_ERROR
}
 Error codes used by FIFO driver. More...
 

Functions

static void fifo_flush (fifo_desc_t *fifo_desc)
 Flushes a software FIFO. More...
 
static uint8_t fifo_get_free_size (fifo_desc_t *fifo_desc)
 Returns the remaining free spaces of the FIFO (in number of elements). More...
 
static uint8_t fifo_get_used_size (fifo_desc_t *fifo_desc)
 Returns the number of elements in the FIFO. More...
 
int fifo_init (fifo_desc_t *fifo_desc, void *buffer, uint8_t size)
 Initializes a new software FIFO for a certain 'size'. More...
 
static bool fifo_is_empty (fifo_desc_t *fifo_desc)
 Tests if a FIFO is empty. More...
 
static bool fifo_is_full (fifo_desc_t *fifo_desc)
 Tests if a FIFO is full. More...
 
static uint16_t fifo_peek_uint16 (fifo_desc_t *fifo_desc)
 Gets a 16-bits element from the FIFO but does not remove it from the FIFO. More...
 
static uint32_t fifo_peek_uint32 (fifo_desc_t *fifo_desc)
 Gets a 32-bits element from the FIFO but does not remove it from the FIFO. More...
 
static uint8_t fifo_peek_uint8 (fifo_desc_t *fifo_desc)
 Gets a 8-bits element from the FIFO but does not remove it from the FIFO. More...
 
static int fifo_pull_uint16 (fifo_desc_t *fifo_desc, uint16_t *item)
 Gets a 16-bits element from the FIFO and checks for a possible underflow. More...
 
static uint16_t fifo_pull_uint16_nocheck (fifo_desc_t *fifo_desc)
 Gets a 16-bits element from the FIFO. More...
 
static int fifo_pull_uint32 (fifo_desc_t *fifo_desc, uint32_t *item)
 Gets a 32-bits element from the FIFO and checks for a possible underflow. More...
 
static uint32_t fifo_pull_uint32_nocheck (fifo_desc_t *fifo_desc)
 Gets a 32-bits element from the FIFO. More...
 
static int fifo_pull_uint8 (fifo_desc_t *fifo_desc, uint8_t *item)
 Gets a 8-bits element from the FIFO and checks for a possible underflow. More...
 
static uint8_t fifo_pull_uint8_nocheck (fifo_desc_t *fifo_desc)
 Gets a 8-bits element from the FIFO. More...
 
static int fifo_push_uint16 (fifo_desc_t *fifo_desc, uint32_t item)
 Puts a new 16-bits element into the FIFO and checks for a possible overflow. More...
 
static void fifo_push_uint16_nocheck (fifo_desc_t *fifo_desc, uint32_t item)
 Puts a new 16-bits element into the FIFO. More...
 
static int fifo_push_uint32 (fifo_desc_t *fifo_desc, uint32_t item)
 Puts a new 32-bits element into the FIFO and checks for a possible overflow. More...
 
static void fifo_push_uint32_nocheck (fifo_desc_t *fifo_desc, uint32_t item)
 Puts a new 32-bits element into the FIFO. More...
 
static int fifo_push_uint8 (fifo_desc_t *fifo_desc, uint32_t item)
 Puts a new 8-bits element into the FIFO and checks for a possible overflow. More...
 
static void fifo_push_uint8_nocheck (fifo_desc_t *fifo_desc, uint32_t item)
 Puts a new 8-bits element into the FIFO. More...
 

typedef struct fifo_desc fifo_desc_t

anonymous enum

Error codes used by FIFO driver.

Enumerator
FIFO_OK 

Normal operation.

FIFO_ERROR_OVERFLOW 

Attempt to push something in a FIFO that is full.

FIFO_ERROR_UNDERFLOW 

Attempt to pull something from a FIFO that is empty.

FIFO_ERROR 

Error condition during FIFO initialization.

static void fifo_flush ( fifo_desc_t fifo_desc)
inlinestatic

Flushes a software FIFO.

Parameters
fifo_descThe FIFO descriptor.

References fifo_desc::read_index, and fifo_desc::write_index.

static uint8_t fifo_get_free_size ( fifo_desc_t fifo_desc)
inlinestatic

Returns the remaining free spaces of the FIFO (in number of elements).

Parameters
fifo_descThe FIFO descriptor.
Returns
The number of free elements.

References fifo_get_used_size(), and fifo_desc::size.

static uint8_t fifo_get_used_size ( fifo_desc_t fifo_desc)
inlinestatic

Returns the number of elements in the FIFO.

Parameters
fifo_descThe FIFO descriptor.
Returns
The number of used elements.

References fifo_desc::mask, fifo_desc::read_index, and fifo_desc::write_index.

Referenced by fifo_get_free_size(), and fifo_is_full().

int fifo_init ( fifo_desc_t fifo_desc,
void *  buffer,
uint8_t  size 
)

Initializes a new software FIFO for a certain 'size'.

Precondition
Both fifo descriptor and buffer must be allocated by the caller before.
Parameters
fifo_descPointer on the FIFO descriptor.
bufferPointer on the FIFO buffer.
sizeSize of the buffer (unit is in number of 'elements'). It must be a 2-power and <= to 128.
Returns
Status
Return values
FIFO_OKwhen no error occurred.
FIFO_ERRORwhen the size is not a 2-power.

References Assert, fifo_desc::buffer, FIFO_OK, fifo_desc::mask, fifo_desc::read_index, fifo_desc::size, fifo_desc::u8ptr, and fifo_desc::write_index.

static bool fifo_is_empty ( fifo_desc_t fifo_desc)
inlinestatic

Tests if a FIFO is empty.

Parameters
fifo_descThe FIFO descriptor.
Returns
Status
Return values
truewhen the FIFO is empty.
falsewhen the FIFO is not empty.

References fifo_desc::read_index, and fifo_desc::write_index.

Referenced by fifo_pull_uint16(), fifo_pull_uint32(), and fifo_pull_uint8().

static bool fifo_is_full ( fifo_desc_t fifo_desc)
inlinestatic

Tests if a FIFO is full.

Parameters
fifo_descThe FIFO descriptor.
Returns
Status
Return values
truewhen the FIFO is full.
falsewhen the FIFO is not full.

References fifo_get_used_size(), and fifo_desc::size.

Referenced by fifo_push_uint16(), fifo_push_uint32(), and fifo_push_uint8().

static uint16_t fifo_peek_uint16 ( fifo_desc_t fifo_desc)
inlinestatic

Gets a 16-bits element from the FIFO but does not remove it from the FIFO.

Parameters
fifo_descThe FIFO descriptor.
Return values
itemextracted element.

References fifo_desc::buffer, fifo_desc::mask, fifo_desc::read_index, and fifo_desc::u16ptr.

static uint32_t fifo_peek_uint32 ( fifo_desc_t fifo_desc)
inlinestatic

Gets a 32-bits element from the FIFO but does not remove it from the FIFO.

Parameters
fifo_descThe FIFO descriptor.
Return values
itemextracted element.

References fifo_desc::buffer, fifo_desc::mask, fifo_desc::read_index, and fifo_desc::u32ptr.

static uint8_t fifo_peek_uint8 ( fifo_desc_t fifo_desc)
inlinestatic

Gets a 8-bits element from the FIFO but does not remove it from the FIFO.

Parameters
fifo_descThe FIFO descriptor.
Return values
itemextracted element.

References fifo_desc::buffer, fifo_desc::mask, fifo_desc::read_index, and fifo_desc::u8ptr.

static int fifo_pull_uint16 ( fifo_desc_t fifo_desc,
uint16_t *  item 
)
inlinestatic

Gets a 16-bits element from the FIFO and checks for a possible underflow.

Parameters
fifo_descThe FIFO descriptor.
itemextracted element.
Returns
Status
Return values
FIFO_OKwhen no error occurred.
FIFO_ERROR_UNDERFLOWwhen the FIFO was empty.

References barrier, fifo_desc::buffer, FIFO_ERROR_UNDERFLOW, fifo_is_empty(), FIFO_OK, fifo_desc::mask, fifo_desc::read_index, and fifo_desc::u16ptr.

static uint16_t fifo_pull_uint16_nocheck ( fifo_desc_t fifo_desc)
inlinestatic

Gets a 16-bits element from the FIFO.

Parameters
fifo_descThe FIFO descriptor.
Returns
extracted element.

References barrier, fifo_desc::buffer, fifo_desc::mask, fifo_desc::read_index, and fifo_desc::u16ptr.

static int fifo_pull_uint32 ( fifo_desc_t fifo_desc,
uint32_t *  item 
)
inlinestatic

Gets a 32-bits element from the FIFO and checks for a possible underflow.

Parameters
fifo_descThe FIFO descriptor.
itemextracted element.
Returns
Status
Return values
FIFO_OKwhen no error occurred.
FIFO_ERROR_UNDERFLOWwhen the FIFO was empty.

References barrier, fifo_desc::buffer, FIFO_ERROR_UNDERFLOW, fifo_is_empty(), FIFO_OK, fifo_desc::mask, fifo_desc::read_index, and fifo_desc::u32ptr.

static uint32_t fifo_pull_uint32_nocheck ( fifo_desc_t fifo_desc)
inlinestatic

Gets a 32-bits element from the FIFO.

Parameters
fifo_descThe FIFO descriptor.
Returns
extracted element.

References barrier, fifo_desc::buffer, fifo_desc::mask, fifo_desc::read_index, and fifo_desc::u32ptr.

static int fifo_pull_uint8 ( fifo_desc_t fifo_desc,
uint8_t *  item 
)
inlinestatic

Gets a 8-bits element from the FIFO and checks for a possible underflow.

Parameters
fifo_descThe FIFO descriptor.
itemextracted element.
Returns
Status
Return values
FIFO_OKwhen no error occurred.
FIFO_ERROR_UNDERFLOWwhen the FIFO was empty.

References barrier, fifo_desc::buffer, FIFO_ERROR_UNDERFLOW, fifo_is_empty(), FIFO_OK, fifo_desc::mask, fifo_desc::read_index, and fifo_desc::u8ptr.

static uint8_t fifo_pull_uint8_nocheck ( fifo_desc_t fifo_desc)
inlinestatic

Gets a 8-bits element from the FIFO.

Parameters
fifo_descThe FIFO descriptor.
Returns
extracted element.

References barrier, fifo_desc::buffer, fifo_desc::mask, fifo_desc::read_index, and fifo_desc::u8ptr.

static int fifo_push_uint16 ( fifo_desc_t fifo_desc,
uint32_t  item 
)
inlinestatic

Puts a new 16-bits element into the FIFO and checks for a possible overflow.

Parameters
fifo_descThe FIFO descriptor.
itemextracted element.
Returns
Status
Return values
FIFO_OKwhen no error occurred.
FIFO_ERROR_UNDERFLOWwhen the FIFO was empty.

References barrier, fifo_desc::buffer, FIFO_ERROR_OVERFLOW, fifo_is_full(), FIFO_OK, fifo_desc::mask, fifo_desc::u16ptr, and fifo_desc::write_index.

static void fifo_push_uint16_nocheck ( fifo_desc_t fifo_desc,
uint32_t  item 
)
inlinestatic

Puts a new 16-bits element into the FIFO.

Parameters
fifo_descThe FIFO descriptor.
itemextracted element.

References barrier, fifo_desc::buffer, fifo_desc::mask, fifo_desc::u16ptr, and fifo_desc::write_index.

static int fifo_push_uint32 ( fifo_desc_t fifo_desc,
uint32_t  item 
)
inlinestatic

Puts a new 32-bits element into the FIFO and checks for a possible overflow.

Parameters
fifo_descThe FIFO descriptor.
itemextracted element.
Returns
Status
Return values
FIFO_OKwhen no error occurred.
FIFO_ERROR_UNDERFLOWwhen the FIFO was empty.

References barrier, fifo_desc::buffer, FIFO_ERROR_OVERFLOW, fifo_is_full(), FIFO_OK, fifo_desc::mask, fifo_desc::u32ptr, and fifo_desc::write_index.

static void fifo_push_uint32_nocheck ( fifo_desc_t fifo_desc,
uint32_t  item 
)
inlinestatic

Puts a new 32-bits element into the FIFO.

Parameters
fifo_descThe FIFO descriptor.
itemextracted element.

References barrier, fifo_desc::buffer, fifo_desc::mask, fifo_desc::u32ptr, and fifo_desc::write_index.

static int fifo_push_uint8 ( fifo_desc_t fifo_desc,
uint32_t  item 
)
inlinestatic

Puts a new 8-bits element into the FIFO and checks for a possible overflow.

Parameters
fifo_descThe FIFO descriptor.
itemextracted element.
Returns
Status
Return values
FIFO_OKwhen no error occurred.
FIFO_ERROR_UNDERFLOWwhen the FIFO was empty.

References barrier, fifo_desc::buffer, FIFO_ERROR_OVERFLOW, fifo_is_full(), FIFO_OK, fifo_desc::mask, fifo_desc::u8ptr, and fifo_desc::write_index.

static void fifo_push_uint8_nocheck ( fifo_desc_t fifo_desc,
uint32_t  item 
)
inlinestatic

Puts a new 8-bits element into the FIFO.

Parameters
fifo_descThe FIFO descriptor.
itemextracted element.

References barrier, fifo_desc::buffer, fifo_desc::mask, fifo_desc::u8ptr, and fifo_desc::write_index.