Byte stream communication primitives. More...

Functions
int	ove_stream_init (ove_stream_t stream, ove_stream_storage_t storage, void *buffer, size_t size, size_t trigger)
	Initialise a stream using caller-provided static storage.

void	ove_stream_deinit (ove_stream_t stream)
	Deinitialise a statically-allocated stream.

int	ove_stream_create (ove_stream_t *stream, size_t size, size_t trigger)
	Allocate and initialise a heap-backed stream.

void	ove_stream_destroy (ove_stream_t stream)
	Destroy a heap-allocated stream.

int	ove_stream_send (ove_stream_t stream, const void data, size_t len, uint32_t timeout_ms, size_t bytes_sent)
	Send bytes into the stream from task context.

int	ove_stream_receive (ove_stream_t stream, void buf, size_t len, uint32_t timeout_ms, size_t bytes_received)
	Receive bytes from the stream in task context.

int	ove_stream_send_from_isr (ove_stream_t stream, const void data, size_t len, size_t bytes_sent)
	Send bytes into the stream from an ISR.

int	ove_stream_receive_from_isr (ove_stream_t stream, void buf, size_t len, size_t bytes_received)
	Receive bytes from the stream from an ISR.

int	ove_stream_reset (ove_stream_t stream)
	Discard all bytes currently held in the stream.

size_t	ove_stream_bytes_available (ove_stream_t stream)
	Query the number of bytes currently available in the stream.

Detailed Description

Byte stream communication primitives.

Provides a FIFO byte-stream channel suitable for producer/consumer communication between tasks or between an ISR and a task. Streams are trigger-aware: a receive unblocks only when at least trigger bytes are available, enabling efficient framing without spin-waiting.

Two allocation strategies are supported:

_create() / _destroy() — unified API that works in both heap and zero-heap mode. In zero-heap mode these are macros that generate per-call-site static storage; the buffer size must be a compile-time constant.
_init() / _deinit() — explicit storage control with caller-supplied buffers. Use when creating objects in loops, arrays, or structs.

Note: Requires CONFIG_OVE_STREAM.

Function Documentation

◆ ove_stream_init()

int ove_stream_init	(	ove_stream_t *	stream,
		ove_stream_storage_t *	storage,
		void *	buffer,
		size_t	size,
		size_t	trigger
	)

Initialise a stream using caller-provided static storage.

Constructs a stream object in storage and associates the raw byte buffer buffer of size bytes with it. The stream will not unblock a waiting receiver until at least trigger bytes are present.

Parameters

[out]	stream	Receives the initialised stream handle.
[in]	storage	Pointer to statically-allocated stream storage.
[in]	buffer	Pointer to the backing byte buffer.
[in]	size	Size of `buffer` in bytes.
[in]	trigger	Minimum bytes available before a blocked receiver wakes.

Returns: OVE_OK on success, negative error code on failure.

Note: Requires CONFIG_OVE_STREAM.

◆ ove_stream_deinit()

void ove_stream_deinit ( ove_stream_t stream )

Deinitialise a statically-allocated stream.

Releases all RTOS resources associated with stream. The caller is responsible for freeing any backing buffer that was passed to ove_stream_init.

Parameters

[in] stream Stream handle returned by ove_stream_init.

Note: Requires CONFIG_OVE_STREAM.

◆ ove_stream_create()

int ove_stream_create	(	ove_stream_t *	stream,
		size_t	size,
		size_t	trigger
	)

Allocate and initialise a heap-backed stream.

Allocates both the stream control structure and the internal byte buffer from the heap. The stream will not wake a blocked receiver until at least trigger bytes are available.

Parameters

[out]	stream	Receives the created stream handle.
[in]	size	Capacity of the stream buffer in bytes.
[in]	trigger	Minimum bytes available before a blocked receiver wakes.

Returns: OVE_OK on success, negative error code on failure.

Note: Requires CONFIG_OVE_STREAM and OVE_HEAP_STREAM.

◆ ove_stream_destroy()

void ove_stream_destroy ( ove_stream_t stream )

Destroy a heap-allocated stream.

Frees the stream control structure and its internal buffer. Must only be called on handles obtained from ove_stream_create.

Parameters

[in] stream Stream handle returned by ove_stream_create.

Note: Requires CONFIG_OVE_STREAM and OVE_HEAP_STREAM.

◆ ove_stream_send()

int ove_stream_send	(	ove_stream_t	stream,
		const void *	data,
		size_t	len,
		uint32_t	timeout_ms,
		size_t *	bytes_sent
	)

Send bytes into the stream from task context.

Copies up to len bytes from data into the stream. Blocks for at most timeout_ms milliseconds if the stream has insufficient space. The actual number of bytes accepted is written to bytes_sent when not NULL.

Parameters

[in]	stream	Stream handle.
[in]	data	Pointer to the data to send.
[in]	len	Number of bytes to send.
[in]	timeout_ms	Maximum wait time in milliseconds; 0 for non-blocking.
[out]	bytes_sent	Receives the number of bytes actually written, or `NULL` if the caller does not need this value.

Returns: OVE_OK on success, negative error code on failure or timeout.

Note: Must not be called from an ISR; use ove_stream_send_from_isr instead.

◆ ove_stream_receive()

int ove_stream_receive	(	ove_stream_t	stream,
		void *	buf,
		size_t	len,
		uint32_t	timeout_ms,
		size_t *	bytes_received
	)

Receive bytes from the stream in task context.

Copies up to len bytes from the stream into buf. Blocks for at most timeout_ms milliseconds until the stream's trigger threshold is satisfied. The actual number of bytes read is written to bytes_received when not NULL.

Parameters

[in]	stream	Stream handle.
[out]	buf	Buffer to receive data.
[in]	len	Maximum number of bytes to read.
[in]	timeout_ms	Maximum wait time in milliseconds; 0 for non-blocking.
[out]	bytes_received	Receives the number of bytes actually read, or `NULL` if the caller does not need this value.

Returns: OVE_OK on success, negative error code on failure or timeout.

Note: Must not be called from an ISR; use ove_stream_receive_from_isr instead.

◆ ove_stream_send_from_isr()

int ove_stream_send_from_isr	(	ove_stream_t	stream,
		const void *	data,
		size_t	len,
		size_t *	bytes_sent
	)

Send bytes into the stream from an ISR.

ISR-safe variant of ove_stream_send. Never blocks; if the stream has insufficient space the call returns immediately with a partial or zero count.

Parameters

[in]	stream	Stream handle.
[in]	data	Pointer to the data to send.
[in]	len	Number of bytes to send.
[out]	bytes_sent	Receives the number of bytes actually written, or `NULL` if the caller does not need this value.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_stream_receive_from_isr()

int ove_stream_receive_from_isr	(	ove_stream_t	stream,
		void *	buf,
		size_t	len,
		size_t *	bytes_received
	)

Receive bytes from the stream from an ISR.

ISR-safe variant of ove_stream_receive. Never blocks; returns only the bytes that are immediately available.

Parameters

[in]	stream	Stream handle.
[out]	buf	Buffer to receive data.
[in]	len	Maximum number of bytes to read.
[out]	bytes_received	Receives the number of bytes actually read, or `NULL` if the caller does not need this value.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_stream_reset()

int ove_stream_reset ( ove_stream_t stream )

Discard all bytes currently held in the stream.

Resets the stream to the empty state without deallocating resources. Any task blocked in ove_stream_receive may remain blocked after this call until new data is written.

Parameters

[in] stream Stream handle.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_stream_bytes_available()

size_t ove_stream_bytes_available ( ove_stream_t stream )

Query the number of bytes currently available in the stream.

Returns the count of bytes that can be read without blocking.

Parameters

[in] stream Stream handle.

Returns: Number of bytes available; 0 if the stream is empty or invalid.

Functions

Detailed Description

Function Documentation

◆ ove_stream_init()

◆ ove_stream_deinit()

◆ ove_stream_create()

◆ ove_stream_destroy()

◆ ove_stream_send()

◆ ove_stream_receive()

◆ ove_stream_send_from_isr()

◆ ove_stream_receive_from_isr()

◆ ove_stream_reset()

◆ ove_stream_bytes_available()