michaelh/zephyr
1
0
Fork 0
Code Releases Activity

lib: ring_buffer: Rename sys_ring_buf_ to ring_buf_item_

Browse source 
Deprecate API prefixed with sys_ring_buf_ and rename it
to ring_buf_item_ since this API is not a typical ring buffer
but ring buffer of data items (metadata + 32bit words).

Signed-off-by: Krzysztof Chruscinski <krzysztof.chruscinski@nordicsemi.no>
This commit is contained in:
Krzysztof Chruscinski 2018-09-14 14:23:34 +02:00 • committed by Anas Nashif
commit ff5f00f2c3
6 changed files with 124 additions and 82 deletions
Download patch file Download diff file Expand all files Collapse all files

35
doc/kernel/other/ring_buffers.rst
View file

@ -72,7 +72,7 @@ Defining a Ring Buffer
======================
A ring buffer is defined using a variable of type :c:type:`struct ring_buf`.
It must then be initialized by calling :cpp:func:`sys_ring_buf_init()`.
It must then be initialized by calling :cpp:func:`ring_buf_init()`.
The following code defines and initializes an empty ring buffer
(which is part of a larger data structure). The ring buffer's data buffer
@ -90,7 +90,7 @@ is capable of holding 64 words of data and metadata information.
struct my_struct ms;
void init_my_struct {
sys_ring_buf_init(&ms.rb, sizeof(ms.buffer), ms.buffer);
ring_buf_init(&ms.rb, sizeof(ms.buffer), ms.buffer);
...
}
@ -104,7 +104,7 @@ which can be accessed using efficient masking operations.
.. code-block:: c
/* Buffer with 2^8 (or 256) words */
SYS_RING_BUF_DECLARE_POW2(my_ring_buf, 8);
RING_BUF_ITEM_DECLARE_POW2(my_ring_buf, 8);
The following code defines a ring buffer with an arbitrary-sized data buffer,
which can be accessed using less efficient modulo operations.
@ -112,19 +112,20 @@ which can be accessed using less efficient modulo operations.
.. code-block:: c
#define MY_RING_BUF_WORDS 93
SYS_RING_BUF_DECLARE_SIZE(my_ring_buf, MY_RING_BUF_WORDS);
RING_BUF_ITEM_DECLARE_SIZE(my_ring_buf, MY_RING_BUF_WORDS);
Enqueuing Data
==============
A data item is added to a ring buffer by calling :cpp:func:`sys_ring_buf_put()`.
A data item is added to a ring buffer by calling
:cpp:func:`ring_buf_item_put()`.
.. code-block:: c
u32_t my_data[MY_DATA_WORDS];
u32_t data[MY_DATA_WORDS];
int ret;
ret = sys_ring_buf_put(&ring_buf, TYPE_FOO, 0, my_data, SIZE32_OF(my_data));
ret = ring_buf_item_put(&ring_buf, TYPE_FOO, 0, data, SIZE32_OF(data));
if (ret == -EMSGSIZE) {
/* not enough room for the data item */
...
@ -138,7 +139,7 @@ can be specified.
int ret;
ret = sys_ring_buf_put(&ring_buf, TYPE_BAR, 17, NULL, 0);
ret = ring_buf_item_put(&ring_buf, TYPE_BAR, 17, NULL, 0);
if (ret == -EMSGSIZE) {
/* not enough room for the data item */
...
@ -148,7 +149,7 @@ Retrieving Data
===============
A data item is removed from a ring buffer by calling
:cpp:func:`sys_ring_buf_get()`.
:cpp:func:`ring_buf_item_get()`.
.. code-block:: c
@ -159,7 +160,7 @@ A data item is removed from a ring buffer by calling
int ret;
my_size = SIZE32_OF(my_data);
ret = sys_ring_buf_get(&ring_buf, &my_type, &my_value, my_data, &my_size);
ret = ring_buf_item_get(&ring_buf, &my_type, &my_value, my_data, &my_size);
if (ret == -EMSGSIZE) {
printk("Buffer is too small, need %d u32_t\n", my_size);
} else if (ret == -EAGAIN) {
@ -175,10 +176,10 @@ APIs
The following ring buffer APIs are provided by :file:`include/ring_buffer.h`:
* :cpp:func:`SYS_RING_BUF_DECLARE_POW2()`
* :cpp:func:`SYS_RING_BUF_DECLARE_SIZE()`
* :cpp:func:`sys_ring_buf_init()`
* :cpp:func:`sys_ring_buf_is_empty()`
* :cpp:func:`sys_ring_buf_space_get()`
* :cpp:func:`sys_ring_buf_put()`
* :cpp:func:`sys_ring_buf_get()`
* :cpp:func:`RING_BUF_ITEM_DECLARE_POW2()`
* :cpp:func:`RING_BUF_ITEM_DECLARE_SIZE()`
* :cpp:func:`ring_buf_init()`
* :cpp:func:`ring_buf_is_empty()`
* :cpp:func:`ring_buf_space_get()`
* :cpp:func:`ring_buf_item_put()`
* :cpp:func:`ring_buf_item_get()`

10
drivers/console/ipm_console_receiver.c
View file

@ -36,7 +36,7 @@ static void ipm_console_thread(void *arg1, void *arg2, void *arg3)
while (1) {
k_sem_take(&driver_data->sem, K_FOREVER);
ret = sys_ring_buf_get(&driver_data->rb, &type,
ret = ring_buf_item_get(&driver_data->rb, &type,
(u8_t *)&config_info->line_buf[pos],
NULL, &size32);
if (ret) {
@ -75,7 +75,7 @@ static void ipm_console_thread(void *arg1, void *arg2, void *arg3)
* clearing the channel_disabled flag.
*/
if (driver_data->channel_disabled &&
sys_ring_buf_space_get(&driver_data->rb)) {
ring_buf_space_get(&driver_data->rb)) {
key = irq_lock();
ipm_set_enabled(driver_data->ipm_device, 1);
driver_data->channel_disabled = 0;
@ -96,7 +96,7 @@ static void ipm_console_receive_callback(void *context, u32_t id,
driver_data = d->driver_data;
/* Should always be at least one free buffer slot */
ret = sys_ring_buf_put(&driver_data->rb, 0, id, NULL, 0);
ret = ring_buf_item_put(&driver_data->rb, 0, id, NULL, 0);
__ASSERT(ret == 0, "Failed to insert data into ring buffer");
k_sem_give(&driver_data->sem);
@ -108,7 +108,7 @@ static void ipm_console_receive_callback(void *context, u32_t id,
* call with the wait flag enabled. It blocks until the receiver side
* re-enables the channel and consumes the data.
*/
if (sys_ring_buf_space_get(&driver_data->rb) == 0) {
if (ring_buf_space_get(&driver_data->rb) == 0) {
ipm_set_enabled(driver_data->ipm_device, 0);
driver_data->channel_disabled = 1;
}
@ -139,7 +139,7 @@ int ipm_console_receiver_init(struct device *d)
driver_data->ipm_device = ipm;
driver_data->channel_disabled = 0;
k_sem_init(&driver_data->sem, 0, UINT_MAX);
sys_ring_buf_init(&driver_data->rb, config_info->rb_size32,
ring_buf_init(&driver_data->rb, config_info->rb_size32,
config_info->ring_buf_data);
ipm_register_callback(ipm, ipm_console_receive_callback, d);

64
include/ring_buffer.h
View file

@ -56,7 +56,7 @@ struct ring_buf {
* @param name Name of the ring buffer.
* @param pow Ring buffer size exponent.
*/
#define SYS_RING_BUF_DECLARE_POW2(name, pow) \
#define RING_BUF_ITEM_DECLARE_POW2(name, pow) \
static u32_t _ring_buffer_data_##name[1 << (pow)]; \
struct ring_buf name = { \
.size = (1 << (pow)), \
@ -64,6 +64,10 @@ struct ring_buf {
.buf = _ring_buffer_data_##name \
};
/** @deprecated Renamed to RING_BUF_ITEM_DECLARE_POW2. */
#define SYS_RING_BUF_DECLARE_POW2(name, pow) \
__DEPRECATED_MACRO RING_BUF_ITEM_DECLARE_POW2(name, pow)
/**
* @brief Statically define and initialize a standard ring buffer.
*
@ -78,19 +82,23 @@ struct ring_buf {
* @param name Name of the ring buffer.
* @param size32 Size of ring buffer (in 32-bit words).
*/
#define SYS_RING_BUF_DECLARE_SIZE(name, size32) \
#define RING_BUF_ITEM_DECLARE_SIZE(name, size32) \
static u32_t _ring_buffer_data_##name[size32]; \
struct ring_buf name = { \
.size = size32, \
.buf = _ring_buffer_data_##name \
};
/** @deprecated Renamed to RING_BUF_ITEM_DECLARE_SIZE. */
#define SYS_RING_BUF_DECLARE_SIZE(name, size32) \
__DEPRECATED_MACRO RING_BUF_ITEM_DECLARE_SIZE(name, size32)
/**
* @brief 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 SYS_RING_BUF_DECLARE_POW2 or
* SYS_RING_BUF_DECLARE_SIZE.
* used for ring buffers not defined using RING_BUF_ITEM_DECLARE_POW2 or
* RING_BUF_ITEM_DECLARE_SIZE.
*
* Setting @a size to a power of 2 establishes a high performance ring buffer
* that doesn't require the use of modulo arithmetic operations to maintain
@ -100,8 +108,7 @@ struct ring_buf {
* @param size Ring buffer size (in 32-bit words).
* @param data Ring buffer data area (typically u32_t data[size]).
*/
static inline void sys_ring_buf_init(struct ring_buf *buf, u32_t size,
u32_t *data)
static inline void ring_buf_init(struct ring_buf *buf, u32_t size, u32_t *data)
{
buf->head = 0;
buf->tail = 0;
@ -113,7 +120,13 @@ static inline void sys_ring_buf_init(struct ring_buf *buf, u32_t size,
} else {
buf->mask = 0;
}
}
/** @deprecated Renamed to ring_buf_init. */
__deprecated static inline void sys_ring_buf_init(struct ring_buf *buf,
u32_t size, u32_t *data)
{
ring_buf_init(buf, size, data);
}
/**
@ -123,11 +136,17 @@ static inline void sys_ring_buf_init(struct ring_buf *buf, u32_t size,
*
* @return 1 if the ring buffer is empty, or 0 if not.
*/
static inline int sys_ring_buf_is_empty(struct ring_buf *buf)
static inline int ring_buf_is_empty(struct ring_buf *buf)
{
return (buf->head == buf->tail);
}
/** @deprecated Renamed to ring_buf_is_empty. */
__deprecated static inline int sys_ring_buf_is_empty(struct ring_buf *buf)
{
return ring_buf_is_empty(buf);
}
/**
* @brief Determine free space in a ring buffer.
*
@ -135,9 +154,9 @@ static inline int sys_ring_buf_is_empty(struct ring_buf *buf)
*
* @return Ring buffer free space (in 32-bit words).
*/
static inline int sys_ring_buf_space_get(struct ring_buf *buf)
static inline int ring_buf_space_get(struct ring_buf *buf)
{
if (sys_ring_buf_is_empty(buf)) {
if (ring_buf_is_empty(buf)) {
return buf->size - 1;
}
@ -149,6 +168,12 @@ static inline int sys_ring_buf_space_get(struct ring_buf *buf)
return (buf->size - buf->tail) + buf->head - 1;
}
/** @deprecated Renamed to ring_buf_space_get. */
__deprecated static inline int sys_ring_buf_space_get(struct ring_buf *buf)
{
return ring_buf_space_get(buf);
}
/**
* @brief Write a data item to a ring buffer.
*
@ -170,9 +195,18 @@ static inline int sys_ring_buf_space_get(struct ring_buf *buf)
* @retval 0 Data item was written.
* @retval -EMSGSIZE Ring buffer has insufficient free space.
*/
int sys_ring_buf_put(struct ring_buf *buf, u16_t type, u8_t value,
int ring_buf_item_put(struct ring_buf *buf, u16_t type, u8_t value,
u32_t *data, u8_t size32);
/** @deprecated Renamed to ring_buf_item_put. */
__deprecated static inline int sys_ring_buf_put(struct ring_buf *buf,
u16_t type, u8_t value,
u32_t *data, u8_t size32)
{
return ring_buf_item_put(buf, type, value, data, size32);
}
/**
* @brief Read a data item from a ring buffer.
*
@ -197,9 +231,17 @@ int sys_ring_buf_put(struct ring_buf *buf, u16_t type, u8_t value,
* @retval -EMSGSIZE Data area @a data is too small; @a size32 now contains
* the number of 32-bit words needed.
*/
int sys_ring_buf_get(struct ring_buf *buf, u16_t *type, u8_t *value,
int ring_buf_item_get(struct ring_buf *buf, u16_t *type, u8_t *value,
u32_t *data, u8_t *size32);
/** @deprecated Renamed to ring_buf_item_get. */
__deprecated static inline int sys_ring_buf_get(struct ring_buf *buf,
u16_t *type, u8_t *value,
u32_t *data, u8_t *size32)
{
return ring_buf_item_get(buf, type, value, data, size32);
}
/**
* @}
*/

8
lib/ring_buffer/ring_buffer.c
View file

@ -20,12 +20,12 @@ struct ring_element {
u32_t value :8; /**< Room for small integral values */
};
int sys_ring_buf_put(struct ring_buf *buf, u16_t type, u8_t value,
int ring_buf_item_put(struct ring_buf *buf, u16_t type, u8_t value,
u32_t *data, u8_t size32)
{
u32_t i, space, index, rc;
space = sys_ring_buf_space_get(buf);
space = ring_buf_space_get(buf);
if (space >= (size32 + 1)) {
struct ring_element *header =
(struct ring_element *)&buf->buf[buf->tail];
@ -55,13 +55,13 @@ int sys_ring_buf_put(struct ring_buf *buf, u16_t type, u8_t value,
return rc;
}
int sys_ring_buf_get(struct ring_buf *buf, u16_t *type, u8_t *value,
int ring_buf_item_get(struct ring_buf *buf, u16_t *type, u8_t *value,
u32_t *data, u8_t *size32)
{
struct ring_element *header;
u32_t i, index;
if (sys_ring_buf_is_empty(buf)) {
if (ring_buf_is_empty(buf)) {
return -EAGAIN;
}

64
tests/lib/ringbuffer/src/main.c
View file

@ -25,17 +25,17 @@
* @defgroup t_ringbuffer_api test_ringbuffer_api
* @brief TestPurpose: verify zephyr ring buffer API functionality
* - API coverage
* -# SYS_RING_BUF_DECLARE_POW2
* -# SYS_RING_BUF_DECLARE_SIZE
* -# sys_ring_buf_init
* -# sys_ring_buf_is_empty
* -# sys_ring_buf_space_get
* -# sys_ring_buf_put
* -# sys_ring_buf_get
* -# RING_BUF_ITEM_DECLARE_POW2
* -# RING_BUF_ITEM_DECLARE_SIZE
* -# ring_buf_init
* -# ring_buf_is_empty
* -# ring_buf_space_get
* -# ring_buf_item_put
* -# ring_buf_item_get
* @}
*/
SYS_RING_BUF_DECLARE_POW2(ring_buf1, 8);
RING_BUF_ITEM_DECLARE_POW2(ring_buf1, 8);
#define TYPE 1
#define VALUE 2
@ -58,20 +58,20 @@ void test_ring_buffer_main(void)
put_count = 0;
while (1) {
ret = sys_ring_buf_put(&ring_buf1, TYPE, VALUE,
ret = ring_buf_item_put(&ring_buf1, TYPE, VALUE,
(u32_t *)rb_data, dsize);
if (ret == -EMSGSIZE) {
SYS_LOG_DBG("ring buffer is full");
break;
}
SYS_LOG_DBG("inserted %d chunks, %d remaining", dsize,
sys_ring_buf_space_get(&ring_buf1));
ring_buf_space_get(&ring_buf1));
dsize = (dsize + 1) % SIZE32_OF(rb_data);
put_count++;
}
getsize = INITIAL_SIZE - 1;
ret = sys_ring_buf_get(&ring_buf1, &gettype, &getval, getdata, &getsize);
ret = ring_buf_item_get(&ring_buf1, &gettype, &getval, getdata, &getsize);
if (ret != -EMSGSIZE) {
SYS_LOG_DBG("Allowed retreival with insufficient destination buffer space");
zassert_true((getsize == INITIAL_SIZE), "Correct size wasn't reported back to the caller");
@ -79,12 +79,12 @@ void test_ring_buffer_main(void)
for (i = 0; i < put_count; i++) {
getsize = SIZE32_OF(getdata);
ret = sys_ring_buf_get(&ring_buf1, &gettype, &getval, getdata,
ret = ring_buf_item_get(&ring_buf1, &gettype, &getval, getdata,
&getsize);
zassert_true((ret == 0), "Couldn't retrieve a stored value");
SYS_LOG_DBG("got %u chunks of type %u and val %u, %u remaining",
getsize, gettype, getval,
sys_ring_buf_space_get(&ring_buf1));
ring_buf_space_get(&ring_buf1));
zassert_true((memcmp((char *)getdata, rb_data, getsize * sizeof(u32_t)) == 0),
"data corrupted");
@ -93,16 +93,16 @@ void test_ring_buffer_main(void)
}
getsize = SIZE32_OF(getdata);
ret = sys_ring_buf_get(&ring_buf1, &gettype, &getval, getdata,
ret = ring_buf_item_get(&ring_buf1, &gettype, &getval, getdata,
&getsize);
zassert_true((ret == -EAGAIN), "Got data out of an empty buffer");
}
/**TESTPOINT: init via SYS_RING_BUF_DECLARE_POW2*/
SYS_RING_BUF_DECLARE_POW2(ringbuf_pow2, POW);
/**TESTPOINT: init via RING_BUF_ITEM_DECLARE_POW2*/
RING_BUF_ITEM_DECLARE_POW2(ringbuf_pow2, POW);
/**TESTPOINT: init via SYS_RING_BUF_DECLARE_SIZE*/
SYS_RING_BUF_DECLARE_SIZE(ringbuf_size, RINGBUFFER_SIZE);
/**TESTPOINT: init via RING_BUF_ITEM_DECLARE_SIZE*/
RING_BUF_ITEM_DECLARE_SIZE(ringbuf_size, RINGBUFFER_SIZE);
static struct ring_buf ringbuf, *pbuf;
@ -124,7 +124,7 @@ static void tringbuf_put(void *p)
{
int index = (int)p;
/**TESTPOINT: ring buffer put*/
int ret = sys_ring_buf_put(pbuf, data[index].type, data[index].value,
int ret = ring_buf_item_put(pbuf, data[index].type, data[index].value,
data[index].buffer, data[index].length);
zassert_equal(ret, 0, NULL);
@ -138,7 +138,7 @@ static void tringbuf_get(void *p)
int ret, index = (int)p;
/**TESTPOINT: ring buffer get*/
ret = sys_ring_buf_get(pbuf, &type, &value, rx_data, &size32);
ret = ring_buf_item_get(pbuf, &type, &value, rx_data, &size32);
zassert_equal(ret, 0, NULL);
zassert_equal(type, data[index].type, NULL);
zassert_equal(value, data[index].value, NULL);
@ -149,22 +149,22 @@ static void tringbuf_get(void *p)
/*test cases*/
void test_ringbuffer_init(void)
{
/**TESTPOINT: init via sys_ring_buf_init*/
sys_ring_buf_init(&ringbuf, RINGBUFFER_SIZE, buffer);
zassert_true(sys_ring_buf_is_empty(&ringbuf), NULL);
zassert_equal(sys_ring_buf_space_get(&ringbuf), RINGBUFFER_SIZE - 1, NULL);
/**TESTPOINT: init via ring_buf_init*/
ring_buf_init(&ringbuf, RINGBUFFER_SIZE, buffer);
zassert_true(ring_buf_is_empty(&ringbuf), NULL);
zassert_equal(ring_buf_space_get(&ringbuf), RINGBUFFER_SIZE - 1, NULL);
}
void test_ringbuffer_declare_pow2(void)
{
zassert_true(sys_ring_buf_is_empty(&ringbuf_pow2), NULL);
zassert_equal(sys_ring_buf_space_get(&ringbuf_pow2), (1 << POW) - 1, NULL);
zassert_true(ring_buf_is_empty(&ringbuf_pow2), NULL);
zassert_equal(ring_buf_space_get(&ringbuf_pow2), (1 << POW) - 1, NULL);
}
void test_ringbuffer_declare_size(void)
{
zassert_true(sys_ring_buf_is_empty(&ringbuf_size), NULL);
zassert_equal(sys_ring_buf_space_get(&ringbuf_size), RINGBUFFER_SIZE - 1,
zassert_true(ring_buf_is_empty(&ringbuf_size), NULL);
zassert_equal(ring_buf_space_get(&ringbuf_size), RINGBUFFER_SIZE - 1,
NULL);
}
@ -176,9 +176,9 @@ void test_ringbuffer_put_get_thread(void)
tringbuf_get((void *)0);
tringbuf_get((void *)1);
tringbuf_put((void *)2);
zassert_false(sys_ring_buf_is_empty(pbuf), NULL);
zassert_false(ring_buf_is_empty(pbuf), NULL);
tringbuf_get((void *)2);
zassert_true(sys_ring_buf_is_empty(pbuf), NULL);
zassert_true(ring_buf_is_empty(pbuf), NULL);
}
void test_ringbuffer_put_get_isr(void)
@ -189,9 +189,9 @@ void test_ringbuffer_put_get_isr(void)
irq_offload(tringbuf_get, (void *)0);
irq_offload(tringbuf_get, (void *)1);
irq_offload(tringbuf_put, (void *)2);
zassert_false(sys_ring_buf_is_empty(pbuf), NULL);
zassert_false(ring_buf_is_empty(pbuf), NULL);
irq_offload(tringbuf_get, (void *)2);
zassert_true(sys_ring_buf_is_empty(pbuf), NULL);
zassert_true(ring_buf_is_empty(pbuf), NULL);
}
void test_ringbuffer_put_get_thread_isr(void)

7
tests/subsys/logging/logger-hook/src/main.c
View file

@ -37,7 +37,7 @@ int logger_put(struct log_cbuffer *logger, char *data, u32_t data_size)
size32 = (data_size + 3) / 4;
key = irq_lock();
ret = sys_ring_buf_put(&logger->ring_buffer, 0, 0,
ret = ring_buf_item_put(&logger->ring_buffer, 0, 0,
(u32_t *)data, size32);
irq_unlock(key);
@ -69,8 +69,7 @@ void test_logging(void)
printk("syslog hook sample configuration is not set correctly %s\n",
CONFIG_ARCH);
#else
sys_ring_buf_init(&log_cbuffer.ring_buffer, LOG_BUF_SIZE,
logger_buffer);
ring_buf_init(&log_cbuffer.ring_buffer, LOG_BUF_SIZE, logger_buffer);
syslog_hook_install(log_cbuf_put);
SYS_LOG_ERR("SYS LOG ERR is ACTIVE");
ring_buf_print(&log_cbuffer.ring_buffer);
@ -91,7 +90,7 @@ static inline void ring_buf_print(struct ring_buf *buf)
unsigned int key;
key = irq_lock();
ret = sys_ring_buf_get(&log_cbuffer.ring_buffer, &type, &val,
ret = ring_buf_item_get(&log_cbuffer.ring_buffer, &type, &val,
(u32_t *)data, &size32);
irq_unlock(key);