Xmega Application Note


fifo.h File Reference

This file controls the software FIFO management. More...

Go to the source code of this file.

Data Structures

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

Enumerations

enum  { FIFO_OK = 0, FIFO_ERROR_OVERFLOW, FIFO_ERROR_UNDERFLOW, FIFO_ERROR }
 

Error codes used by FIFO driver.

More...
enum  { FIFO_ELEMENT_8BITS = 0, FIFO_ELEMENT_16BITS, FIFO_ELEMENT_32BITS }
 

Size of the element.

More...

Functions

uint16_t fifo_get_free_size (fifo_desc_t *fifo_desc)
 This function returns the remaining free spaces of the FIFO (in number of elements).
uint16_t fifo_get_used_size (fifo_desc_t *fifo_desc)
 This function returns the number of elements in the FIFO.
int fifo_init_malloc (fifo_desc_t **fifo_desc, uint16_t size, uint16_t element_size)
 This function initializes a new software FIFO for a certain 'size'. Both fifo descriptor and buffer are allocated by the function.
int fifo_init_no_malloc (fifo_desc_t *fifo_desc, void *buffer, uint16_t size, uint16_t element_size)
 This function initializes a new software FIFO for a certain 'size'. Both fifo descriptor and buffer must be allocated by the caller before calling this function.
int fifo_pull (fifo_desc_t *fifo_desc, void *item)
 This function gets a new element from the FIFO.
int fifo_push (fifo_desc_t *fifo_desc, uint32_t item)
 This function pushes a new element in the FIFO.
void fifo_reset (fifo_desc_t *fifo_desc)
 This function resets a software FIFO.
void fifo_stop_malloc (fifo_desc_t **fifo_desc)
 This function stops a software FIFO and free the allocated buffer.

Detailed Description

This file controls the software FIFO management.

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 particurly well suited for any kind of application needing queuing data, events, ...

Author:
Atmel Corporation: http://www.atmel.com
Support and FAQ: http://support.atmel.no/

Definition in file fifo.h.


Enumeration Type Documentation

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 (malloc failed, ...).

Definition at line 57 of file fifo.h.

00057      {
00058         FIFO_OK = 0, 
00059         FIFO_ERROR_OVERFLOW, 
00060         FIFO_ERROR_UNDERFLOW, 
00061         FIFO_ERROR
00063 };

anonymous enum

Size of the element.

Enumerator:
FIFO_ELEMENT_8BITS 

Element is 8 bits.

FIFO_ELEMENT_16BITS 

Element is 16 bits.

FIFO_ELEMENT_32BITS 

Element is 32 bits.

Definition at line 66 of file fifo.h.

00066      {
00067         FIFO_ELEMENT_8BITS = 0, 
00068         FIFO_ELEMENT_16BITS, 
00069         FIFO_ELEMENT_32BITS
00071 };


Function Documentation

uint16_t fifo_get_free_size ( fifo_desc_t fifo_desc  ) 

This function returns the remaining free spaces of the FIFO (in number of elements).

Parameters:
fifo_desc The FIFO descriptor.
Returns:
The number of free elements.

Definition at line 147 of file fifo.c.

References fifo_get_used_size(), and fifo_desc_t::size.

Referenced by fifo_push().

00148 {
00149         return fifo_desc->size - fifo_get_used_size(fifo_desc);
00150 }

Here is the call graph for this function:

uint16_t fifo_get_used_size ( fifo_desc_t fifo_desc  ) 

This function returns the number of elements in the FIFO.

Parameters:
fifo_desc The FIFO descriptor.
Returns:
The number of used elements.

Definition at line 139 of file fifo.c.

References fifo_desc_t::rd_id, fifo_desc_t::size, and fifo_desc_t::wr_id.

Referenced by fifo_get_free_size(), and fifo_pull().

00140 {
00141         uint16_t val;
00142         val = fifo_desc->wr_id + 2 * fifo_desc->size;
00143         val -= fifo_desc->rd_id;
00144         return val & ((2 * fifo_desc->size) - 1);
00145 }

int fifo_init_malloc ( fifo_desc_t **  fifo_desc,
uint16_t  size,
uint16_t  element_size 
)

This function initializes a new software FIFO for a certain 'size'. Both fifo descriptor and buffer are allocated by the function.

Parameters:
fifo_desc The FIFO descriptor.
size Size of the buffer (unit is in number of 'item'). It must be a 2-power.
fifo_desc The size of the element.

  • FIFO_ELEMENT_8BITS
  • FIFO_ELEMENT_16BITS
  • FIFO_ELEMENT_32BITS
Returns:
Status
Return values:
FIFO_OK when no error occured.
FIFO_ERROR when the buffer can not be allocated or if the size is not a 2-power.

Definition at line 84 of file fifo.c.

References ctz, FIFO_ERROR, and FIFO_OK.

00086 {
00087         uint16_t tmp;
00088 
00089         // Check the size parameter. It must be a 2-power.
00090         tmp = size >> ctz(size);
00091         if (tmp != 1) {
00092                 // We prefer catching this critical situation that way since most of users does not
00093                 // even test return value...
00094                 while (1) {
00095                 }
00096                 //return FIFO_ERROR;
00097         }
00098 
00099         if (!(*fifo_desc = malloc(sizeof(fifo_desc_t))))
00100                 return FIFO_ERROR;
00101 
00102         // Allocate memory for the buffer.
00103         if (!((*fifo_desc)->buffer.u8ptr = malloc(size))) {
00104                 free(*fifo_desc);
00105                 return FIFO_ERROR;
00106         }
00107 
00108         // Keep the alignement
00109         (*fifo_desc)->align = element_size;
00110 
00111         // Fifo starts empty.
00112         (*fifo_desc)->rd_id = (*fifo_desc)->wr_id = 0;
00113 
00114         // Save the size parameter.
00115         (*fifo_desc)->size = size;
00116 
00117         return FIFO_OK;
00118 }

int fifo_init_no_malloc ( fifo_desc_t fifo_desc,
void *  buffer,
uint16_t  size,
uint16_t  element_size 
)

This function initializes a new software FIFO for a certain 'size'. Both fifo descriptor and buffer must be allocated by the caller before calling this function.

Parameters:
fifo_desc Pointer on the FIFO descriptor.
buffer Pointer on the buffer.
size Size of the buffer (unit is in number of 'item'). It must be a 2-power.
fifo_desc The size of the element.

  • FIFO_ELEMENT_8BITS
  • FIFO_ELEMENT_16BITS
  • FIFO_ELEMENT_32BITS
Returns:
Status
Return values:
FIFO_OK when no error occured.
FIFO_ERROR when the size is not a 2-power.

Definition at line 54 of file fifo.c.

References fifo_desc_t::align, fifo_desc_t::buffer, ctz, FIFO_OK, fifo_desc_t::rd_id, fifo_desc_t::size, UnionVPtr::u8ptr, and fifo_desc_t::wr_id.

00056 {
00057         uint16_t tmp;
00058 
00059         // Check the size parameter. It must be a 2-power.
00060         tmp = size >> ctz(size);
00061         if (tmp != 1) {
00062                 // We prefer catching this critical situation that way since most of users does not
00063                 // even test return value...
00064                 while (1) {
00065                 }
00066                 //return FIFO_ERROR;
00067         }
00068 
00069         // Keep the alignement
00070         fifo_desc->align = element_size;
00071 
00072         // Fifo starts empty.
00073         fifo_desc->rd_id = fifo_desc->wr_id = 0;
00074 
00075         // Save the size parameter.
00076         fifo_desc->size = size;
00077 
00078         // Save the buffer pointer
00079         fifo_desc->buffer.u8ptr = buffer;
00080 
00081         return FIFO_OK;
00082 }

int fifo_pull ( fifo_desc_t fifo_desc,
void *  item 
)

This function gets a new element from the FIFO.

Parameters:
fifo_desc The FIFO descriptor.
item extracted element.
Returns:
Status
Return values:
FIFO_OK when no error occured.
FIFO_ERROR_UNDERFLOW when the FIFO was empty.

Definition at line 173 of file fifo.c.

References fifo_desc_t::align, fifo_desc_t::buffer, FIFO_ELEMENT_16BITS, FIFO_ELEMENT_8BITS, FIFO_ERROR_UNDERFLOW, fifo_get_used_size(), FIFO_OK, fifo_desc_t::rd_id, fifo_desc_t::size, UnionVPtr::u16ptr, UnionVPtr::u32ptr, and UnionVPtr::u8ptr.

00174 {
00175         uint8_t rd_id;
00176         if (fifo_get_used_size(fifo_desc) == 0)
00177                 return FIFO_ERROR_UNDERFLOW;
00178 
00179         rd_id = fifo_desc->rd_id;
00180         if (fifo_desc->align == FIFO_ELEMENT_8BITS)
00181                 *(uint8_t*) item = fifo_desc->buffer.u8ptr[rd_id & (fifo_desc->size - 1)];
00182         else if (fifo_desc->align == FIFO_ELEMENT_16BITS)
00183                 *(uint16_t*) item = fifo_desc->buffer.u16ptr[rd_id
00184                       & (fifo_desc->size - 1)];
00185         else
00186                 // if( fifo_desc->align==FIFO_ELEMENT_32BITS )
00187                 *(uint32_t*) item = fifo_desc->buffer.u32ptr[rd_id
00188                       & (fifo_desc->size - 1)];
00189 
00190         // Must be the last thing to do.
00191         fifo_desc->rd_id = (rd_id + 1) & ((2 * fifo_desc->size) - 1);
00192         return FIFO_OK;
00193 }

Here is the call graph for this function:

int fifo_push ( fifo_desc_t fifo_desc,
uint32_t  item 
)

This function pushes a new element in the FIFO.

Parameters:
fifo_desc The FIFO descriptor.
item element to push.
Returns:
Status
Return values:
FIFO_OK when no error occured.
FIFO_ERROR_OVERFLOW when the FIFO was already full before pushing the element.

Definition at line 152 of file fifo.c.

References fifo_desc_t::align, fifo_desc_t::buffer, FIFO_ELEMENT_16BITS, FIFO_ELEMENT_8BITS, FIFO_ERROR_OVERFLOW, fifo_get_free_size(), FIFO_OK, fifo_desc_t::size, UnionVPtr::u16ptr, UnionVPtr::u32ptr, UnionVPtr::u8ptr, and fifo_desc_t::wr_id.

00153 {
00154         uint8_t wr_id;
00155         if (fifo_get_free_size(fifo_desc) == 0)
00156                 return FIFO_ERROR_OVERFLOW;
00157 
00158         wr_id = fifo_desc->wr_id;
00159 
00160         if (fifo_desc->align == FIFO_ELEMENT_8BITS)
00161                 fifo_desc->buffer.u8ptr[wr_id & (fifo_desc->size - 1)] = item;
00162         else if (fifo_desc->align == FIFO_ELEMENT_16BITS)
00163                 fifo_desc->buffer.u16ptr[wr_id & (fifo_desc->size - 1)] = item;
00164         else
00165                 // if( fifo_desc->align==FIFO_ELEMENT_32BITS )
00166                 fifo_desc->buffer.u32ptr[wr_id & (fifo_desc->size - 1)] = item;
00167 
00168         // Must be the last thing to do.
00169         fifo_desc->wr_id = (wr_id + 1) & ((2 * fifo_desc->size) - 1);
00170         return FIFO_OK;
00171 }

Here is the call graph for this function:

void fifo_reset ( fifo_desc_t fifo_desc  ) 

This function resets a software FIFO.

Parameters:
fifo_desc The FIFO descriptor.

Definition at line 120 of file fifo.c.

References fifo_desc_t::rd_id, and fifo_desc_t::wr_id.

00121 {
00122         // Fifo starts empty.
00123         fifo_desc->rd_id = fifo_desc->wr_id = 0;
00124 }

void fifo_stop_malloc ( fifo_desc_t **  fifo_desc  ) 

This function stops a software FIFO and free the allocated buffer.

Parameters:
fifo_desc The FIFO descriptor.

Definition at line 126 of file fifo.c.

00127 {
00128         // Free allocated memory
00129         if ((*fifo_desc)->buffer.u8ptr) {
00130                 free((void*) (*fifo_desc)->buffer.u8ptr);
00131                 (*fifo_desc)->buffer.u8ptr = NULL;
00132         }
00133         if (*fifo_desc) {
00134                 free((void*) *fifo_desc);
00135                 *fifo_desc = NULL;
00136         }
00137 }

@DOC_TITLE@
Generated on Fri Oct 22 12:15:25 2010 for AVR1300 Using the Xmega ADC by doxygen 1.6.3