Chapter 2. API Reference
BaseType_t xStreamBufferReset(StreamBufferHandle_t xStreamBuffer)
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.
Return If the stream buffer is reset then pdPASS is returned. If there was a task blocked waiting to send to
or read from the stream buffer then the stream buffer is not reset and pdFAIL is returned.
Parameters
• xStreamBuffer: The handle of the stream buffer being reset.
size_t xStreamBufferSpacesAvailable(StreamBufferHandle_t xStreamBuffer)
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.
Return The number of bytes that can be written to the stream buffer before the stream buffer would be full.
Parameters
• xStreamBuffer: The handle of the stream buffer being queried.
size_t xStreamBufferBytesAvailable(StreamBufferHandle_t xStreamBuffer)
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.
Return The number of bytes that can be read from the stream buffer before the stream buffer would be empty.
Parameters
• xStreamBuffer: The handle of the stream buffer being queried.
BaseType_t xStreamBufferSetTriggerLevel(StreamBufferHandle_t xStreamBuffer, size_t xTrig-
gerLevel)
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 xStreamBufferSetTrigger-
Level().
Return If xTriggerLevel was less than or equal to the stream buffer’s length then the trigger level will be
updated and pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters
• xStreamBuffer: The handle of the stream buffer being updated.
• xTriggerLevel: The new trigger level for the stream buffer.
BaseType_t xStreamBufferSendCompletedFromISR(StreamBufferHandle_t xStreamBuffer, Base-
Type_t *pxHigherPriorityTaskWoken)
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.
Return If a task was removed from the Blocked state then pdTRUE is returned. Otherwise pdFALSE is
returned.
Parameters
• xStreamBuffer: The handle of the stream buffer to which data was written.
Espressif Systems 944
Submit Document Feedback
Release v4.4
To Next Page
Loading...