Microchip® Advanced Software Framework

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

See fifo_quickstart.

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.

Data Structures

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

Typedefs

typedef struct ser_fifo_desc ser_fifo_desc_t
 
typedef struct ser_fifo_desc ser_fifo_desc_t
 

Enumerations

enum  {
  SER_FIFO_OK = 0,
  SER_FIFO_ERROR_OVERFLOW,
  SER_FIFO_ERROR_UNDERFLOW,
  SER_FIFO_ERROR
}
 Error codes used by SERIAL FIFO driver. More...
 
enum  {
  SER_FIFO_OK = 0,
  SER_FIFO_ERROR_OVERFLOW,
  SER_FIFO_ERROR_UNDERFLOW,
  SER_FIFO_ERROR
}
 

Functions

static void ser_fifo_flush (ser_fifo_desc_t *ser_fifo_desc)
 Flushes a software FIFO. More...
 
static uint8_t ser_fifo_get_free_size (ser_fifo_desc_t *ser_fifo_desc)
 Returns the remaining free spaces of the FIFO (in number of elements). More...
 
static uint16_t ser_fifo_get_used_size (ser_fifo_desc_t *ser_fifo_desc)
 Returns the number of elements in the FIFO. More...
 
int ser_fifo_init (ser_fifo_desc_t *ser_fifo_desc, void *buffer, uint16_t size)
 Initializes a new software FIFO for a certain 'size'. More...
 
static bool ser_fifo_is_empty (ser_fifo_desc_t *ser_fifo_desc)
 Tests if a FIFO is empty. More...
 
static bool ser_fifo_is_full (ser_fifo_desc_t *ser_fifo_desc)
 Tests if a FIFO is full. More...
 
static uint16_t ser_fifo_peek_uint16 (ser_fifo_desc_t *ser_fifo_desc)
 Gets a 16-bits element from the FIFO but does not remove it from the FIFO. More...
 
static uint32_t ser_fifo_peek_uint32 (ser_fifo_desc_t *ser_fifo_desc)
 Gets a 32-bits element from the FIFO but does not remove it from the FIFO. More...
 
static uint8_t ser_fifo_peek_uint8 (ser_fifo_desc_t *ser_fifo_desc)
 Gets a 8-bits element from the FIFO but does not remove it from the FIFO. More...
 
static int ser_fifo_pull_uint16 (ser_fifo_desc_t *ser_fifo_desc, uint16_t *item)
 Gets a 16-bits element from the FIFO and checks for a possible underflow. More...
 
static uint16_t ser_fifo_pull_uint16_nocheck (ser_fifo_desc_t *ser_fifo_desc)
 Gets a 16-bits element from the FIFO. More...
 
static int ser_fifo_pull_uint32 (ser_fifo_desc_t *ser_fifo_desc, uint32_t *item)
 Gets a 32-bits element from the FIFO and checks for a possible underflow. More...
 
static uint32_t ser_fifo_pull_uint32_nocheck (ser_fifo_desc_t *ser_fifo_desc)
 Gets a 32-bits element from the FIFO. More...
 
static int ser_fifo_pull_uint8 (ser_fifo_desc_t *ser_fifo_desc, uint8_t *item)
 Gets a 8-bits element from the FIFO and checks for a possible underflow. More...
 
static uint8_t ser_fifo_pull_uint8_nocheck (ser_fifo_desc_t *ser_fifo_desc)
 Gets a 8-bits element from the FIFO. More...
 
static int ser_fifo_push_uint16 (ser_fifo_desc_t *ser_fifo_desc, uint32_t item)
 Puts a new 16-bits element into the FIFO and checks for a possible overflow. More...
 
static void ser_fifo_push_uint16_nocheck (ser_fifo_desc_t *ser_fifo_desc, uint32_t item)
 Puts a new 16-bits element into the FIFO. More...
 
static int ser_fifo_push_uint32 (ser_fifo_desc_t *ser_fifo_desc, uint32_t item)
 Puts a new 32-bits element into the FIFO and checks for a possible overflow. More...
 
static void ser_fifo_push_uint32_nocheck (ser_fifo_desc_t *ser_fifo_desc, uint32_t item)
 Puts a new 32-bits element into the FIFO. More...
 
static int ser_fifo_push_uint8 (ser_fifo_desc_t *ser_fifo_desc, uint32_t item)
 Puts a new 8-bits element into the FIFO and checks for a possible overflow. More...
 
static void ser_fifo_push_uint8_nocheck (ser_fifo_desc_t *ser_fifo_desc, uint32_t item)
 Puts a new 8-bits element into the FIFO. More...
 

Variables

union {
   uint16_t *   ser_fifo_desc::u16ptr
 
   uint32_t *   ser_fifo_desc::u32ptr
 
   uint8_t *   ser_fifo_desc::u8ptr
 
ser_fifo_desc::buffer
 
union {
   uint16_t *   ser_fifo_desc::u16ptr
 Pointer to unsigned-16 bits location. More...
 
   uint32_t *   ser_fifo_desc::u32ptr
 Pointer to unsigned-32 bits location. More...
 
   uint8_t *   ser_fifo_desc::u8ptr
 Pointer to unsigned-8 bits location. More...
 
ser_fifo_desc::buffer
 
uint16_t ser_fifo_desc::mask
 Mask used to speed up FIFO operation (wrapping) More...
 
volatile uint16_t ser_fifo_desc::read_index
 Read index. More...
 
uint16_t ser_fifo_desc::size
 Size of the FIFO (unit is in number of 'element') More...
 
uint16_t *   ser_fifo_desc::u16ptr
 
uint16_t *   ser_fifo_desc::u16ptr
 Pointer to unsigned-16 bits location. More...
 
uint32_t *   ser_fifo_desc::u32ptr
 
uint32_t *   ser_fifo_desc::u32ptr
 Pointer to unsigned-32 bits location. More...
 
uint8_t *   ser_fifo_desc::u8ptr
 
uint8_t *   ser_fifo_desc::u8ptr
 Pointer to unsigned-8 bits location. More...
 
volatile uint16_t ser_fifo_desc::write_index
 Write index. More...
 

anonymous enum

Error codes used by SERIAL FIFO driver.

Enumerator
SER_FIFO_OK 

Normal operation.

SER_FIFO_ERROR_OVERFLOW 

Attempt to push something in a FIFO that is full.

SER_FIFO_ERROR_UNDERFLOW 

Attempt to pull something from a FIFO that is empty.

SER_FIFO_ERROR 

Error condition during FIFO initialization.

anonymous enum

Error codes used by SERIAL FIFO driver.

Enumerator
SER_FIFO_OK 

Normal operation.

SER_FIFO_ERROR_OVERFLOW 

Attempt to push something in a FIFO that is full.

SER_FIFO_ERROR_UNDERFLOW 

Attempt to pull something from a FIFO that is empty

SER_FIFO_ERROR 

Error condition during FIFO initialization

static void ser_fifo_flush ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

Flushes a software FIFO.

Parameters
ser_fifo_descThe FIFO descriptor.

References ser_fifo_desc::read_index, and ser_fifo_desc::write_index.

static uint8_t ser_fifo_get_free_size ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

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

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

References ser_fifo_get_used_size(), and ser_fifo_desc::size.

static uint16_t ser_fifo_get_used_size ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

Returns the number of elements in the FIFO.

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

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

Referenced by ser_fifo_get_free_size(), and ser_fifo_is_full().

int ser_fifo_init ( ser_fifo_desc_t ser_fifo_desc,
void *  buffer,
uint16_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
ser_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, buffer, ser_fifo_desc::buffer, ser_fifo_desc::mask, ser_fifo_desc::read_index, SER_FIFO_OK, ser_fifo_desc::size, ser_fifo_desc::u8ptr, and ser_fifo_desc::write_index.

Referenced by serial_bridge_init().

static bool ser_fifo_is_empty ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

Tests if a FIFO is empty.

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

References ser_fifo_desc::read_index, and ser_fifo_desc::write_index.

Referenced by ser_fifo_pull_uint16(), ser_fifo_pull_uint32(), and ser_fifo_pull_uint8().

static bool ser_fifo_is_full ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

Tests if a FIFO is full.

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

References ser_fifo_get_used_size(), and ser_fifo_desc::size.

Referenced by ser_fifo_push_uint16(), ser_fifo_push_uint32(), and ser_fifo_push_uint8().

static uint16_t ser_fifo_peek_uint16 ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

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

Parameters
ser_fifo_descThe FIFO descriptor.
Return values
itemextracted element.

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

static uint32_t ser_fifo_peek_uint32 ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

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

Parameters
ser_fifo_descThe FIFO descriptor.
Return values
itemextracted element.

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

static uint8_t ser_fifo_peek_uint8 ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

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

Parameters
ser_fifo_descThe FIFO descriptor.
Return values
itemextracted element.

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

static int ser_fifo_pull_uint16 ( ser_fifo_desc_t ser_fifo_desc,
uint16_t *  item 
)
inlinestatic

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

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

References barrier, ser_fifo_desc::buffer, ser_fifo_desc::mask, ser_fifo_desc::read_index, SER_FIFO_ERROR_UNDERFLOW, ser_fifo_is_empty(), SER_FIFO_OK, and ser_fifo_desc::u16ptr.

static uint16_t ser_fifo_pull_uint16_nocheck ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

Gets a 16-bits element from the FIFO.

Parameters
ser_fifo_descThe FIFO descriptor.
Returns
extracted element.

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

static int ser_fifo_pull_uint32 ( ser_fifo_desc_t ser_fifo_desc,
uint32_t *  item 
)
inlinestatic

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

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

References barrier, ser_fifo_desc::buffer, ser_fifo_desc::mask, ser_fifo_desc::read_index, SER_FIFO_ERROR_UNDERFLOW, ser_fifo_is_empty(), SER_FIFO_OK, and ser_fifo_desc::u32ptr.

static uint32_t ser_fifo_pull_uint32_nocheck ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

Gets a 32-bits element from the FIFO.

Parameters
ser_fifo_descThe FIFO descriptor.
Returns
extracted element.

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

static int ser_fifo_pull_uint8 ( ser_fifo_desc_t ser_fifo_desc,
uint8_t *  item 
)
inlinestatic

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

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

References barrier, ser_fifo_desc::buffer, ser_fifo_desc::mask, ser_fifo_desc::read_index, SER_FIFO_ERROR_UNDERFLOW, ser_fifo_is_empty(), SER_FIFO_OK, and ser_fifo_desc::u8ptr.

Referenced by serial_bridge_task(), and serial_drv_edbg_write_cb().

static uint8_t ser_fifo_pull_uint8_nocheck ( ser_fifo_desc_t ser_fifo_desc)
inlinestatic

Gets a 8-bits element from the FIFO.

Parameters
ser_fifo_descThe FIFO descriptor.
Returns
extracted element.

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

static int ser_fifo_push_uint16 ( ser_fifo_desc_t ser_fifo_desc,
uint32_t  item 
)
inlinestatic

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

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

References barrier, ser_fifo_desc::buffer, ser_fifo_desc::mask, SER_FIFO_ERROR_OVERFLOW, ser_fifo_is_full(), SER_FIFO_OK, ser_fifo_desc::u16ptr, and ser_fifo_desc::write_index.

static void ser_fifo_push_uint16_nocheck ( ser_fifo_desc_t ser_fifo_desc,
uint32_t  item 
)
inlinestatic

Puts a new 16-bits element into the FIFO.

Parameters
ser_fifo_descThe FIFO descriptor.
itemextracted element.

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

static int ser_fifo_push_uint32 ( ser_fifo_desc_t ser_fifo_desc,
uint32_t  item 
)
inlinestatic

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

Parameters
ser_fifo_descThe FIFO descriptor.
itemextracted element.
Returns
Status
Return values
SER_FIFO_OKwhen no error occurred.
SER_FIFO_ERROR_UNDERFLOWwhen the FIFO was empty.

References barrier, ser_fifo_desc::buffer, ser_fifo_desc::mask, SER_FIFO_ERROR_OVERFLOW, ser_fifo_is_full(), SER_FIFO_OK, ser_fifo_desc::u32ptr, and ser_fifo_desc::write_index.

static void ser_fifo_push_uint32_nocheck ( ser_fifo_desc_t ser_fifo_desc,
uint32_t  item 
)
inlinestatic

Puts a new 32-bits element into the FIFO.

Parameters
ser_fifo_descThe FIFO descriptor.
itemextracted element.

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

static int ser_fifo_push_uint8 ( ser_fifo_desc_t ser_fifo_desc,
uint32_t  item 
)
inlinestatic

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

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

References barrier, ser_fifo_desc::buffer, ser_fifo_desc::mask, SER_FIFO_ERROR_OVERFLOW, ser_fifo_is_full(), SER_FIFO_OK, ser_fifo_desc::u8ptr, and ser_fifo_desc::write_index.

Referenced by platform_dtm_interface_receive(), serial_bridge_task(), and serial_drv_edbg_read_cb().

static void ser_fifo_push_uint8_nocheck ( ser_fifo_desc_t ser_fifo_desc,
uint32_t  item 
)
inlinestatic

Puts a new 8-bits element into the FIFO.

Parameters
ser_fifo_descThe FIFO descriptor.
itemextracted element.

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

union { ... } ser_fifo_desc::buffer
uint16_t ser_fifo_desc::size

Size of the FIFO (unit is in number of 'element')

Size of the FIFO (unit is in number of 'element')

Referenced by ser_fifo_get_free_size(), ser_fifo_init(), and ser_fifo_is_full().

uint16_t* { ... } ::u16ptr

Pointer to unsigned-16 bits location

uint16_t* { ... } ::u16ptr

Pointer to unsigned-16 bits location.

uint16_t* ser_fifo_desc::u16ptr

Pointer to unsigned-16 bits location.

Pointer to unsigned-16 bits location

Referenced by ser_fifo_peek_uint16(), ser_fifo_pull_uint16(), ser_fifo_pull_uint16_nocheck(), ser_fifo_push_uint16(), and ser_fifo_push_uint16_nocheck().

uint32_t* { ... } ::u32ptr

Pointer to unsigned-32 bits location

uint32_t* { ... } ::u32ptr

Pointer to unsigned-32 bits location.

uint32_t* ser_fifo_desc::u32ptr

Pointer to unsigned-32 bits location.

Pointer to unsigned-32 bits location

Referenced by ser_fifo_peek_uint32(), ser_fifo_pull_uint32(), ser_fifo_pull_uint32_nocheck(), ser_fifo_push_uint32(), and ser_fifo_push_uint32_nocheck().

uint8_t* { ... } ::u8ptr

Pointer to unsigned-8 bits location

uint8_t* { ... } ::u8ptr

Pointer to unsigned-8 bits location.

uint8_t* ser_fifo_desc::u8ptr

Pointer to unsigned-8 bits location.

Pointer to unsigned-8 bits location

Referenced by ser_fifo_init(), ser_fifo_peek_uint8(), ser_fifo_pull_uint8(), ser_fifo_pull_uint8_nocheck(), ser_fifo_push_uint8(), and ser_fifo_push_uint8_nocheck().