xStreamBufferCreate/xStreamBufferCreateWithCallback
[RTOS 流缓冲区 API]
stream_buffer.h
StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes,
size_t xTriggerLevelBytes );
StreamBufferHandle_t xStreamBufferCreateWithCallback(
size_t xBufferSizeBytes,
size_t xTriggerLevelBytes
StreamBufferCallbackFunction_t pxSendCompletedCallback,
StreamBufferCallbackFunction_t pxReceiveCompletedCallback );
创建一个使用动态分配内存的新流缓冲区。流缓冲区
在完成每个发送和接收操作时执行回调。使用 xStreamBufferCreate()API 创建的流缓冲区
共享相同的发送和接收完成回调函数,这些函数是用 sbSEND_COMPLETED() 和 sbRECEIVE_COMPLETED() 宏定义的
。使用 xStreamBufferCreateWithCallback() API 创建的流缓冲区可以有各自独特的发送和接收完成
回调函数。请参阅 xStreamBufferCreateStatic() 和
xStreamBufferCreateStaticWithCallback() 了解使用动态分配内存(在编译时分配的内存)的对应版本
。
configSUPPORT_DYNAMIC_ALLOCATION 必须
在 FreeRTOSConfig.h 中设置为 1 或未定义, xStreamBufferCreate () 才可用。此外,configUSE_SB_COMPLETED_CALLBACK 必须在
FreeRTOSConfig.h 中设置为 1,xStreamBufferCreateWithCallback() 才可用。
将 FreeRTOS/source/stream_buffer.c 源文件包含在构建中即可启用流缓冲区功能。
参数:
-
xBufferSizeBytes
- 流缓冲区在任何时候能够容纳的总字节数。
xTriggerLevelBytes
- 在流缓冲区中被阻塞以等待数据的任务离开阻塞状态之前,
流缓冲区中必须包含的字节数。例如,如果一个任务在读取触发等级为 1 的空流缓冲区时被阻塞,
那么当单个字节写入缓冲区或该任务的阻塞时间结束时,该任务将被解除阻塞。
另一个例子是,如果一个任务在读取触发等级为 10 的空流缓冲区时被阻塞,
那么直到流缓冲区至少包含 10 个字节或该任务的阻塞时间结束之前,该任务将不会被解除阻塞。如果
读任务的阻塞时间在达到触发等级之前过期,那么该任务仍将接收实际可用的字节数
。将触发等级设置为 0 将导致使用触发等级 1。指定
一个大于缓冲区大小的触发等级是无效的。
pxSendCompletedCallback
- 当对流缓冲区的数据写入导致缓冲区的字节数超过触发等级时调用的回调函数
。如果参数为 NULL,则使用 sbSEND_COMPLETED 宏所提供的默认实现
。发送完成的回调函数必须具有 StreamBufferCallbackFunction_t 定义的原型,即:
void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken );
pxReceiveCompletedCallback
- 当从流缓冲区读取数据(多于 0 字节)时调用的回调函数。如果参数为 NULL,
则使用 sbRECEIVE_COMPLETED 宏所提供的默认实现。接收完成回调函数必须
具有 StreamBufferCallbackFunction_t 定义的原型,即:
void vReceiveCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken );
返回:
- 如果返回 NULL,则说明因为没有足够的堆内存可供 FreeRTOS
分配流缓冲区的数据结构体和存储区域,所以流缓冲区无法被创建。如果返回的值不是 NULL,则说明流缓冲区已经成功创建
——返回值应该作为所创建流缓冲区的句柄来存储。
用法示例:
-
void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken )
{
}
void vReceiveCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken )
{
}
void vAFunction( void )
{
StreamBufferHandle_t xStreamBuffer, xStreamBufferWithCallback;
const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes,
xTriggerLevel );
if( xStreamBuffer == NULL )
{
}
else
{
}
xStreamBufferWithCallback = xStreamBufferCreateWithCallback(
xStreamBufferSizeBytes,
xTriggerLevel,
vSendCallbackFunction,
vReceiveCallbackFunction );
if( xStreamBufferWithCallback == NULL )
{
}
else
{
}
}
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.