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...

typedef struct ser_fifo_desc ser_fifo_desc_t

typedef struct ser_fifo_desc ser_fifo_desc_t

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_desc

The 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_desc

The 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_desc

The 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_desc	Pointer on the FIFO descriptor.
buffer	Pointer on the FIFO buffer.
size	Size of the buffer (unit is in number of 'elements'). It must be a 2-power and <= to 128.

Returns

Status

Return values

FIFO_OK	when no error occurred.
FIFO_ERROR	when the size is not a 2-power.

References Assert, ser_fifo_desc::buffer, 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_desc

The FIFO descriptor.

Returns

Status

Return values

true	when the FIFO is empty.
false	when 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_desc

The FIFO descriptor.

Returns

Status

Return values

true	when the FIFO is full.
false	when 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_desc

The FIFO descriptor.

Return values

item	extracted 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_desc

The FIFO descriptor.

Return values

item	extracted 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_desc

The FIFO descriptor.

Return values

item	extracted 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_desc	The FIFO descriptor.
item	extracted element.

Returns

Status

Return values

FIFO_OK	when no error occurred.
FIFO_ERROR_UNDERFLOW	when 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_desc

The 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_desc	The FIFO descriptor.
item	extracted element.

Returns

Status

Return values

FIFO_OK	when no error occurred.
FIFO_ERROR_UNDERFLOW	when 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_desc

The 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_desc	The FIFO descriptor.
item	extracted element.

Returns

Status

Return values

FIFO_OK	when no error occurred.
FIFO_ERROR_UNDERFLOW	when 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_desc

The 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_desc	The FIFO descriptor.
item	extracted element.

Returns

Status

Return values

FIFO_OK	when no error occurred.
FIFO_ERROR_UNDERFLOW	when 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_desc	The FIFO descriptor.
item	extracted 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_desc	The FIFO descriptor.
item	extracted element.

Returns

Status

Return values

SER_FIFO_OK	when no error occurred.
SER_FIFO_ERROR_UNDERFLOW	when 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_desc	The FIFO descriptor.
item	extracted 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_desc	The FIFO descriptor.
item	extracted element.

Returns

Status

Return values

FIFO_OK	when no error occurred.
FIFO_ERROR_UNDERFLOW	when 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_desc	The FIFO descriptor.
item	extracted 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

Referenced by ser_fifo_init(), ser_fifo_peek_uint16(), ser_fifo_peek_uint32(), ser_fifo_peek_uint8(), ser_fifo_pull_uint16(), ser_fifo_pull_uint16_nocheck(), ser_fifo_pull_uint32(), ser_fifo_pull_uint32_nocheck(), ser_fifo_pull_uint8(), ser_fifo_pull_uint8_nocheck(), ser_fifo_push_uint16(), ser_fifo_push_uint16_nocheck(), ser_fifo_push_uint32(), ser_fifo_push_uint32_nocheck(), ser_fifo_push_uint8(), and ser_fifo_push_uint8_nocheck().

union { ... } ser_fifo_desc::buffer

uint16_t ser_fifo_desc::mask

Mask used to speed up FIFO operation (wrapping)

Mask used to speed up FIFO operation (wrapping)

Referenced by ser_fifo_get_used_size(), ser_fifo_init(), ser_fifo_peek_uint16(), ser_fifo_peek_uint32(), ser_fifo_peek_uint8(), ser_fifo_pull_uint16(), ser_fifo_pull_uint16_nocheck(), ser_fifo_pull_uint32(), ser_fifo_pull_uint32_nocheck(), ser_fifo_pull_uint8(), ser_fifo_pull_uint8_nocheck(), ser_fifo_push_uint16(), ser_fifo_push_uint16_nocheck(), ser_fifo_push_uint32(), ser_fifo_push_uint32_nocheck(), ser_fifo_push_uint8(), and ser_fifo_push_uint8_nocheck().

volatile uint16_t ser_fifo_desc::read_index

Read index.

Read index

Referenced by ser_fifo_flush(), ser_fifo_get_used_size(), ser_fifo_init(), ser_fifo_is_empty(), ser_fifo_peek_uint16(), ser_fifo_peek_uint32(), ser_fifo_peek_uint8(), ser_fifo_pull_uint16(), ser_fifo_pull_uint16_nocheck(), ser_fifo_pull_uint32(), ser_fifo_pull_uint32_nocheck(), ser_fifo_pull_uint8(), and ser_fifo_pull_uint8_nocheck().

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().

volatile uint16_t ser_fifo_desc::write_index

Write index.

Write index

Referenced by ser_fifo_flush(), ser_fifo_get_used_size(), ser_fifo_init(), ser_fifo_is_empty(), ser_fifo_push_uint16(), ser_fifo_push_uint16_nocheck(), ser_fifo_push_uint32(), ser_fifo_push_uint32_nocheck(), ser_fifo_push_uint8(), and ser_fifo_push_uint8_nocheck().