Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Updated Jul 2025

xMessageBufferCreateStatic, xMessageBufferCreateStaticWithCallback

[RTOS Message Buffer API]

message_buffer.h

1MessageBufferHandle_t xMessageBufferCreateStatic(
2 size_t xBufferSizeBytes,
3 uint8_t *pucMessageBufferStorageArea,
4 StaticMessageBuffer_t *pxStaticMessageBuffer );
5
6MessageBufferHandle_t xMessageBufferCreateStaticWithCallback(
7 size_t xBufferSizeBytes,
8 uint8_t *pucMessageBufferStorageArea,
9 StaticMessageBuffer_t *pxStaticMessageBuffer,
10 StreamBufferCallbackFunction_t pxSendCompletedCallback,
11 StreamBufferCallbackFunction_t pxReceiveCompletedCallback );

Creates a new message buffer using statically allocated memory. Message buffers execute a callback upon completion of each send and receive operation. Message buffers created using xMessageBufferCreateStatic() API share the same send and receive completed callback functions, which are defined using the sbSEND_COMPLETED() and sbRECEIVE_COMPLETED() macros. Message buffers created using the xMessageBufferCreateStaticWithCallback() API can each have their own unique send and receive completed callback functions. See xMessageBufferCreate() and xMessageBufferCreateWithCallback() for corresponding versions that use dynamically allocated memory.

configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for xMessageBufferCreateStatic() to be available. Additionally, configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h for xMessageBufferCreateStaticWithCallback() to be available.

Message buffer functionality is enabled by including the FreeRTOS/source/stream_buffer.c source file in the build (as message buffers use stream buffers).

Parameters:

  • xBufferSizeBytes

    The size, in bytes, of the buffer pointed to by the pucMessageBufferStorageArea parameter. When a message is written to the message buffer an additional sizeof( size_t ) bytes are also written to store the message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so on most 32-bit architecture a 10 byte message will take up 14 bytes of message buffer space. The maximum number of bytes that can be stored in the message buffer is actually (xBufferSizeBytes - 1).

  • pucMessageBufferStorageArea

    Must point to a uint8_t array that is at least xBufferSizeBytes big. This is the array to which messages are copied when they are written to the message buffer.

  • pxStaticMessageBuffer

    Must point to a variable of type StaticMessageBuffer_t, which will be used to hold the message buffer's data structure.

  • pxSendCompletedCallback

    The callback function invoked when a message is written to the message buffer. If the parameter is NULL, the default implementation provided by the sbSEND_COMPLETED macro is used. The send completed callback function must have the prototype defined by StreamBufferCallbackFunction_t, which is:

    1void vSendCallbackFunction( MessageBufferHandle_t xMessageBuffer,
    2 BaseType_t xIsInsideISR,
    3 BaseType_t * const pxHigherPriorityTaskWoken );
  • pxReceiveCompletedCallback

    The callback function invoked when a message is read from a message buffer. If the parameter is NULL, the default implementation provided by the sbRECEIVE_COMPLETED macro is used. The receive completed callback function must have the prototype defined by StreamBufferCallbackFunction_t, which is:

    1void vReceiveCallbackFunction( MessageBufferHandle_t xMessageBuffer,
    2 BaseType_t xIsInsideISR,
    3 BaseType_t * const pxHigherPriorityTaskWoken );

Returns:

If the message buffer is created successfully, then a handle to the created message buffer is returned. If either pucMessageBufferStorageArea or pxStaticMessageBuffer are NULL then NULL is returned.

Example usage:

1/* Used to dimension the array used to hold the messages. The available
2 * space will actually be one less than this, so 999. */
3#define STORAGE_SIZE_BYTES 1000
4
5/* Defines the memory that will actually hold the messages within the message
6 * buffer. Should be one more than the value passed in the xBufferSizeBytes
7 * parameter. */
8static uint8_t ucMessageBufferStorage[ STORAGE_SIZE_BYTES ];
9static uint8_t ucMessageBufferWithCallbackStorage[ STORAGE_SIZE_BYTES ];
10
11/* The variable used to hold the message buffer structure. */
12StaticMessageBuffer_t xMessageBufferStruct;
13StaticMessageBuffer_t xMessageBufferWithCallbackStruct;
14
15void vSendCallbackFunction( MessageBufferHandle_t xMessageBuffer,
16 BaseType_t xIsInsideISR,
17 BaseType_t * const pxHigherPriorityTaskWoken )
18{
19 /* Insert code here which is invoked when a message is written to
20 * the message buffer.
21
22 * This is useful when a message buffer is used to pass messages between
23 * cores on a multicore processor. In that scenario, this callback
24 * can be implemented to generate an interrupt in the other CPU core,
25 * and the interrupt's service routine can then use the
26 * xMessageBufferSendCompletedFromISR() API function to check, and if
27 * necessary unblock, a task that was waiting for message. */
28}
29
30
31void vReceiveCallbackFunction( MessageBufferHandle_t xMessageBuffer,
32 BaseType_t xIsInsideISR,
33 BaseType_t * const pxHigherPriorityTaskWoken )
34{
35 /* Insert code here which is invoked when a message is read from a message
36 * buffer.
37
38 * This is useful when a message buffer is used to pass messages between
39 * cores on a multicore processor. In that scenario, this callback
40 * can be implemented to generate an interrupt in the other CPU core,
41 * and the interrupt's service routine can then use the
42 * xMessageBufferReceiveCompletedFromISR() API function to check, and if
43 * necessary unblock, a task that was waiting to send message. */
44}
45
46void MyFunction( void )
47{
48MessageBufferHandle_t xMessageBuffer, xMessageBufferWithCallback;
49
50 /* Create a message buffer that uses the functions defined
51 * using the sbSEND_COMPLETED() and sbRECEIVE_COMPLETED()
52 * macros as send and receive completed callback functions. */
53 xMessageBuffer = xMessageBufferCreateStatic( sizeof( ucMessageBufferStorage ),
54 ucMessageBufferStorage,
55 &xMessageBufferStruct );
56
57
58 /* Create a message buffer that uses the functions
59 * vSendCallbackFunction and vReceiveCallbackFunction as send
60 * and receive completed callback functions. */
61 xMessageBufferWithCallback = xMessageBufferCreateStaticWithCallback(
62 sizeof( ucMessageBufferWithCallbackStorage ),
63 ucMessageBufferWithCallbackStorage,
64 &xMessageBufferWithCallbackStruct,
65 vSendCallbackFunction,
66 vReceiveCallbackFunction );
67
68 /* As neither the pucMessageBufferStorageArea or pxStaticMessageBuffer
69 * parameters were NULL, xMessageBuffer and xMessageBufferWithCallback
70 * will not be NULL, and can be used to reference the created message
71 * buffers in other message buffer API calls. */
72
73 /* Other code that uses the message buffers can go here. */
74}