Flipper Zero Firmware
Loading...
Searching...
No Matches
stream_buffer.h File Reference

Furi stream buffer primitive. More...

#include "base.h"

Go to the source code of this file.

Typedefs

typedef struct FuriStreamBuffer FuriStreamBuffer
 

Functions

FuriStreamBufferfuri_stream_buffer_alloc (size_t size, size_t trigger_level)
 Allocate stream buffer instance.
 
void furi_stream_buffer_free (FuriStreamBuffer *stream_buffer)
 Free stream buffer instance.
 
bool furi_stream_set_trigger_level (FuriStreamBuffer *stream_buffer, size_t trigger_level)
 Set trigger level for stream buffer.
 
size_t furi_stream_buffer_send (FuriStreamBuffer *stream_buffer, const void *data, size_t length, uint32_t timeout)
 Sends bytes to a stream buffer.
 
size_t furi_stream_buffer_receive (FuriStreamBuffer *stream_buffer, void *data, size_t length, uint32_t timeout)
 Receives bytes from a stream buffer.
 
size_t furi_stream_buffer_bytes_available (FuriStreamBuffer *stream_buffer)
 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.
 
size_t furi_stream_buffer_spaces_available (FuriStreamBuffer *stream_buffer)
 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.
 
bool furi_stream_buffer_is_full (FuriStreamBuffer *stream_buffer)
 Queries a stream buffer to see if it is full.
 
bool furi_stream_buffer_is_empty (FuriStreamBuffer *stream_buffer)
 Queries a stream buffer to see if it is empty.
 
FuriStatus furi_stream_buffer_reset (FuriStreamBuffer *stream_buffer)
 Resets a stream buffer to its initial, empty, state.
 

Detailed Description

Furi stream buffer primitive.

Stream buffers are used to send a continuous stream of data from one task or interrupt to another. Their implementation is light weight, making them particularly suited for interrupt to task and core to core communication scenarios.

NOTE: Stream buffer implementation 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).

Function Documentation

◆ furi_stream_buffer_alloc()

FuriStreamBuffer * furi_stream_buffer_alloc ( size_t size,
size_t trigger_level )

Allocate stream buffer instance.

Stream buffer implementation 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).

Parameters
sizeThe total number of bytes the stream buffer will be able to hold at any one time.
trigger_levelThe 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.
Returns
The stream buffer instance.

◆ furi_stream_buffer_bytes_available()

size_t furi_stream_buffer_bytes_available ( FuriStreamBuffer * stream_buffer)

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.

Parameters
stream_bufferThe stream buffer instance.
Returns
The number of bytes that can be read from the stream buffer before the stream buffer would be empty.

◆ furi_stream_buffer_free()

void furi_stream_buffer_free ( FuriStreamBuffer * stream_buffer)

Free stream buffer instance.

Parameters
stream_bufferThe stream buffer instance.

◆ furi_stream_buffer_is_empty()

bool furi_stream_buffer_is_empty ( FuriStreamBuffer * stream_buffer)

Queries a stream buffer to see if it is empty.

Parameters
stream_bufferThe stream buffer instance.
Returns
true if the stream buffer is empty.
false if the stream buffer is not empty.

◆ furi_stream_buffer_is_full()

bool furi_stream_buffer_is_full ( FuriStreamBuffer * stream_buffer)

Queries a stream buffer to see if it is full.

Parameters
stream_bufferstream buffer instance.
Returns
true if the stream buffer is full.
false if the stream buffer is not full.

◆ furi_stream_buffer_receive()

size_t furi_stream_buffer_receive ( FuriStreamBuffer * stream_buffer,
void * data,
size_t length,
uint32_t timeout )

Receives bytes from a stream buffer.

Wakes up task waiting for space to become available if called from ISR.

Parameters
stream_bufferThe stream buffer instance.
dataA pointer to the buffer into which the received bytes will be copied.
lengthThe length of the buffer pointed to by the data parameter.
timeoutThe maximum amount of time the task should remain in the Blocked state to wait for data to become available if the stream buffer is empty. Will return immediately if timeout is zero. Setting timeout to FuriWaitForever will cause the task to wait indefinitely. Ignored if called from ISR.
Returns
The number of bytes read from the stream buffer, if any.

◆ furi_stream_buffer_reset()

FuriStatus furi_stream_buffer_reset ( FuriStreamBuffer * 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.

Parameters
stream_bufferThe stream buffer instance.
Returns
FuriStatusOk if the stream buffer is reset.
FuriStatusError if there was a task blocked waiting to send to or read from the stream buffer then the stream buffer is not reset.

◆ furi_stream_buffer_send()

size_t furi_stream_buffer_send ( FuriStreamBuffer * stream_buffer,
const void * data,
size_t length,
uint32_t timeout )

Sends bytes to a stream buffer.

The bytes are copied into the stream buffer. Wakes up task waiting for data to become available if called from ISR.

Parameters
stream_bufferThe stream buffer instance.
dataA pointer to the data that is to be copied into the stream buffer.
lengthThe maximum number of bytes to copy from data into the stream buffer.
timeoutThe maximum amount of time the task should remain in the Blocked state to wait for space to become available if the stream buffer is full. Will return immediately if timeout is zero. Setting timeout to FuriWaitForever will cause the task to wait indefinitely. Ignored if called from ISR.
Returns
The number of bytes actually written to the stream buffer.

◆ furi_stream_buffer_spaces_available()

size_t furi_stream_buffer_spaces_available ( FuriStreamBuffer * stream_buffer)

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.

Parameters
stream_bufferThe stream buffer instance.
Returns
The number of bytes that can be written to the stream buffer before the stream buffer would be full.

◆ furi_stream_set_trigger_level()

bool furi_stream_set_trigger_level ( FuriStreamBuffer * stream_buffer,
size_t trigger_level )

Set trigger level for stream buffer.

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.

Parameters
stream_bufferThe stream buffer instance
trigger_levelThe new trigger level for the stream buffer.
Returns
true if trigger level can be be updated (new trigger level was less than or equal to the stream buffer's length).
false if trigger level can't be be updated (new trigger level was greater than the stream buffer's length).