FreeRTOS 中文参考手册 /8 流缓冲区 API

第 8 章 · 原书 353–376 页 · 13 个函数流缓冲区 API

Chapter 8 · Stream Buffer API

流缓冲区(stream buffer)是 FreeRTOS 提供的一种字节流容器,可以理解为“变长的环形缓冲”:写入方按字节往里塞,读取方按字节往外取,不要求“一条消息一个长度”,因此非常适合“一边产、一边消”的场景,例如串口接收数据交给解析任务,或中断以不固定长度写入、任务批量读出。

它和队列的关键差异:

对比项队列 Queue流缓冲区 Stream Buffer
数据单位定长元素,逐个拷贝字节流,可一次写多个、一次读多个
长度每个元素长度在创建时固定写入/读取长度任意,只要不超过容量
并发多任务可同时发送、同时接收仅支持单写者、单读者(一写一读)
阻塞条件队列满/空达到触发级别(trigger level)才算“有数据可读”

触发级别(trigger level)是流缓冲区的核心概念:读取方在 xStreamBufferReceive() 里阻塞时,只有当缓冲区中的数据量达到或超过触发级别,才会被唤醒;但如果读取方已经在等待,那么即使后续写入的量没到触发级别,也会被唤醒(避免“永远等不到”)。默认触发级别等于创建时传入的值)。

流缓冲区不是线程安全的“多生产者”容器。多个任务或中断同时写同一个流缓冲区会破坏内部状态。要“多写一读”,需要用临界区/互斥量在外层保护,或改用队列。

消息缓冲区(第 9 章)是流缓冲区的上层封装:它给每段数据加一个长度前缀,从而能按“消息”边界读取,而流缓冲区只能按字节数读取。

8.1xStreamBufferBytesAvailable()

流缓冲区 · 查询 stream_buffer.h
size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer );

参数

参数方向说明
xStreamBufferin流缓冲区句柄。

返回值

当前缓冲区中可读取的字节数。

说明

查询流缓冲区里现有的字节数量,用于判断“现在读一次能读到多少”,或做水位监控。

注意

8.2xStreamBufferCreate()

流缓冲区 · 创建 stream_buffer.h
StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes,
                                           size_t xTriggerLevelBytes );

参数

参数方向说明
xBufferSizeBytesin缓冲区总字节数(内部会额外占用少量控制结构)。
xTriggerLevelBytesin触发级别:数据量达到该值才唤醒阻塞的读取方。传 0 表示自动取 1。

返回值

创建成功返回句柄;堆内存不足返回 NULL。

说明

动态创建流缓冲区。写入方用 xStreamBufferSend() 写入,读取方用 xStreamBufferReceive() 读取。

触发级别的意义:让读取方“攒够一批再处理”,避免频繁被单个字节唤醒导致切换开销过大。

注意

典型用法

/* 256 字节缓冲,攒够 32 字节再唤醒读取任务 */
StreamBufferHandle_t xStream = xStreamBufferCreate( 256, 32 );

8.3xStreamBufferCreateStatic()

流缓冲区 · 创建 stream_buffer.h
StreamBufferHandle_t xStreamBufferCreateStatic( size_t xBufferSizeBytes,
                                                 size_t xTriggerLevelBytes,
                                                 uint8_t *pucStreamBufferStorageArea,
                                                 StaticStreamBuffer_t *pxStaticStreamBuffer );

参数

参数方向说明
xBufferSizeBytesin缓冲区字节数,必须与 pucStreamBufferStorageArea 的实际大小匹配。
xTriggerLevelBytesin触发级别。
pucStreamBufferStorageAreain应用提供的字节数组,作为缓冲区存储区。
pxStaticStreamBufferin应用提供的 StaticStreamBuffer_t 结构,作为控制块。

返回值

创建成功返回句柄;任一指针为 NULL 或参数非法时返回 NULL。

说明

静态创建流缓冲区,存储区与控制块都由应用提供,不依赖 FreeRTOS 堆。

注意

8.4vStreamBufferDelete()

流缓冲区 stream_buffer.h
void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer );

参数

参数方向说明
xStreamBufferin要删除的流缓冲区句柄。

说明

删除流缓冲区并释放内存(静态创建的只复位状态,不释放外部内存)。正阻塞在 Send/Receive 上的任务会被解除阻塞。

注意

8.5xStreamBufferIsEmpty()

流缓冲区 · 查询 stream_buffer.h
BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer );

参数

参数方向说明
xStreamBufferin流缓冲区句柄。

返回值

pdTRUE 表示没有可读数据;pdFALSE 表示还有数据。

说明

判断缓冲区是否为空。

注意

8.6xStreamBufferIsFull()

流缓冲区 · 查询 stream_buffer.h
BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer );

参数

参数方向说明
xStreamBufferin流缓冲区句柄。

返回值

pdTRUE 表示缓冲区已满;pdFALSE 表示还能写入。

说明

判断缓冲区是否已满(没有剩余空间)。

注意

8.7xStreamBufferReceive()

流缓冲区 · 读取 stream_buffer.h
size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
                              void *pvRxData,
                              size_t xBufferLengthBytes,
                              TickType_t xTicksToWait );

参数

参数方向说明
xStreamBufferin流缓冲区句柄。
pvRxDataout接收数据的目标缓冲区。
xBufferLengthBytesin本次最多接收的字节数(一般等于目标缓冲区大小)。
xTicksToWaitin无满足触发级别数据时的最长阻塞节拍数。0 表示立即返回;portMAX_DELAY 表示无限等待。

返回值

实际读取到的字节数;0 表示没有数据(超时或缓冲区空)。

说明

从流缓冲区读取数据。读到的是从最旧字节开始的一段连续字节,长度最多 xBufferLengthBytes——不必一次读空,因此读取方必须用返回值判断本次读了多少。

阻塞语义:若当前数据量未达触发级别,则阻塞等待;一旦被唤醒,就读取当前可用的字节(可能多于、也可能等于触发级别)。

注意

典型用法

uint8_t ucBuf[64];
size_t xRead;

xRead = xStreamBufferReceive( xStream, ucBuf, sizeof( ucBuf ), portMAX_DELAY );
if( xRead > 0 )
{
    /* 只有前 xRead 个字节有效 */
}

8.8xStreamBufferReceiveFromISR()

流缓冲区 · 中断 stream_buffer.h
size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
                                     void *pvRxData,
                                     size_t xBufferLengthBytes,
                                     BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xStreamBufferin流缓冲区句柄。
pvRxDataout接收数据的目标缓冲区。
xBufferLengthBytesin本次最多接收的字节数。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;若读取动作使更高优先级的写入任务解除阻塞,则被置为 pdTRUE。

返回值

实际读取到的字节数。

说明

中断里从流缓冲区读取。实际工程中很少这样用(中断通常作为写入方),主要用于特殊的数据回灌场景。

注意

8.9xStreamBufferReset()

流缓冲区 stream_buffer.h
BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer );

参数

参数方向说明
xStreamBufferin要复位的流缓冲区句柄。

返回值

pdPASS 表示复位成功;pdFAIL 表示有任务正阻塞在该缓冲区上,复位被拒绝。

说明

清空缓冲区(丢弃所有未读数据),恢复到初始的“空”状态,但不释放内存。

用于协议出错后的重同步:发现帧校验失败,直接 Reset 丢弃脏数据,重新收帧。

注意

8.10xStreamBufferSend()

流缓冲区 · 写入 stream_buffer.h
size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
                           const void *pvTxData,
                           size_t xDataLengthBytes,
                           TickType_t xTicksToWait );

参数

参数方向说明
xStreamBufferin流缓冲区句柄。
pvTxDatain要写入的数据起始地址。
xDataLengthBytesin要写入的字节数。
xTicksToWaitin空间不足时的最长阻塞节拍数。0 表示不等待;portMAX_DELAY 表示无限等待。

返回值

实际写入的字节数;0 表示一字节也没写进去(空间不足且超时)。

说明

向流缓冲区写入数据。若剩余空间不足,按 xTicksToWait 等待;被唤醒后尽可能写入,但可能只写入一部分——返回值告诉实际成功了多少。

典型用法:中断里以不固定长度写入串口收到的字节,任务侧按批读出解析。

注意

典型用法

size_t xWritten;
xWritten = xStreamBufferSend( xStream, pucFrame, uxFrameLen, pdMS_TO_TICKS( 10 ) );
if( xWritten != uxFrameLen )
{
    /* 未写全:丢弃该帧或重试 */
}

8.11xStreamBufferSendFromISR()

流缓冲区 · 中断 stream_buffer.h
size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
                                   const void *pvTxData,
                                   size_t xDataLengthBytes,
                                   BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xStreamBufferin流缓冲区句柄。
pvTxDatain要写入的数据起始地址。
xDataLengthBytesin要写入的字节数。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;若写入使更高优先级的读取任务解除阻塞,则被置为 pdTRUE。

返回值

实际写入的字节数;空间不足时可能小于请求长度,甚至为 0。

说明

中断里向流缓冲区写入,这是流缓冲区最主要的落地场景:ISR 收数据,任务做解析。

注意

8.12xStreamBufferSetTriggerLevel()

流缓冲区 stream_buffer.h
BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel );

参数

参数方向说明
xStreamBufferin流缓冲区句柄。
xTriggerLevelin新的触发级别(字节数)。传 0 表示取 1。

返回值

pdPASS 表示设置成功;pdFAIL 表示触发级别超过缓冲区容量。

说明

运行期修改触发级别。例如协议切换后,一帧最小长度变化,需要对应调整批处理阈值。

注意

8.13xStreamBufferSpacesAvailable()

流缓冲区 · 查询 stream_buffer.h
size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer );

参数

参数方向说明
xStreamBufferin流缓冲区句柄。

返回值

当前还可写入的字节数。

说明

查询剩余空间。写入方在“必须整块写入”的场景下,先查空间再写,可避免部分写入破坏数据。

注意