ring_buffer.h : FIFO ring buffer
[/general : General utility files & modules]

A data structure that uses a single, fixed-size buffer as if it were connected end-to-end (circular). More...

Data Structures
struct	ring_buffer_t
	Ring buffer structure. More...
Functions
void	ring_buffer_init (ring_buffer_t *ring_buffer, u8_t *buffer, size_t buffer_size)
	Initialize the ring buffer.
bool_t	ring_buffer_empty (ring_buffer_t *ring_buffer)
	See if the ring buffer is empty.
bool_t	ring_buffer_full (ring_buffer_t *ring_buffer)
	See if the ring buffer is full.
bool_t	ring_buffer_write_byte (ring_buffer_t *ring_buffer, const u8_t data)
	Write (store) a byte in the ring buffer.
u16_t	ring_buffer_write_data (ring_buffer_t *ring_buffer, const u8_t *data, u16_t bytes_to_write)
	Write (store) data in the ring buffer.
bool_t	ring_buffer_read_byte (ring_buffer_t *ring_buffer, u8_t *data)
	Read (retrieve) a byte from the ring buffer.
u16_t	ring_buffer_read_data (ring_buffer_t *ring_buffer, u8_t *data, u16_t bytes_to_read)
	Read (retrieve) data from the ring buffer.

---

Detailed Description

Files: ring_buffer.h & ring_buffer.c

A fixed-sized buffer is managed as a FIFO buffer with a "zero-copy" policy, i.e. data is not shifted (copied) when data is removed or added to the buffer. If more data is written to the buffer than there is space for, it is ignored/discarded; no buffer overflow vulnerability.

In this implementation, the maximum amount of bytes that can be stored is one less than the size of the fixed-size buffer, e.g. if the buffer size is 8 bytes, then a maximum of 7 bytes can be stored.

See also:

http://en.wikipedia.org/wiki/Circular_buffer

Graphical examples:

  Buffer is empty:
  
   start       head     end
   |           |        |
  [ ][ ][ ][ ][ ][ ][ ][ ]
               |
               tail
  
  One byte is written to the buffer ('1'):
  
                  head
                  |
  [ ][ ][ ][ ][1][ ][ ][ ]
               |
               tail
  
  One byte is read ('1'); buffer is empty again:
 
                  head
                  |
  [ ][ ][ ][ ][ ][ ][ ][ ]
                  |
                  tail
  
  5 bytes are written ('2','3','4','5','6'); buffer wraps:
  
         head
         |
  [5][6][ ][ ][ ][2][3][4]
                  |
                  tail
  
  2 bytes are written ('7','8'); buffer is full:
  
               head
               |
  [5][6][7][8][ ][2][3][4]
                  |
                  tail

---

Function Documentation

void ring_buffer_init	(	ring_buffer_t *	ring_buffer,
		u8_t *	buffer,
		size_t	buffer_size
	)

Parameters:

	ring_buffer	Pointer to the ring buffer object
	buffer	Fixed-size data buffer
	buffer_size	Fixed-size data buffer size

Definition at line 58 of file ring_buffer.c.

References ring_buffer_t::end, ring_buffer_t::head, ring_buffer_t::start, and ring_buffer_t::tail.

Referenced by uart1_init(), uart2_init(), usart0_init(), and usart1_init().

{
    // Initialise the ring buffer structure to be empty
    ring_buffer->start = buffer;
    ring_buffer->end   = buffer+(buffer_size-1);
    ring_buffer->head  = buffer;
    ring_buffer->tail  = buffer;
}

bool_t ring_buffer_empty

(

ring_buffer_t *

ring_buffer

)

Parameters:

ring_buffer

Pointer to the ring buffer object

Return values:

	TRUE	buffer is empty
	FALSE	buffer contains data

Definition at line 69 of file ring_buffer.c.

References ring_buffer_t::head, and ring_buffer_t::tail.

Referenced by uart1_rx_buffer_empty(), uart1_tx_buffer_empty(), uart1_tx_finished(), uart2_rx_buffer_empty(), uart2_tx_buffer_empty(), uart2_tx_finished(), usart0_rx_buffer_empty(), usart0_tx_buffer_empty(), usart0_tx_finished(), usart1_rx_buffer_empty(), usart1_tx_buffer_empty(), and usart1_tx_finished().

{
    return (ring_buffer->tail == ring_buffer->head);
}

bool_t ring_buffer_full

(

ring_buffer_t *

ring_buffer

)

Parameters:

ring_buffer

Pointer to the ring buffer object

Return values:

	TRUE	buffer is full
	FALSE	buffer is NOT full

Definition at line 74 of file ring_buffer.c.

References ring_buffer_t::end, ring_buffer_t::head, ring_buffer_t::start, and ring_buffer_t::tail.

Referenced by uart1_tx_buffer_full(), uart2_tx_buffer_full(), usart0_tx_buffer_full(), and usart1_tx_buffer_full().

{
    // Calculate next position of in pointer
    u8_t *next_pos = ring_buffer->head;
    if (next_pos == ring_buffer->end)
    {
        // Wrap pointer to start of buffer
        next_pos = ring_buffer->start;
    }
    else
    {
        // Increment pointer
        next_pos++;
    }

    return(next_pos == ring_buffer->tail);
}

bool_t ring_buffer_write_byte	(	ring_buffer_t *	ring_buffer,
		const u8_t	data
	)

Parameters:

	ring_buffer	Pointer to the ring buffer object
	data	The byte to store in the ring buffer

Return values:

	TRUE	Byte has been stored in the ring buffer
	FALSE	Buffer is full and byte was not stored

Definition at line 92 of file ring_buffer.c.

References ring_buffer_t::end, ring_buffer_t::head, ring_buffer_t::start, and ring_buffer_t::tail.

Referenced by uart1_tx_byte(), uart2_tx_byte(), usart0_tx_byte(), and usart1_tx_byte().

{
    // Calculate next position of in pointer
    u8_t *next_pos = ring_buffer->head;
    if (next_pos == ring_buffer->end)
    {
        // Wrap pointer to start of buffer
        next_pos = ring_buffer->start;
    }
    else
    {
        // Increment pointer
        next_pos++;
    }

    // Make sure buffer is not full
    if (next_pos == ring_buffer->tail)
    {
        // Buffer is full
        return FALSE;
    }

    // Add data to buffer
    *ring_buffer->head = data;

    // Advance pointer
    ring_buffer->head = next_pos;

    return TRUE;
}

u16_t ring_buffer_write_data	(	ring_buffer_t *	ring_buffer,
		const u8_t *	data,
		u16_t	bytes_to_write
	)

Parameters:

	ring_buffer	Pointer to the ring buffer object
	data	Pointer to array of data to be stored in the ring buffer
	bytes_to_write	Amount of data bytes to be written

Returns:

u16_t The actual number of data bytes stored, which may be less than the number specified, because the buffer is full.

Definition at line 124 of file ring_buffer.c.

References ring_buffer_t::end, ring_buffer_t::head, ring_buffer_t::start, and ring_buffer_t::tail.

Referenced by uart1_tx_data(), uart2_tx_data(), usart0_tx_data(), and usart1_tx_data().

{
    u8_t *next_pos;
    u16_t bytes_written = 0;    

    while (bytes_to_write)
    {
        // Calculate next position of in pointer
        next_pos = ring_buffer->head;
        if (next_pos == ring_buffer->end)
        {
            // Wrap pointer to start of buffer
            next_pos = ring_buffer->start;
        }
        else
        {
            // Increment pointer
            next_pos++;
        }
        // Make sure buffer is not full
        if (next_pos == ring_buffer->tail)
        {
            // Buffer is full
            break;
        }

        // Add data to buffer
        *ring_buffer->head = *data++;

        // Advance pointer
        ring_buffer->head = next_pos;

        // Next byte
        bytes_written++;
        bytes_to_write--;
    }

    return bytes_written;
}

bool_t ring_buffer_read_byte	(	ring_buffer_t *	ring_buffer,
		u8_t *	data
	)

Parameters:

	ring_buffer	Pointer to the ring buffer object
	data	Pointer to location where byte must be stored

Return values:

	TRUE	Valid byte has been retrieved
	FALSE	Buffer is empty

Definition at line 166 of file ring_buffer.c.

References ring_buffer_t::end, ring_buffer_t::head, ring_buffer_t::start, and ring_buffer_t::tail.

Referenced by uart1_get_rx_byte(), uart2_get_rx_byte(), usart0_get_rx_byte(), and usart1_get_rx_byte().

{
    u8_t *next_pos;

    // See if there is data in the buffer
    if (ring_buffer->head == ring_buffer->tail)
    {
        // Buffer is empty
        return FALSE;
    }

    // Fetch data
    *data = *ring_buffer->tail;

    // Calculate next position of out pointer
    next_pos = ring_buffer->tail;
    if (next_pos == ring_buffer->end)
    {
        // Wrap pointer to start of buffer
        next_pos = ring_buffer->start;
    }
    else
    {
        // Increment pointer
        next_pos++;
    }

    // Advance pointer
    ring_buffer->tail = next_pos;

    return TRUE;
}

u16_t ring_buffer_read_data	(	ring_buffer_t *	ring_buffer,
		u8_t *	data,
		u16_t	bytes_to_read
	)

Parameters:

	ring_buffer	Pointer to the ring buffer object
	data	Pointer to location where data must be stored
	bytes_to_read	Number of bytes to retrieve

Returns:

u16_t The actual number of bytes retrieved, which may be less than the number specified, because the buffer is empty.

Definition at line 200 of file ring_buffer.c.

References ring_buffer_t::end, ring_buffer_t::head, ring_buffer_t::start, and ring_buffer_t::tail.

Referenced by uart1_get_rx_data(), uart2_get_rx_data(), usart0_get_rx_data(), and usart1_get_rx_data().

{
    u8_t  *next_pos;
    u16_t bytes_read = 0;    

    while (bytes_to_read)
    {
        // See if there is data in the buffer
        if (ring_buffer->head == ring_buffer->tail)
        {
            // Buffer is empty
            break;
        }
        // Fetch data
        *data++ = *ring_buffer->tail;

        // Calculate next position
        next_pos = ring_buffer->tail;
        if (next_pos == ring_buffer->end)
        {
            // Wrap pointer to start of buffer
            next_pos = ring_buffer->start;
        }
        else
        {
            // Increment pointer
            next_pos++;
        }

        // Advance pointer
        ring_buffer->tail = next_pos;

        // Next byte
        bytes_read++;
        bytes_to_read--;
    }

    return bytes_read;
}