Zephys OS nano 内核篇：环形缓冲 Ring Buffer

Zephyr OS 所有的学习笔记已托管到 Github，CSDN 博客里的内容只是 Github 里内容的拷贝，因此链接会有错误，请谅解。

最新的学习笔记请移步 GitHub：https://github.com/tidyjiang8/zephyr-inside

与栈有点类似，环形缓冲的大小也是在初始化时就固定了。

• 环形缓冲的类型定义
• 环形缓冲的初始化
  
  • SYS_RING_BUF_DECLARE_POW2
  • SYS_RING_BUF_DECLARE_SIZE
  • sys_ring_buf_init
• define MY_RING_BUF_SIZE 64
• 添加数据
• 取出数据

环形缓冲的类型定义

struct ring_buf {    uint32_t head;   /**< Index in buf for the head element */    uint32_t tail;   /**< Index in buf for the tail element */    uint32_t dropped_put_count; /**< Running tally of the number of failed put attempts */    uint32_t size;   /**< Size of buf in 32-bit chunks */    uint32_t *buf;   /**< Memory region for stored entries */    uint32_t mask;   /**< Modulo mask if size is a power of 2 */#ifdef CONFIG_DEBUG_TRACING_KERNEL_OBJECTS    struct ring_buf *__next;#endif};

不考虑用于调试的 __next，环形buffer一个有6个成员：

• head：“指向”环形buffer中数据的头部。注意，head不是指针，而是一个下标索引。
• tail：“指向”环形buffer中数据的尾部的下一个地址。注意，tail也不是指针，是一个下标索引。
• dropped_put_count：记录向buffer中添加数据时由于buffer剩余空间不够而被丢弃的数据的次数。
• size：环形buffer的总容量。
• buf：指向环形buffer的起始地址。
• mask：当buffer的长度是2的整数次幂时，使用该成员进行“取模”运算，将buffer的下标索引表示在(0, size-1)范围内。

环形缓冲的初始化

nanokernel 提供了三种初始化环形buffer的方法，它们分别有各自的使用场景

SYS_RING_BUF_DECLARE_POW2

#define SYS_RING_BUF_DECLARE_POW2(name, pow) \    static uint32_t _ring_buffer_data_##name[1 << (pow)]; \    struct ring_buf name = { \        .size = (1 << (pow)), \        .mask = (1 << (pow)) - 1, \        .buf = _ring_buffer_data_##name \    };

当buffer的长度是2的整数次幂时，推荐使用该宏进行初始化。当使用该宏进行初始化后，再向该buffer中添加数据和取出数据时的效率比使用第二种方法的效率高。该宏做了两件事儿：

• 先定义了一个buffer，即环形缓冲实际用来存放数据的buffer。
• 定义了一个描述环形缓冲的结构体，并对其相关成员进行初始化。
  
  • size：初始化为
    2pow
    。
  • mask：初始化为二进制的0b111…111，即后面一共有pow个1。
  • buf：指向所分配的内存空间。
  • buffer中其它成员被初始化为 0。

使用该宏进行初始化时，所开辟的buffer的内存空间的长度是

4∗2pow

字节。

SYS_RING_BUF_DECLARE_SIZE

#define SYS_RING_BUF_DECLARE_SIZE(name, size32) \    static uint32_t _ring_buffer_data_##name[size32]; \    struct ring_buf name = { \        .size = size32, \        .buf = _ring_buffer_data_##name \    };

当buffer的长度不是2的整数次幂时，可以使用该宏进行初始化。使用该宏初始化后，再向该buffer中添加数据和取出数据时的效率比使用第一种方法的效率低。该宏做了两件事儿：

• 先定义了一个buffer，即环形缓冲实际用来存放数据的buffer。
• 定义了一个描述环形缓冲的结构体，并对其相关成员进行初始化。
  
  • size：初始化为size32。
  • buf：指向所分配的内存空间。
  • buffer中其它成员被初始化为 0。

使用该宏进行初始化时，所开辟的buffer的内存空间的长度是

4∗size32

。

sys_ring_buf_init

static inline void sys_ring_buf_init(struct ring_buf *buf, uint32_t size,                     uint32_t *data){    buf->head = 0;    buf->tail = 0;    buf->dropped_put_count = 0;    buf->size = size;    buf->buf = data;    // is_power_of_two()用于判断一个数是不是2的整数次幂，其实现非常    // 巧妙，有兴趣的可以研究研究    if (is_power_of_two(size)) {        buf->mask = size - 1;    } else {        buf->mask = 0;    }    SYS_TRACING_OBJ_INIT(sys_ring_buf, buf);}

该函数能判断buffer的大小是不是2的整数次幂，然后进行相应的初始化。使用该函数进行初始化的一般步骤为：

#define MY_RING_BUF_SIZE    64struct my_struct {    struct ring_buffer rb;    uint32_t buffer[MY_RING_BUF_SIZE];    ...};struct my_struct ms;void init_my_struct {    sys_ring_buf_init(&ms.rb, sizeof(ms.buffer), ms.buffer);    ...}

假设我们初始化了一个长度为16的buffer，那么其内存空间分布情况如图 1 所示。

图 1. 环形缓冲的内存空间存储情况

添加数据

int sys_ring_buf_put(struct ring_buf *buf, uint16_t type, uint8_t value,             uint32_t *data, uint8_t size32){    uint32_t i, space, index, rc;    // 先获取buffer中剩余空间的长度    space = sys_ring_buf_space_get(buf);    if (space >= (size32 + 1)) {        // 如果剩余空间足够存放数据，才将其存放到buffer中        // 这里判断剩余空间的长度是否大于 size32 + 1，是因为除了真实的数据外，        // 还有一个数据头(占一个整型的长度)，用于记录数据的 metadata。        struct ring_element *header =                (struct ring_element *)&buf->buf[buf->tail];        header->type = type;        header->length = size32;        header->value = value;        // 通过mask的值是否为0，判断buffer的长度是否是2的整数次幂，然后分开处理        if (likely(buf->mask)) {            //　如果是2的整数次幂            for (i = 0; i < size32; ++i) {                // 一个字节一个字节地将数据复制到buffer中                // 先通过与 mask 按位与取得index                index = (i + buf->tail + 1) & buf->mask;                // 再复制数据                buf->buf[index] = data[i];            }            //　将tail“指向”数据buffer中数据末尾的下一个地址处            buf->tail = (buf->tail + size32 + 1) & buf->mask;        } else {            // 如果不是2的整数次幂            for (i = 0; i < size32; ++i) {                // 一个字节一个字节地将数据复制到buffer中                // 先通过对 size 进行取模运算取得 index                index = (i + buf->tail + 1) % buf->size;                // 再复制数据                buf->buf[index] = data[i];            }            //　将tail“指向”数据buffer中数据末尾的下一个地址处            buf->tail = (buf->tail + size32 + 1) % buf->size;        }        rc = 0;    } else {        // 如果buffer的剩余空间不够存放数据，dropped_put_count 递增        buf->dropped_put_count++;        // 并返回错误码        rc = -EMSGSIZE;    }    return rc;} 

sys_ring_buf_space_get()用于获取buffer的剩余空间，其实现如下：

static inline int sys_ring_buf_space_get(struct ring_buf *buf){    if (sys_ring_buf_is_empty(buf)) {        // 当buffer为空，参考图1        return buf->size - 1;    }    // 当tail < head，参考图 2    if (buf->tail < buf->head) {        return buf->head - buf->tail - 1;    }    // 当 tail > head，参考图3    return (buf->size - buf->tail) + buf->head - 1;}

图 2. tail < head 的示意图

图 3. tail < head 的示意图

取出数据

int sys_ring_buf_get(struct ring_buf *buf, uint16_t *type, uint8_t *value,             uint32_t *data, uint8_t *size32){    struct ring_element *header;    uint32_t i, index;    if (sys_ring_buf_is_empty(buf)) {        // 如果 buffer 是空的，直接返回错误码        return -EAGAIN;    }    header = (struct ring_element *) &buf->buf[buf->head];    if (header->length > *size32) {        // 数据长度不匹配，将实际长度返回给调用者        *size32 = header->length;        // 然后返回错误码        return -EMSGSIZE;    }    *size32 = header->length;    *type = header->type;    *value = header->value;    if (likely(buf->mask)) {        // 如果 buffer 的长度是 2 的整数次幂        for (i = 0; i < header->length; ++i) {            // 通过与 mask 的按位与运算，取得 index            index = (i + buf->head + 1) & buf->mask;            // 然后复制数据到 data 中            data[i] = buf->buf[index];        }        // 重新调整头部 index        buf->head = (buf->head + header->length + 1) & buf->mask;    } else {        // 如果 buffer 的长度不是 2 的整数次幂        for (i = 0; i < header->length; ++i) {            // 通过与 buffer 的 size 进行取模运算，获取 index            index = (i + buf->head + 1) % buf->size;            // 然后复制数据到 data 中            data[i] = buf->buf[index];        }        // 重新调整头部 index        buf->head = (buf->head + header->length + 1) % buf->size;    }    return 0;}