STM32 模块化开发指南 · 第 3 篇 环形缓冲区 RingBuffer 模块设计与单元测试

本文是《STM32 模块化开发实战指南》第 3 篇，聚焦于“如何设计一个高性能、稳定、安全的环形缓冲区模块”。我们将从基本结构讲起，逐步完成接口定义、边界处理、API 实现与单元测试，最终实现一个可移植、线程安全、可嵌入 UART/BLE/协议模块的通用 RingBuffer。

---

一、RingBuffer 是什么？在嵌入式中为什么重要？

RingBuffer（环形缓冲区）是一种先进先出（FIFO）的内存管理结构，常用于：

• 串口接收缓存

• 数据流中断缓冲

• BLE 广播帧缓存

• 串口透传数据中转

• 中断 → 主循环 数据通道

它的优势在于：

• 零拷贝访问：不需要频繁移动数据

• 高性能：通过索引运算快速定位读写位置

• 适配中断场景：写入/读取操作互不干扰

• 可做线程安全封装：读写在不同上下文中协作

---

二、RingBuffer 模块设计目标

• ✅ 固定内存池 + 索引管理，避免动态分配

• ✅ 支持写入、读取、状态查询、清空等操作

• ✅ 边界条件清晰：满/空状态判断严谨

• ✅ 不依赖任何外部库，可脱离操作系统独立运行

• ✅ 可复用：不同模块均可引用

---

三、接口定义（ring_buffer.h）

#ifndef RING_BUFFER_H
#define RING_BUFFER_H

#include <stdint.h>
#include <stddef.h>

typedef struct {
    uint8_t *buf;
    uint16_t size;
    uint16_t head;
    uint16_t tail;
} ring_buf_t;

void ringbuf_init(ring_buf_t *rb, uint8_t *data, uint16_t size);
int  ringbuf_put(ring_buf_t *rb, uint8_t byte);
int  ringbuf_get(ring_buf_t *rb, uint8_t *byte);
int  ringbuf_is_empty(const ring_buf_t *rb);
int  ringbuf_is_full(const ring_b