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

xStreamBufferCreateStatic, xStreamBufferCreateStaticWithCallback

[RTOS Stream Buffer API]

stream_buffer.h

1StreamBufferHandle_t xStreamBufferCreateStatic(
2 size_t xBufferSizeBytes,
3 size_t xTriggerLevelBytes,
4 uint8_t *pucStreamBufferStorageArea,
5 StaticStreamBuffer_t *pxStaticStreamBuffer );
6
7StreamBufferHandle_t xStreamBufferCreateStaticWithCallback(
8 size_t xBufferSizeBytes,
9 size_t xTriggerLevelBytes,
10 uint8_t *pucStreamBufferStorageArea,
11 StaticStreamBuffer_t *pxStaticStreamBuffer,
12 StreamBufferCallbackFunction_t pxSendCompletedCallback,
13 StreamBufferCallbackFunction_t pxReceiveCompletedCallback );

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

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

Enable stream buffer functionality by including the FreeRTOS/source/stream_buffer.c source file in the build.

Parameters:

  • xBufferSizeBytes

    The total number of bytes the stream buffer will be able to hold at any one time.

  • xTriggerLevelBytes

    The number of bytes that must be in the stream buffer before a task that is blocked on the stream buffer waiting for data is moved out of the blocked state. For example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 1 then the task will be unblocked when a single byte is written to the buffer or the task's block time expires. As another example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 10, then the task will not be unblocked until the stream buffer contains at least 10 bytes or the task's block time expires. If a reading task's block time expires before the trigger level is reached, then the task will still receive as many bytes as are actually available. Setting a trigger level of 0 will result in a trigger level of 1 being used. It is not valid to specify a trigger level that is greater than the buffer size.

  • pucStreamBufferStorageArea

    Must point to a uint8_t array that is at least xBufferSizeBytes + 1 big. This is the array to which streams are copied when they are written to the stream buffer.

  • pxStaticStreamBuffer

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

  • pxSendCompletedCallback

    The callback function invoked when a data write to the stream buffer causes the number of bytes in the buffer to be more than the trigger level. 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( StreamBufferHandle_t xStreamBuffer,
    2 BaseType_t xIsInsideISR,
    3 BaseType_t * const pxHigherPriorityTaskWoken );
  • pxReceiveCompletedCallback

    The callback function invoked when data (more than zero bytes) is read from a stream 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( StreamBufferHandle_t xStreamBuffer,
    2 BaseType_t xIsInsideISR,
    3 BaseType_t * const pxHigherPriorityTaskWoken );

Returns:

If the stream buffer is created successfully, then a handle to the created stream buffer is returned. If either pucStreamBufferStorageArea or pxStaticstreamBuffer are NULL then NULL is returned.

Example usage:

1/* The total number of bytes the stream buffer will be able to hold at any one time. */
2#define STREAM_BUFFER_SIZE_BYTES 1000
3
4/* Defines the memory that will actually hold the streams within the
5 * stream buffer. Note that it needs to be of size (STREAM_BUFFER_SIZE_BYTES + 1). */
6static uint8_t ucStreamBufferStorage[ STREAM_BUFFER_SIZE_BYTES + 1 ];
7static uint8_t ucStreamBufferWithCallbackStorage[ STREAM_BUFFER_SIZE_BYTES + 1 ];
8
9/* The variable used to hold the stream buffer structure. */
10StaticStreamBuffer_t xStreamBufferStruct;
11StaticStreamBuffer_t xStreamBufferWithCallbackStruct;
12
13void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
14 BaseType_t xIsInsideISR,
15 BaseType_t * const pxHigherPriorityTaskWoken )
16{
17 /* Insert code here which is invoked when a data write operation
18 * to the stream buffer causes the number of bytes in the buffer
19 * to be more then the trigger level.
20 * This is useful when a stream buffer is used to pass data between
21 * cores on a multicore processor. In that scenario, this callback
22 * can be implemented to generate an interrupt in the other CPU core,
23 * and the interrupt's service routine can then use the
24 * xStreamBufferSendCompletedFromISR() API function to check, and if
25 * necessary unblock, a task that was waiting for the data. */
26}
27
28void vReceiveCallbackFunction( StreamBufferHandle_t xStreamBuffer,
29 BaseType_t xIsInsideISR,
30 BaseType_t * const pxHigherPriorityTaskWoken )
31{
32 /* Insert code here which is invoked when data is read from a stream
33 * buffer.
34 * This is useful when a stream buffer is used to pass data between
35 * cores on a multicore processor. In that scenario, this callback
36 * can be implemented to generate an interrupt in the other CPU core,
37 * and the interrupt's service routine can then use the
38 * xStreamBufferReceiveCompletedFromISR() API function to check, and if
39 * necessary unblock, a task that was waiting to send the data. */
40}
41
42
43void MyFunction( void )
44{
45StreamBufferHandle_t xStreamBuffer, xStreamBufferWithCallback;
46const size_t xTriggerLevel = 1;
47
48 /* Create a stream buffer that uses the functions defined
49 * using the sbSEND\COMPLETED() and sbRECEIVE_COMPLETED()
50 * macros as send and receive completed callback functions. */
51 xStreamBuffer = xStreamBufferCreateStatic( STREAM_BUFFER_SIZE_BYTES,
52 xTriggerLevel,
53 ucStreamBufferStorage,
54 &xStreamBufferStruct );
55
56 /* Create a stream buffer that uses the functions
57 * vSendCallbackFunction and vReceiveCallbackFunction as send
58 * and receive completed callback functions. */
59 xStreamBufferWithCallback = xStreamBufferCreateStaticWithCallback(
60 STREAM_BUFFER_SIZE_BYTES,
61 xTriggerLevel,
62 ucStreamBufferWithCallbackStorage,
63 &xStreamBufferWithCallbackStruct,
64 vSendCallbackFunction,
65 vReceiveCallbackFunction );
66
67 /* As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer
68 * parameters were NULL, xStreamBuffer and xStreamBufferWithCallback
69 * will not be NULL, and can be used to reference the created stream
70 * buffers in other stream buffer API calls. */
71
72 /* Other code that uses the stream buffers can go here. */
73}