xMessageBufferCreateStatic / xMessageBufferCreateStaticWithCallback
[RTOS 消息缓冲区 API]
message_buffer.h
MessageBufferHandle_t xMessageBufferCreateStatic(
size_t xBufferSizeBytes,
uint8_t *pucMessageBufferStorageArea,
StaticMessageBuffer_t *pxStaticMessageBuffer );
MessageBufferHandle_t xMessageBufferCreateStaticWithCallback(
size_t xBufferSizeBytes,
uint8_t *pucMessageBufferStorageArea,
StaticMessageBuffer_t *pxStaticMessageBuffer,
StreamBufferCallbackFunction_t pxSendCompletedCallback,
StreamBufferCallbackFunction_t pxReceiveCompletedCallback );
使用静态分配的内存创建新的消息缓冲区。消息缓冲区
在完成每个发送和接收操作时执行回调。使用 xMessageBufferCreateStatic()API
创建的消息缓冲区共享相同的发送和接收完成回调函数,这些函数是用 sbSEND_COMPLETED() 和 sbRECEIVE_COMPLETED() 宏定义的。
使用 xMessageBufferCreateStaticWithCallback() API 创建的消息缓冲区可以有各自独特的发送和接收完成
回调函数。请参阅 xMessageBufferCreate() and xMessageBufferCreateWithCallback()
了解使用动态分配内存的对应版本。
configSUPPORT_STATIC_ALLOCATION 必须在 FreeRTOSConfig.h 中设置为 1,
才能使用 xMessageBufferCreateStatic()。此外,configUSE_SB_COMPLETED_CALLBACK 必须在 FreeRTOSConfig.h 中设置为 1,
xMessageBufferCreateStaticWithCallback() 才可用。
将 FreeRTOS/source/stream_buffer.c 源文件包含在构建中即可启用消息缓冲区功能
(因为消息缓冲区使用流缓冲区)。
参数:
-
xBufferSizeBytes
- pucMessageBufferStorageArea 参数所指向的缓冲区的大小(单位:字节)。当消息写入消息缓冲区时,
同时也会写入额外的 sizeof(size_t)字节以存储消息的长度。
sizeof( size_t ) 在 32 位架构上的大小通常是 4 个字节,因此在大多数 32 位架构中,10 字节的消息将占用 14 字节的
消息缓冲区空间。可以存储在消息缓冲区的最大字节数实际上是 (xBufferSizeBytes - 1)。
pucMessageBufferStorageArea
- 必须指向一个大小至少为 xBufferSizeBytes + 1 的 uint8_t 数组。将消息写入消息缓冲区时,
实际上是将消息复制到这个数组。
pxStaticMessageBuffer
- 必须指向一个 StaticMessageBuffer_t 类型的变量,它将用于保存消息缓冲区的数据结构体。
pxSendCompletedCallback
- 当一条消息被写入消息缓冲区时调用的回调函数。如果参数为 NULL,则使用 sbSEND_COMPLETED 宏所提供的默认实现。发送完成回调函数必须具有 StreamBufferCallbackFunction_t 定义的原型,即:
void vSendCallbackFunction( MessageBufferHandle_t xMessageBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken );
pxReceiveCompletedCallback
- 当从消息缓冲区读取消息时 调用的回调函数。如果参数为 NULL,则使用 sbRECEIVE_COMPLETED 宏所提供的默认实现。接收完成回调函数必须具有 StreamBufferCallbackFunction_t 定义的原型,即:
void vReceiveCallbackFunction( MessageBufferHandle_t xMessageBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken );
返回:
如果成功创建了消息缓冲区,那么将返回一个所创建消息缓冲区的句柄。如果
pucMessageBufferStorageArea 或 pxStaticMessageBuffer 为 NULL,则返回 NULL。
用法示例:
#define STORAGE_SIZE_BYTES 1000
static uint8_t ucMessageBufferStorage[ STORAGE_SIZE_BYTES ];
static uint8_t ucMessageBufferWithCallbackStorage[ STORAGE_SIZE_BYTES ];
[/code-comment]/* The variable used to hold the message buffer structure. */[/code-comment]
StaticMessageBuffer_t xMessageBufferStruct;
StaticMessageBuffer_t xMessageBufferWithCallbackStruct;
void vSendCallbackFunction( MessageBufferHandle_t xMessageBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken )
{
}
void vReceiveCallbackFunction( MessageBufferHandle_t xMessageBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken )
{
}
void MyFunction( void )
{
MessageBufferHandle_t xMessageBuffer, xMessageBufferWithCallback;
xMessageBuffer = xMessageBufferCreateStatic( sizeof( ucMessageBufferStorage ),
ucMessageBufferStorage,
&xMessageBufferStruct );
xMessageBufferWithCallback = xMessageBufferCreateStaticWithCallback(
sizeof( ucMessageBufferWithCallbackStorage ),
ucMessageBufferWithCallbackStorage,
&xMessageBufferWithCallbackStruct,
vSendCallbackFunction,
vReceiveCallbackFunction );
}
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.