Updated Jul 2025
xStreamBufferCreateStatic, xStreamBufferCreateStaticWithCallback
stream_buffer.h
1StreamBufferHandle_t xStreamBufferCreateStatic(2 size_t xBufferSizeBytes,3 size_t xTriggerLevelBytes,4 uint8_t *pucStreamBufferStorageArea,5 StaticStreamBuffer_t *pxStaticStreamBuffer );67StreamBufferHandle_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 100034/* Defines the memory that will actually hold the streams within the5 * 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 ];89/* The variable used to hold the stream buffer structure. */10StaticStreamBuffer_t xStreamBufferStruct;11StaticStreamBuffer_t xStreamBufferWithCallbackStruct;1213void 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 operation18 * to the stream buffer causes the number of bytes in the buffer19 * to be more then the trigger level.20 * This is useful when a stream buffer is used to pass data between21 * cores on a multicore processor. In that scenario, this callback22 * can be implemented to generate an interrupt in the other CPU core,23 * and the interrupt's service routine can then use the24 * xStreamBufferSendCompletedFromISR() API function to check, and if25 * necessary unblock, a task that was waiting for the data. */26}2728void 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 stream33 * buffer.34 * This is useful when a stream buffer is used to pass data between35 * cores on a multicore processor. In that scenario, this callback36 * can be implemented to generate an interrupt in the other CPU core,37 * and the interrupt's service routine can then use the38 * xStreamBufferReceiveCompletedFromISR() API function to check, and if39 * necessary unblock, a task that was waiting to send the data. */40}414243void MyFunction( void )44{45StreamBufferHandle_t xStreamBuffer, xStreamBufferWithCallback;46const size_t xTriggerLevel = 1;4748 /* Create a stream buffer that uses the functions defined49 * 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 );5556 /* Create a stream buffer that uses the functions57 * vSendCallbackFunction and vReceiveCallbackFunction as send58 * and receive completed callback functions. */59 xStreamBufferWithCallback = xStreamBufferCreateStaticWithCallback(60 STREAM_BUFFER_SIZE_BYTES,61 xTriggerLevel,62 ucStreamBufferWithCallbackStorage,63 &xStreamBufferWithCallbackStruct,64 vSendCallbackFunction,65 vReceiveCallbackFunction );6667 /* As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer68 * parameters were NULL, xStreamBuffer and xStreamBufferWithCallback69 * will not be NULL, and can be used to reference the created stream70 * buffers in other stream buffer API calls. */7172 /* Other code that uses the stream buffers can go here. */73}