xMessageBufferCreate / xMessageBufferCreateWithCallback
[RTOS 消息缓冲区 API]

message_buffer.h

MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes );

MessageBufferHandle_t xMessageBufferCreateWithCallback( 
                          size_t xBufferSizeBytes,
                          StreamBufferCallbackFunction_t pxSendCompletedCallback,
                          StreamBufferCallbackFunction_t pxReceiveCompletedCallback );

使用动态分配的内存新建消息缓冲区。消息缓冲区会在每次发送和接收操作完成后执行回调。使用 xMessageBufferCreate() API 创建的消息缓冲区共享相同的发送和接收完成回调函数，这些回调函数通过 sbSEND_COMPLETED() 和 sbRECEIVE_COMPLETED() 宏定义。使用 xMessageBufferCreateWithCallback() API 创建的消息缓冲区可以有自己唯一的发送和接收完成回调函数。请参阅 xMessageBufferCreateStatic() and xMessageBufferCreateStaticWithCallback() 获取使用静态分配内存（在编译时分配的内存）的相应版本。

configSUPPORT_DYNAMIC_ALLOCATION 必须在 FreeRTOSConfig.h 中设置为 1 或未定义，xMessageBufferCreate() 才可用。此外，configUSE_SB_COMPLETED_CALLBACK 必须在 FreeRTOSConfig.h 中设置为 1，xMessageBufferCreateWithCallback() 才可用。

将 FreeRTOS/source/stream_buffer.c 源文件包含在构建中即可启用消息缓冲区功能（因为消息缓冲区使用流缓冲区）。

参数：

xBufferSizeBytes

消息缓冲区在任何时候能够容纳的字节（而非消息）总数。当消息写入消息缓冲区时，同时也会写入额外的 sizeof( size_t ) 字节以存储消息的长度。 sizeof( size_t ) 在 32 位架构上的大小通常是 4 个字节，因此在大多数 32 位架构中，10 字节的消息将占用 14 字节的消息缓冲区空间。

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 );

返回：

如果返回 NULL，则说明因为没有足够的堆内存可供 FreeRTOS 分配消息缓冲区的数据结构体和存储区域，所以无法创建消息缓冲区。如果返回非 NULL 值，则表示消息缓冲区已成功创建，返回值应该作为所创建消息缓冲区的句柄来存储。

用法示例：



void vSendCallbackFunction( MessageBufferHandle_t xMessageBuffer,

                            BaseType_t xIsInsideISR,

                            BaseType_t * const pxHigherPriorityTaskWoken )

{

    /* Insert code here which is invoked when a message is written to


     * the message buffer.


     * This is useful when a message buffer is used to pass messages between


     * cores on a multicore processor. In that scenario, this callback


     * can be implemented to generate an interrupt in the other CPU core,


     * and the interrupt's service routine can then use the


     * xMessageBufferSendCompletedFromISR() API function to check, and if


     * necessary unblock, a task that was waiting for message. */

}



void vReceiveCallbackFunction( MessageBufferHandle_t xMessageBuffer,

                               BaseType_t xIsInsideISR,

                               BaseType_t * const pxHigherPriorityTaskWoken )

{

    /* Insert code here which is invoked when a message is read from a message


     * buffer.


     * This is useful when a message buffer is used to pass messages between


     * cores on a multicore processor. In that scenario, this callback


     * can be implemented to generate an interrupt in the other CPU core,


     * and the interrupt's service routine can then use the


     * xMessageBufferReceiveCompletedFromISR() API function to check, and if


     * necessary unblock, a task that was waiting to send message. */

}



void vAFunction( void )

{

MessageBufferHandle_t xMessageBuffer, xMessageBufferWithCallback;

const size_t xMessageBufferSizeBytes = 100;



    /* Create a message buffer that can hold 100 bytes and uses the


     * functions defined using the sbSEND_COMPLETED() and


     * sbRECEIVE_COMPLETED() macros as send and receive completed


     * callback functions. The memory used to hold both the message


     * buffer structure and the data in the message buffer is


     * allocated dynamically. */

    xMessageBuffer = xMessageBufferCreate( xMessageBufferSizeBytes );

    

    if( xMessageBuffer == NULL )

    {

        /* There was not enough heap memory space available to create the


         * message buffer. */

    }

    else

    {

        /* The message buffer was created successfully and can now be used. */

    }

    

    /* Create a message buffer that can hold 100 bytes and uses the


     * functions vSendCallbackFunction and vReceiveCallbackFunction


     * as send and receive completed callback functions. The memory


     * used to hold both the message buffer structure and the data


     * in the message buffer is allocated dynamically. */

    xMessageBufferWithCallback = xMessageBufferCreateWithCallback( 

                                     xMessageBufferSizeBytes,

                                     vSendCallbackFunction,

                                     vReceiveCallbackFunction );

    if( xMessageBufferWithCallback == NULL )

    {

        /* There was not enough heap memory space available to create the


         * message buffer. */

    }

    else

    {

        /* The message buffer was created successfully and can now be used. */

    }

}

出色的 RTOS & 嵌入式软件 下载 FreeRTOS 菜单

xMessageBufferCreate / xMessageBufferCreateWithCallback [RTOS 消息缓冲区 API]

出色的 RTOS & 嵌入式软件

下载 FreeRTOS
菜单

xMessageBufferCreate / xMessageBufferCreateWithCallback
[RTOS 消息缓冲区 API]