ring_buffer.h

Go to the documentation of this file.

/*
 * Copyright (c) 2026 Nicolas Pitre     <npitre@baylibre.com>
 *               2026 Måns Ansgariusson <mansgariusson@gmail.com>
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_SYS_RING_BUFFER_H_
#define ZEPHYR_INCLUDE_SYS_RING_BUFFER_H_
 
#include <errno.h>
#include <stdbool.h>
#include <stdint.h>
#include <string.h>
 
#include <zephyr/sys/util.h>
#include <zephyr/toolchain.h>
#include <zephyr/sys/__assert.h>
 
#ifdef __cplusplus
extern "C" {
#endif


#ifdef CONFIG_RING_BUFFER_LARGE
typedef uint32_t ring_buf_idx_t;
typedef uint32_t ring_buf_size_t;
/* read_idx/write_idx + n must not overflow size_t on 32-bit targets (index < 2N, n <= N) */
#define RING_BUFFER_MAX_SIZE (UINT32_MAX / 4U)
#define RING_BUFFER_SIZE_ASSERT_MSG "Size too large"
#else
typedef uint16_t ring_buf_idx_t;
typedef uint16_t ring_buf_size_t;
/* read_idx/write_idx live in [0, 2N) */
#define RING_BUFFER_MAX_SIZE (UINT16_MAX / 2U)
#define RING_BUFFER_SIZE_ASSERT_MSG \
        "Size too large, please enable CONFIG_RING_BUFFER_LARGE"
#endif

struct ring_buf {
        uint8_t *buffer;
        ring_buf_size_t size;
        ring_buf_idx_t read_idx;
        ring_buf_idx_t write_idx;
#ifdef CONFIG_RING_BUFFER
        ring_buf_idx_t put_claimed;
        ring_buf_idx_t get_claimed;
#endif /* CONFIG_RING_BUFFER */
};

 
/*
 * Advance a free-running index into [0, 2N) and convert it to the index type.
 * Takes the buffer capacity N and forms the 2N wrap limit internally, so the
 * [0, 2N) convention stays in one place. Callers guarantee value < 4N (index
 * < 2N plus an increment <= N), so a single conditional subtraction suffices.
 */
static ALWAYS_INLINE ring_buf_idx_t rb_idx_advance(size_t value, ring_buf_size_t size)
{
        size_t lim = 2U * size;
 
        return (ring_buf_idx_t)(value >= lim ? value - lim : value);
}
 
static ALWAYS_INLINE ring_buf_idx_t rb_load_acquire(const ring_buf_idx_t *p)
{
        ring_buf_idx_t v;
 
#if IS_ENABLED(CONFIG_SMP) && (CONFIG_MP_MAX_NUM_CPUS > 1)
        v = __atomic_load_n(p, __ATOMIC_ACQUIRE);
#else
        v = *p;
        compiler_barrier();
#endif
        return v;
}
 
static ALWAYS_INLINE ring_buf_idx_t rb_load_relaxed(const ring_buf_idx_t *p)
{
#if IS_ENABLED(CONFIG_SMP) && (CONFIG_MP_MAX_NUM_CPUS > 1)
        return __atomic_load_n(p, __ATOMIC_RELAXED);
#else
        return *p;
#endif
}
 
static ALWAYS_INLINE void rb_store_release(ring_buf_idx_t *p, ring_buf_idx_t v)
{
#if IS_ENABLED(CONFIG_SMP) && (CONFIG_MP_MAX_NUM_CPUS > 1)
        __atomic_store_n(p, v, __ATOMIC_RELEASE);
#else
        compiler_barrier();
        *p = v;
#endif
}
 
static ALWAYS_INLINE void rb_store_relaxed(ring_buf_idx_t *p, ring_buf_idx_t v)
{
#if IS_ENABLED(CONFIG_SMP) && (CONFIG_MP_MAX_NUM_CPUS > 1)
        __atomic_store_n(p, v, __ATOMIC_RELAXED);
#else
        *p = v;
#endif
}


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

#define RING_BUF_DECLARE(name, size8)                                                   \
        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))

static inline uint32_t ring_buf_capacity_get(const struct ring_buf *rb)
{
        return rb->size;
}

static inline uint32_t ring_buf_size_get(const struct ring_buf *rb)
{
        ring_buf_idx_t write_idx = rb_load_acquire(&rb->write_idx);
        ring_buf_idx_t read_idx = rb_load_acquire(&rb->read_idx);
        ring_buf_size_t occ = write_idx - read_idx;
 
        if (write_idx < read_idx) {
                occ += 2U * rb->size;
        }
        return occ;
}

static inline uint32_t ring_buf_space_get(const struct ring_buf *rb)
{
        return ring_buf_capacity_get(rb) - ring_buf_size_get(rb);
}

static inline bool ring_buf_is_empty(const struct ring_buf *rb)
{
        ring_buf_idx_t write_idx = rb_load_acquire(&rb->write_idx);
        ring_buf_idx_t read_idx = rb_load_acquire(&rb->read_idx);
 
        return write_idx == read_idx;
}

static inline bool ring_buf_is_full(const struct ring_buf *rb)
{
        return ring_buf_size_get(rb) == ring_buf_capacity_get(rb);
}

static inline void ring_buf_reset(struct ring_buf *rb)
{
        rb_store_relaxed(&rb->read_idx, 0);
        rb_store_relaxed(&rb->write_idx, 0);
#ifdef CONFIG_RING_BUFFER
        rb->put_claimed = 0;
        rb->get_claimed = 0;
#endif /* CONFIG_RING_BUFFER */
}

static inline void ring_buf_init(struct ring_buf *rb, uint32_t size, uint8_t *data)
{
        __ASSERT(size <= RING_BUFFER_MAX_SIZE, RING_BUFFER_SIZE_ASSERT_MSG);
 
        rb->size = (ring_buf_size_t)size;
        rb->buffer = data;
        ring_buf_reset(rb);
}

static inline uint32_t ring_buf_put_ptr(struct ring_buf *rb, uint8_t **data, size_t offset)
{
        ring_buf_idx_t write_idx = rb_load_relaxed(&rb->write_idx);
        ring_buf_idx_t read_idx = rb_load_acquire(&rb->read_idx);
        ring_buf_idx_t off, avail;
 
        __ASSERT_NO_MSG(offset <= ring_buf_space_get(rb));
        if (offset > 0) {
                write_idx = rb_idx_advance((size_t)write_idx + offset, rb->size);
        }
 
        if (write_idx >= rb->size) {
                off = write_idx - rb->size;
                avail = (read_idx >= rb->size ? rb->size : read_idx) - off;
        } else {
                off = write_idx;
                avail = (read_idx >= rb->size ? read_idx - rb->size : rb->size) - off;
        }
        *data = &rb->buffer[off];
        return avail;
}

static inline void ring_buf_commit(struct ring_buf *rb, size_t size)
{
        size_t write_idx = rb_load_relaxed(&rb->write_idx);
 
        __ASSERT_NO_MSG(size <= ring_buf_space_get(rb));
        rb_store_release(&rb->write_idx, rb_idx_advance(write_idx + size, rb->size));
}

static inline uint32_t ring_buf_get_ptr(struct ring_buf *rb, uint8_t **data, size_t offset)
{
        ring_buf_idx_t read_idx = rb_load_relaxed(&rb->read_idx);
        ring_buf_idx_t write_idx = rb_load_acquire(&rb->write_idx);
        ring_buf_idx_t off, avail;
 
        __ASSERT_NO_MSG(offset <= ring_buf_size_get(rb));
        if (offset > 0) {
                read_idx = rb_idx_advance((size_t)read_idx + offset, rb->size);
        }
 
        if (read_idx >= rb->size) {
                off = read_idx - rb->size;
                avail = (write_idx >= rb->size ? write_idx : 2U * rb->size) - read_idx;
        } else {
                off = read_idx;
                avail = (write_idx >= rb->size ? rb->size : write_idx) - read_idx;
        }
        *data = &rb->buffer[off];
        return avail;
}

static inline void ring_buf_consume(struct ring_buf *rb, size_t size)
{
        size_t read_idx = rb_load_relaxed(&rb->read_idx);
 
        __ASSERT_NO_MSG(size <= ring_buf_size_get(rb));
        rb_store_release(&rb->read_idx, rb_idx_advance(read_idx + size, rb->size));
}

static inline uint32_t ring_buf_put(struct ring_buf *rb, const uint8_t *data, uint32_t size)
{
        uint8_t *dst;
        uint32_t total = 0;
        uint32_t chunk;
        uint32_t avail;
 
        do {
                avail = ring_buf_put_ptr(rb, &dst, total);
                chunk = MIN(avail, size - total);
                if (chunk == 0U) {
                        break;
                }
                memcpy(dst, &data[total], chunk);
                total += chunk;
        } while (total < size);
        ring_buf_commit(rb, total);
 
        return total;
}

static inline uint32_t ring_buf_get(struct ring_buf *rb, uint8_t *data, uint32_t size)
{
        uint8_t *src;
        uint32_t chunk;
        uint32_t avail;
        uint32_t total = 0;
 
        do {
                avail = ring_buf_get_ptr(rb, &src, total);
                chunk = MIN(avail, size - total);
                if (chunk == 0U) {
                        break;
                }
                if (!IS_ENABLED(CONFIG_RING_BUFFER) || data != NULL) {
                        memcpy(&data[total], src, chunk);
                }
                total += chunk;
        } while (total < size);
        ring_buf_consume(rb, total);
 
        return total;
}

static inline uint32_t ring_buf_peek(const struct ring_buf *rb, uint8_t *data, uint32_t size)
{
        uint8_t *src;
        uint32_t chunk;
        uint32_t avail;
        uint32_t total = 0;
 
        do {
                avail = ring_buf_get_ptr((struct ring_buf *)rb, &src, total);
                chunk = MIN(avail, size - total);
                if (chunk == 0U) {
                        break;
                }
                memcpy(&data[total], src, chunk);
                total += chunk;
        } while (total < size);
 
        return total;
}
 
#ifdef CONFIG_RING_BUFFER

#define RING_BUF_ITEM_DECLARE(name, size32)                                             \
        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 = RING_BUF_INIT((uint8_t *)_ring_buffer_data_##name, 4 * (size32))

#define RING_BUF_ITEM_DECLARE_SIZE(name, size32) \
        RING_BUF_ITEM_DECLARE(name, (size32))

#define RING_BUF_ITEM_DECLARE_POW2(name, pow) \
        RING_BUF_ITEM_DECLARE(name, BIT(pow))

#define RING_BUF_ITEM_SIZEOF(expr) DIV_ROUND_UP(sizeof(expr), sizeof(uint32_t))

__deprecated /* use #include <zephyr/sys/ringq.h> instead */
static inline void ring_buf_item_init(struct ring_buf *rb, uint32_t size, uint32_t *data)
{
        __ASSERT(size <= RING_BUFFER_MAX_SIZE / 4, RING_BUFFER_SIZE_ASSERT_MSG);
        ring_buf_init(rb, 4 * size, (uint8_t *)data);
}

__deprecated /* use #include <zephyr/sys/ringq.h> instead */
static inline uint32_t ring_buf_item_space_get(const struct ring_buf *rb)
{
        return ring_buf_space_get(rb) / 4;
}

__deprecated /* use ring_buf_put_ptr(...) & ring_buf_commit(...) instead */
static inline uint32_t ring_buf_put_claim(struct ring_buf *rb, uint8_t **data, uint32_t size)
{
        uint32_t claimed = MIN(ring_buf_put_ptr(rb, data, rb->put_claimed), size);
 
        rb->put_claimed += claimed;
        return claimed;
}

__deprecated /* use ring_buf_put_ptr(...) & ring_buf_commit(...) instead */
static inline int ring_buf_put_finish(struct ring_buf *rb, uint32_t size)
{
        if (rb->put_claimed < size) {
                return -EINVAL;
        }
        ring_buf_commit(rb, size);
        rb->put_claimed = 0;
        return 0;
}
 

__deprecated /* use ring_buf_get_ptr(...) & ring_buf_consume(...) instead */
static inline uint32_t ring_buf_get_claim(struct ring_buf *rb, uint8_t **data, uint32_t size)
{
        uint32_t claimed = MIN(ring_buf_get_ptr(rb, data, rb->get_claimed), size);
 
        rb->get_claimed += claimed;
        return claimed;
}

__deprecated /* use ring_buf_get_ptr(...) & ring_buf_consume(...) instead */
static inline int ring_buf_get_finish(struct ring_buf *rb, uint32_t size)
{
        if (rb->get_claimed < size) {
                return -EINVAL;
        }
 
        ring_buf_consume(rb, size);
        rb->get_claimed = 0;
        return 0;
}

struct ring_element {
        uint32_t type   : 16;
        uint32_t length : 8;
        uint32_t value  : 8;
};

static inline void z_rb_write_no_commit(struct ring_buf *rb, const uint8_t *data,
                                        uint32_t size, uint32_t offset)
{
        uint32_t avail;
        uint32_t chunk;
        uint8_t *dst;
        uint32_t off = 0;
 
        while (off < size) {
                avail = ring_buf_put_ptr(rb, &dst, offset + off);
                chunk = MIN(avail, size - off);
 
                memcpy(dst, &data[off], chunk);
                off += chunk;
        }
}


__deprecated /* use #include <zephyr/sys/ringq.h> instead */
static inline int ring_buf_item_put(struct ring_buf *buf, uint16_t type, uint8_t value,
                                        uint32_t *data, uint8_t size32)
{
        struct ring_element header;
        uint32_t size = size32 * 4;
 
        if (size + sizeof(header) > ring_buf_space_get(buf)) {
                return -EMSGSIZE;
        }
 
        header.type = type;
        header.length = size32;
        header.value = value;
        z_rb_write_no_commit(buf, (const uint8_t *)&header, sizeof(header), 0);
        z_rb_write_no_commit(buf, (const uint8_t *)data, size, sizeof(header));
        ring_buf_commit(buf, sizeof(header) + size);
        return 0;
}

__deprecated /* use #include <zephyr/sys/ringq.h> instead */
static inline int ring_buf_item_get(struct ring_buf *buf, uint16_t *type, uint8_t *value,
                                        uint32_t *data, uint8_t *size32)
{
        struct ring_element header;
 
        if (ring_buf_is_empty(buf)) {
                return -EAGAIN;
        }
 
        ring_buf_peek(buf, (uint8_t *)&header, sizeof(header));
        if (data != NULL && (header.length > *size32)) {
                *size32 = header.length;
                return -EMSGSIZE;
        }
 
        *size32 = header.length;
        *type = header.type;
        *value = header.value;
 
        ring_buf_consume(buf, sizeof(header));
        ring_buf_get(buf, (uint8_t *)data, header.length * 4);
        return 0;
}


static inline void ring_buf_internal_reset(struct ring_buf *rb, ring_buf_idx_t value)
{
        ring_buf_size_t lim = 2U * rb->size;
 
        value = (lim != 0U) ? (ring_buf_idx_t)(value % lim) : 0U;
        rb_store_relaxed(&rb->read_idx, value);
        rb_store_relaxed(&rb->write_idx, value);
        rb->put_claimed = 0;
        rb->get_claimed = 0;
}

 
#else /* CONFIG_RING_BUFFER */

#define Z_RING_BUF_CLAIM_REMOVED(name)                                          \
        ({                                                                      \
                BUILD_ASSERT(0, #name "() is deprecated and not available "     \
                        "when CONFIG_RING_BUFFER=n. Enable "                    \
                        "CONFIG_RING_BUFFER to keep it during the "             \
                        "deprecation period, or migrate as described in the "   \
                        "Zephyr 4.5 migration guide.");                         \
                0;                                                              \
        })
 
#define Z_RING_BUF_DECLARE_REMOVED(name)                                        \
        BUILD_ASSERT(0, #name " is deprecated and not available when "          \
                "CONFIG_RING_BUFFER=n. Enable CONFIG_RING_BUFFER "              \
                "to keep it during the deprecation period, or migrate as "      \
                "described in the Zephyr 4.5 migration guide.")
 
#define ring_buf_put_claim(...)         Z_RING_BUF_CLAIM_REMOVED(ring_buf_put_claim)
#define ring_buf_put_finish(...)        Z_RING_BUF_CLAIM_REMOVED(ring_buf_put_finish)
#define ring_buf_get_claim(...)         Z_RING_BUF_CLAIM_REMOVED(ring_buf_get_claim)
#define ring_buf_get_finish(...)        Z_RING_BUF_CLAIM_REMOVED(ring_buf_get_finish)
#define ring_buf_item_init(...)         Z_RING_BUF_CLAIM_REMOVED(ring_buf_item_init)
#define ring_buf_item_put(...)          Z_RING_BUF_CLAIM_REMOVED(ring_buf_item_put)
#define ring_buf_item_get(...)          Z_RING_BUF_CLAIM_REMOVED(ring_buf_item_get)
#define ring_buf_item_space_get(...)    Z_RING_BUF_CLAIM_REMOVED(ring_buf_item_space_get)
#define ring_buf_internal_reset(...)    Z_RING_BUF_CLAIM_REMOVED(ring_buf_internal_reset)
 
#define RING_BUF_ITEM_DECLARE(...)      Z_RING_BUF_DECLARE_REMOVED(RING_BUF_ITEM_DECLARE)
#define RING_BUF_ITEM_DECLARE_SIZE(...) Z_RING_BUF_DECLARE_REMOVED(RING_BUF_ITEM_DECLARE_SIZE)
#define RING_BUF_ITEM_DECLARE_POW2(...) Z_RING_BUF_DECLARE_REMOVED(RING_BUF_ITEM_DECLARE_POW2)
#endif /* CONFIG_RING_BUFFER */

 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SYS_RING_BUFFER_H_ */