Quality RTOS & Embedded Software

KERNEL
WHAT'S NEW
New FreeRTOS Long Term Support version now available.
FreeRTOS Extended Maintenance Program (EMP) registration now open.
FreeRTOS-Plus-TCP v3.0.0 released:
Featured FreeRTOS IoT Integrations:
Delta Over-the-Air Updates:

xStreamBufferCreateStatic / xStreamBufferCreateStaticWithCallback
[RTOS Stream Buffer API]


stream_buffer.h

StreamBufferHandle_t xStreamBufferCreateStatic(
                                    size_t xBufferSizeBytes,
                                    size_t xTriggerLevelBytes,
                                    uint8_t *pucStreamBufferStorageArea,
                                    StaticStreamBuffer_t *pxStaticStreamBuffer );

StreamBufferHandle_t xStreamBufferCreateStaticWithCallback(
                                    size_t xBufferSizeBytes,
                                    size_t xTriggerLevelBytes,
                                    uint8_t *pucStreamBufferStorageArea,
                                    StaticStreamBuffer_t *pxStaticStreamBuffer,
                                    StreamBufferCallbackFunction_t pxSendCompletedCallback,
                                    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 size, in bytes, of the buffer pointed to by the pucStreamBufferStorageArea parameter.

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:

void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
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:

void vReceiveCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
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:


/* Used to dimension the array used to hold the streams. The available

* space will actually be one less than this, so 999. */

#define STORAGE_SIZE_BYTES 1000

/* Defines the memory that will actually hold the streams within the

* stream buffer. */

static uint8_t ucStreamBufferStorage[ STORAGE_SIZE_BYTES ];
static uint8_t ucStreamBufferWithCallbackStorage[ STORAGE_SIZE_BYTES ];

/* The variable used to hold the stream buffer structure. */
StaticStreamBuffer_t xStreamBufferStruct;
StaticStreamBuffer_t xStreamBufferWithCallbackStruct;

void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken )
{
/* Insert code here which is invoked when a data write operation

* to the stream buffer causes the number of bytes in the buffer

* to be more then the trigger level.

* This is useful when a stream buffer is used to pass data 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

* xStreamBufferSendCompletedFromISR() API function to check, and if

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

}

void vReceiveCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken )
{
/* Insert code here which is invoked when data is read from a stream

* buffer.

* This is useful when a stream buffer is used to pass data 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

* xStreamBufferReceiveCompletedFromISR() API function to check, and if

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

}

void MyFunction( void )
{
StreamBufferHandle_t xStreamBuffer, xStreamBufferWithCallback;
const size_t xTriggerLevel = 1;

/* Create a stream buffer that uses the functions defined

* using the sbSEND_COMPLETED() and sbRECEIVE_COMPLETED()

* macros as send and receive completed callback functions. */

xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucStreamBufferStorage ),
xTriggerLevel,
ucStreamBufferStorage,
&xStreamBufferStruct );

/* Create a stream buffer that uses the functions

* vSendCallbackFunction and vReceiveCallbackFunction as send

* and receive completed callback functions. */

xStreamBufferWithCallback = xStreamBufferCreateStaticWithCallback(
sizeof( ucStreamBufferWithCallbackStorage ),
xTriggerLevel,
ucStreamBufferWithCallbackStorage,
&xStreamBufferWithCallbackStruct,
vSendCallbackFunction,
vReceiveCallbackFunction );

/* As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer

* parameters were NULL, xStreamBuffer and xStreamBufferWithCallback

* will not be NULL, and can be used to reference the created stream

* buffers in other stream buffer API calls. */


/* Other code that uses the stream buffers can go here. */





Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.