Description

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

File(s):

A fixed-sized array 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 number 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.

Reference:

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

Example:

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

Data Structures
struct	px_ring_buf_t
	Ring buffer structure. More...

Typedefs
typedef uint16_t	px_ring_buf_idx_t
	Ring buffer index size definition. More...

Functions
void	px_ring_buf_init (px_ring_buf_t px_ring_buf, uint8_t buf, px_ring_buf_idx_t buf_size)
	Initialize the ring buffer. More...

bool	px_ring_buf_is_empty (const px_ring_buf_t *px_ring_buf)
	See if the ring buffer is empty. More...

bool	px_ring_buf_is_full (const px_ring_buf_t *px_ring_buf)
	See if the ring buffer is full. More...

void	px_ring_buf_flush (px_ring_buf_t *px_ring_buf, size_t nr_of_bytes)
	Removed data from ring buffer. More...

bool	px_ring_buf_wr_u8 (px_ring_buf_t *px_ring_buf, const uint8_t data)
	Write (store) a byte in the ring buffer. More...

px_ring_buf_idx_t	px_ring_buf_wr (px_ring_buf_t px_ring_buf, const void data, size_t nr_of_bytes)
	Write (store) data in the ring buffer. More...

bool	px_ring_buf_rd_u8 (px_ring_buf_t px_ring_buf, uint8_t data)
	Read (retrieve) a byte from the ring buffer. More...

px_ring_buf_idx_t	px_ring_buf_rd (px_ring_buf_t px_ring_buf, void data, size_t nr_of_bytes)
	Read (retrieve) data from the ring buffer. More...

px_ring_buf_idx_t	px_ring_buf_peek (px_ring_buf_t px_ring_buf, void data, size_t nr_of_bytes)
	Peek data from the ring buffer, without advancing the read pointer. More...

px_ring_buf_idx_t	px_ring_buf_get_count_used (px_ring_buf_t *px_ring_buf)
	Get number of bytes stored in the buffer. More...

px_ring_buf_idx_t	px_ring_buf_get_count_free (px_ring_buf_t *px_ring_buf)
	Get number of free bytes available in buffer. More...

void	px_ring_buf_log_report (px_ring_buf_t *px_ring_buf)
	Report status of ring buffer. More...

Data Structure Documentation

◆ px_ring_buf_t

struct px_ring_buf_t

Ring buffer structure.

Definition at line 106 of file px_ring_buf.h.

Data Fields
uint8_t *	buf	Pointer to fixed-size buffer.
px_ring_buf_idx_t	buf_size	Size of fixed-size buffer.
volatile px_ring_buf_idx_t	idx_wr	Index that is next open position to write to in the buffer.
volatile px_ring_buf_idx_t	idx_rd	Index to the next byte to be read from the buffer.

Typedef Documentation

◆ px_ring_buf_idx_t

typedef uint16_t px_ring_buf_idx_t

Ring buffer index size definition.

Definition at line 102 of file px_ring_buf.h.

Function Documentation

◆ px_ring_buf_init()

void px_ring_buf_init	(	px_ring_buf_t *	px_ring_buf,
		uint8_t *	buf,
		px_ring_buf_idx_t	buf_size
	)

Initialize the ring buffer.

Parameters

px_ring_buf	Pointer to the ring buffer object
buf	Fixed-size data buffer
buf_size	Fixed-size data buffer size

Definition at line 49 of file px_ring_buf.c.

◆ px_ring_buf_is_empty()

bool px_ring_buf_is_empty ( const px_ring_buf_t * px_ring_buf )

See if the ring buffer is empty.

Parameters

px_ring_buf Pointer to the ring buffer object

Return values

true	buffer is empty
false	buffer contains data

Definition at line 60 of file px_ring_buf.c.

◆ px_ring_buf_is_full()

bool px_ring_buf_is_full ( const px_ring_buf_t * px_ring_buf )

See if the ring buffer is full.

Parameters

px_ring_buf Pointer to the ring buffer object

Return values

true	buffer is full
false	buffer is NOT full

Definition at line 65 of file px_ring_buf.c.

◆ px_ring_buf_flush()

void px_ring_buf_flush	(	px_ring_buf_t *	px_ring_buf,
		size_t	nr_of_bytes
	)

Removed data from ring buffer.

Parameters

px_ring_buf	Pointer to the ring buffer object
nr_of_bytes	Number of bytes to flush; 0 = flush everything

Definition at line 70 of file px_ring_buf.c.

◆ px_ring_buf_wr_u8()

bool px_ring_buf_wr_u8	(	px_ring_buf_t *	px_ring_buf,
		const uint8_t	data
	)

Write (store) a byte in the ring buffer.

Parameters

px_ring_buf	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 102 of file px_ring_buf.c.

◆ px_ring_buf_wr()

px_ring_buf_idx_t px_ring_buf_wr	(	px_ring_buf_t *	px_ring_buf,
		const void *	data,
		size_t	nr_of_bytes
	)

Write (store) data in the ring buffer.

Parameters

px_ring_buf	Pointer to the ring buffer object
data	Pointer to array of data to be stored in the ring buffer
nr_of_bytes	Number of data bytes to write

Returns: px_ring_buf_idx_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 px_ring_buf.c.

◆ px_ring_buf_rd_u8()

bool px_ring_buf_rd_u8	(	px_ring_buf_t *	px_ring_buf,
		uint8_t *	data
	)

Read (retrieve) a byte from the ring buffer.

Parameters

px_ring_buf	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 155 of file px_ring_buf.c.

◆ px_ring_buf_rd()

px_ring_buf_idx_t px_ring_buf_rd	(	px_ring_buf_t *	px_ring_buf,
		void *	data,
		size_t	nr_of_bytes
	)

Read (retrieve) data from the ring buffer.

Parameters

px_ring_buf	Pointer to the ring buffer object
data	Pointer to location where data must be stored
nr_of_bytes	Number of bytes to read

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

Definition at line 176 of file px_ring_buf.c.

◆ px_ring_buf_peek()

px_ring_buf_idx_t px_ring_buf_peek	(	px_ring_buf_t *	px_ring_buf,
		void *	data,
		size_t	nr_of_bytes
	)

Peek data from the ring buffer, without advancing the read pointer.

Parameters

px_ring_buf	Pointer to the ring buffer object
data	Pointer to location where data must be stored
nr_of_bytes	Number of bytes to peek

Returns: px_ring_buf_idx_t The actual number of bytes peeked, which may be less than the number specified, because the buffer is empty.

Definition at line 207 of file px_ring_buf.c.

◆ px_ring_buf_get_count_used()

px_ring_buf_idx_t px_ring_buf_get_count_used ( px_ring_buf_t * px_ring_buf )

Get number of bytes stored in the buffer.

Parameters

px_ring_buf Pointer to the ring buffer object

Returns: px_ring_buf_idx_t Number of bytes stored in the buffer

Definition at line 235 of file px_ring_buf.c.

◆ px_ring_buf_get_count_free()

px_ring_buf_idx_t px_ring_buf_get_count_free ( px_ring_buf_t * px_ring_buf )

Get number of free bytes available in buffer.

Note: an empty buffer has one less byte than the buffer size

Parameters

px_ring_buf Pointer to the ring buffer object

Returns: px_ring_buf_idx_t Number of bytes available in the buffer

Definition at line 262 of file px_ring_buf.c.

◆ px_ring_buf_log_report()

void px_ring_buf_log_report ( px_ring_buf_t * px_ring_buf )

Report status of ring buffer.

Parameters

px_ring_buf Pointer to the ring buffer object

Definition at line 289 of file px_ring_buf.c.

Description

Data Structures

Typedefs

Functions

Data Structure Documentation

◆ px_ring_buf_t

Typedef Documentation

◆ px_ring_buf_idx_t

Function Documentation

◆ px_ring_buf_init()

◆ px_ring_buf_is_empty()

◆ px_ring_buf_is_full()

◆ px_ring_buf_flush()

◆ px_ring_buf_wr_u8()

◆ px_ring_buf_wr()

◆ px_ring_buf_rd_u8()

◆ px_ring_buf_rd()

◆ px_ring_buf_peek()

◆ px_ring_buf_get_count_used()

◆ px_ring_buf_get_count_free()

◆ px_ring_buf_log_report()