嵌入式环形缓冲区设计:从Linux内核kfifo到实战避坑指南

// 传统取模运算（效率低）index = (index + 1) % buffer_size; // 位运算优化（效率高）index = (index + 1) & (buffer_size - 1);

/*********************************************************************************** * @brief    环形缓冲区管理器<ring_buf_t>(参考linux/kfifo)* @note     在单生产者/单消费者模式下使用不需要加锁，多生产者/多消费者模式下需要加锁*           避免数据丢失或数据损坏。************************************************************************************/typedef struct{    uint8_t *u8Buf_ptr;                  // 环形缓冲区    uint32_t u32Size;                    // 环形缓冲区大小    uint32_t u32Front;                   // 头指针    uint32_t u32Rear;                    // 尾指针}ring_buf_t;

boolbRingBuf_Init(ring_buf_t *r, uint8_t *buf, uint32_t len){    r->u8Buf_ptr=buf;    r->u32Size=len;    r->u32Front =r->u32Rear=0;        return buf!=NULL && (len&len-1) ==0;}

// 错误示例：忘记验证缓冲区大小boolinit_ring_buffer(ring_buf_t *r, uint8_t *buf, uint32_t len){    r->buffer = buf;    r->size = len;  // 如果len不是2的N次幂，后续位运算会出错！    return true;}

/** *@brief      将指定长度的数据放到环形缓冲区中  *@param[in]  r - 环形缓冲区管理器 *@param[in]  buf - 数据缓冲区 *@param[in]  len - 缓冲区长度  *@retval     实际放到中的数据  */uint32_tu32RingBuf_Write(ring_buf_t *r,uint8_t *buf,uint32_t len){    uint32_t i;    uint32_t left;    left = r->u32Size + r->u32Front  - r->u32Rear;                    // 缓冲区空闲空间    len  = MIN(len , left);                                           // 取实际可写入长度    i    = MIN(len, r->u32Size - (r->u32Rear & r->u32Size - 1));      // 计算从rear到缓冲区末尾的长度    memcpy(r->u8Buf_ptr + (r->u32Rear & r->u32Size - 1), buf, i);     // 分段写入数据(从rear到缓冲区末尾)    memcpy(r->u8Buf_ptr, buf + i, len - i);                           // 分段写入数据(从缓冲区开头继续写入剩余数据)    r->u32Rear += len;                                                // 更新rear指针    return len; }

/** *@brief      从环形缓冲区中读取指定长度的数据 *@param[in]  r - 环形缓冲区管理器 *@param[in]  buf - 数据缓冲区 *@param[in]  len - 缓冲区长度  *@retval     实际读取到的数据  */uint32_tu32RingBuf_Read(ring_buf_t *r,uint8_t *buf,uint32_t len){    uint32_t i;    uint32_t left;    left = r->u32Rear - r->u32Front;                                  // 缓冲区有效数据长度    len  = MIN(len , left);                                           // 取实际可读取长度    i    = MIN(len, r->u32Size - (r->u32Front & r->u32Size - 1));     // 计算从front到缓冲区末尾的长度    memcpy(buf, r->u8Buf_ptr + (r->u32Front & r->u32Size - 1), i);    // 分段读取数据(从front到缓冲区末尾)    memcpy(buf + i, r->u8Buf_ptr, len - i);                           // 分段读取数据(从缓冲区开头继续读取剩余数据)    r->u32Front += len;                                               // 更新front指针    return len; }

// 单生产者/单消费者模式示例voidproducer_thread(ring_buf_t *buffer){    while(1) {        uint8_t data[100];        // 生产数据        u32RingBuf_Write(buffer, data, sizeof(data));    }}voidconsumer_thread(ring_buf_t *buffer){    while(1) {        uint8_t data[100];        // 消费数据        u32RingBuf_Read(buffer, data, sizeof(data));    }}

// 多线程安全版本typedef struct {    ring_buf_t buffer;    pthread_mutex_t lock;  // 或其他锁机制} thread_safe_ring_buf_t;uint32_tthread_safe_write(thread_safe_ring_buf_t *ts_buf,                           uint8_t *data, uint32_t len) {    pthread_mutex_lock(&ts_buf->lock);    uint32_t written = u32RingBuf_Write(&ts_buf->buffer, data, len);    pthread_mutex_unlock(&ts_buf->lock);    return written;}

// 推荐的大小选择#define RING_BUF_SIZE_1K    1024    // 1KB#define RING_BUF_SIZE_2K    2048    // 2KB  #define RING_BUF_SIZE_4K    4096    // 4KB#define RING_BUF_SIZE_8K    8192    // 8KB

// 测试缓冲区大小（必须是2的N次幂）#define TEST_BUF_SIZE 32intmain(void){    uint8_t buffer[TEST_BUF_SIZE];    ring_buf_t ring;    uint8_t write_data[64];    uint8_t read_data[64];    uint32_t ret;    printf("========== 环形缓冲区测试程序 ==========\n\n");    // 1. 测试初始化    printf("[测试1] 初始化环形缓冲区...\n");    if (bRingBuf_Init(&ring, buffer, TEST_BUF_SIZE)) {        printf("        初始化成功！缓冲区大小: %u\n", TEST_BUF_SIZE);    } else {        printf("        初始化失败！\n");        return -1;    }    // 2. 测试基本写入和读取    printf("\n[测试2] 基本写入和读取测试...\n");    memset(write_data, 0xAA, 10);    ret = u32RingBuf_Write(&ring, write_data, 10);    printf("        写入 %u 字节数据 (期望: 10)\n", ret);    memset(read_data, 0, sizeof(read_data));    ret = u32RingBuf_Read(&ring, read_data, 10);    printf("        读取 %u 字节数据 (期望: 10)\n", ret);    if (memcmp(write_data, read_data, 10) == 0) {        printf("        数据验证: PASS\n");    } else {        printf("        数据验证: FAIL\n");    }    // 3. 测试环形绕回（数据跨越缓冲区边界）    printf("\n[测试3] 环形绕回测试...\n");    // 先填满大部分缓冲区    for (int i = 0; i < 28; i++) {        write_data[i] = i;    }    ret = u32RingBuf_Write(&ring, write_data, 28);    printf("        写入 %u 字节数据 (期望: 28)\n", ret);    // 再写入8字节，触发绕回    for (int i = 0; i < 8; i++) {        write_data[i] = 0x80 + i;    }    ret = u32RingBuf_Write(&ring, write_data, 8);    printf("        再次写入 %u 字节数据 (期望: 4，因为只剩4字节空闲)\n", ret);    // 读取所有数据    memset(read_data, 0, sizeof(read_data));    ret = u32RingBuf_Read(&ring, read_data, 32);    printf("        读取 %u 字节数据 (期望: 32)\n", ret);    // 验证数据完整性    int pass = 1;    for (int i = 0; i < 28; i++) {        if (read_data[i] != i) {            pass = 0;            break;        }    }    for (int i = 0; i < 4; i++) {        if (read_data[28 + i] != 0x80 + i) {            pass = 0;            break;        }    }    printf("        环形绕回验证: %s\n", pass ? "PASS" : "FAIL");    // 4. 测试清空功能    printf("\n[测试4] 清空缓冲区测试...\n");    u32RingBuf_Write(&ring, write_data, 10);    printf("        写入数据后长度: %u (期望: 10)\n", u32RingBuf_Len(&ring));    vRingBuf_Clear(&ring);    printf("        清空后长度: %u (期望: 0)\n", u32RingBuf_Len(&ring));    // 5. 测试空读取和满写入    printf("\n[测试5] 边界条件测试...\n");    // 空读取    memset(read_data, 0xFF, sizeof(read_data));    ret = u32RingBuf_Read(&ring, read_data, 5);    printf("        空缓冲区读取: %u 字节 (期望: 0)\n", ret);    // 满写入测试    for (int i = 0; i < 40; i++) {        write_data[i] = i;    }    ret = u32RingBuf_Write(&ring, write_data, 40);    printf("        写入40字节到32字节缓冲区: %u 字节 (期望: 32)\n", ret);    // 再次写入（已满）    ret = u32RingBuf_Write(&ring, write_data, 10);    printf("        缓冲区满时写入: %u 字节 (期望: 0)\n", ret);    printf("\n========== 测试完成 ==========\n");    return 0;}