FreeRTOS stream compatibility APIs. More...

#include "FreeRTOS.h"
#include <queue.h>

Typedefs
typedef struct MessageQueue *	StreamBufferHandle_t
	Stream handle.

Functions
static StreamBufferHandle_t	xStreamBufferCreate (size_t xBufferSizeBytes, size_t xTriggerLevelBytes)
	Create a stream buffer that can store xBufferSizeBytes bytes.
static void	vStreamBufferDelete (StreamBufferHandle_t xStreamBuffer)
	Destroy a queue.
static size_t	xStreamBufferSend (StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, TickType_t waitTicks)
	Sends xDataLengthBytes of data from pvTxData to the stream xStreamBuffer.
static size_t	xStreamBufferSendFromISR (StreamBufferHandle_t xStreamBuffer, const void pvTxData, size_t xDataLengthBytes, BaseType_t pxHigherPriorityTaskWoken)
static size_t	xStreamBufferReceive (StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, TickType_t xTicksToWait)
	Receive up to xBufferLengthBytes bytes into pvRxData from the stream given by xStreamBuffer.
static size_t	xStreamBufferReceiveFromISR (StreamBufferHandle_t xStreamBuffer, void pvRxData, size_t xBufferLengthBytes, BaseType_t pxHigherPriorityTaskWoken)
static size_t	xStreamBufferBytesAvailable (StreamBufferHandle_t xStreamBuffer)
	Returns the amount of data in a stream, in bytes.
static size_t	xStreamBufferSpacesAvailable (StreamBufferHandle_t xStreamBuffer)
	Returns the amount of space available in a stream, in bytes.
static BaseType_t	xStreamBufferSetTriggerLevel (StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel)
	Updates the trigger level of the stream.
static BaseType_t	xStreamBufferIsEmpty (StreamBufferHandle_t xStreamBuffer)
	Returns pdTRUE if the stream is empty, pdFALSE otherwise.
static BaseType_t	xStreamBufferIsFull (StreamBufferHandle_t xStreamBuffer)
	Returns pdTRUE if the stream is full, pdFALSE otherwise.
static BaseType_t	xStreamBufferReset (StreamBufferHandle_t xStreamBuffer)
	Reset the stream, unless another thread is currently active using it.
static BaseType_t	xStreamBufferResetFromISR (StreamBufferHandle_t xStreamBuffer)
	Reset a stream from an ISR.

Detailed Description

FreeRTOS stream compatibility APIs.

This file defines the compatibility wrappers for FreeRTOS's stream abstraction. This is intended for porting code from FreeRTOS and should not be used in new CHERIoT software. The functions in this file wrap the APIs exposed in queue.h. Streams are implemented as queues of bytes (CHERIoT RTOS message queues allow inserting and receiving multiple queue elements at the same time). These are implemented in the message_queue_library library and, if used across a trust boundary, the message_queue compartment, which must be linked to the final firmware image.

Definition in file stream_buffer.h.

Typedef Documentation

◆ StreamBufferHandle_t

typedef struct MessageQueue* StreamBufferHandle_t

Stream handle.

This is used to reference streams in the API functions.

Definition at line 22 of file stream_buffer.h.

Function Documentation

◆ vStreamBufferDelete()

void vStreamBufferDelete ( StreamBufferHandle_t xStreamBuffer )

inlinestatic

Destroy a queue.

Note that, unlike the underlying CHERIoT RTOS API, this has no mechanism to signal failure. If memory deallocation fails (for example, as a result of insufficient stack or trusted-stack space, this API may leak the queue.

Definition at line 48 of file stream_buffer.h.

References queue_destroy(), and UnlimitedTimeout.

◆ xStreamBufferBytesAvailable()

size_t xStreamBufferBytesAvailable ( StreamBufferHandle_t xStreamBuffer )

inlinestatic

Returns the amount of data in a stream, in bytes.

This API is intrinsically racy because more data can be sent to the queue in between calling this function and acting on the result.

Note that, unlike FreeRTOS streams, CHERIoT RTOS message queues are thread safe and so this amount can also decrease if another thread receives from this stream.

Definition at line 148 of file stream_buffer.h.

References queue_items_remaining().

Referenced by xStreamBufferIsEmpty().

◆ xStreamBufferCreate()

StreamBufferHandle_t xStreamBufferCreate	(	size_t	xBufferSizeBytes,
		size_t	xTriggerLevelBytes )

inlinestatic

Create a stream buffer that can store xBufferSizeBytes bytes.

Returns NULL if queue creation failed, false otherwise.

Definition at line 31 of file stream_buffer.h.

References queue_create(), and UnlimitedTimeout.

◆ xStreamBufferIsEmpty()

BaseType_t xStreamBufferIsEmpty ( StreamBufferHandle_t xStreamBuffer )

inlinestatic

Returns pdTRUE if the stream is empty, pdFALSE otherwise.

Note, this API is inherently racy.

Definition at line 197 of file stream_buffer.h.

References xStreamBufferBytesAvailable().

◆ xStreamBufferIsFull()

BaseType_t xStreamBufferIsFull ( StreamBufferHandle_t xStreamBuffer )

inlinestatic

Returns pdTRUE if the stream is full, pdFALSE otherwise.

Note, this API is inherently racy.

Definition at line 207 of file stream_buffer.h.

References xStreamBufferSpacesAvailable().

◆ xStreamBufferReceive()

size_t xStreamBufferReceive	(	StreamBufferHandle_t	xStreamBuffer,
		void *	pvRxData,
		size_t	xBufferLengthBytes,
		TickType_t	xTicksToWait )

inlinestatic

Receive up to xBufferLengthBytes bytes into pvRxData from the stream given by xStreamBuffer.

Returns the number of bytes read, this may be zero in case of an error. Unlike the underlying CHERIoT RTOS API, this API has no way of signalling specific errors so all errors are reported as zero return values.

Definition at line 104 of file stream_buffer.h.

References queue_receive_multiple().

◆ xStreamBufferReceiveFromISR()

size_t xStreamBufferReceiveFromISR	(	StreamBufferHandle_t	xStreamBuffer,
		void *	pvRxData,
		size_t	xBufferLengthBytes,
		BaseType_t *	pxHigherPriorityTaskWoken )

inlinestatic

Definition at line 128 of file stream_buffer.h.

◆ xStreamBufferReset()

BaseType_t xStreamBufferReset ( StreamBufferHandle_t xStreamBuffer )

inlinestatic

Reset the stream, unless another thread is currently active using it.

This differs slightly from the FreeRTOS implementation, threads blocked waiting to acquire the endpoint locks do not prevent this operation and any threads waiting to send will become unblocked.

Definition at line 219 of file stream_buffer.h.

References queue_reset().

Referenced by xStreamBufferResetFromISR().

◆ xStreamBufferResetFromISR()

BaseType_t xStreamBufferResetFromISR ( StreamBufferHandle_t xStreamBuffer )

inlinestatic

Reset a stream from an ISR.

We do not allow running code from ISRs and so this behaves like a non-blocking xStreamBufferReset.

Definition at line 230 of file stream_buffer.h.

References xStreamBufferReset().

◆ xStreamBufferSend()

size_t xStreamBufferSend	(	StreamBufferHandle_t	xStreamBuffer,
		const void *	pvTxData,
		size_t	xDataLengthBytes,
		TickType_t	waitTicks )

inlinestatic

Sends xDataLengthBytes of data from pvTxData to the stream xStreamBuffer.

Returns the number of bytes read or zero in case of an error. Unlike the underlying CHERIoT RTOS API, this API has no way of signalling specific errors so all errors are reported as zero return values.

Definition at line 63 of file stream_buffer.h.

References queue_send_multiple().

◆ xStreamBufferSendFromISR()

size_t xStreamBufferSendFromISR	(	StreamBufferHandle_t	xStreamBuffer,
		const void *	pvTxData,
		size_t	xDataLengthBytes,
		BaseType_t *	pxHigherPriorityTaskWoken )

inlinestatic

Definition at line 87 of file stream_buffer.h.

◆ xStreamBufferSetTriggerLevel()

BaseType_t xStreamBufferSetTriggerLevel	(	StreamBufferHandle_t	xStreamBuffer,
		size_t	xTriggerLevel )

inlinestatic

Updates the trigger level of the stream.

Trigger levels are not currently supported by CHERIoT RTOS.

Definition at line 185 of file stream_buffer.h.

References pdFALSE, and xStreamBufferSetTriggerLevel().

Referenced by xStreamBufferSetTriggerLevel().

◆ xStreamBufferSpacesAvailable()

size_t xStreamBufferSpacesAvailable ( StreamBufferHandle_t xStreamBuffer )

inlinestatic

Returns the amount of space available in a stream, in bytes.

This API is intrinsically racy because more data can be read from the queue in between calling this function and acting on the result.

Note that, unlike FreeRTOS streams, CHERIoT RTOS message queues are thread safe and so this amount can also decrease if another thread sends over this stream.

Definition at line 168 of file stream_buffer.h.

References queue_items_remaining(), and MessageQueue::queueSize.

Referenced by xStreamBufferIsFull().

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ StreamBufferHandle_t

Function Documentation

◆ vStreamBufferDelete()

◆ xStreamBufferBytesAvailable()

◆ xStreamBufferCreate()

◆ xStreamBufferIsEmpty()

◆ xStreamBufferIsFull()

◆ xStreamBufferReceive()

◆ xStreamBufferReceiveFromISR()

◆ xStreamBufferReset()

◆ xStreamBufferResetFromISR()

◆ xStreamBufferSend()

◆ xStreamBufferSendFromISR()

◆ xStreamBufferSetTriggerLevel()

◆ xStreamBufferSpacesAvailable()