Ring Buffer APIs

Simple ring buffer implementation. More...

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

Macros
#define	RING_BUF_DECLARE(name, size8)
	Define and initialize a ring buffer for byte data.
#define	RING_BUF_ITEM_DECLARE(name, size32)
	Define and initialize an "item based" ring buffer.
#define	RING_BUF_ITEM_DECLARE_SIZE(name, size32)
	Define and initialize an "item based" ring buffer.
#define	RING_BUF_ITEM_DECLARE_POW2(name, pow)
	Define and initialize a power-of-2 sized "item based" ring buffer.
#define	RING_BUF_ITEM_SIZEOF(expr)
	Compute the ring buffer size in 32-bit needed to store an element.

Functions
static void	ring_buf_internal_reset (struct ring_buf *buf, int32_t value)
	Function to force ring_buf internal states to given value.
static void	ring_buf_init (struct ring_buf *buf, uint32_t size, uint8_t *data)
	Initialize a ring buffer for byte data.
static void	ring_buf_item_init (struct ring_buf *buf, uint32_t size, uint32_t *data)
	Initialize an "item based" ring buffer.
static bool	ring_buf_is_empty (struct ring_buf *buf)
	Determine if a ring buffer is empty.
static void	ring_buf_reset (struct ring_buf *buf)
	Reset ring buffer state.
static uint32_t	ring_buf_space_get (struct ring_buf *buf)
	Determine free space in a ring buffer.
static uint32_t	ring_buf_item_space_get (struct ring_buf *buf)
	Determine free space in an "item based" ring buffer.
static uint32_t	ring_buf_capacity_get (struct ring_buf *buf)
	Return ring buffer capacity.
static uint32_t	ring_buf_size_get (struct ring_buf *buf)
	Determine used space in a ring buffer.
uint32_t	ring_buf_put_claim (struct ring_buf *buf, uint8_t **data, uint32_t size)
	Allocate buffer for writing data to a ring buffer.
int	ring_buf_put_finish (struct ring_buf *buf, uint32_t size)
	Indicate number of bytes written to allocated buffers.
uint32_t	ring_buf_put (struct ring_buf *buf, const uint8_t *data, uint32_t size)
	Write (copy) data to a ring buffer.
uint32_t	ring_buf_get_claim (struct ring_buf *buf, uint8_t **data, uint32_t size)
	Get address of a valid data in a ring buffer.
int	ring_buf_get_finish (struct ring_buf *buf, uint32_t size)
	Indicate number of bytes read from claimed buffer.
uint32_t	ring_buf_get (struct ring_buf *buf, uint8_t *data, uint32_t size)
	Read data from a ring buffer.
uint32_t	ring_buf_peek (struct ring_buf *buf, uint8_t *data, uint32_t size)
	Peek at data from a ring buffer.
int	ring_buf_item_put (struct ring_buf *buf, uint16_t type, uint8_t value, uint32_t *data, uint8_t size32)
	Write a data item to a ring buffer.
int	ring_buf_item_get (struct ring_buf *buf, uint16_t *type, uint8_t *value, uint32_t *data, uint8_t *size32)
	Read a data item from a ring buffer.

Detailed Description

Simple ring buffer implementation.

Macro Definition Documentation

RING_BUF_DECLARE

#define RING_BUF_DECLARE	(		name,
			size8 )

#include <zephyr/sys/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 = { \
                .buffer = _ring_buffer_data_##name, \
                .size = size8 \
        }

Define and initialize a ring buffer for byte data.

This macro establishes a ring buffer of an arbitrary size. The basic storage unit is a byte.

The ring buffer can be accessed outside the module where it is defined using:

extern struct ring_buf <name>; 

Parameters

name	Name of the ring buffer.
size8	Size of ring buffer (in bytes).

RING_BUF_ITEM_DECLARE

#define RING_BUF_ITEM_DECLARE	(		name,
			size32 )

#include <zephyr/sys/ring_buffer.h>

Value:

        BUILD_ASSERT((size32) < RING_BUFFER_MAX_SIZE / 4,\
                RING_BUFFER_SIZE_ASSERT_MSG); \
        static uint32_t __noinit _ring_buffer_data_##name[size32]; \
        struct ring_buf name = { \
                .buffer = (uint8_t *) _ring_buffer_data_##name, \
                .size = 4 * (size32) \
        }

Define and initialize an "item based" ring buffer.

This macro establishes an "item based" ring buffer. Each data item is an array of 32-bit words (from zero to 1020 bytes in length), coupled with a 16-bit type identifier and an 8-bit integer value.

The ring buffer can be accessed outside the module where it is defined using:

extern struct ring_buf <name>; 

Parameters

name	Name of the ring buffer.
size32	Size of ring buffer (in 32-bit words).

RING_BUF_ITEM_DECLARE_POW2

#define RING_BUF_ITEM_DECLARE_POW2	(		name,
			pow )

#include <zephyr/sys/ring_buffer.h>

Value:

        RING_BUF_ITEM_DECLARE(name, BIT(pow))

Define and initialize a power-of-2 sized "item based" ring buffer.

This macro establishes an "item based" ring buffer by specifying its size using a power of 2. This exists mainly for backward compatibility reasons. RING_BUF_ITEM_DECLARE should be used instead.

Parameters

name	Name of the ring buffer.
pow	Ring buffer size exponent.

RING_BUF_ITEM_DECLARE_SIZE

#define RING_BUF_ITEM_DECLARE_SIZE	(		name,
			size32 )

#include <zephyr/sys/ring_buffer.h>

Value:

        RING_BUF_ITEM_DECLARE(name, size32)

Define and initialize an "item based" ring buffer.

This exists for backward compatibility reasons. RING_BUF_ITEM_DECLARE should be used instead.

Parameters

name	Name of the ring buffer.
size32	Size of ring buffer (in 32-bit words).

RING_BUF_ITEM_SIZEOF

#define RING_BUF_ITEM_SIZEOF

(

expr

)

#include <zephyr/sys/ring_buffer.h>

Value:

DIV_ROUND_UP(sizeof(expr), sizeof(uint32_t))

Compute the ring buffer size in 32-bit needed to store an element.

The argument can be a type or an expression. Note: rounds up if the size is not a multiple of 32 bits.

Parameters

expr	Expression or type to compute the size of

Function Documentation

ring_buf_capacity_get()

static uint32_t ring_buf_capacity_get ( struct ring_buf * buf )

inlinestatic

#include <zephyr/sys/ring_buffer.h>

Return ring buffer capacity.

Parameters

buf	Address of ring buffer.

Returns

Ring buffer capacity (in bytes).

ring_buf_get()

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

#include <zephyr/sys/ring_buffer.h>

Read data from a ring buffer.

This routine reads data from a ring buffer buf.

Warning

Use cases involving multiple reads of the ring buffer must prevent concurrent read operations, either by preventing all readers from being preempted or by using a mutex to govern reads to the ring buffer.

Ring buffer instance should not mix byte access and item mode (calls prefixed with ring_buf_item_).

Parameters

buf	Address of ring buffer.
data	Address of the output buffer. Can be NULL to discard data.
size	Data size (in bytes).

Return values

Number

of bytes written to the output buffer.

ring_buf_get_claim()

uint32_t ring_buf_get_claim	(	struct ring_buf *	buf,
		uint8_t **	data,
		uint32_t	size )

#include <zephyr/sys/ring_buffer.h>

Get address of a valid data in a ring buffer.

With this routine, memory copying can be reduced since internal ring buffer can be used directly by the user. Once data is processed it must be freed using ring_buf_get_finish.

Warning

Use cases involving multiple reads of the ring buffer must prevent concurrent read operations, either by preventing all readers from being preempted or by using a mutex to govern reads to the ring buffer.

Ring buffer instance should not mix byte access and item access (calls prefixed with ring_buf_item_).

Parameters

[in]	buf	Address of ring buffer.
[out]	data	Pointer to the address. It is set to a location within ring buffer.
[in]	size	Requested size (in bytes).

Returns

Number of valid bytes in the provided buffer which can be smaller than requested if there is not enough free space or buffer wraps.

ring_buf_get_finish()

int ring_buf_get_finish	(	struct ring_buf *	buf,
		uint32_t	size )

#include <zephyr/sys/ring_buffer.h>

Indicate number of bytes read from claimed buffer.

The number of bytes must be equal or lower than the sum corresponding to all preceding ring_buf_get_claim invocations (or even 0). Surplus bytes will remain available in the buffer.

Warning

Use cases involving multiple reads of the ring buffer must prevent concurrent read operations, either by preventing all readers from being preempted or by using a mutex to govern reads to the ring buffer.

Ring buffer instance should not mix byte access and item mode (calls prefixed with ring_buf_item_).

Parameters

buf	Address of ring buffer.
size	Number of bytes that can be freed.

Return values

0	Successful operation.
-EINVAL	Provided size exceeds valid bytes in the ring buffer.

ring_buf_init()

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

inlinestatic

#include <zephyr/sys/ring_buffer.h>

Initialize a ring buffer for byte data.

This routine initializes a ring buffer, prior to its first use. It is only used for ring buffers not defined using RING_BUF_DECLARE.

Parameters

buf	Address of ring buffer.
size	Ring buffer size (in bytes).
data	Ring buffer data area (uint8_t data[size]).

ring_buf_internal_reset()

static void ring_buf_internal_reset ( struct ring_buf * buf, int32_t value )

inlinestatic

#include <zephyr/sys/ring_buffer.h>

Function to force ring_buf internal states to given value.

Any value other than 0 makes sense only in validation testing context.

ring_buf_is_empty()

static bool ring_buf_is_empty ( struct ring_buf * buf )

inlinestatic

#include <zephyr/sys/ring_buffer.h>

Determine if a ring buffer is empty.

Parameters

buf	Address of ring buffer.

Returns

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

ring_buf_item_get()

int ring_buf_item_get	(	struct ring_buf *	buf,
		uint16_t *	type,
		uint8_t *	value,
		uint32_t *	data,
		uint8_t *	size32 )

#include <zephyr/sys/ring_buffer.h>

Read a data item from a ring buffer.

This routine reads a data item from ring buffer buf. The data item is an array of 32-bit words (up to 1020 bytes in length), coupled with a 16-bit type identifier and an 8-bit integer value.

Warning

Use cases involving multiple reads of the ring buffer must prevent concurrent read operations, either by preventing all readers from being preempted or by using a mutex to govern reads to the ring buffer.

Parameters

buf	Address of ring buffer.
type	Area to store the data item's type identifier.
value	Area to store the data item's integer value.
data	Area to store the data item. Can be NULL to discard data.
size32	Size of the data item storage area (number of 32-bit chunks).

Return values

0	Data item was fetched; size32 now contains the number of 32-bit words read into data area data.
-EAGAIN	Ring buffer is empty.
-EMSGSIZE	Data area data is too small; size32 now contains the number of 32-bit words needed.

ring_buf_item_init()

static void ring_buf_item_init ( struct ring_buf * buf, uint32_t size, uint32_t * data )

inlinestatic

#include <zephyr/sys/ring_buffer.h>

Initialize an "item based" ring buffer.

This routine initializes a ring buffer, prior to its first use. It is only used for ring buffers not defined using RING_BUF_ITEM_DECLARE.

Each data item is an array of 32-bit words (from zero to 1020 bytes in length), coupled with a 16-bit type identifier and an 8-bit integer value.

Parameters

buf	Address of ring buffer.
size	Ring buffer size (in 32-bit words)
data	Ring buffer data area (uint32_t data[size]).

ring_buf_item_put()

int ring_buf_item_put	(	struct ring_buf *	buf,
		uint16_t	type,
		uint8_t	value,
		uint32_t *	data,
		uint8_t	size32 )

#include <zephyr/sys/ring_buffer.h>

Write a data item to a ring buffer.

This routine writes a data item to ring buffer buf. The data item is an array of 32-bit words (from zero to 1020 bytes in length), coupled with a 16-bit type identifier and an 8-bit integer value.

Warning

Use cases involving multiple writers to the ring buffer must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the ring buffer.

Parameters

buf	Address of ring buffer.
type	Data item's type identifier (application specific).
value	Data item's integer value (application specific).
data	Address of data item.
size32	Data item size (number of 32-bit words).

Return values

0	Data item was written.
-EMSGSIZE	Ring buffer has insufficient free space.

ring_buf_item_space_get()

static uint32_t ring_buf_item_space_get ( struct ring_buf * buf )

inlinestatic

#include <zephyr/sys/ring_buffer.h>

Determine free space in an "item based" ring buffer.

Parameters

buf	Address of ring buffer.

Returns

Ring buffer free space (in 32-bit words).

ring_buf_peek()

uint32_t ring_buf_peek	(	struct ring_buf *	buf,
		uint8_t *	data,
		uint32_t	size )

#include <zephyr/sys/ring_buffer.h>

Peek at data from a ring buffer.

This routine reads data from a ring buffer buf without removal.

Warning

Use cases involving multiple reads of the ring buffer must prevent concurrent read operations, either by preventing all readers from being preempted or by using a mutex to govern reads to the ring buffer.

Ring buffer instance should not mix byte access and item mode (calls prefixed with ring_buf_item_).

Multiple calls to peek will result in the same data being 'peeked' multiple times. To remove data, use either ring_buf_get or ring_buf_get_claim followed by ring_buf_get_finish with a non-zero size.

Parameters

buf	Address of ring buffer.
data	Address of the output buffer. Cannot be NULL.
size	Data size (in bytes).

Return values

Number

of bytes written to the output buffer.

ring_buf_put()

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

#include <zephyr/sys/ring_buffer.h>

Write (copy) data to a ring buffer.

This routine writes data to a ring buffer buf.

Warning

Use cases involving multiple writers to the ring buffer must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the ring buffer.

Ring buffer instance should not mix byte access and item access (calls prefixed with ring_buf_item_).

Parameters

buf	Address of ring buffer.
data	Address of data.
size	Data size (in bytes).

Return values

Number

of bytes written.

ring_buf_put_claim()

uint32_t ring_buf_put_claim	(	struct ring_buf *	buf,
		uint8_t **	data,
		uint32_t	size )

#include <zephyr/sys/ring_buffer.h>

Allocate buffer for writing data to a ring buffer.

With this routine, memory copying can be reduced since internal ring buffer can be used directly by the user. Once data is written to allocated area number of bytes written must be confirmed (see ring_buf_put_finish).

Warning

Use cases involving multiple writers to the ring buffer must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the ring buffer.

Ring buffer instance should not mix byte access and item access (calls prefixed with ring_buf_item_).

Parameters

[in]	buf	Address of ring buffer.
[out]	data	Pointer to the address. It is set to a location within ring buffer.
[in]	size	Requested allocation size (in bytes).

Returns

Size of allocated buffer which can be smaller than requested if there is not enough free space or buffer wraps.

ring_buf_put_finish()

int ring_buf_put_finish	(	struct ring_buf *	buf,
		uint32_t	size )

#include <zephyr/sys/ring_buffer.h>

Indicate number of bytes written to allocated buffers.

The number of bytes must be equal to or lower than the sum corresponding to all preceding ring_buf_put_claim invocations (or even 0). Surplus bytes will be returned to the available free buffer space.

Warning

Use cases involving multiple writers to the ring buffer must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the ring buffer.

Ring buffer instance should not mix byte access and item access (calls prefixed with ring_buf_item_).

Parameters

buf	Address of ring buffer.
size	Number of valid bytes in the allocated buffers.

Return values

0	Successful operation.
-EINVAL	Provided size exceeds free space in the ring buffer.

ring_buf_reset()

static void ring_buf_reset ( struct ring_buf * buf )

inlinestatic

#include <zephyr/sys/ring_buffer.h>

Reset ring buffer state.

Parameters

buf	Address of ring buffer.

ring_buf_size_get()

static uint32_t ring_buf_size_get ( struct ring_buf * buf )

inlinestatic

#include <zephyr/sys/ring_buffer.h>

Determine used space in a ring buffer.

Parameters

buf	Address of ring buffer.

Returns

Ring buffer space used (in bytes).

ring_buf_space_get()

static uint32_t ring_buf_space_get ( struct ring_buf * buf )

inlinestatic

#include <zephyr/sys/ring_buffer.h>

Determine free space in a ring buffer.

Parameters

buf	Address of ring buffer.

Returns

Ring buffer free space (in bytes).