xStreamBufferSend() function

The handle of the stream buffer to which a stream is being sent.

A pointer to the buffer that holds the bytes to be copied into the stream buffer.

The maximum number of bytes to copy from pvTxData into the stream buffer.

The maximum amount of time the task should remain in the Blocked state to wait for enough space to become available in the stream buffer, should the stream buffer contain too little space to hold the another xDataLengthBytes bytes. The block time is specified in tick periods, so the absolute time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out before it can write all xDataLengthBytes into the buffer it will still write as many bytes as possible. A task does not use any CPU time when it is in the blocked state.

stream_buffer.h @code{c} size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ); @endcode Queries a stream buffer to see how much free space it contains, which is equal to the amount of data that can be sent to the stream buffer before it is full. configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferSpacesAvailable() to be available.

stream_buffer.h @code{c} BaseType_t xStreamBufferResetFromISR( StreamBufferHandle_t xStreamBuffer ); @endcode An interrupt safe version of the API function that resets the stream buffer. Resets a stream buffer to its initial, empty, state. Any data that was in the stream buffer is discarded. A stream buffer can only be reset if there are no tasks blocked waiting to either send to or receive from the stream buffer. Use xStreamBufferReset() to reset a stream buffer from a task. Use xStreamBufferResetFromISR() to reset a stream buffer from an interrupt service routine (ISR). configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferResetFromISR() to be available.

stream_buffer.h @code{c} BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel ); @endcode A stream buffer's trigger level is the number of bytes that must be in the stream buffer before a task that is blocked on the stream buffer to wait 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 however many bytes 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. A trigger level is set when the stream buffer is created, and can be modified using xStreamBufferSetTriggerLevel(). configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferSetTriggerLevel() to be available.

stream_buffer.h @code{c} size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ); @endcode Queries a stream buffer to see how much data it contains, which is equal to the number of bytes that can be read from the stream buffer before the stream buffer would be empty. configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferBytesAvailable() to be available.

stream_buffer.h @code{c} void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ); @endcode Deletes a stream buffer that was previously created using a call to xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream buffer was created using dynamic memory (that is, by xStreamBufferCreate()), then the allocated memory is freed. A stream buffer handle must not be used after the stream buffer has been deleted. configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for vStreamBufferDelete() to be available.

stream_buffer.h @code{c} BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ); @endcode Resets a stream buffer to its initial, empty, state. Any data that was in the stream buffer is discarded. A stream buffer can only be reset if there are no tasks blocked waiting to either send to or receive from the stream buffer. Use xStreamBufferReset() to reset a stream buffer from a task. Use xStreamBufferResetFromISR() to reset a stream buffer from an interrupt service routine (ISR). configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferReset() to be available.

stream_buffer.h @code{c} size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, BaseType_t *pxHigherPriorityTaskWoken ); @endcode Interrupt safe version of the API function that sends a stream of bytes to the stream buffer. ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as xStreamBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then the application writer must place each call to a reading API function (such as xStreamBufferReceive()) inside a critical section and set the receive block time to 0. Use xStreamBufferSend() to write to a stream buffer from a task. Use xStreamBufferSendFromISR() to write to a stream buffer from an interrupt service routine (ISR). configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferSendFromISR() to be available. Example use: @code{c} // A stream buffer that has already been created. StreamBufferHandle_t xStreamBuffer; void vAnInterruptServiceRoutine( void ) { size_t xBytesSent; char *pcStringToSend = "String to send"; BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE. // Attempt to send the string to the stream buffer. xBytesSent = xStreamBufferSendFromISR( xStreamBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), &xHigherPriorityTaskWoken ); if( xBytesSent != strlen( pcStringToSend ) ) { // There was not enough free space in the stream buffer for the entire // string to be written, ut xBytesSent bytes were written. } // If xHigherPriorityTaskWoken was set to pdTRUE inside // xStreamBufferSendFromISR() then a task that has a priority above the // priority of the currently executing task was unblocked and a context // switch should be performed to ensure the ISR returns to the unblocked // task. In most FreeRTOS ports this is done by simply passing // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the // variables value, and perform the context switch if necessary. Check the // documentation for the port in use for port specific instructions. portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); } @endcode

stream_buffer.h @code{c} size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, TickType_t xTicksToWait ); @endcode Receives bytes from a stream buffer. ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as xStreamBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then the application writer must place each call to a reading API function (such as xStreamBufferReceive()) inside a critical section and set the receive block time to 0. Use xStreamBufferReceive() to read from a stream buffer from a task. Use xStreamBufferReceiveFromISR() to read from a stream buffer from an interrupt service routine (ISR). configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferReceive() to be available. Example use: @code{c} void vAFunction( StreamBuffer_t xStreamBuffer ) { uint8_t ucRxData[ 20 ]; size_t xReceivedBytes; const TickType_t xBlockTime = pdMS_TO_TICKS( 20 ); // Receive up to another sizeof( ucRxData ) bytes from the stream buffer. // Wait in the Blocked state (so not using any CPU processing time) for a // maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be // available. xReceivedBytes = xStreamBufferReceive( xStreamBuffer, ( void * ) ucRxData, sizeof( ucRxData ), xBlockTime ); if( xReceivedBytes > 0 ) { // A ucRxData contains another xReceivedBytes bytes of data, which can // be processed here.... } } @endcode

stream_buffer.h @code{c} BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ); @endcode For advanced users only. The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when data is sent to a message buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting for data to arrive then the sbSEND_COMPLETED() macro sends a notification to the task to remove it from the Blocked state. xStreamBufferSendCompletedFromISR() does the same thing. It is provided to enable application writers to implement their own version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME. See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for additional information. configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferSendCompletedFromISR() to be available.

stream_buffer.h @code{c} BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ); @endcode Queries a stream buffer to see if it is empty. A stream buffer is empty if it does not contain any data. configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferIsEmpty() to be available.

stream_buffer.h @code{c} BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ); @endcode Queries a stream buffer to see if it is full. A stream buffer is full if it does not have any free space, and therefore cannot accept any more data. configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferIsFull() to be available.

stream_buffer.h @code{c} size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, BaseType_t *pxHigherPriorityTaskWoken ); @endcode An interrupt safe version of the API function that receives bytes from a stream buffer. Use xStreamBufferReceive() to read bytes from a stream buffer from a task. Use xStreamBufferReceiveFromISR() to read bytes from a stream buffer from an interrupt service routine (ISR). configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferReceiveFromISR() to be available. Example use: @code{c} // A stream buffer that has already been created. StreamBuffer_t xStreamBuffer; void vAnInterruptServiceRoutine( void ) { uint8_t ucRxData[ 20 ]; size_t xReceivedBytes; BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE. // Receive the next stream from the stream buffer. xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer, ( void * ) ucRxData, sizeof( ucRxData ), &xHigherPriorityTaskWoken ); if( xReceivedBytes > 0 ) { // ucRxData contains xReceivedBytes read from the stream buffer. // Process the stream here.... } // If xHigherPriorityTaskWoken was set to pdTRUE inside // xStreamBufferReceiveFromISR() then a task that has a priority above the // priority of the currently executing task was unblocked and a context // switch should be performed to ensure the ISR returns to the unblocked // task. In most FreeRTOS ports this is done by simply passing // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the // variables value, and perform the context switch if necessary. Check the // documentation for the port in use for port specific instructions. portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); } @endcode

stream_buffer.h @code{c} BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ); @endcode For advanced users only. The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when data is read out of a message buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting for data to arrive then the sbRECEIVE_COMPLETED() macro sends a notification to the task to remove it from the Blocked state. xStreamBufferReceiveCompletedFromISR() does the same thing. It is provided to enable application writers to implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME. See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for additional information. configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for xStreamBufferReceiveCompletedFromISR() to be available.

stream_buffer.h @code{c} UBaseType_t uxStreamBufferGetStreamBufferNotificationIndex( StreamBufferHandle_t xStreamBuffer ); @endcode Get the task notification index used for the supplied stream buffer which can be set using vStreamBufferSetStreamBufferNotificationIndex. If the task notification index for the stream buffer is not changed using vStreamBufferSetStreamBufferNotificationIndex, this function returns the default value (tskDEFAULT_INDEX_TO_NOTIFY). configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for uxStreamBufferGetStreamBufferNotificationIndex() to be available.

stream_buffer.h @code{c} void vStreamBufferSetStreamBufferNotificationIndex ( StreamBuffer_t xStreamBuffer, UBaseType_t uxNotificationIndex ); @endcode Set the task notification index used for the supplied stream buffer. Successive calls to stream buffer APIs (like xStreamBufferSend or xStreamBufferReceive) for this stream buffer will use this new index for their task notifications. If this function is not called, the default index (tskDEFAULT_INDEX_TO_NOTIFY) is used for task notifications. It is recommended to call this function before attempting to send or receive data from the stream buffer to avoid inconsistencies. configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for vStreamBufferSetStreamBufferNotificationIndex() to be available.