FreeRTOS semaphore compatibility layer. More...

#include "FreeRTOS.h"
#include <locks.h>
#include <stdatomic.h>

Classes
struct	StaticSemaphore_t
	Type used to define space for storing any of the exposed FreeRTOS semaphore types. More...

Macros
#define	CHERIOT_FREERTOS_SEMAPHORE_CASE(x)
#define	CHERIOT_FREERTOS_MUTEX_CASE(x)
#define	CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE(x)
#define	CHERIOT_FREERTOS_SEMAPHORE_SWITCH(x)
#define	CHERIOT_FREERTOS_SEMAPHORE_KIND_SET(x, y)

Typedefs
typedef StaticSemaphore_t *	SemaphoreHandle_t
	Type for a handle to a counting semaphore.

Enumerations
enum	CheriotFreeRTOS_SemaphoreKind : uint8_t { CheriotFreeRTOS_Semaphore , CheriotFreeRTOS_Mutex , CheriotFreeRTOS_RecursiveMutex }
	Enumeration used to differentiate the different kinds of FreeRTOS semaphores in this compatibility layer. More...

Functions
static SemaphoreHandle_t	xSemaphoreCreateCountingStatic (UBaseType_t uxMaxCount, UBaseType_t uxInitialCount, StaticSemaphore_t *pxSemaphoreBuffer)
	Initialise a statically allocated semaphore.
static SemaphoreHandle_t	xSemaphoreCreateCounting (UBaseType_t uxMaxCount, UBaseType_t uxInitialCount)
	Allocate a counting semaphore on the heap.
static SemaphoreHandle_t	xSemaphoreCreateBinary ()
	Create a heap-allocated binary semaphore.
static SemaphoreHandle_t	xSemaphoreCreateBinaryStatic (StaticSemaphore_t *pxSemaphoreBuffer)
	Create a statically allocated binary semaphore.
static SemaphoreHandle_t	xSemaphoreCreateMutexStatic (StaticSemaphore_t *pxMutexBuffer)
	Create statically allocated mutex.
static SemaphoreHandle_t	xSemaphoreCreateMutex ()
	Create a heap-allocated mutex.
static SemaphoreHandle_t	xSemaphoreCreateRecursiveMutexStatic (StaticSemaphore_t *pxMutexBuffer)
	Create a statically allocated recursive mutex.
static SemaphoreHandle_t	xSemaphoreCreateRecursiveMutex (void)
	Create a heap-allocated recursive mutex.
static void	vSemaphoreDelete (SemaphoreHandle_t xSemaphore)
	Delete a heap-allocated semaphore, of any kind.
static TaskHandle_t	xSemaphoreGetMutexHolder (SemaphoreHandle_t xMutex)
	Get the current owner (thread ID) of a mutex.
static UBaseType_t	uxSemaphoreGetCount (SemaphoreHandle_t xSemaphore)
	Returns the current count of a counting semaphore, or whether a mutex or binary semaphore is available.
static _Bool	xSemaphoreTake (SemaphoreHandle_t xSemaphore, TickType_t xTicksToWait)
	A semaphore get (down) operation.
static _Bool	xSemaphoreTakeFromISR (SemaphoreHandle_t xSemaphore, BaseType_t *pxHigherPriorityTaskWoken)
	Take a semaphore from code that may run in an ISR.
static _Bool	xSemaphoreTakeFromISR (SemaphoreHandle_t xSemaphore)
static _Bool	xSemaphoreGive (SemaphoreHandle_t xSemaphore)
	A semaphore put (up) operation.
static _Bool	xSemaphoreGiveFromISR (SemaphoreHandle_t xSemaphore, BaseType_t *pxHigherPriorityTaskWoken)
	Give a semaphore from code that may run in an ISR.
static _Bool	xSemaphoreGiveFromISR (SemaphoreHandle_t xSemaphore)
static _Bool	xSemaphoreTakeRecursive (SemaphoreHandle_t xMutex, TickType_t xTicksToWait)
	Try to acquire a recursive mutex.
static _Bool	xSemaphoreGiveRecursive (SemaphoreHandle_t xMutex)
	Release a recursive mutex.
static BaseType_t	xSemaphoreGetStaticBuffer (SemaphoreHandle_t xSemaphore, StaticSemaphore_t **ppxSemaphoreBuffer)
	Launder a semaphore back into the type used to initialise it.

Detailed Description

FreeRTOS semaphore compatibility layer.

This maps FreeRTOS semaphore types to their CHERIoT RTOS equivalents.

There is some overhead from dynamic dispatch that can be avoided if only one of the FreeRTOS semaphore types needs to be supported in a particular component. You can enable individual semaphore types by defining the following macros:

CHERIOT_EXPOSE_FREERTOS_SEMAPHORE: Enable counting and binary semaphores.
CHERIOT_EXPOSE_FREERTOS_MUTEX: Enable non-recursive, priority-inheriting mutexes.
CHERIOT_EXPOSE_FREERTOS_RECURSIVE_MUTEX: Enable recursive mutexes.

Definition in file semphr.h.

Macro Definition Documentation

◆ CHERIOT_FREERTOS_MUTEX_CASE

#define CHERIOT_FREERTOS_MUTEX_CASE ( x )

Value:

case CheriotFreeRTOS_Mutex:                                            \
    x;                                                                 \
    break;

Definition at line 39 of file semphr.h.

◆ CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE

#define CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE ( x )

Value:

case CheriotFreeRTOS_RecursiveMutex:                                   \
    x;                                                                 \
    break;

Definition at line 48 of file semphr.h.

◆ CHERIOT_FREERTOS_SEMAPHORE_CASE

#define CHERIOT_FREERTOS_SEMAPHORE_CASE ( x )

Value:

case CheriotFreeRTOS_Semaphore:                                        \
    x;                                                                 \
    break;

Definition at line 30 of file semphr.h.

◆ CHERIOT_FREERTOS_SEMAPHORE_KIND_SET

#define CHERIOT_FREERTOS_SEMAPHORE_KIND_SET	(		x,
			y )

Value:

x->kind = y

Definition at line 112 of file semphr.h.

◆ CHERIOT_FREERTOS_SEMAPHORE_SWITCH

#define CHERIOT_FREERTOS_SEMAPHORE_SWITCH ( x )

Value:

switch (x->kind)

Definition at line 106 of file semphr.h.

Typedef Documentation

◆ SemaphoreHandle_t

typedef StaticSemaphore_t* SemaphoreHandle_t

Type for a handle to a counting semaphore.

Definition at line 132 of file semphr.h.

Enumeration Type Documentation

◆ CheriotFreeRTOS_SemaphoreKind

enum CheriotFreeRTOS_SemaphoreKind : uint8_t

Enumeration used to differentiate the different kinds of FreeRTOS semaphores in this compatibility layer.

Enumerator
CheriotFreeRTOS_Semaphore	A FreeRTOS counting or binary semaphore.
CheriotFreeRTOS_Mutex	A non-recursive, priority-inheriting mutex.
CheriotFreeRTOS_RecursiveMutex	A recursive mutex.

Definition at line 60 of file semphr.h.

Function Documentation

◆ uxSemaphoreGetCount()

UBaseType_t uxSemaphoreGetCount ( SemaphoreHandle_t xSemaphore )

inlinestatic

Returns the current count of a counting semaphore, or whether a mutex or binary semaphore is available.

Note: This API is inherently racy. Unless run with interrupts disabled, there is no guarantee that the value returned is still valid by the time the caller inspects it.

Definition at line 305 of file semphr.h.

References RecursiveMutexState::lock.

◆ vSemaphoreDelete()

void vSemaphoreDelete ( SemaphoreHandle_t xSemaphore )

inlinestatic

Delete a heap-allocated semaphore, of any kind.

Note: As on FreeRTOS, if there are waiters blocked on this semaphore then they will remain blocked until their timeout (if ever).

Definition at line 271 of file semphr.h.

◆ xSemaphoreCreateBinary()

SemaphoreHandle_t xSemaphoreCreateBinary ( )

inlinestatic

Create a heap-allocated binary semaphore.

Binary semaphores are implemented as counting semaphores with a maximum count of 1.

Definition at line 184 of file semphr.h.

References xSemaphoreCreateCounting().

◆ xSemaphoreCreateBinaryStatic()

SemaphoreHandle_t xSemaphoreCreateBinaryStatic ( StaticSemaphore_t * pxSemaphoreBuffer )

inlinestatic

Create a statically allocated binary semaphore.

Binary semaphores are implemented as counting semaphores with a maximum count of 1.

Definition at line 196 of file semphr.h.

References xSemaphoreCreateCountingStatic().

◆ xSemaphoreCreateCounting()

SemaphoreHandle_t xSemaphoreCreateCounting	(	UBaseType_t	uxMaxCount,
		UBaseType_t	uxInitialCount )

inlinestatic

Allocate a counting semaphore on the heap.

The initial value and maximum are specified with uxInitialCount and uxMaxCount respectively.

Returns a pointer to the semaphore on success, NULL on allocation failure.

Definition at line 166 of file semphr.h.

References xSemaphoreCreateCountingStatic().

Referenced by xSemaphoreCreateBinary().

◆ xSemaphoreCreateCountingStatic()

SemaphoreHandle_t xSemaphoreCreateCountingStatic	(	UBaseType_t	uxMaxCount,
		UBaseType_t	uxInitialCount,
		StaticSemaphore_t *	pxSemaphoreBuffer )

inlinestatic

Initialise a statically allocated semaphore.

The initial value and maximum are specified with uxInitialCount and uxMaxCount respectively.

Returns a pointer to the semaphore.

Definition at line 142 of file semphr.h.

References CheriotFreeRTOS_Semaphore, and CountingSemaphoreState::maxCount.

Referenced by xSemaphoreCreateBinaryStatic(), and xSemaphoreCreateCounting().

◆ xSemaphoreCreateMutex()

SemaphoreHandle_t xSemaphoreCreateMutex ( )

inlinestatic

Create a heap-allocated mutex.

Definition at line 218 of file semphr.h.

References xSemaphoreCreateMutexStatic().

◆ xSemaphoreCreateMutexStatic()

SemaphoreHandle_t xSemaphoreCreateMutexStatic ( StaticSemaphore_t * pxMutexBuffer )

inlinestatic

Create statically allocated mutex.

Definition at line 207 of file semphr.h.

References CheriotFreeRTOS_Mutex.

Referenced by xSemaphoreCreateMutex().

◆ xSemaphoreCreateRecursiveMutex()

SemaphoreHandle_t xSemaphoreCreateRecursiveMutex ( void )

inlinestatic

Create a heap-allocated recursive mutex.

Definition at line 251 of file semphr.h.

References xSemaphoreCreateRecursiveMutexStatic().

◆ xSemaphoreCreateRecursiveMutexStatic()

SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic ( StaticSemaphore_t * pxMutexBuffer )

inlinestatic

Create a statically allocated recursive mutex.

Definition at line 237 of file semphr.h.

References CheriotFreeRTOS_RecursiveMutex, RecursiveMutexState::depth, and RecursiveMutexState::lock.

Referenced by xSemaphoreCreateRecursiveMutex().

◆ xSemaphoreGetMutexHolder()

TaskHandle_t xSemaphoreGetMutexHolder ( SemaphoreHandle_t xMutex )

inlinestatic

Get the current owner (thread ID) of a mutex.

If this is a counting semaphore, or if the lock is not held, returns zero.

Note: This API is inherently somewhat racy. If this returns the current thread's thread ID, then it cannot change, but any other return value may change between the time it is returned and the time the caller inspects it.

Definition at line 285 of file semphr.h.

References RecursiveMutexState::lock.

◆ xSemaphoreGetStaticBuffer()

BaseType_t xSemaphoreGetStaticBuffer	(	SemaphoreHandle_t	xSemaphore,
		StaticSemaphore_t **	ppxSemaphoreBuffer )

inlinestatic

Launder a semaphore back into the type used to initialise it.

Definition at line 453 of file semphr.h.

References pdTRUE.

◆ xSemaphoreGive()

_Bool xSemaphoreGive ( SemaphoreHandle_t xSemaphore )

inlinestatic

A semaphore put (up) operation.

If there are tasks blocked on the semaphore, this will unblock one of them. Otherwise, the semaphore value is incremented by one.

Definition at line 372 of file semphr.h.

References flaglock_unlock(), and semaphore_put().

Referenced by xSemaphoreGiveFromISR().

◆ xSemaphoreGiveFromISR() [1/2]

_Bool xSemaphoreGiveFromISR ( SemaphoreHandle_t xSemaphore )

inlinestatic

Definition at line 408 of file semphr.h.

◆ xSemaphoreGiveFromISR() [2/2]

_Bool xSemaphoreGiveFromISR	(	SemaphoreHandle_t	xSemaphore,
		BaseType_t *	pxHigherPriorityTaskWoken )

inlinestatic

Give a semaphore from code that may run in an ISR.

CHERIoT RTOS does not permit code to run in ISRs and so this simply calls the normal code paths.

The second parameter is a pointer to a variable that will be set to true if the caller needs to yield to wake a higher-priority task. This is unconditionally false on CHERIoT RTOS.

Definition at line 396 of file semphr.h.

References xSemaphoreGive(), and xSemaphoreGiveFromISR().

Referenced by xSemaphoreGiveFromISR().

◆ xSemaphoreGiveRecursive()

_Bool xSemaphoreGiveRecursive ( SemaphoreHandle_t xMutex )

inlinestatic

Release a recursive mutex.

Definition at line 436 of file semphr.h.

References recursivemutex_unlock().

◆ xSemaphoreTake()

_Bool xSemaphoreTake	(	SemaphoreHandle_t	xSemaphore,
		TickType_t	xTicksToWait )

inlinestatic

A semaphore get (down) operation.

If the semaphore value is zero, this can block for up to xTicksToWait ticks. Returns true if the semaphore was obtained, false if the timeout expired.

Definition at line 322 of file semphr.h.

References flaglock_priority_inheriting_trylock(), and semaphore_get().

Referenced by xSemaphoreTakeFromISR().

◆ xSemaphoreTakeFromISR() [1/2]

_Bool xSemaphoreTakeFromISR ( SemaphoreHandle_t xSemaphore )

inlinestatic

Definition at line 362 of file semphr.h.

◆ xSemaphoreTakeFromISR() [2/2]

_Bool xSemaphoreTakeFromISR	(	SemaphoreHandle_t	xSemaphore,
		BaseType_t *	pxHigherPriorityTaskWoken )

inlinestatic

Take a semaphore from code that may run in an ISR.

CHERIoT RTOS does not permit code to run in ISRs and so this simply calls the normal code paths.

The second parameter is a pointer to a variable that will be set to true if the caller needs to yield to wake a higher-priority task. This is unconditionally false on CHERIoT RTOS because the scheduler will wake any threads that are waiting on a semaphore. It is necessary on FreeRTOS because code in ISRs cannot call into the scheduler.

Definition at line 350 of file semphr.h.

References xSemaphoreTake(), and xSemaphoreTakeFromISR().

Referenced by xSemaphoreTakeFromISR().

◆ xSemaphoreTakeRecursive()

_Bool xSemaphoreTakeRecursive	(	SemaphoreHandle_t	xMutex,
		TickType_t	xTicksToWait )

inlinestatic

Try to acquire a recursive mutex.

Returns true on success, false on failure.

Definition at line 418 of file semphr.h.

References recursivemutex_trylock().

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CHERIOT_FREERTOS_MUTEX_CASE

◆ CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE

◆ CHERIOT_FREERTOS_SEMAPHORE_CASE

◆ CHERIOT_FREERTOS_SEMAPHORE_KIND_SET

◆ CHERIOT_FREERTOS_SEMAPHORE_SWITCH

Typedef Documentation

◆ SemaphoreHandle_t

Enumeration Type Documentation

◆ CheriotFreeRTOS_SemaphoreKind

Function Documentation

◆ uxSemaphoreGetCount()

◆ vSemaphoreDelete()

◆ xSemaphoreCreateBinary()

◆ xSemaphoreCreateBinaryStatic()

◆ xSemaphoreCreateCounting()

◆ xSemaphoreCreateCountingStatic()

◆ xSemaphoreCreateMutex()

◆ xSemaphoreCreateMutexStatic()

◆ xSemaphoreCreateRecursiveMutex()

◆ xSemaphoreCreateRecursiveMutexStatic()

◆ xSemaphoreGetMutexHolder()

◆ xSemaphoreGetStaticBuffer()

◆ xSemaphoreGive()

◆ xSemaphoreGiveFromISR() [1/2]

◆ xSemaphoreGiveFromISR() [2/2]

◆ xSemaphoreGiveRecursive()

◆ xSemaphoreTake()

◆ xSemaphoreTakeFromISR() [1/2]

◆ xSemaphoreTakeFromISR() [2/2]

◆ xSemaphoreTakeRecursive()