fifobuf.h File Reference

General pourpose FIFO buffer implemented with a ring buffer. More...

#include <cpu/types.h>
#include <cpu/irq.h>
#include <cfg/debug.h>

Go to the source code of this file.

Functions
bool	fifo_isempty (const FIFOBuffer *fb)
	Check whether the fifo is empty.
bool	fifo_isfull (const FIFOBuffer *fb)
	Check whether the fifo is full.
void	fifo_push (FIFOBuffer *fb, unsigned char c)
	Push a character on the fifo buffer.
unsigned char	fifo_pop (FIFOBuffer *fb)
	Pop a character from the fifo buffer.
void	fifo_flush (FIFOBuffer *fb)
	Make the fifo empty, discarding all its current contents.
bool	fifo_isempty_locked (const FIFOBuffer *fb)
	Similar to fifo_isempty(), but with stronger guarantees for concurrent access between user and interrupt code.
void	fifo_push_locked (FIFOBuffer *fb, unsigned char c)
	Similar to fifo_push(), but with stronger guarantees for concurrent access between user and interrupt code.
void	fifo_flush_locked (FIFOBuffer *fb)
	Similar to fifo_flush(), but with stronger guarantees for concurrent access between user and interrupt code.
bool	fifo_isfull_locked (const FIFOBuffer *_fb)
	Thread safe version of fifo_isfull().
void	fifo_init (FIFOBuffer *fb, unsigned char *buf, size_t size)
	FIFO Initialization.
size_t	fifo_len (FIFOBuffer *fb)

---

Detailed Description

General pourpose FIFO buffer implemented with a ring buffer.

• begin points to the first buffer element;
• end points to the last buffer element (unlike the STL convention);
• head points to the element to be extracted next;
• tail points to the location following the last insertion;
• when any of the pointers advances beyond end, it is reset back to begin.

  +-----------------------------------+
  |  empty  |   valid data   |  empty |
  +-----------------------------------+
  ^         ^                ^        ^
  begin    head             tail     end

The buffer is EMPTY when head and tail point to the same location:

 head == tail 

The buffer is FULL when tail points to the location immediately after head:

 tail == head - 1 

The buffer is also FULL when tail points to the last buffer location and head points to the first one:

 head == begin && tail == end 

Version:

Id

fifobuf.h 2506 2009-04-15 08:29:07Z duplo

Author:

Bernie Innocenti <bernie@codewiz.org>

Definition in file fifobuf.h.

---

Function Documentation

void fifo_flush_locked

(

FIFOBuffer *

fb

)

[inline]

Similar to fifo_flush(), but with stronger guarantees for concurrent access between user and interrupt code.

Note:

This is actually only needed for 8-bit processors.

See also:

fifo_flush()

Definition at line 261 of file fifobuf.h.

bool fifo_isempty

(

const FIFOBuffer *

fb

)

[inline]

Check whether the fifo is empty.

Note:

Calling fifo_isempty() is safe while a concurrent execution context is calling fifo_push() or fifo_pop() only if the CPU can atomically update a pointer (which the AVR and other 8-bit processors can't do).

See also:

fifo_isempty_locked

Definition at line 102 of file fifobuf.h.

bool fifo_isempty_locked

(

const FIFOBuffer *

fb

)

[inline]

Similar to fifo_isempty(), but with stronger guarantees for concurrent access between user and interrupt code.

Note:

This is actually only needed for 8-bit processors.

See also:

fifo_isempty()

Definition at line 224 of file fifobuf.h.

bool fifo_isfull

(

const FIFOBuffer *

fb

)

[inline]

Check whether the fifo is full.

Note:

Calling fifo_isfull() is safe while a concurrent execution context is calling fifo_pop() and the CPU can update a pointer atomically. It is NOT safe when the other context calls fifo_push(). This limitation is not usually problematic in a consumer/producer scenario because the fifo_isfull() and fifo_push() are usually called in the producer context.

Definition at line 122 of file fifobuf.h.

size_t fifo_len

(

FIFOBuffer *

fb

)

[inline]

Returns:

Lenght of the FIFOBuffer fb.

Definition at line 295 of file fifobuf.h.

unsigned char fifo_pop

(

FIFOBuffer *

fb

)

[inline]

Pop a character from the fifo buffer.

Note:

Calling fifo_pop() on an empty buffer is undefined. The caller must make sure the buffer contains at least one character before calling this function.

It is safe to call fifo_pop() and fifo_push() from concurrent contexts.

Definition at line 174 of file fifobuf.h.

void fifo_push	(	FIFOBuffer *	fb,
		unsigned char	c
	)			[inline]

Push a character on the fifo buffer.

Note:

Calling fifo_push() on a full buffer is undefined. The caller must make sure the buffer has at least one free slot before calling this function.

It is safe to call fifo_pop() and fifo_push() from concurrent contexts, unless the CPU can't update a pointer atomically (which the AVR and other 8-bit processors can't do).

See also:

fifo_push_locked

Definition at line 145 of file fifobuf.h.

void fifo_push_locked	(	FIFOBuffer *	fb,
		unsigned char	c
	)			[inline]

Similar to fifo_push(), but with stronger guarantees for concurrent access between user and interrupt code.

Note:

This is actually only needed for 8-bit processors.

See also:

fifo_push()

Definition at line 240 of file fifobuf.h.