Ring Buffer APIs

Macros
#define	RING_BUF_ITEM_DECLARE_POW2(name, pow)
	Define and initialize a high performance ring buffer. More...
#define	RING_BUF_ITEM_DECLARE_SIZE(name, size32)
	Define and initialize a standard ring buffer. More...
#define	RING_BUF_DECLARE(name, size8)
	Define and initialize a ring buffer for byte data. More...

Functions
static void	ring_buf_init (struct ring_buf *buf, uint32_t size, void *data)
	Initialize a ring buffer. More...
int	ring_buf_is_empty (struct ring_buf *buf)
	Determine if a ring buffer is empty. More...
static void	ring_buf_reset (struct ring_buf *buf)
	Reset ring buffer state. More...
uint32_t	ring_buf_space_get (struct ring_buf *buf)
	Determine free space in a ring buffer. More...
static uint32_t	ring_buf_capacity_get (struct ring_buf *buf)
	Return ring buffer capacity. More...
uint32_t	ring_buf_size_get (struct ring_buf *buf)
	Determine used space in a ring buffer. More...
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. More...
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. More...
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. More...
int	ring_buf_put_finish (struct ring_buf *buf, uint32_t size)
	Indicate number of bytes written to allocated buffers. More...
uint32_t	ring_buf_put (struct ring_buf *buf, const uint8_t *data, uint32_t size)
	Write (copy) data to a ring buffer. More...
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. More...
int	ring_buf_get_finish (struct ring_buf *buf, uint32_t size)
	Indicate number of bytes read from claimed buffer. More...
uint32_t	ring_buf_get (struct ring_buf *buf, uint8_t *data, uint32_t size)
	Read data from a ring buffer. More...
uint32_t	ring_buf_peek (struct ring_buf *buf, uint8_t *data, uint32_t size)
	Peek at data from a ring buffer. More...

Detailed Description

Macro Definition Documentation

RING_BUF_DECLARE

#define RING_BUF_DECLARE	(		name,
			size8
	)

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

Define and initialize a ring buffer for byte data.

This macro establishes a ring buffer of an arbitrary size.

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_POW2

#define RING_BUF_ITEM_DECLARE_POW2	(		name,
			pow
	)

#include <include/sys/ring_buffer.h>

Value:

        BUILD_ASSERT((1 << pow) < RING_BUFFER_MAX_SIZE,\
                RING_BUFFER_SIZE_ASSERT_MSG); \
        static uint32_t __noinit _ring_buffer_data_##name[BIT(pow)]; \
        struct ring_buf name = { \
                .size = (BIT(pow)),       \
                .mask = (BIT(pow)) - 1, \
                .buf = { .buf32 = _ring_buffer_data_##name } \
        }

Define and initialize a high performance ring buffer.

This macro establishes a ring buffer whose size must be a power of 2; that is, the ring buffer contains 2^pow 32-bit words, where pow is the specified ring buffer size exponent. A high performance ring buffer doesn't require the use of modulo arithmetic operations to maintain itself.

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.
pow	Ring buffer size exponent.

RING_BUF_ITEM_DECLARE_SIZE

#define RING_BUF_ITEM_DECLARE_SIZE	(		name,
			size32
	)

#include <include/sys/ring_buffer.h>

Value:

        BUILD_ASSERT(size32 < RING_BUFFER_MAX_SIZE,\
                RING_BUFFER_SIZE_ASSERT_MSG); \
        static uint32_t __noinit _ring_buffer_data_##name[size32]; \
        struct ring_buf name = { \
                .size = size32, \
                .buf = { .buf32 = _ring_buffer_data_##name} \
        }

Define and initialize a standard ring buffer.

This macro establishes a ring buffer of an arbitrary size. A standard ring buffer uses modulo arithmetic operations to maintain itself.

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).

Function Documentation

ring_buf_capacity_get()

static uint32_t ring_buf_capacity_get ( struct ring_buf *  buf )

inlinestatic

#include <include/sys/ring_buffer.h>

Return ring buffer capacity.

Parameters

buf	Address of ring buffer.

Returns

Ring buffer capacity (in 32-bit words or bytes).

ring_buf_get()

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

#include <include/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 <include/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 can 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 <include/sys/ring_buffer.h>

Indicate number of bytes read from claimed 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, void *  data  )

inlinestatic

#include <include/sys/ring_buffer.h>

Initialize a 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_DECLARE, RING_BUF_ITEM_DECLARE_POW2 or RING_BUF_ITEM_DECLARE_SIZE.

Setting size to a power of 2 establishes a high performance ring buffer that doesn't require the use of modulo arithmetic operations to maintain itself.

Parameters

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

ring_buf_is_empty()

int ring_buf_is_empty

(

struct ring_buf *

buf

)

#include <include/sys/ring_buffer.h>

Determine if a ring buffer is empty.

Parameters

buf	Address of ring buffer.

Returns

1 if the ring buffer is empty, or 0 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 <include/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_put()

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

#include <include/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_peek()

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

#include <include/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 <include/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 <include/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 can 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 <include/sys/ring_buffer.h>

Indicate number of bytes written to allocated buffers.

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 <include/sys/ring_buffer.h>

Reset ring buffer state.

Parameters

buf	Address of ring buffer.

ring_buf_size_get()

uint32_t ring_buf_size_get

(

struct ring_buf *

buf

)

#include <include/sys/ring_buffer.h>

Determine used space in a ring buffer.

Parameters

buf	Address of ring buffer.

Returns

Ring buffer space used (in 32-bit words or bytes).

ring_buf_space_get()

uint32_t ring_buf_space_get

(

struct ring_buf *

buf

)

#include <include/sys/ring_buffer.h>

Determine free space in a ring buffer.

Parameters

buf	Address of ring buffer.

Returns

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