FreeRTOS.h

Go to the documentation of this file.

/*
 * SuperTinyKernel(TM) RTOS: Lightweight High-Performance Deterministic C++ RTOS for Embedded Systems.
 *
 * Source: https://github.com/SuperTinyKernel-RTOS
 *
 * Copyright (c) 2022-2026 Neutron Code Limited <stk@neutroncode.com>. All Rights Reserved.
 * License: MIT License, see LICENSE for a full text.
 */
 
#ifndef FREERTOS_STK_H_
#define FREERTOS_STK_H_
 
#include <stdint.h>
#include <stddef.h>
 
#include "FreeRTOSConfig.h"

 
/* -------------------------------------------------------------------------
 * Portability macros - mirror what FreeRTOS normally provides via
 * FreeRTOSConfig.h + portmacro.h so that application code compiles
 * without changes when those headers are absent.
 * -------------------------------------------------------------------------*/
 
#ifndef configMAX_PRIORITIES
#define configMAX_PRIORITIES             32U
#endif
 
#ifndef configMINIMAL_STACK_SIZE
#define configMINIMAL_STACK_SIZE         128U   
#endif
 
#ifndef configTICK_RATE_HZ
#define configTICK_RATE_HZ               1000U
#endif
 
#ifndef configNUM_THREAD_LOCAL_STORAGE_POINTERS
#define configNUM_THREAD_LOCAL_STORAGE_POINTERS  4U  
#endif
 
#ifndef configTASK_NOTIFICATION_ARRAY_ENTRIES
#define configTASK_NOTIFICATION_ARRAY_ENTRIES    1U  
#endif
 
#ifndef configUSE_QUEUE_SETS
#define configUSE_QUEUE_SETS             1U  
#endif
 
#ifndef configUSE_MUTEXES
#define configUSE_MUTEXES                1U  
#endif
 
#ifndef configUSE_TIMERS
#define configUSE_TIMERS                 1U  
#endif
 
#ifndef configUSE_EVENT_GROUPS
#define configUSE_EVENT_GROUPS           1U  
#endif
 
#ifndef configUSE_STREAM_BUFFERS
#define configUSE_STREAM_BUFFERS         1U  
#endif
 
#ifndef configUSE_COUNTING_SEMAPHORES
#define configUSE_COUNTING_SEMAPHORES    1U  
#endif
 
#ifndef configUSE_TASK_NOTIFICATIONS
#define configUSE_TASK_NOTIFICATIONS     1U  
#endif
 
#ifndef configTOTAL_HEAP_SIZE
#define configTOTAL_HEAP_SIZE            10240U 
#endif

#ifndef FREERTOS_STK_MAX_TASKS
#define FREERTOS_STK_MAX_TASKS           16U
#endif

#ifndef FREERTOS_STK_DEFAULT_STACK_WORDS
#define FREERTOS_STK_DEFAULT_STACK_WORDS 256U
#endif

#ifndef FREERTOS_STK_PEND_CALL_QUEUE_SIZE
#define FREERTOS_STK_PEND_CALL_QUEUE_SIZE  8U
#endif
 
/* =========================================================================
 * Single extern "C" block - matches the cmsis_os2.h pattern.
 * All typedefs, enums, macros referencing C functions, and all function
 * declarations are enclosed here so both C and C++ translation units
 * see consistent C linkage with no per-declaration repetition.
 * =========================================================================*/
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* -------------------------------------------------------------------------
 * FreeRTOS primitive types
 * -------------------------------------------------------------------------*/
 
typedef uint32_t      TickType_t;
typedef long          BaseType_t;
typedef unsigned long UBaseType_t;
typedef long          portBASE_TYPE;
typedef uintptr_t     StackType_t;   
 
#define portMAX_DELAY        ((TickType_t)0xFFFFFFFFUL) 
#define pdTRUE               ((BaseType_t)1)
#define pdFALSE              ((BaseType_t)0)
#define pdPASS               (pdTRUE)
#define pdFAIL               (pdFALSE)
#define errQUEUE_EMPTY       ((BaseType_t)0)
#define errQUEUE_FULL        ((BaseType_t)0)
 
#ifndef configSTACK_DEPTH_TYPE
    #define configSTACK_DEPTH_TYPE StackType_t 
#endif
 
/* -------------------------------------------------------------------------
 * Task state (eTaskState)
 * -------------------------------------------------------------------------*/

typedef enum
{
    eRunning   = 0, 
    eReady,         
    eBlocked,       
    eSuspended,     
    eDeleted,       
    eInvalid        
} eTaskState;
 
/* -------------------------------------------------------------------------
 * Task notification actions (xTaskNotify)
 * -------------------------------------------------------------------------*/

typedef enum
{
    eNoAction = 0,            
    eSetBits,                 
    eIncrement,               
    eSetValueWithOverwrite,   
    eSetValueWithoutOverwrite 
} eNotifyAction;
 
/* -------------------------------------------------------------------------
 * Opaque handle types
 *
 * All handles are pointers to internal control block structs defined in
 * freertos_stk.cpp.  Application code treats them as opaque void *.
 * -------------------------------------------------------------------------*/
 
typedef void *TaskHandle_t;         
typedef void *QueueHandle_t;        
typedef void *SemaphoreHandle_t;    
typedef void *TimerHandle_t;        
typedef void *EventGroupHandle_t;   
typedef void *StreamBufferHandle_t; 
typedef void *MessageBufferHandle_t;
 
/* QueueSet is not supported; typedefs kept for compilation compatibility. */
typedef void *QueueSetHandle_t;
typedef void *QueueSetMemberHandle_t;
 
/* -------------------------------------------------------------------------
 * Function pointer types
 * -------------------------------------------------------------------------*/
 
typedef void (*TaskFunction_t)(void *pvParameters);           
typedef void (*TimerCallbackFunction_t)(TimerHandle_t xTimer);
typedef void (*PendedFunction_t)(void *pvParameter1, uint32_t ulParameter2); 

typedef void (*StreamBufferCallbackFunction_t)(
    StreamBufferHandle_t xStreamBuffer,
    BaseType_t          *pxHigherPriorityTaskWoken);
 
/* -------------------------------------------------------------------------
 * Task parameters structure
 * -------------------------------------------------------------------------*/

typedef struct
{
    const char  *pcName;       
    uint32_t     usStackDepth; 
    void        *pvParameters; 
    UBaseType_t  uxPriority;   
} TaskParameters_t;
 
/* -------------------------------------------------------------------------
 * TaskStatus_t — per-task snapshot filled by uxTaskGetSystemState()
 * -------------------------------------------------------------------------*/

typedef struct
{
    TaskHandle_t  xHandle;             
    const char   *pcTaskName;          
    eTaskState    eCurrentState;       
    UBaseType_t   uxCurrentPriority;   
    UBaseType_t   uxBasePriority;      
    uint32_t      ulRunTimeCounter;    
    StackType_t  *pxStackBase;         
    configSTACK_DEPTH_TYPE usStackHighWaterMark; 
    uint32_t      xTaskNumber;         
} TaskStatus_t;
 
/* -------------------------------------------------------------------------
 * Event group bits type
 * -------------------------------------------------------------------------*/
 
typedef uint32_t EventBits_t; 
 
/* -------------------------------------------------------------------------
 * Critical section and yield - underlying C functions called by the macros
 * below.  Declared here inside the extern "C" block so they are correctly
 * resolved whether the caller is a C or a C++ translation unit.
 * -------------------------------------------------------------------------*/

void vPortEnterCritical(void);

void vPortExitCritical(void);

void taskYIELD_impl(void);
 
#define taskENTER_CRITICAL()     vPortEnterCritical()
#define taskEXIT_CRITICAL()      vPortExitCritical()
#define taskDISABLE_INTERRUPTS() vPortEnterCritical()
#define taskENABLE_INTERRUPTS()  vPortExitCritical()
#define taskYIELD()              taskYIELD_impl()
#define portYIELD()              taskYIELD_impl()
 
/* -------------------------------------------------------------------------
 * Kernel control
 * -------------------------------------------------------------------------*/

void vTaskStartScheduler(void);

void vTaskEndScheduler(void);

void vTaskSuspendAll(void);

BaseType_t xTaskResumeAll(void);

TickType_t xTaskGetTickCount(void);

TickType_t xTaskGetTickCountFromISR(void);

UBaseType_t uxTaskGetNumberOfTasks(void);
 
/* Scheduler state constants returned by xTaskGetSchedulerState(). */
#define taskSCHEDULER_NOT_STARTED  ((BaseType_t)0) 
#define taskSCHEDULER_RUNNING      ((BaseType_t)1) 
#define taskSCHEDULER_SUSPENDED    ((BaseType_t)2) 

BaseType_t xTaskGetSchedulerState(void);
 
/* -------------------------------------------------------------------------
 * Task management
 * -------------------------------------------------------------------------*/

BaseType_t xTaskCreate(TaskFunction_t  pvTaskCode,
                       const char     *pcName,
                       uint32_t        usStackDepth,
                       void           *pvParameters,
                       UBaseType_t     uxPriority,
                       TaskHandle_t   *pxCreatedTask);

void vTaskDelete(TaskHandle_t xTaskToDelete);

#define STATIC_TASK_TCB_SIZE_WORDS  (19U + configNUM_THREAD_LOCAL_STORAGE_POINTERS \
                                         + (3U * (configTASK_NOTIFICATION_ARRAY_ENTRIES - 1U)))
typedef struct
{
    uintptr_t _opaque[STATIC_TASK_TCB_SIZE_WORDS];
} StaticTask_t;

#define STATIC_QUEUE_TCB_SIZE_WORDS  24U
typedef struct
{
    uintptr_t _opaque[STATIC_QUEUE_TCB_SIZE_WORDS];
} StaticQueue_t;

#define STATIC_SEMAPHORE_TCB_SIZE_WORDS  8U
typedef struct
{
    uintptr_t _opaque[STATIC_SEMAPHORE_TCB_SIZE_WORDS];
} StaticSemaphore_t;

#define STATIC_TIMER_TCB_SIZE_WORDS  16U
typedef struct
{
    uintptr_t _opaque[STATIC_TIMER_TCB_SIZE_WORDS];
} StaticTimer_t;

#define STATIC_EVENT_GROUP_TCB_SIZE_WORDS  10U
typedef struct
{
    uintptr_t _opaque[STATIC_EVENT_GROUP_TCB_SIZE_WORDS];
} StaticEventGroup_t;

#define STATIC_STREAM_BUFFER_TCB_SIZE_WORDS  26U
typedef struct
{
    uintptr_t _opaque[STATIC_STREAM_BUFFER_TCB_SIZE_WORDS];
} StaticStreamBuffer_t;

#define STATIC_MESSAGE_BUFFER_TCB_SIZE_WORDS  38U
typedef struct
{
    uintptr_t _opaque[STATIC_MESSAGE_BUFFER_TCB_SIZE_WORDS];
} StaticMessageBuffer_t;

TaskHandle_t xTaskCreateStatic(TaskFunction_t  pvTaskCode,
                               const char     *pcName,
                               uint32_t        ulStackDepth,
                               void           *pvParameters,
                               UBaseType_t     uxPriority,
                               StackType_t    *puxStackBuffer,
                               StaticTask_t   *pxTaskBuffer);

#ifndef portNUM_CONFIGURABLE_REGIONS
#  define portNUM_CONFIGURABLE_REGIONS 3U
#endif
typedef struct
{
    void       *pvBaseAddress;   
    uint32_t    ulLengthInBytes; 
    uint32_t    ulParameters;    
} MemoryRegion_t;

typedef struct
{
    TaskFunction_t  pvTaskCode;    
    const char     *pcName;        
    uint32_t        usStackDepth;  
    void           *pvParameters;  
    UBaseType_t     uxPriority;    
    StackType_t    *puxStackBuffer;
    StaticTask_t   *pxTaskBuffer;  
    MemoryRegion_t  xRegions[portNUM_CONFIGURABLE_REGIONS]; 
} TaskParameters_restricted_t;

BaseType_t xTaskCreateRestrictedStatic(
    const TaskParameters_restricted_t *pxTaskDefinition,
    TaskHandle_t                       *pxCreatedTask);

BaseType_t xTaskCreateRestricted(
    const TaskParameters_restricted_t *pxTaskDefinition,
    TaskHandle_t                       *pxCreatedTask);

void vTaskList(char *pcWriteBuffer);

void vTaskGetRunTimeStats(char *pcWriteBuffer);

void vTaskSuspend(TaskHandle_t xTaskToSuspend);

void vTaskResume(TaskHandle_t xTaskToResume);

BaseType_t xTaskResumeFromISR(TaskHandle_t xTaskToResume);

BaseType_t xTaskAbortDelay(TaskHandle_t xTask);

void vTaskDelay(TickType_t xTicksToDelay);

void vTaskDelayUntil(TickType_t *pxPreviousWakeTime, TickType_t xTimeIncrement);

BaseType_t xTaskDelayUntil(TickType_t *pxPreviousWakeTime, TickType_t xTimeIncrement);

void vTaskPrioritySet(TaskHandle_t xTask, UBaseType_t uxNewPriority);

UBaseType_t uxTaskPriorityGet(TaskHandle_t xTask);

UBaseType_t uxTaskPriorityGetFromISR(TaskHandle_t xTask);

eTaskState eTaskGetState(TaskHandle_t xTask);

TaskHandle_t xTaskGetCurrentTaskHandle(void);

TaskHandle_t xTaskGetHandle(const char *pcNameToQuery);

const char *pcTaskGetName(TaskHandle_t xTaskToQuery);

UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask);

configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2(TaskHandle_t xTask);

UBaseType_t uxTaskGetSystemState(TaskStatus_t    *pxTaskStatusArray,
                                  UBaseType_t      uxArraySize,
                                  uint32_t        *pulTotalRunTime);
 
/* -------------------------------------------------------------------------
 * Queue API
 * -------------------------------------------------------------------------*/

QueueHandle_t xQueueCreate(UBaseType_t uxQueueLength, UBaseType_t uxItemSize);

QueueHandle_t xQueueCreateStatic(UBaseType_t    uxQueueLength,
                                  UBaseType_t    uxItemSize,
                                  uint8_t       *pucQueueStorage,
                                  StaticQueue_t *pxStaticQueue);

void vQueueDelete(QueueHandle_t xQueue);

BaseType_t xQueueSend(QueueHandle_t xQueue,
                      const void   *pvItemToQueue,
                      TickType_t    xTicksToWait);

BaseType_t xQueueSendToBack(QueueHandle_t xQueue,
                            const void   *pvItemToQueue,
                            TickType_t    xTicksToWait);

BaseType_t xQueueSendToFront(QueueHandle_t xQueue,
                             const void   *pvItemToQueue,
                             TickType_t    xTicksToWait);

BaseType_t xQueueReceive(QueueHandle_t xQueue,
                         void         *pvBuffer,
                         TickType_t    xTicksToWait);

BaseType_t xQueuePeek(QueueHandle_t xQueue,
                      void         *pvBuffer,
                      TickType_t    xTicksToWait);

BaseType_t xQueuePeekFromISR(QueueHandle_t  xQueue,
                              void          *pvBuffer);

UBaseType_t uxQueueMessagesWaiting(QueueHandle_t xQueue);

UBaseType_t uxQueueMessagesWaitingFromISR(QueueHandle_t xQueue);

UBaseType_t uxQueueSpacesAvailable(QueueHandle_t xQueue);

BaseType_t xQueueReset(QueueHandle_t xQueue);

BaseType_t xQueueOverwrite(QueueHandle_t xQueue, const void *pvItemToQueue);

BaseType_t xQueueOverwriteFromISR(QueueHandle_t  xQueue,
                                   const void    *pvItemToQueue,
                                   BaseType_t    *pxHigherPriorityTaskWoken);

BaseType_t xQueueSendFromISR(QueueHandle_t  xQueue,
                             const void    *pvItemToQueue,
                             BaseType_t    *pxHigherPriorityTaskWoken);

BaseType_t xQueueReceiveFromISR(QueueHandle_t  xQueue,
                                void          *pvBuffer,
                                BaseType_t    *pxHigherPriorityTaskWoken);

BaseType_t xQueueSendToBackFromISR(QueueHandle_t  xQueue,
                                   const void    *pvItemToQueue,
                                   BaseType_t    *pxHigherPriorityTaskWoken);

BaseType_t xQueueSendToFrontFromISR(QueueHandle_t  xQueue,
                                    const void    *pvItemToQueue,
                                    BaseType_t    *pxHigherPriorityTaskWoken);

BaseType_t xQueueIsQueueEmptyFromISR(const QueueHandle_t xQueue);

BaseType_t xQueueIsQueueFullFromISR(const QueueHandle_t xQueue);

TaskHandle_t xQueueGetMutexHolder(QueueHandle_t xQueue);

TaskHandle_t xQueueGetMutexHolderFromISR(QueueHandle_t xQueue);
 
/* -------------------------------------------------------------------------
 * Queue Set API
 *
 * A queue set allows a single task to block on multiple queues and/or binary
 * or counting semaphores simultaneously, waking as soon as any member
 * transitions from empty to non-empty.
 *
 * Usage rules (matching the FreeRTOS API contract):
 *   1. Call xQueueCreateSet() with a capacity >= the sum of the capacities
 *      of all queues and semaphores that will be added to the set.
 *   2. Add members with xQueueAddToSet() while they are empty.
 *   3. Call xQueueSelectFromSet() or xQueueSelectFromSetFromISR() to wait for
 *      any member to receive an item.  The returned handle identifies which
 *      member fired; call xQueueReceive() or xSemaphoreTake() on that handle
 *      to consume the item.
 *   4. Remove members with xQueueRemoveFromSet() only while they are empty.
 *   5. Mutexes must not be added to queue sets.
 *
 * \warning  xQueueOverwrite / xQueueOverwriteFromISR should not be used on
 *           queues that are set members, as they generate a set notification
 *           even when replacing an existing item rather than filling a new
 *           slot, which can cause spurious wakeups.
 * -------------------------------------------------------------------------*/

QueueSetHandle_t xQueueCreateSet(UBaseType_t uxEventQueueLength);

BaseType_t xQueueAddToSet(QueueSetMemberHandle_t xQueueOrSemaphore,
                          QueueSetHandle_t       xQueueSet);

BaseType_t xQueueRemoveFromSet(QueueSetMemberHandle_t xQueueOrSemaphore,
                               QueueSetHandle_t       xQueueSet);

QueueSetMemberHandle_t xQueueSelectFromSet(QueueSetHandle_t xQueueSet,
                                           TickType_t       xTicksToWait);

QueueSetMemberHandle_t xQueueSelectFromSetFromISR(QueueSetHandle_t xQueueSet);
 
/* -------------------------------------------------------------------------
 * Semaphore / Mutex API
 * -------------------------------------------------------------------------*/

SemaphoreHandle_t xSemaphoreCreateBinary(void);

SemaphoreHandle_t xSemaphoreCreateBinaryStatic(StaticSemaphore_t *pxSemaphoreBuffer);

SemaphoreHandle_t xSemaphoreCreateCounting(UBaseType_t uxMaxCount,
                                           UBaseType_t uxInitialCount);

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

SemaphoreHandle_t xSemaphoreCreateMutex(void);

SemaphoreHandle_t xSemaphoreCreateMutexStatic(StaticSemaphore_t *pxMutexBuffer);

SemaphoreHandle_t xSemaphoreCreateRecursiveMutex(void);

SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic(StaticSemaphore_t *pxMutexBuffer);

void vSemaphoreDelete(SemaphoreHandle_t xSemaphore);

BaseType_t xSemaphoreTake(SemaphoreHandle_t xSemaphore, TickType_t xTicksToWait);

BaseType_t xSemaphoreTakeFromISR(SemaphoreHandle_t xSemaphore,
                                  BaseType_t       *pxHigherPriorityTaskWoken);

BaseType_t xSemaphoreTakeRecursive(SemaphoreHandle_t xMutex, TickType_t xTicksToWait);

BaseType_t xSemaphoreGive(SemaphoreHandle_t xSemaphore);

BaseType_t xSemaphoreGiveRecursive(SemaphoreHandle_t xMutex);

BaseType_t xSemaphoreGiveFromISR(SemaphoreHandle_t xSemaphore,
                                 BaseType_t       *pxHigherPriorityTaskWoken);

UBaseType_t uxSemaphoreGetCount(SemaphoreHandle_t xSemaphore);

TaskHandle_t xSemaphoreGetMutexHolder(SemaphoreHandle_t xMutex);

TaskHandle_t xSemaphoreGetMutexHolderFromISR(SemaphoreHandle_t xMutex);
 
/* -------------------------------------------------------------------------
 * Software Timer API
 * -------------------------------------------------------------------------*/

TimerHandle_t xTimerCreate(const char             *pcTimerName,
                           TickType_t              xTimerPeriodInTicks,
                           UBaseType_t             uxAutoReload,
                           void                   *pvTimerID,
                           TimerCallbackFunction_t  pxCallbackFunction);

TimerHandle_t xTimerCreateStatic(const char             *pcTimerName,
                                  TickType_t              xTimerPeriodInTicks,
                                  UBaseType_t             uxAutoReload,
                                  void                   *pvTimerID,
                                  TimerCallbackFunction_t  pxCallbackFunction,
                                  StaticTimer_t           *pxTimerBuffer);

BaseType_t xTimerDelete(TimerHandle_t xTimer, TickType_t xTicksToWait);

BaseType_t xTimerStart(TimerHandle_t xTimer, TickType_t xTicksToWait);

BaseType_t xTimerStop(TimerHandle_t xTimer, TickType_t xTicksToWait);

BaseType_t xTimerReset(TimerHandle_t xTimer, TickType_t xTicksToWait);

BaseType_t xTimerChangePeriod(TimerHandle_t xTimer,
                              TickType_t    xNewPeriod,
                              TickType_t    xTicksToWait);

BaseType_t xTimerIsTimerActive(TimerHandle_t xTimer);

void *pvTimerGetTimerID(TimerHandle_t xTimer);

void vTimerSetTimerID(TimerHandle_t xTimer, void *pvNewID);

const char *pcTimerGetName(TimerHandle_t xTimer);

TickType_t xTimerGetPeriod(TimerHandle_t xTimer);

TickType_t xTimerGetExpiryTime(TimerHandle_t xTimer);
 
/* -------------------------------------------------------------------------
 * Timer ISR API
 *
 * These functions are safe to call from an interrupt service routine.  They
 * post a command to the TimerHost command queue (a stk::sync::PipeT write
 * with NO_WAIT) and return immediately without blocking.
 *
 * The xTicksToWait parameter is accepted for FreeRTOS API compatibility but
 * is always ignored: the STK command queue write is non-blocking by design
 * (PipeT::TryWrite / NO_WAIT), so there is no meaningful timeout to honour
 * from ISR context.  If the command queue is full the function returns pdFAIL.
 *
 * pxHigherPriorityTaskWoken is always set to pdFALSE.  STK's tick task wakes
 * itself via the command queue CV, which is handled internally by the
 * scheduler without requiring the ISR to request a manual context switch.
 * -------------------------------------------------------------------------*/

BaseType_t xTimerStartFromISR(TimerHandle_t xTimer,
                               BaseType_t   *pxHigherPriorityTaskWoken);

BaseType_t xTimerStopFromISR(TimerHandle_t xTimer,
                              BaseType_t   *pxHigherPriorityTaskWoken);

BaseType_t xTimerResetFromISR(TimerHandle_t xTimer,
                               BaseType_t   *pxHigherPriorityTaskWoken);

BaseType_t xTimerChangePeriodFromISR(TimerHandle_t xTimer,
                                      TickType_t    xNewPeriod,
                                      BaseType_t   *pxHigherPriorityTaskWoken);

BaseType_t xTimerPendFunctionCall(PendedFunction_t xFunctionToPend,
                                   void            *pvParameter1,
                                   uint32_t         ulParameter2,
                                   TickType_t       xTicksToWait);

BaseType_t xTimerPendFunctionCallFromISR(PendedFunction_t  xFunctionToPend,
                                          void             *pvParameter1,
                                          uint32_t          ulParameter2,
                                          BaseType_t       *pxHigherPriorityTaskWoken);
 
/* -------------------------------------------------------------------------
 * Event Group API
 * -------------------------------------------------------------------------*/

EventGroupHandle_t xEventGroupCreate(void);

EventGroupHandle_t xEventGroupCreateStatic(StaticEventGroup_t *pxEventGroupBuffer);

void vEventGroupDelete(EventGroupHandle_t xEventGroup);

EventBits_t xEventGroupSetBits(EventGroupHandle_t xEventGroup,
                               EventBits_t        uxBitsToSet);

EventBits_t xEventGroupClearBits(EventGroupHandle_t xEventGroup,
                                 EventBits_t        uxBitsToClear);

EventBits_t xEventGroupGetBits(EventGroupHandle_t xEventGroup);

EventBits_t xEventGroupWaitBits(EventGroupHandle_t xEventGroup,
                                EventBits_t        uxBitsToWaitFor,
                                BaseType_t         xClearOnExit,
                                BaseType_t         xWaitForAllBits,
                                TickType_t         xTicksToWait);

BaseType_t xEventGroupSetBitsFromISR(EventGroupHandle_t  xEventGroup,
                                     EventBits_t         uxBitsToSet,
                                     BaseType_t         *pxHigherPriorityTaskWoken);

EventBits_t xEventGroupClearBitsFromISR(EventGroupHandle_t xEventGroup,
                                        EventBits_t        uxBitsToClear);

EventBits_t xEventGroupSync(EventGroupHandle_t xEventGroup,
                            EventBits_t        uxBitsToSet,
                            EventBits_t        uxBitsToWaitFor,
                            TickType_t         xTicksToWait);
 
/* -------------------------------------------------------------------------
 * Task Notification API
 *
 * Non-indexed variants always operate on slot 0 and are thin wrappers around
 * the indexed variants below.  Indexed variants accept a slot index in the
 * range [0, configTASK_NOTIFICATION_ARRAY_ENTRIES).
 * -------------------------------------------------------------------------*/

BaseType_t xTaskNotifyGive(TaskHandle_t xTaskToNotify);

uint32_t ulTaskNotifyTake(BaseType_t ulClearCountOnExit, TickType_t xTicksToWait);

BaseType_t xTaskNotify(TaskHandle_t  xTaskToNotify,
                       uint32_t      ulValue,
                       eNotifyAction eAction);

BaseType_t xTaskNotifyWait(uint32_t   ulBitsToClearOnEntry,
                           uint32_t   ulBitsToClearOnExit,
                           uint32_t  *pulNotificationValue,
                           TickType_t xTicksToWait);

BaseType_t xTaskNotifyFromISR(TaskHandle_t  xTaskToNotify,
                              uint32_t      ulValue,
                              eNotifyAction eAction,
                              BaseType_t   *pxHigherPriorityTaskWoken);
 
/* -------------------------------------------------------------------------
 * Task Notification — Indexed API
 *
 * Each task has configTASK_NOTIFICATION_ARRAY_ENTRIES independent notification
 * slots, indexed 0 .. configTASK_NOTIFICATION_ARRAY_ENTRIES-1.  Each slot
 * is backed by its own stk::sync::Semaphore + value word + pending flag,
 * matching the per-slot isolation guarantee of the FreeRTOS reference implementation.
 *
 * Out-of-range uxIndexToNotify / uxIndexToWait causes an assertion in debug
 * builds and is treated as a no-op / failure in release builds.
 * -------------------------------------------------------------------------*/

BaseType_t xTaskNotifyGiveIndexed(TaskHandle_t xTaskToNotify,
                                  UBaseType_t  uxIndexToNotify);

uint32_t ulTaskNotifyTakeIndexed(UBaseType_t uxIndexToWait,
                                 BaseType_t  ulClearCountOnExit,
                                 TickType_t  xTicksToWait);

BaseType_t xTaskNotifyIndexed(TaskHandle_t  xTaskToNotify,
                               UBaseType_t   uxIndexToNotify,
                               uint32_t      ulValue,
                               eNotifyAction eAction);

BaseType_t xTaskNotifyWaitIndexed(UBaseType_t  uxIndexToWait,
                                   uint32_t     ulBitsToClearOnEntry,
                                   uint32_t     ulBitsToClearOnExit,
                                   uint32_t    *pulNotificationValue,
                                   TickType_t   xTicksToWait);

BaseType_t xTaskNotifyFromISRIndexed(TaskHandle_t  xTaskToNotify,
                                      UBaseType_t   uxIndexToNotify,
                                      uint32_t      ulValue,
                                      eNotifyAction eAction,
                                      BaseType_t   *pxHigherPriorityTaskWoken);
 
/* -------------------------------------------------------------------------
 * Task Notification — AndQuery / StateClear / ValueClear extensions
 *
 * These functions extend the notification API with query-on-send and
 * targeted clear operations, matching the FreeRTOS 10.4+ additions.
 * -------------------------------------------------------------------------*/

BaseType_t xTaskNotifyAndQuery(TaskHandle_t  xTaskToNotify,
                               uint32_t      ulValue,
                               eNotifyAction eAction,
                               uint32_t     *pulPreviousNotifyValue);

BaseType_t xTaskNotifyAndQueryIndexed(TaskHandle_t  xTaskToNotify,
                                      UBaseType_t   uxIndexToNotify,
                                      uint32_t      ulValue,
                                      eNotifyAction eAction,
                                      uint32_t     *pulPreviousNotifyValue);

BaseType_t xTaskNotifyAndQueryFromISR(TaskHandle_t  xTaskToNotify,
                                      uint32_t      ulValue,
                                      eNotifyAction eAction,
                                      uint32_t     *pulPreviousNotifyValue,
                                      BaseType_t   *pxHigherPriorityTaskWoken);

BaseType_t xTaskNotifyAndQueryFromISRIndexed(TaskHandle_t  xTaskToNotify,
                                             UBaseType_t   uxIndexToNotify,
                                             uint32_t      ulValue,
                                             eNotifyAction eAction,
                                             uint32_t     *pulPreviousNotifyValue,
                                             BaseType_t   *pxHigherPriorityTaskWoken);

BaseType_t xTaskNotifyStateClear(TaskHandle_t xTask);

BaseType_t xTaskNotifyStateClearIndexed(TaskHandle_t xTask,
                                        UBaseType_t  uxIndexToClear);

uint32_t ulTaskNotifyValueClear(TaskHandle_t xTask,
                                uint32_t     ulBitsToClear);

uint32_t ulTaskNotifyValueClearIndexed(TaskHandle_t xTask,
                                       UBaseType_t  uxIndexToClear,
                                       uint32_t     ulBitsToClear);
 
/* -------------------------------------------------------------------------
 * Thread-local storage (TLS) API
 *
 * Each task has a fixed-size array of configNUM_THREAD_LOCAL_STORAGE_POINTERS
 * void* slots, indexed 0 .. configNUM_THREAD_LOCAL_STORAGE_POINTERS-1.
 * The slots are initialised to NULL at task creation.
 * Passing NULL for xTaskToQuery/xTaskToSet selects the calling task.
 * -------------------------------------------------------------------------*/

void vTaskSetThreadLocalStoragePointer(TaskHandle_t xTaskToSet,
                                       BaseType_t   xIndex,
                                       void        *pvValue);

void *pvTaskGetThreadLocalStoragePointer(TaskHandle_t xTaskToQuery,
                                          BaseType_t   xIndex);
 
/* -------------------------------------------------------------------------
 * Stream Buffer API
 *
 * A stream buffer is a lightweight, ISR-safe byte-stream FIFO backed by a
 * stk::sync::MessageQueue with msg_size = 1.  Producers write arbitrary-length
 * byte spans; consumers read arbitrary-length spans.  A trigger level can be
 * set so that Receive() blocks until at least N bytes are available.
 *
 * xStreamBufferCreate()       - heap-allocated control block + data buffer.
 * xStreamBufferCreateStatic() - caller-supplied StaticStreamBuffer_t TCB and
 *                               pucStreamBufferStorageArea data buffer (no heap).
 *
 * ISR variants (SendFromISR / ReceiveFromISR) are non-blocking (NO_WAIT).
 * Passing NULL for pxHigherPriorityTaskWoken is safe; it is always set to
 * pdFALSE because STK handles scheduling internally.
 * -------------------------------------------------------------------------*/

StreamBufferHandle_t xStreamBufferCreate(size_t xBufferSizeBytes,
                                          size_t xTriggerLevelBytes);

StreamBufferHandle_t xStreamBufferCreateStatic(
    size_t                xBufferSizeBytes,
    size_t                xTriggerLevelBytes,
    uint8_t              *pucStreamBufferStorageArea,
    StaticStreamBuffer_t *pxStaticStreamBuffer);

void vStreamBufferDelete(StreamBufferHandle_t xStreamBuffer);

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

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

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

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

size_t xStreamBufferBytesAvailable(StreamBufferHandle_t xStreamBuffer);

size_t xStreamBufferSpacesAvailable(StreamBufferHandle_t xStreamBuffer);

BaseType_t xStreamBufferIsEmpty(StreamBufferHandle_t xStreamBuffer);

BaseType_t xStreamBufferIsFull(StreamBufferHandle_t xStreamBuffer);

BaseType_t xStreamBufferReset(StreamBufferHandle_t xStreamBuffer);

BaseType_t xStreamBufferResetFromISR(StreamBufferHandle_t  xStreamBuffer,
                                      BaseType_t           *pxHigherPriorityTaskWoken);

BaseType_t xStreamBufferSetTriggerLevel(StreamBufferHandle_t xStreamBuffer,
                                         size_t               xTriggerLevelBytes);

size_t xStreamBufferGetTriggerLevel(StreamBufferHandle_t xStreamBuffer);

size_t xStreamBufferNextMessageLengthBytes(StreamBufferHandle_t xStreamBuffer);

StreamBufferHandle_t xStreamBufferCreateWithCallback(
    size_t                         xBufferSizeBytes,
    size_t                         xTriggerLevelBytes,
    StreamBufferCallbackFunction_t pxSendCompletedCallback,
    StreamBufferCallbackFunction_t pxReceiveCompletedCallback);

StreamBufferHandle_t xStreamBufferCreateStaticWithCallback(
    size_t                         xBufferSizeBytes,
    size_t                         xTriggerLevelBytes,
    uint8_t                       *pucStreamBufferStorageArea,
    StaticStreamBuffer_t          *pxStaticStreamBuffer,
    StreamBufferCallbackFunction_t pxSendCompletedCallback,
    StreamBufferCallbackFunction_t pxReceiveCompletedCallback);
 
/* -------------------------------------------------------------------------
 * Message Buffer API
 *
 * A message buffer carries discrete, variable-length messages.  Each message
 * is stored as a pool block (payload) plus an envelope {size, block*} in a
 * separate queue.  Receive() always returns exactly one complete message.
 *
 * Backed by:
 *   - stk::memory::BlockMemoryPool — fixed-size payload blocks
 *     (block size = AlignBlockSize(xMaxMessageSize)).
 *   - stk::sync::MessageQueue      — envelope FIFO of {len, block*} structs,
 *     providing correct blocking on both "pool full" and "queue empty".
 *
 * xMessageBufferCreate()                    - heap-allocated control block + pool storage.
 * xMessageBufferCreateStatic()              - caller-supplied TCB and storage buffer.
 * xMessageBufferCreateWithCallback()        - heap-allocated + send/recv callbacks.
 * xMessageBufferCreateStaticWithCallback()  - static + send/recv callbacks.
 * -------------------------------------------------------------------------*/

MessageBufferHandle_t xMessageBufferCreate(size_t xBufferSizeBytes,
                                            size_t xMaxMessageSize);

MessageBufferHandle_t xMessageBufferCreateStatic(
    size_t                 xMaxMessageSize,
    size_t                 xMessageCount,
    uint8_t               *pucMessageBufferStorageArea,
    StaticMessageBuffer_t *pxStaticMessageBuffer);

MessageBufferHandle_t xMessageBufferCreateWithCallback(
    size_t                         xBufferSizeBytes,
    size_t                         xMaxMessageSize,
    StreamBufferCallbackFunction_t pxSendCompletedCallback,
    StreamBufferCallbackFunction_t pxReceiveCompletedCallback);

MessageBufferHandle_t xMessageBufferCreateStaticWithCallback(
    size_t                         xMaxMessageSize,
    size_t                         xMessageCount,
    uint8_t                       *pucMessageBufferStorageArea,
    StaticMessageBuffer_t         *pxStaticMessageBuffer,
    StreamBufferCallbackFunction_t pxSendCompletedCallback,
    StreamBufferCallbackFunction_t pxReceiveCompletedCallback);

void vMessageBufferDelete(MessageBufferHandle_t xMessageBuffer);

size_t xMessageBufferSend(MessageBufferHandle_t xMessageBuffer,
                           const void           *pvTxData,
                           size_t                xDataLengthBytes,
                           TickType_t            xTicksToWait);

size_t xMessageBufferSendFromISR(MessageBufferHandle_t  xMessageBuffer,
                                  const void            *pvTxData,
                                  size_t                 xDataLengthBytes,
                                  BaseType_t            *pxHigherPriorityTaskWoken);

size_t xMessageBufferReceive(MessageBufferHandle_t xMessageBuffer,
                              void                 *pvRxData,
                              size_t                xBufferLengthBytes,
                              TickType_t            xTicksToWait);

size_t xMessageBufferReceiveFromISR(MessageBufferHandle_t  xMessageBuffer,
                                     void                  *pvRxData,
                                     size_t                 xBufferLengthBytes,
                                     BaseType_t            *pxHigherPriorityTaskWoken);

BaseType_t xMessageBufferIsEmpty(MessageBufferHandle_t xMessageBuffer);

BaseType_t xMessageBufferIsFull(MessageBufferHandle_t xMessageBuffer);

size_t xMessageBufferSpacesAvailable(MessageBufferHandle_t xMessageBuffer);

size_t xMessageBufferNextLengthBytes(MessageBufferHandle_t xMessageBuffer);

BaseType_t xMessageBufferReset(MessageBufferHandle_t xMessageBuffer);

BaseType_t xMessageBufferResetFromISR(MessageBufferHandle_t  xMessageBuffer,
                                       BaseType_t            *pxHigherPriorityTaskWoken);
 
/* -------------------------------------------------------------------------
 * Heap API
 *
 * pvPortMalloc / vPortFree are thin wrappers around
 * stk::memory::MemoryAllocator::Allocate / Free — the same allocation seam
 * used internally by all STK and FreeRTOS-STK objects.  Replacing the two
 * MemoryAllocator definitions in freertos_stk.cpp (e.g. to point at a static
 * pool) automatically redirects both the internal and application-facing heap.
 *
 * xPortGetFreeHeapSize / xPortGetMinimumEverFreeHeapSize / vPortGetHeapStats
 * read from the same s_MemStats accounting structure maintained by
 * MemoryAllocator::Allocate() and ::Free().
 * -------------------------------------------------------------------------*/

typedef struct
{
    size_t xAvailableHeapSpaceInBytes;      
    size_t xSizeOfLargestFreeBlockInBytes;  
    size_t xSizeOfSmallestFreeBlockInBytes; 
    size_t xNumberOfFreeBlocks;             
    size_t xMinimumEverFreeBytesRemaining;  
    size_t xNumberOfSuccessfulAllocations;  
    size_t xNumberOfSuccessfulFrees;        
} HeapStats_t;

void *pvPortMalloc(size_t xWantedSize);

void vPortFree(void *pv);

size_t xPortGetFreeHeapSize(void);

size_t xPortGetMinimumEverFreeHeapSize(void);

void vPortGetHeapStats(HeapStats_t *pxHeapStats);
 
/* -------------------------------------------------------------------------
 * Convenience macros matching standard FreeRTOS naming conventions
 * -------------------------------------------------------------------------*/
 
#define pdMS_TO_TICKS(xTimeInMs)  ((TickType_t)(xTimeInMs)) 
#define tskIDLE_PRIORITY          ((UBaseType_t)0U)          
#define xTaskHandle               TaskHandle_t               
 
#ifdef __cplusplus
}
#endif

 
#endif /* FREERTOS_STK_H_ */