Ring Buffer APIs

Simple, header-only ring buffer implementation. More...

Files
file	ring_buffer.h
	Simple, header-only ring buffer implementation.

Data Structures
struct	ring_buf
	A structure to represent a ring buffer. More...

Macros
#define	RING_BUF_INIT(buf, sz)
	Statically initialize a ring buffer.
#define	RING_BUF_DECLARE(name, size8)
	Define and initialize a ring buffer for byte data.

Functions
static uint32_t	ring_buf_capacity_get (const struct ring_buf *rb)
	Return ring buffer capacity.
static uint32_t	ring_buf_size_get (const struct ring_buf *rb)
	Determine size of available data in a ring buffer.
static uint32_t	ring_buf_space_get (const struct ring_buf *rb)
	Determine free space in a ring buffer.
static bool	ring_buf_is_empty (const struct ring_buf *rb)
	Determine if a ring buffer is empty.
static bool	ring_buf_is_full (const struct ring_buf *rb)
	Determine if a ring buffer is full.
static void	ring_buf_reset (struct ring_buf *rb)
	Reset ring buffer state.
static void	ring_buf_init (struct ring_buf *rb, uint32_t size, uint8_t *data)
	Initialize a ring buffer for byte data.
static uint32_t	ring_buf_put_ptr (struct ring_buf *rb, uint8_t **data, size_t offset)
	Get address of region for writing data to a ring buffer.
static void	ring_buf_commit (struct ring_buf *rb, size_t size)
	Indicate number of bytes written to a ring buffer.
static uint32_t	ring_buf_get_ptr (struct ring_buf *rb, uint8_t **data, size_t offset)
	Get address of valid data within a ring buffer.
static void	ring_buf_consume (struct ring_buf *rb, size_t size)
	Indicate number of bytes consumed from a ring buffer.
static uint32_t	ring_buf_put (struct ring_buf *rb, const uint8_t *data, uint32_t size)
	Write (copy) data to a ring buffer.
static uint32_t	ring_buf_get (struct ring_buf *rb, uint8_t *data, uint32_t size)
	Read data from a ring buffer.
static uint32_t	ring_buf_peek (const struct ring_buf *rb, uint8_t *data, uint32_t size)
	Peek at data from a ring buffer without consuming it.

Detailed Description

Simple, header-only ring buffer implementation.

Macro Definition Documentation

RING_BUF_DECLARE

#define RING_BUF_DECLARE	(		name,
			size8 )

#include <ring_buffer.h>

Value:

BUILD_ASSERT((size8) <= RING_BUFFER_MAX_SIZE, RING_BUFFER_SIZE_ASSERT_MSG);     \
static uint8_t __noinit _ring_buffer_data_##name[(size8)];                      \
struct ring_buf name = RING_BUF_INIT(_ring_buffer_data_##name, (size8))

Define and initialize a ring buffer for byte data.

The user-visible capacity equals the requested size8. The backing storage is allocated as a static array of uint8_t with size equal to size8. The ring buffer struct is initialized to point to this backing storage and set the size accordingly.

The ring buffer can be referenced from other modules with:

extern struct ring_buf <name>; 

Parameters

name	Name of the ring buffer.
size8	buffer capacity in bytes.

RING_BUF_INIT

#define RING_BUF_INIT	(		buf,
			sz )

#include <ring_buffer.h>

Value:

{                                               \
        .buffer = (buf),                        \
        .size = (ring_buf_size_t)(sz),          \
}

Statically initialize a ring buffer.

size denotes the buffer capacity in bytes, which equals the user-visible capacity; no slot is reserved internally.

Parameters

buf	Pointer to the backing byte storage.
sz	Buffer capacity, in bytes. Equals the user-visible capacity.

Function Documentation

ring_buf_capacity_get()

uint32_t ring_buf_capacity_get ( const struct ring_buf * rb )

inlinestatic

#include <ring_buffer.h>

Return ring buffer capacity.

Parameters

rb	Address of ring buffer.

Returns

Ring buffer capacity (in bytes).

ring_buf_commit()

void ring_buf_commit ( struct ring_buf * rb, size_t size )

inlinestatic

#include <ring_buffer.h>

Indicate number of bytes written to a ring buffer.

The size must be less than or equal to the value returned by the most recent ring_buf_put_ptr.

Parameters

rb	Address of ring buffer.
size	Number of bytes that have been written.

ring_buf_consume()

void ring_buf_consume ( struct ring_buf * rb, size_t size )

inlinestatic

#include <ring_buffer.h>

Indicate number of bytes consumed from a ring buffer.

The size must be less than or equal to the value returned by the most recent ring_buf_get_ptr.

Parameters

rb	Address of ring buffer.
size	Number of bytes that have been consumed.

ring_buf_get()

uint32_t ring_buf_get ( struct ring_buf * rb, uint8_t * data, uint32_t size )

inlinestatic

#include <ring_buffer.h>

Read data from a ring buffer.

Parameters

rb	Address of ring buffer.
data	Destination buffer.
size	Maximum number of bytes to read.

Returns

Number of bytes read.

ring_buf_get_ptr()

uint32_t ring_buf_get_ptr ( struct ring_buf * rb, uint8_t ** data, size_t offset )

inlinestatic

#include <ring_buffer.h>

Get address of valid data within a ring buffer.

Memory copying can be reduced since the internal ring buffer storage can be used directly by the user. Once data is processed it must be released via ring_buf_consume.

Parameters

[in]	rb	Address of ring buffer.
[out]	data	Set to the start of the readable region within the buffer.
[in]	offset	Bytes past the current read index that the caller has already tentatively consumed (0 for a fresh peek). Must not exceed the amount of valid data.

Returns

Number of bytes available for reading. May be smaller than the total amount of valid data if the data wraps around the end of the buffer.

ring_buf_init()

void ring_buf_init ( struct ring_buf * rb, uint32_t size, uint8_t * data )

inlinestatic

#include <ring_buffer.h>

Initialize a ring buffer for byte data.

Used for ring buffers not defined using RING_BUF_DECLARE. size denotes the buffer capacity in bytes, which equals the user-visible capacity; no slot is reserved internally.

Parameters

rb	Address of ring buffer.
size	Buffer capacity (in bytes). A size of 0 produces a degenerate buffer with capacity 0.
data	Ring buffer data area (uint8_t data[size]).

ring_buf_is_empty()

bool ring_buf_is_empty ( const struct ring_buf * rb )

inlinestatic

#include <ring_buffer.h>

Determine if a ring buffer is empty.

Parameters

rb	Address of ring buffer.

Returns

true if the ring buffer is empty, or false if not.

ring_buf_is_full()

bool ring_buf_is_full ( const struct ring_buf * rb )

inlinestatic

#include <ring_buffer.h>

Determine if a ring buffer is full.

Parameters

rb	Address of ring buffer.

Returns

true if the ring buffer is full, or false if not.

ring_buf_peek()

uint32_t ring_buf_peek ( const struct ring_buf * rb, uint8_t * data, uint32_t size )

inlinestatic

#include <ring_buffer.h>

Peek at data from a ring buffer without consuming it.

Multiple peek operations return the same data; use ring_buf_get or ring_buf_consume to actually advance the read pointer.

Parameters

rb	Address of ring buffer.
data	Destination buffer. Must not be NULL.
size	Maximum number of bytes to peek.

Returns

Number of bytes copied into data.

ring_buf_put()

uint32_t ring_buf_put ( struct ring_buf * rb, const uint8_t * data, uint32_t size )

inlinestatic

#include <ring_buffer.h>

Write (copy) data to a ring buffer.

Parameters

rb	Address of ring buffer.
data	Source data. Must not be NULL.
size	Data size (in bytes).

Returns

Number of bytes written.

ring_buf_put_ptr()

uint32_t ring_buf_put_ptr ( struct ring_buf * rb, uint8_t ** data, size_t offset )

inlinestatic

#include <ring_buffer.h>

Get address of region for writing data to a ring buffer.

Memory copying can be reduced since the internal ring buffer storage can be used directly by the user. Once data is written to the allotted area, the number of bytes written must be confirmed via ring_buf_commit.

Parameters

[in]	rb	Address of ring buffer.
[out]	data	Set to the start of the writable region within the buffer.
[in]	offset	Bytes past the current write index that the caller has already tentatively reserved (0 for a fresh reservation). Must not exceed the free space.

Returns

Number of bytes available for writing. May be smaller than the total free space if the free region wraps around the end of the buffer.

ring_buf_reset()

void ring_buf_reset ( struct ring_buf * rb )

inlinestatic

#include <ring_buffer.h>

Reset ring buffer state.

Parameters

rb	Address of ring buffer.

ring_buf_size_get()

uint32_t ring_buf_size_get ( const struct ring_buf * rb )

inlinestatic

#include <ring_buffer.h>

Determine size of available data in a ring buffer.

Parameters

rb	Address of ring buffer.

Returns

Ring buffer data size (in bytes).

ring_buf_space_get()

uint32_t ring_buf_space_get ( const struct ring_buf * rb )

inlinestatic

#include <ring_buffer.h>

Determine free space in a ring buffer.

Parameters

rb	Address of ring buffer.

Returns

Ring buffer free space (in bytes).