semphr.h

Go to the documentation of this file.

#pragma once
/**
 * \file
 * 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.
 */
#include "FreeRTOS.h"
#include <locks.h>
#include <stdatomic.h>
 
#if !defined(CHERIOT_EXPOSE_FREERTOS_SEMAPHORE) &&                             \
  !defined(CHERIOT_EXPOSE_FREERTOS_MUTEX) &&                                   \
  !defined(CHERIOT_EXPOSE_FREERTOS_RECURSIVE_MUTEX)
#   error At least one out of CHERIOT_EXPOSE_FREERTOS_SEMAPHORE, \
  CHERIOT_EXPOSE_FREERTOS_MUTEX, or CHERIOT_EXPOSE_FREERTOS_RECURSIVE_MUTEX \
  must be defined.
#endif
 
#ifdef CHERIOT_EXPOSE_FREERTOS_SEMAPHORE
#   define CHERIOT_FREERTOS_SEMAPHORE_CASE(x)                                 \
        case CheriotFreeRTOS_Semaphore:                                        \
            x;                                                                 \
            break;
#else
#   define CHERIOT_FREERTOS_SEMAPHORE_CASE(x)
#endif
 
#ifdef CHERIOT_EXPOSE_FREERTOS_MUTEX
#   define CHERIOT_FREERTOS_MUTEX_CASE(x)                                     \
        case CheriotFreeRTOS_Mutex:                                            \
            x;                                                                 \
            break;
#else
#   define CHERIOT_FREERTOS_MUTEX_CASE(x)
#endif
 
#ifdef CHERIOT_EXPOSE_FREERTOS_RECURSIVE_MUTEX
#   define CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE(x)                           \
        case CheriotFreeRTOS_RecursiveMutex:                                   \
            x;                                                                 \
            break;
#else
#   define CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE(x)
#endif
 
/**
 * Enumeration used to differentiate the different kinds of FreeRTOS semaphores
 * in this compatibility layer.
 */
enum CheriotFreeRTOS_SemaphoreKind : uint8_t
{
#ifdef CHERIOT_EXPOSE_FREERTOS_SEMAPHORE
    /**
     * A FreeRTOS counting or binary semaphore.
     */
    CheriotFreeRTOS_Semaphore,
#endif
#ifdef CHERIOT_EXPOSE_FREERTOS_MUTEX
    /**
     * A non-recursive, priority-inheriting mutex.
     */
    CheriotFreeRTOS_Mutex,
#endif
#ifdef CHERIOT_EXPOSE_FREERTOS_RECURSIVE_MUTEX
    /**
     * A recursive mutex.
     */
    CheriotFreeRTOS_RecursiveMutex,
#endif
};
 
/**
 * Type used to define space for storing any of the exposed FreeRTOS semaphore
 * types.
 */
typedef struct
{
    /**
     * The state for the various kinds of FreeRTOS semaphores.
     */
    union
    {
#ifdef CHERIOT_EXPOSE_FREERTOS_RECURSIVE_MUTEX
        struct RecursiveMutexState recursiveMutex;
#endif
#ifdef CHERIOT_EXPOSE_FREERTOS_MUTEX
        struct FlagLockState mutex;
#endif
#ifdef CHERIOT_EXPOSE_FREERTOS_SEMAPHORE
        struct CountingSemaphoreState semaphore;
#endif
    };
#if (defined(CHERIOT_EXPOSE_FREERTOS_SEMAPHORE) +                              \
     defined(CHERIOT_EXPOSE_FREERTOS_MUTEX) +                                  \
     defined(CHERIOT_EXPOSE_FREERTOS_RECURSIVE_MUTEX)) > 1
#   define CHERIOT_FREERTOS_SEMAPHORE_SWITCH(x) switch (x->kind)
    /**
     * The discriminator for the union above.  If only one kind of semaphore is
     * supported, this is omitted.
     */
    enum CheriotFreeRTOS_SemaphoreKind kind;
#   define CHERIOT_FREERTOS_SEMAPHORE_KIND_SET(x, y) x->kind = y
#else
#   if defined(CHERIOT_EXPOSE_FREERTOS_RECURSIVE_MUTEX)
#       define CHERIOT_FREERTOS_SEMAPHORE_SWITCH(x)                           \
            switch (CheriotFreeRTOS_RecursiveMutex)
#   elif defined(CHERIOT_EXPOSE_FREERTOS_MUTEX)
#       define CHERIOT_FREERTOS_SEMAPHORE_SWITCH(x)                           \
            switch (CheriotFreeRTOS_Mutex)
#   elif defined(CHERIOT_EXPOSE_FREERTOS_SEMAPHORE)
#       define CHERIOT_FREERTOS_SEMAPHORE_SWITCH(x)                           \
            switch (CheriotFreeRTOS_Semaphore)
#   endif
 
#   define CHERIOT_FREERTOS_SEMAPHORE_KIND_SET(x, y)
#endif
} StaticSemaphore_t;
 
/**
 * Type for a handle to a counting semaphore.
 */
typedef StaticSemaphore_t *SemaphoreHandle_t;
 
#ifdef CHERIOT_EXPOSE_FREERTOS_SEMAPHORE
/**
 * Initialise a statically allocated semaphore.  The initial value and maximum
 * are specified with `uxInitialCount` and `uxMaxCount` respectively.
 *
 * Returns a pointer to the semaphore.
 */
__always_inline static inline SemaphoreHandle_t
xSemaphoreCreateCountingStatic(UBaseType_t        uxMaxCount,
                               UBaseType_t        uxInitialCount,
                               StaticSemaphore_t *pxSemaphoreBuffer)
{
    pxSemaphoreBuffer->semaphore.maxCount = uxMaxCount;
#   ifdef __cplusplus
    pxSemaphoreBuffer->semaphore.count = uxInitialCount;
#   else
    // In C mode, we don't want a variable-sized atomic store here!
    atomic_init(&pxSemaphoreBuffer->semaphore.count, uxInitialCount);
#   endif
    CHERIOT_FREERTOS_SEMAPHORE_KIND_SET(pxSemaphoreBuffer,
                                        CheriotFreeRTOS_Semaphore);
    return pxSemaphoreBuffer;
}
 
#   ifndef CHERIOT_NO_AMBIENT_MALLOC
/**
 * 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.
 */
__always_inline static inline SemaphoreHandle_t
xSemaphoreCreateCounting(UBaseType_t uxMaxCount, UBaseType_t uxInitialCount)
{
    SemaphoreHandle_t semaphore =
      (SemaphoreHandle_t)malloc(sizeof(StaticSemaphore_t));
    if (semaphore != NULL)
    {
        xSemaphoreCreateCountingStatic(uxMaxCount, uxInitialCount, semaphore);
    }
    return semaphore;
}
#   endif
 
/**
 * Create a heap-allocated binary semaphore.
 *
 * Binary semaphores are implemented as counting semaphores with a maximum count
 * of 1.
 */
__always_inline static inline SemaphoreHandle_t xSemaphoreCreateBinary()
{
    return xSemaphoreCreateCounting(1, 0);
}
 
/**
 * Create a statically allocated binary semaphore.
 *
 * Binary semaphores are implemented as counting semaphores with a maximum count
 * of 1.
 */
__always_inline static inline SemaphoreHandle_t
xSemaphoreCreateBinaryStatic(StaticSemaphore_t *pxSemaphoreBuffer)
{
    return xSemaphoreCreateCountingStatic(1, 0, pxSemaphoreBuffer);
}
#endif
 
#ifdef CHERIOT_EXPOSE_FREERTOS_MUTEX
/**
 * Create statically allocated mutex.
 */
__always_inline static inline SemaphoreHandle_t
xSemaphoreCreateMutexStatic(StaticSemaphore_t *pxMutexBuffer)
{
    pxMutexBuffer->mutex.lockWord = 0;
    CHERIOT_FREERTOS_SEMAPHORE_KIND_SET(pxMutexBuffer, CheriotFreeRTOS_Mutex);
    return pxMutexBuffer;
}
 
#   ifndef CHERIOT_NO_AMBIENT_MALLOC
/**
 * Create a heap-allocated mutex.
 */
__always_inline static inline SemaphoreHandle_t xSemaphoreCreateMutex()
{
    SemaphoreHandle_t semaphore =
      (SemaphoreHandle_t)malloc(sizeof(StaticSemaphore_t));
    if (semaphore != NULL)
    {
        xSemaphoreCreateMutexStatic(semaphore);
    }
    return semaphore;
}
#   endif
#endif
 
#ifdef CHERIOT_EXPOSE_FREERTOS_RECURSIVE_MUTEX
 
/**
 * Create a statically allocated recursive mutex.
 */
__always_inline static inline SemaphoreHandle_t
xSemaphoreCreateRecursiveMutexStatic(StaticSemaphore_t *pxMutexBuffer)
{
    pxMutexBuffer->recursiveMutex.lock.lockWord = 0;
    pxMutexBuffer->recursiveMutex.depth         = 0;
    CHERIOT_FREERTOS_SEMAPHORE_KIND_SET(pxMutexBuffer,
                                        CheriotFreeRTOS_RecursiveMutex);
    return pxMutexBuffer;
}
 
#   ifndef CHERIOT_NO_AMBIENT_MALLOC
/**
 * Create a heap-allocated recursive mutex.
 */
__always_inline static inline SemaphoreHandle_t
xSemaphoreCreateRecursiveMutex(void)
{
    SemaphoreHandle_t semaphore =
      (SemaphoreHandle_t)malloc(sizeof(StaticSemaphore_t));
    if (semaphore != NULL)
    {
        xSemaphoreCreateRecursiveMutexStatic(semaphore);
    }
    return semaphore;
}
#   endif
#endif
 
/**
 * 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).
 */
__always_inline static inline void
vSemaphoreDelete(SemaphoreHandle_t xSemaphore)
{
    free(xSemaphore);
}
 
/**
 * 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.
 */
__always_inline static inline TaskHandle_t
xSemaphoreGetMutexHolder(SemaphoreHandle_t xMutex)
{
    CHERIOT_FREERTOS_SEMAPHORE_SWITCH(xMutex)
    {
        CHERIOT_FREERTOS_SEMAPHORE_CASE(return 0;)
        CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE(
          return xMutex->recursiveMutex.lock.lockWord & 0xffff;)
        CHERIOT_FREERTOS_MUTEX_CASE(return xMutex->mutex.lockWord & 0xffff;)
    }
    return 0;
}
 
/**
 * 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.
 */
static inline UBaseType_t uxSemaphoreGetCount(SemaphoreHandle_t xSemaphore)
{
    CHERIOT_FREERTOS_SEMAPHORE_SWITCH(xSemaphore)
    {
        CHERIOT_FREERTOS_SEMAPHORE_CASE(return xSemaphore->semaphore.count;)
        CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE(
          return xSemaphore->recursiveMutex.lock.lockWord != 0;)
        CHERIOT_FREERTOS_MUTEX_CASE(return xSemaphore->mutex.lockWord != 0;)
    }
    return 0;
}
 
/**
 * 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.
 */
static inline _Bool xSemaphoreTake(SemaphoreHandle_t xSemaphore,
                                   TickType_t        xTicksToWait)
{
    Timeout t   = {0, xTicksToWait};
    int     ret = -1;
    CHERIOT_FREERTOS_SEMAPHORE_SWITCH(xSemaphore)
    {
        CHERIOT_FREERTOS_SEMAPHORE_CASE(
          ret = semaphore_get(&t, &xSemaphore->semaphore);)
        CHERIOT_FREERTOS_MUTEX_CASE(
          ret = flaglock_priority_inheriting_trylock(&t, &xSemaphore->mutex);)
        // Recursive mutexes are not supposed to use this interface.
        CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE(;);
    }
    return ret == 0;
}
 
/**
 * 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.
 */
__always_inline static inline _Bool __attribute__((overloadable))
xSemaphoreTakeFromISR(SemaphoreHandle_t xSemaphore,
                      BaseType_t       *pxHigherPriorityTaskWoken)
{
    *pxHigherPriorityTaskWoken = 0;
    return xSemaphoreTake(xSemaphore, 0);
}
 
/*
 * 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.
 */
__always_inline static inline _Bool __attribute__((overloadable))
xSemaphoreTakeFromISR(SemaphoreHandle_t xSemaphore)
{
    return xSemaphoreTake(xSemaphore, 0);
}
 
/**
 * 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.
 */
__always_inline static inline _Bool xSemaphoreGive(SemaphoreHandle_t xSemaphore)
{
    int ret = -1;
    CHERIOT_FREERTOS_SEMAPHORE_SWITCH(xSemaphore)
    {
        CHERIOT_FREERTOS_SEMAPHORE_CASE(
          ret = semaphore_put(&xSemaphore->semaphore);)
        CHERIOT_FREERTOS_MUTEX_CASE(flaglock_unlock(&xSemaphore->mutex);
                                    ret = 0;)
        // Recursive mutexes are not supposed to use this interface.
        CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE(;);
    }
    return ret == 0;
}
 
/**
 * 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.
 */
__always_inline static inline _Bool __attribute__((overloadable))
xSemaphoreGiveFromISR(SemaphoreHandle_t xSemaphore,
                      BaseType_t       *pxHigherPriorityTaskWoken)
{
    *pxHigherPriorityTaskWoken = 0;
    return xSemaphoreGive(xSemaphore);
}
 
/*
 * 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.
 */
__always_inline static inline _Bool __attribute__((overloadable))
xSemaphoreGiveFromISR(SemaphoreHandle_t xSemaphore)
{
    return xSemaphoreGive(xSemaphore);
}
 
/**
 * Try to acquire a recursive mutex.  Returns true on success, false on
 * failure.
 */
__always_inline static inline _Bool
xSemaphoreTakeRecursive(SemaphoreHandle_t xMutex, TickType_t xTicksToWait)
{
    Timeout t   = {0, xTicksToWait};
    int     ret = -1;
    CHERIOT_FREERTOS_SEMAPHORE_SWITCH(xMutex)
    {
        CHERIOT_FREERTOS_SEMAPHORE_CASE(;)
        CHERIOT_FREERTOS_MUTEX_CASE(;)
        CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE(
          ret = recursivemutex_trylock(&t, &xMutex->recursiveMutex);)
    }
    return ret == 0;
}
 
/**
 * Release a recursive mutex.
 */
__always_inline static inline _Bool
xSemaphoreGiveRecursive(SemaphoreHandle_t xMutex)
{
    int ret = -1;
    CHERIOT_FREERTOS_SEMAPHORE_SWITCH(xMutex)
    {
        CHERIOT_FREERTOS_SEMAPHORE_CASE(;)
        CHERIOT_FREERTOS_MUTEX_CASE(;)
        CHERIOT_FREERTOS_RECURSIVE_MUTEX_CASE(
          ret = recursivemutex_unlock(&xMutex->recursiveMutex);)
    }
    return ret == 0;
}
 
/**
 * Launder a semaphore back into the type used to initialise it.
 */
__always_inline static inline BaseType_t
xSemaphoreGetStaticBuffer(SemaphoreHandle_t   xSemaphore,
                          StaticSemaphore_t **ppxSemaphoreBuffer)
{
    *ppxSemaphoreBuffer = xSemaphore;
    return pdTRUE;
}