SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
STK FreeRTOS API

FreeRTOS interface for C++ API of SuperTinyKernel RTOS. More...

Classes

struct  TaskParameters_t
 Parameters passed to xTaskCreate(). More...
struct  TaskStatus_t
struct  StaticTask_t
struct  StaticQueue_t
struct  StaticSemaphore_t
struct  StaticTimer_t
struct  StaticEventGroup_t
struct  StaticStreamBuffer_t
struct  StaticMessageBuffer_t
struct  MemoryRegion_t
struct  TaskParameters_restricted_t
struct  HeapStats_t

Macros

#define configTICK_RATE_HZ   1000U
#define configNUM_THREAD_LOCAL_STORAGE_POINTERS   4U
#define configTASK_NOTIFICATION_ARRAY_ENTRIES   1U
#define configUSE_QUEUE_SETS   1U
#define configUSE_MUTEXES   1U
#define configUSE_TIMERS   1U
#define configUSE_EVENT_GROUPS   1U
#define configUSE_STREAM_BUFFERS   1U
#define configUSE_COUNTING_SEMAPHORES   1U
#define configUSE_TASK_NOTIFICATIONS   1U
#define FREERTOS_STK_MAX_TASKS   16U
 Maximum number of concurrent tasks managed by the kernel. Increase if your application creates more tasks simultaneously.
#define FREERTOS_STK_DEFAULT_STACK_WORDS   256U
 Default stack depth in Words when the caller passes usStackDepth = 0.
#define FREERTOS_STK_PEND_CALL_QUEUE_SIZE   8U
 Capacity of the static deferred-call queue used by xTimerPendFunctionCall() and xTimerPendFunctionCallFromISR().
#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)
#define configSTACK_DEPTH_TYPE   StackType_t
#define taskENTER_CRITICAL()
#define taskEXIT_CRITICAL()
#define taskDISABLE_INTERRUPTS()
#define taskENABLE_INTERRUPTS()
#define taskYIELD()
#define portYIELD()
#define taskSCHEDULER_NOT_STARTED   ((BaseType_t)0)
#define taskSCHEDULER_RUNNING   ((BaseType_t)1)
#define taskSCHEDULER_SUSPENDED   ((BaseType_t)2)
#define STATIC_TASK_TCB_SIZE_WORDS
#define STATIC_QUEUE_TCB_SIZE_WORDS   25U
#define STATIC_SEMAPHORE_TCB_SIZE_WORDS   8U
#define STATIC_TIMER_TCB_SIZE_WORDS   10U
#define STATIC_EVENT_GROUP_TCB_SIZE_WORDS   13U
#define STATIC_STREAM_BUFFER_TCB_SIZE_WORDS   27U
#define STATIC_MESSAGE_BUFFER_TCB_SIZE_WORDS   53U
#define portNUM_CONFIGURABLE_REGIONS   3U
#define pdMS_TO_TICKS(xTimeInMs)
#define tskIDLE_PRIORITY   ((UBaseType_t)0U)
#define xTaskHandle   TaskHandle_t

Typedefs

typedef uint32_t TickType_t
typedef long BaseType_t
typedef unsigned long UBaseType_t
typedef long portBASE_TYPE
typedef uintptr_t StackType_t
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
typedef void * QueueSetHandle_t
typedef void * QueueSetMemberHandle_t
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)
typedef uint32_t EventBits_t

Enumerations

enum  eTaskState {
  eRunning = 0 ,
  eReady ,
  eBlocked ,
  eSuspended ,
  eDeleted ,
  eInvalid
}
 Task execution state, returned by eTaskGetState(). More...
enum  eNotifyAction {
  eNoAction = 0 ,
  eSetBits ,
  eIncrement ,
  eSetValueWithOverwrite ,
  eSetValueWithoutOverwrite
}
 Action applied to a task's notification value by xTaskNotify(). More...

Functions

void vPortEnterCritical (void)
void vPortExitCritical (void)
void taskYIELD_impl (void)
void vTaskStartScheduler (void)
void vTaskEndScheduler (void)
 End scheduling (KERNEL_DYNAMIC only). Included for API completeness.
void vTaskSuspendAll (void)
 Suspend the scheduler (disables preemption; interrupts remain enabled).
BaseType_t xTaskResumeAll (void)
TickType_t xTaskGetTickCount (void)
 Return the tick count since the scheduler started.
TickType_t xTaskGetTickCountFromISR (void)
 Return the tick count from ISR context (ISR-safe).
UBaseType_t uxTaskGetNumberOfTasks (void)
 Return the number of tasks currently under kernel management.
BaseType_t xTaskGetSchedulerState (void)
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)
TaskHandle_t xTaskCreateStatic (TaskFunction_t pvTaskCode, const char *pcName, uint32_t ulStackDepth, void *pvParameters, UBaseType_t uxPriority, StackType_t *puxStackBuffer, StaticTask_t *pxTaskBuffer)
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)
StackType_t uxTaskGetStackHighWaterMark2 (TaskHandle_t xTask)
UBaseType_t uxTaskGetSystemState (TaskStatus_t *pxTaskStatusArray, UBaseType_t uxArraySize, uint32_t *pulTotalRunTime)
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)
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)
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)
 Create a recursive mutex (same implementation as xSemaphoreCreateMutex).
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)
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)
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)
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)
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)
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)
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)
void vTaskSetThreadLocalStoragePointer (TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue)
void * pvTaskGetThreadLocalStoragePointer (TaskHandle_t xTaskToQuery, BaseType_t xIndex)
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)
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)
void * pvPortMalloc (size_t xWantedSize)
void vPortFree (void *pv)
size_t xPortGetFreeHeapSize (void)
size_t xPortGetMinimumEverFreeHeapSize (void)
void vPortGetHeapStats (HeapStats_t *pxHeapStats)

Detailed Description

FreeRTOS interface for C++ API of SuperTinyKernel RTOS.

Maps standard FreeRTOS C API onto the STK C++ API, allowing existing FreeRTOS-based projects to run on STK with minimal or no application changes.

Supported API groups:

  • Kernel control (vTaskStartScheduler, taskENTER/EXIT_CRITICAL, xTaskGetTickCount, vTaskDelay, vTaskDelayUntil, xTaskDelayUntil, xTaskGetSchedulerState)
  • Task management (xTaskCreate, vTaskDelete, vTaskSuspend, vTaskResume, xTaskAbortDelay, vTaskPrioritySet, uxTaskPriorityGet, xTaskGetHandle, xTaskGetCurrentTaskHandle, pcTaskGetName, uxTaskGetStackHighWaterMark, eTaskGetState, uxTaskGetSystemState, xTaskCreateRestricted, xTaskCreateRestrictedStatic, vTaskList, vTaskGetRunTimeStats)
  • Queue (xQueueCreate, xQueueCreateStatic, vQueueDelete, xQueueSend, xQueueSendToBack, xQueueSendToFront, xQueueReceive, xQueuePeek, xQueuePeekFromISR, xQueueOverwrite, xQueueOverwriteFromISR, uxQueueMessagesWaiting, uxQueueMessagesWaitingFromISR, uxQueueSpacesAvailable, xQueueReset, xQueueSendFromISR, xQueueReceiveFromISR, xQueueSendToBackFromISR, xQueueSendToFrontFromISR, xQueueIsQueueEmptyFromISR, xQueueIsQueueFullFromISR, xQueueGetMutexHolder, xQueueGetMutexHolderFromISR, xQueueCreateSet, xQueueAddToSet, xQueueRemoveFromSet, xQueueSelectFromSet, xQueueSelectFromSetFromISR)
  • Semaphore / Mutex (xSemaphoreCreateBinary, xSemaphoreCreateBinaryStatic, xSemaphoreCreateCounting, xSemaphoreCreateCountingStatic, xSemaphoreCreateMutex, xSemaphoreCreateMutexStatic, xSemaphoreCreateRecursiveMutex, xSemaphoreCreateRecursiveMutexStatic, vSemaphoreDelete, xSemaphoreTake, xSemaphoreTakeFromISR, xSemaphoreTakeRecursive, xSemaphoreGive, xSemaphoreGiveRecursive, xSemaphoreGiveFromISR, uxSemaphoreGetCount, xSemaphoreGetMutexHolder, xSemaphoreGetMutexHolderFromISR)
  • Software timers (xTimerCreate, xTimerCreateStatic, xTimerDelete, xTimerStart, xTimerStop, xTimerReset, xTimerChangePeriod, xTimerIsTimerActive, pvTimerGetTimerID, pcTimerGetName, xTimerStartFromISR, xTimerStopFromISR, xTimerResetFromISR, xTimerChangePeriodFromISR, xTimerPendFunctionCall, xTimerPendFunctionCallFromISR)
  • Event groups (xEventGroupCreate, xEventGroupCreateStatic, vEventGroupDelete, xEventGroupSetBits, xEventGroupClearBits, xEventGroupGetBits, xEventGroupWaitBits, xEventGroupSetBitsFromISR, xEventGroupClearBitsFromISR, xEventGroupSync)
  • Task notifications (xTaskNotifyGive, ulTaskNotifyTake, xTaskNotify, xTaskNotifyWait, xTaskNotifyFromISR, xTaskNotifyGiveIndexed, ulTaskNotifyTakeIndexed, xTaskNotifyIndexed, xTaskNotifyWaitIndexed, xTaskNotifyFromISRIndexed, xTaskNotifyAndQuery, xTaskNotifyAndQueryIndexed, xTaskNotifyAndQueryFromISR, xTaskNotifyAndQueryFromISRIndexed, xTaskNotifyStateClear, xTaskNotifyStateClearIndexed, ulTaskNotifyValueClear, ulTaskNotifyValueClearIndexed)
  • Stream buffers (xStreamBufferCreate, xStreamBufferCreateStatic, xStreamBufferCreateWithCallback, xStreamBufferCreateStaticWithCallback, xStreamBufferSend, xStreamBufferReceive, xStreamBufferSendFromISR, xStreamBufferReceiveFromISR, vStreamBufferDelete, xStreamBufferBytesAvailable, xStreamBufferSpacesAvailable, xStreamBufferIsEmpty, xStreamBufferIsFull, xStreamBufferReset, xStreamBufferResetFromISR, xStreamBufferSetTriggerLevel, xStreamBufferGetTriggerLevel, xStreamBufferNextMessageLengthBytes)
  • Message buffers (xMessageBufferCreate, xMessageBufferCreateStatic, xMessageBufferCreateWithCallback, xMessageBufferCreateStaticWithCallback, xMessageBufferSend, xMessageBufferSendFromISR, xMessageBufferReceive, xMessageBufferReceiveFromISR, vMessageBufferDelete, xMessageBufferIsEmpty, xMessageBufferIsFull, xMessageBufferSpacesAvailable, xMessageBufferReset, xMessageBufferResetFromISR, xMessageBufferNextLengthBytes)

Design notes:

  • All objects are heap-allocated with operator new/delete. For static deployments replace with a static pool allocator.
  • One global STK Kernel instance (g_StkKernel) is configured with KERNEL_DYNAMIC | KERNEL_SYNC and sched::SwitchStrategyFixedPriority<configMAX_PRIORITIES, true> (fixed-priority levels with round-robin inside a level; the 'true' selects the no-sleep yield). FreeRTOS priorities (0=lowest .. configMAX_PRIORITIES-1=highest) map directly to STK priority levels 0..configMAX_PRIORITIES-1. configMAX_PRIORITIES must be in [1, 1024] (compile-time assertion in the .cpp); the ready-priorities bitmap is selected automatically (uint32_t up to 32 levels, uint64_t up to 64, stk::sched::PriorityBitmap above that). RAM use of the strategy grows with the number of levels. The highest-priority ready task always preempts lower ones, exactly matching FreeRTOS fixed-priority preemptive scheduling semantics.
  • portMAX_DELAY (0xFFFFFFFF) is translated to stk::WAIT_INFINITE.
  • Timeout values are in ticks; STK also takes ticks, so no conversion needed when tick resolution is 1 ms (the default PERIODICITY_DEFAULT).
  • Recursive mutexes are backed by stk::sync::Mutex (always recursive in STK).
  • Binary semaphores are backed by stk::sync::Semaphore with max_count=1.
  • Counting semaphores are backed by stk::sync::Semaphore.
  • Event groups are backed by stk::sync::EventFlags (32-bit, bits 0..23 usable per FreeRTOS convention; bits 24..30 are free, bit 31 is reserved by STK).
  • Software timers are backed by stk::time::TimerHost.
  • Task notifications are backed by per-task stk::sync::Semaphore.
  • Queue sets are backed by a per-set stk::sync::MessageQueue of void* tokens (sizeof(void*) per slot). Member queues and semaphores carry a non-owning back-pointer to their registered set; QueueSetNotify() posts the member handle into the set's token FIFO after every successful send or signal. Type discrimination between FrtosQueue and FrtosSemaphore uses the fact that SemKind (offset 0 in FrtosSemaphore, values 0 or 1) is always < the first byte of a MessageQueue vtable pointer (>= 4).

Limitations / deviations:

  • Priority inheritance is not supported (STK mutex is always recursive, not priority-inheriting).
  • configUSE_PREEMPTION is assumed to be 1; cooperative scheduling is not modelled.
  • Task notifications: indexed API supports slots 0 .. configTASK_NOTIFICATION_ARRAY_ENTRIES-1.
  • uxTaskGetNumberOfTasks() requires the kernel to be running.

Macro Definition Documentation

◆ configNUM_THREAD_LOCAL_STORAGE_POINTERS

#define configNUM_THREAD_LOCAL_STORAGE_POINTERS   4U

Per-task TLS pointer slots.

Definition at line 168 of file FreeRTOS.h.

Referenced by pvTaskGetThreadLocalStoragePointer(), and vTaskSetThreadLocalStoragePointer().

◆ configSTACK_DEPTH_TYPE

#define configSTACK_DEPTH_TYPE   StackType_t

Stack depth word type.

Definition at line 278 of file FreeRTOS.h.

Referenced by uxTaskGetStackHighWaterMark2(), and uxTaskGetSystemState().

◆ configTASK_NOTIFICATION_ARRAY_ENTRIES

#define configTASK_NOTIFICATION_ARRAY_ENTRIES   1U

Number of per-task notification slots (indexed API).

Definition at line 172 of file FreeRTOS.h.

◆ configTICK_RATE_HZ

#define configTICK_RATE_HZ   1000U

Definition at line 164 of file FreeRTOS.h.

◆ configUSE_COUNTING_SEMAPHORES

#define configUSE_COUNTING_SEMAPHORES   1U

Include counting semaphore API.

Definition at line 196 of file FreeRTOS.h.

◆ configUSE_EVENT_GROUPS

#define configUSE_EVENT_GROUPS   1U

Include event group API.

Definition at line 188 of file FreeRTOS.h.

◆ configUSE_MUTEXES

#define configUSE_MUTEXES   1U

Include mutex and recursive-mutex API.

Definition at line 180 of file FreeRTOS.h.

◆ configUSE_QUEUE_SETS

#define configUSE_QUEUE_SETS   1U

Include queue sets API.

Definition at line 176 of file FreeRTOS.h.

◆ configUSE_STREAM_BUFFERS

#define configUSE_STREAM_BUFFERS   1U

Include stream buffer and message buffer API.

Definition at line 192 of file FreeRTOS.h.

◆ configUSE_TASK_NOTIFICATIONS

#define configUSE_TASK_NOTIFICATIONS   1U

Include task notification API (xTaskNotify etc.).

Definition at line 200 of file FreeRTOS.h.

◆ configUSE_TIMERS

#define configUSE_TIMERS   1U

Include software timer API.

Definition at line 184 of file FreeRTOS.h.

◆ errQUEUE_EMPTY

#define errQUEUE_EMPTY   ((BaseType_t)0)

Definition at line 274 of file FreeRTOS.h.

◆ errQUEUE_FULL

#define errQUEUE_FULL   ((BaseType_t)0)

Definition at line 275 of file FreeRTOS.h.

◆ FREERTOS_STK_DEFAULT_STACK_WORDS

#define FREERTOS_STK_DEFAULT_STACK_WORDS   256U

Default stack depth in Words when the caller passes usStackDepth = 0.

Definition at line 219 of file FreeRTOS.h.

Referenced by xTaskCreate().

◆ FREERTOS_STK_MAX_TASKS

#define FREERTOS_STK_MAX_TASKS   16U

Maximum number of concurrent tasks managed by the kernel. Increase if your application creates more tasks simultaneously.

Definition at line 212 of file FreeRTOS.h.

Referenced by uxTaskGetSystemState(), vTaskEndScheduler(), vTaskGetRunTimeStats(), vTaskList(), and xTaskGetHandle().

◆ FREERTOS_STK_PEND_CALL_QUEUE_SIZE

#define FREERTOS_STK_PEND_CALL_QUEUE_SIZE   8U

Capacity of the static deferred-call queue used by xTimerPendFunctionCall() and xTimerPendFunctionCallFromISR().

Each slot holds one PendCall record: one function pointer, one void* parameter, and one uint32_t parameter — typically 12–16 bytes on 32-bit targets. The queue lives in static storage (zero heap), so this value determines RAM consumption at link time rather than runtime.

Choose the maximum number of deferred calls that can be simultaneously in-flight before the TimerHost handler task drains them. A value of 8 is sufficient for most applications; increase it if your ISR rate is high relative to the RTOS tick rate or if several ISRs may pend calls concurrently.

Note
xTimerPendFunctionCall() returns pdFAIL when the queue is full.
xTimerPendFunctionCallFromISR() also returns pdFAIL when full (non-blocking).
Must be >= 1.

Definition at line 242 of file FreeRTOS.h.

◆ pdFAIL

◆ pdFALSE

◆ pdMS_TO_TICKS

#define pdMS_TO_TICKS ( xTimeInMs)
Value:
((TickType_t)(xTimeInMs))
uint32_t TickType_t
Definition FreeRTOS.h:260

1 ms tick resolution.

Examples
blinky_c-freertos/example.c.

Definition at line 2214 of file FreeRTOS.h.

Referenced by clock_task(), and signal_func().

◆ pdPASS

◆ pdTRUE

◆ portNUM_CONFIGURABLE_REGIONS

#define portNUM_CONFIGURABLE_REGIONS   3U

MPU memory region descriptor used by xTaskCreateRestrictedStatic().

Note
STK does not implement MPU support. This struct is provided for source compatibility only; region fields are accepted but ignored.

Definition at line 577 of file FreeRTOS.h.

◆ portYIELD

#define portYIELD ( )
Value:
void taskYIELD_impl(void)

Definition at line 415 of file FreeRTOS.h.

◆ STATIC_EVENT_GROUP_TCB_SIZE_WORDS

#define STATIC_EVENT_GROUP_TCB_SIZE_WORDS   13U

Opaque buffer type that the caller must supply for xEventGroupCreateStatic(). Must be at least sizeof(FrtosEventGroup) bytes. Declared as a fixed-size array of uintptr_t to enforce natural alignment without exposing FrtosEventGroup internals.

Definition at line 525 of file FreeRTOS.h.

◆ STATIC_MESSAGE_BUFFER_TCB_SIZE_WORDS

#define STATIC_MESSAGE_BUFFER_TCB_SIZE_WORDS   53U

Opaque buffer type for xMessageBufferCreateStatic() and xMessageBufferCreateStaticWithCallback(). Covers FrtosMessageBuffer (BlockMemoryPool header + envelope MessageQueue header

  • ownership flags + two StreamBufferCallbackFunction_t pointers) on all supported STK targets. Size is conservative (+2 words vs the pre-callback layout).

Definition at line 547 of file FreeRTOS.h.

◆ STATIC_QUEUE_TCB_SIZE_WORDS

#define STATIC_QUEUE_TCB_SIZE_WORDS   25U

Opaque buffer type that the caller must supply for xQueueCreateStatic(). Must be at least sizeof(StaticQueue_t) bytes. Declared as a fixed-size array of uintptr_t to enforce natural alignment without exposing FrtosQueue internals. Size is conservative: covers FrtosQueue on all supported targets.

Definition at line 493 of file FreeRTOS.h.

◆ STATIC_SEMAPHORE_TCB_SIZE_WORDS

#define STATIC_SEMAPHORE_TCB_SIZE_WORDS   8U

Opaque buffer type that the caller must supply for xSemaphoreCreateBinaryStatic() and related static semaphore/mutex creation functions. Must be at least sizeof(FrtosSemaphore) bytes. Declared as a fixed-size array of uintptr_t to enforce natural alignment without exposing FrtosSemaphore internals. Size is conservative: covers FrtosSemaphore on all supported targets.

Definition at line 504 of file FreeRTOS.h.

◆ STATIC_STREAM_BUFFER_TCB_SIZE_WORDS

#define STATIC_STREAM_BUFFER_TCB_SIZE_WORDS   27U

Opaque buffer type for xStreamBufferCreateStatic() and xStreamBufferCreateStaticWithCallback(). Covers FrtosStreamBuffer (Pipe + trigger level + ownership flags + two StreamBufferCallbackFunction_t pointers) on all supported STK targets. Size is conservative (+2 words vs the pre-callback layout).

Definition at line 536 of file FreeRTOS.h.

◆ STATIC_TASK_TCB_SIZE_WORDS

#define STATIC_TASK_TCB_SIZE_WORDS
Value:
#define configTASK_NOTIFICATION_ARRAY_ENTRIES
Definition FreeRTOS.h:172
#define configNUM_THREAD_LOCAL_STORAGE_POINTERS
Definition FreeRTOS.h:168

Opaque buffer type that the caller must supply for xTaskCreateStatic(). Must be at least sizeof(StaticTask_t) bytes; declared as a fixed-size array of uintptr_t so the compiler enforces natural alignment without requiring knowledge of FrtosTask internals. Size is conservative: covers FrtosTask on all supported STK targets.

Definition at line 482 of file FreeRTOS.h.

482#define STATIC_TASK_TCB_SIZE_WORDS (21U + configNUM_THREAD_LOCAL_STORAGE_POINTERS \
483 + (3U * (configTASK_NOTIFICATION_ARRAY_ENTRIES - 1U)))

◆ STATIC_TIMER_TCB_SIZE_WORDS

#define STATIC_TIMER_TCB_SIZE_WORDS   10U

Opaque buffer type that the caller must supply for xTimerCreateStatic(). Must be at least sizeof(FrtosTimer) bytes. Declared as a fixed-size array of uintptr_t to enforce natural alignment without exposing FrtosTimer internals. Size is conservative: covers FrtosTimer (vtable ptr + base + 5 members) on all supported targets.

Definition at line 515 of file FreeRTOS.h.

◆ taskDISABLE_INTERRUPTS

#define taskDISABLE_INTERRUPTS ( )
Value:
void vPortEnterCritical(void)

Definition at line 412 of file FreeRTOS.h.

◆ taskENABLE_INTERRUPTS

#define taskENABLE_INTERRUPTS ( )
Value:
void vPortExitCritical(void)

Definition at line 413 of file FreeRTOS.h.

◆ taskENTER_CRITICAL

#define taskENTER_CRITICAL ( )
Value:

Definition at line 410 of file FreeRTOS.h.

◆ taskEXIT_CRITICAL

#define taskEXIT_CRITICAL ( )
Value:

Definition at line 411 of file FreeRTOS.h.

◆ taskSCHEDULER_NOT_STARTED

#define taskSCHEDULER_NOT_STARTED   ((BaseType_t)0)

Scheduler has not yet been started (STATE_INACTIVE / STATE_READY).

Definition at line 445 of file FreeRTOS.h.

Referenced by xTaskGetSchedulerState().

◆ taskSCHEDULER_RUNNING

#define taskSCHEDULER_RUNNING   ((BaseType_t)1)

Scheduler is running normally (STATE_RUNNING).

Definition at line 446 of file FreeRTOS.h.

Referenced by xTaskGetSchedulerState().

◆ taskSCHEDULER_SUSPENDED

#define taskSCHEDULER_SUSPENDED   ((BaseType_t)2)

Scheduler is suspended via vTaskSuspendAll() (STATE_SUSPENDED).

Definition at line 447 of file FreeRTOS.h.

Referenced by xTaskGetSchedulerState().

◆ taskYIELD

#define taskYIELD ( )
Value:

Definition at line 414 of file FreeRTOS.h.

◆ tskIDLE_PRIORITY

#define tskIDLE_PRIORITY   ((UBaseType_t)0U)

Idle task priority.

Definition at line 2215 of file FreeRTOS.h.

◆ xTaskHandle

#define xTaskHandle   TaskHandle_t

Legacy handle alias.

Definition at line 2216 of file FreeRTOS.h.

Typedef Documentation

◆ BaseType_t

typedef long BaseType_t

Definition at line 261 of file FreeRTOS.h.

◆ EventBits_t

typedef uint32_t EventBits_t

Bitmask for event group operations (bits 0..23 per FreeRTOS convention).

Definition at line 387 of file FreeRTOS.h.

◆ EventGroupHandle_t

typedef void* EventGroupHandle_t

Handle for an event group.

Definition at line 321 of file FreeRTOS.h.

◆ MessageBufferHandle_t

typedef void* MessageBufferHandle_t

Handle for a message buffer.

Definition at line 323 of file FreeRTOS.h.

◆ PendedFunction_t

typedef void(* PendedFunction_t) (void *pvParameter1, uint32_t ulParameter2)

Callback for xTimerPendFunctionCall().

Definition at line 335 of file FreeRTOS.h.

◆ portBASE_TYPE

typedef long portBASE_TYPE

Definition at line 263 of file FreeRTOS.h.

◆ QueueHandle_t

typedef void* QueueHandle_t

Handle for a queue.

Definition at line 318 of file FreeRTOS.h.

◆ QueueSetHandle_t

typedef void* QueueSetHandle_t

Definition at line 326 of file FreeRTOS.h.

◆ QueueSetMemberHandle_t

typedef void* QueueSetMemberHandle_t

Definition at line 327 of file FreeRTOS.h.

◆ SemaphoreHandle_t

typedef void* SemaphoreHandle_t

Handle for a semaphore/mutex.

Definition at line 319 of file FreeRTOS.h.

◆ StackType_t

typedef uintptr_t StackType_t

Native-word stack element type, matches stk::Word.

Definition at line 264 of file FreeRTOS.h.

◆ StreamBufferCallbackFunction_t

typedef void(* StreamBufferCallbackFunction_t) (StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken)

Stream / message buffer send-complete and receive-complete callback. Invoked after bytes are successfully written (send) or read (receive) from the buffer. \a xHigherPriorityTaskWoken is always set to pdFALSE by the STK backend; it is included only for FreeRTOS API compatibility. May be NULL (no callback).

Definition at line 343 of file FreeRTOS.h.

◆ StreamBufferHandle_t

typedef void* StreamBufferHandle_t

Handle for a stream buffer.

Definition at line 322 of file FreeRTOS.h.

◆ TaskFunction_t

typedef void(* TaskFunction_t) (void *pvParameters)

Task entry function.

Definition at line 333 of file FreeRTOS.h.

◆ TaskHandle_t

typedef void* TaskHandle_t

Handle for a task.

Examples
blinky_c-freertos/example.c.

Definition at line 317 of file FreeRTOS.h.

◆ TickType_t

typedef uint32_t TickType_t

Definition at line 260 of file FreeRTOS.h.

◆ TimerCallbackFunction_t

typedef void(* TimerCallbackFunction_t) (TimerHandle_t xTimer)

Timer expiry callback.

Definition at line 334 of file FreeRTOS.h.

◆ TimerHandle_t

typedef void* TimerHandle_t

Handle for a software timer.

Definition at line 320 of file FreeRTOS.h.

◆ UBaseType_t

typedef unsigned long UBaseType_t

Definition at line 262 of file FreeRTOS.h.

Enumeration Type Documentation

◆ eNotifyAction

Action applied to a task's notification value by xTaskNotify().

Enumerator
eNoAction 

No action; notification sent without modifying the value.

eSetBits 

OR ulValue into the notification value.

eIncrement 

Increment the notification value by 1 (ulValue ignored).

eSetValueWithOverwrite 

Set notification value to ulValue unconditionally.

eSetValueWithoutOverwrite 

Set only if the previous notification was consumed.

Definition at line 301 of file FreeRTOS.h.

302{
303 eNoAction = 0,
304 eSetBits,
305 eIncrement,
eNotifyAction
Action applied to a task's notification value by xTaskNotify().
Definition FreeRTOS.h:302
@ eIncrement
Definition FreeRTOS.h:305
@ eSetValueWithOverwrite
Definition FreeRTOS.h:306
@ eSetBits
Definition FreeRTOS.h:304
@ eNoAction
Definition FreeRTOS.h:303
@ eSetValueWithoutOverwrite
Definition FreeRTOS.h:307

◆ eTaskState

enum eTaskState

Task execution state, returned by eTaskGetState().

Enumerator
eRunning 

Task is actively executing on the CPU.

eReady 

Task is in the ready list, eligible to run.

eBlocked 

Task is waiting for an event or timeout.

eSuspended 

Task is explicitly suspended via vTaskSuspend().

eDeleted 

Task has been deleted but not yet cleaned up.

eInvalid 

Invalid / unknown state.

Definition at line 286 of file FreeRTOS.h.

287{
288 eRunning = 0,
289 eReady,
290 eBlocked,
291 eSuspended,
292 eDeleted,
293 eInvalid
294} eTaskState;
eTaskState
Task execution state, returned by eTaskGetState().
Definition FreeRTOS.h:287
@ eRunning
Definition FreeRTOS.h:288
@ eReady
Definition FreeRTOS.h:289
@ eInvalid
Definition FreeRTOS.h:293
@ eDeleted
Definition FreeRTOS.h:292
@ eBlocked
Definition FreeRTOS.h:290
@ eSuspended
Definition FreeRTOS.h:291

Function Documentation

◆ eTaskGetState()

eTaskState eTaskGetState ( TaskHandle_t xTask)

Return the current execution state of a task.

Parameters
xTaskHandle of the task to query.
Returns
One of eRunning, eReady, eBlocked, eSuspended, eDeleted, or eInvalid.

Definition at line 1678 of file freertos_stk.cpp.

1679{
1680 if (xTask == nullptr)
1681 return eInvalid;
1682
1683 FrtosTask *t = static_cast<FrtosTask *>(xTask);
1684
1685 if (t->m_state == FrtosTask::State::Deleted)
1686 return eDeleted;
1687
1688 if (t->m_state == FrtosTask::State::Suspended)
1689 return eSuspended;
1690
1691 // Check whether this is the currently running task.
1692 if (stk::GetTid() == FrtosTidFromTask(t))
1693 return eRunning;
1694
1695 return eReady;
1696}
static TId GetTid()
Get task/thread Id of the calling task.
Definition stk_helper.h:374

References eDeleted, eInvalid, eReady, eRunning, eSuspended, and stk::GetTid().

Here is the call graph for this function:

◆ pcTaskGetName()

const char * pcTaskGetName ( TaskHandle_t xTaskToQuery)

Return the name string of a task.

Parameters
xTaskToQueryHandle of the task to query, or NULL for the calling task.
Returns
Pointer to the task's name string (not a copy; valid for the task's lifetime).

Definition at line 1728 of file freertos_stk.cpp.

1729{
1730 if (xTaskToQuery == nullptr)
1731 return nullptr;
1732
1733 return static_cast<FrtosTask *>(xTaskToQuery)->m_name;
1734}

◆ pcTimerGetName()

const char * pcTimerGetName ( TimerHandle_t xTimer)

Return the name string of a timer.

Parameters
xTimerHandle of the timer to query.
Returns
Pointer to the timer's name string (not a copy; valid for the timer's lifetime).

Definition at line 3312 of file freertos_stk.cpp.

3313{
3314 if (xTimer == nullptr)
3315 return nullptr;
3316
3317 return static_cast<FrtosTimer *>(xTimer)->m_name;
3318}

◆ pvPortMalloc()

void * pvPortMalloc ( size_t xWantedSize)

Allocate xWantedSize bytes from the system heap.

Returns
Pointer to the allocated block, or NULL on failure.
Note
Thread-safe if the underlying MemoryAllocator::Allocate is. The default implementation delegates to malloc.

Definition at line 1244 of file freertos_stk.cpp.

1245{
1246 return stk::memory::MemoryAllocator::Allocate(xWantedSize);
1247}
static void * Allocate(size_t size)
Allocate the memory chunk (checked).

References __stk_weak, and stk::memory::MemoryAllocator::Allocate().

Here is the call graph for this function:

◆ pvTaskGetThreadLocalStoragePointer()

void * pvTaskGetThreadLocalStoragePointer ( TaskHandle_t xTaskToQuery,
BaseType_t xIndex )

Read a TLS pointer slot for a task.

Parameters
xTaskToQueryTask handle, or NULL for the calling task.
xIndexSlot index (0 .. configNUM_THREAD_LOCAL_STORAGE_POINTERS-1).
Returns
Stored pointer, or NULL if the index is out of range.

< Per-task TLS pointer slots.

Definition at line 3959 of file freertos_stk.cpp.

3961{
3962 if (xIndex < 0 || static_cast<size_t>(xIndex) >= configNUM_THREAD_LOCAL_STORAGE_POINTERS)
3963 return nullptr;
3964
3965 // Resolve NULL -> calling task.
3966 if (xTaskToQuery == nullptr)
3967 xTaskToQuery = xTaskGetCurrentTaskHandle();
3968
3969 if (xTaskToQuery == nullptr)
3970 return nullptr;
3971
3972 const FrtosTask *t = static_cast<const FrtosTask *>(xTaskToQuery);
3973
3975 return t->m_tls[static_cast<size_t>(xIndex)];
3976}
TaskHandle_t xTaskGetCurrentTaskHandle(void)
RAII-style low-level synchronization primitive for atomic code execution. Used as building brick for ...
Definition stk_sync_cs.h:58

References configNUM_THREAD_LOCAL_STORAGE_POINTERS, and xTaskGetCurrentTaskHandle().

Here is the call graph for this function:

◆ pvTimerGetTimerID()

void * pvTimerGetTimerID ( TimerHandle_t xTimer)

Return the application-defined ID stored in a timer.

Parameters
xTimerHandle of the timer to query.
Returns
The ID value set at creation or by vTimerSetTimerID().

Definition at line 3296 of file freertos_stk.cpp.

3297{
3298 if (xTimer == nullptr)
3299 return nullptr;
3300
3301 return static_cast<FrtosTimer *>(xTimer)->m_timer_id;
3302}

◆ taskYIELD_impl()

void taskYIELD_impl ( void )

Request an immediate context switch to the highest-priority ready task. Called by the taskYIELD() and portYIELD() macros.

Note
May trigger a preemption; safe only from task context.

Definition at line 1333 of file freertos_stk.cpp.

1334{
1335 stk::Yield();
1336}
static void Yield()
Notify scheduler to switch to the next runnable task.
Definition stk_helper.h:562

References stk::Yield().

Here is the call graph for this function:

◆ ulTaskNotifyTake()

uint32_t ulTaskNotifyTake ( BaseType_t ulClearCountOnExit,
TickType_t xTicksToWait )

Receive a notification (slot 0), optionally clearing or decrementing the value.

Parameters
ulClearCountOnExitpdTRUE = clear to 0 on exit, pdFALSE = decrement by 1.
xTicksToWaitTicks to wait for a notification.
Returns
Notification value before the clear/decrement, or 0 on timeout.

Definition at line 3677 of file freertos_stk.cpp.

3678{
3679 return ulTaskNotifyTakeIndexed(0U, ulClearCountOnExit, xTicksToWait);
3680}
uint32_t ulTaskNotifyTakeIndexed(UBaseType_t uxIndexToWait, BaseType_t ulClearCountOnExit, TickType_t xTicksToWait)

References ulTaskNotifyTakeIndexed().

Here is the call graph for this function:

◆ ulTaskNotifyTakeIndexed()

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

Receive a notification from a specific slot of the calling task.

Parameters
uxIndexToWaitNotification slot index.
ulClearCountOnExitpdTRUE = clear slot value to 0, pdFALSE = decrement by 1.
xTicksToWaitTicks to wait.
Returns
Slot value before the clear/decrement, or 0 on timeout or bad index.

Definition at line 3551 of file freertos_stk.cpp.

3554{
3555 if (IsIrqContext())
3556 return 0U;
3557
3558 FrtosTask *t = ResolveNotifyTarget(nullptr, uxIndexToWait);
3559 if (t == nullptr)
3560 return 0U;
3561
3562 FrtosTask::NotifySlot &slot = t->m_notify[uxIndexToWait];
3563
3564 if (!slot.sem.Wait(FrtosTimeoutToStk(xTicksToWait)))
3565 return 0U;
3566
3567 uint32_t val = 0U;
3568
3569 {
3571 val = slot.value;
3572 slot.pending = false;
3573
3574 if (ulClearCountOnExit == pdTRUE)
3575 {
3576 slot.value = 0U;
3577 }
3578 else
3579 {
3580 if (slot.value > 0U)
3581 slot.value--;
3582 }
3583
3584 // counting semaphore behavior: while notifications remain, keep the wake flag raised
3585 if (slot.value > 0U)
3586 (void)slot.sem.TrySignal();
3587 }
3588
3589 return val; // notification value before it was cleared / decremented (FreeRTOS contract)
3590}
#define pdTRUE
Definition FreeRTOS.h:270
bool Wait(Timeout timeout_ticks=WAIT_INFINITE)
Wait for a signal (decrement counter).
bool TrySignal()
Try to post a signal without exceeding max_count.

References pdTRUE, stk::sync::SemaphoreT< T >::TrySignal(), and stk::sync::SemaphoreT< T >::Wait().

Referenced by ulTaskNotifyTake().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ulTaskNotifyValueClear()

uint32_t ulTaskNotifyValueClear ( TaskHandle_t xTask,
uint32_t ulBitsToClear )

Atomically clear the specified bits in the notification value of slot 0 of a task, and return the value of the notification word before the bits were cleared.

Parameters
xTaskHandle of the task. NULL selects the calling task.
ulBitsToClearBitmask of bits to clear (ANDed with complement). Pass 0xFFFFFFFF to clear all bits.
Returns
Notification value before the clear operation, or 0 on bad handle.
Note
ISR-safe.

Definition at line 3912 of file freertos_stk.cpp.

3914{
3915 return ulTaskNotifyValueClearIndexed(xTask, 0U, ulBitsToClear);
3916}
uint32_t ulTaskNotifyValueClearIndexed(TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear)

References ulTaskNotifyValueClearIndexed().

Here is the call graph for this function:

◆ ulTaskNotifyValueClearIndexed()

uint32_t ulTaskNotifyValueClearIndexed ( TaskHandle_t xTask,
UBaseType_t uxIndexToClear,
uint32_t ulBitsToClear )

Indexed variant of ulTaskNotifyValueClear.

Parameters
xTaskHandle of the task. NULL selects the calling task.
uxIndexToClearNotification slot index.
ulBitsToClearBitmask of bits to clear.
Returns
Notification value before the clear, or 0 on bad handle / index.
Note
ISR-safe.

Definition at line 3890 of file freertos_stk.cpp.

3893{
3894 FrtosTask *t = ResolveNotifyTarget(xTask, uxIndexToClear);
3895 if (t == nullptr)
3896 return 0U;
3897
3898 FrtosTask::NotifySlot &slot = t->m_notify[uxIndexToClear];
3899
3901
3902 const uint32_t prev = slot.value;
3903 slot.value &= ~ulBitsToClear;
3904
3905 return prev;
3906}

Referenced by ulTaskNotifyValueClear().

Here is the caller graph for this function:

◆ uxQueueMessagesWaiting()

UBaseType_t uxQueueMessagesWaiting ( QueueHandle_t xQueue)

Return the number of items currently in the queue.

Parameters
xQueueHandle of the queue to inspect.
Returns
Number of items currently stored in the queue.

Definition at line 2147 of file freertos_stk.cpp.

2148{
2149 if (xQueue == nullptr)
2150 return 0U;
2151
2152 return static_cast<UBaseType_t>(
2153 static_cast<FrtosQueue *>(xQueue)->m_mq.GetCount());
2154}
unsigned long UBaseType_t
Definition FreeRTOS.h:262

◆ uxQueueMessagesWaitingFromISR()

UBaseType_t uxQueueMessagesWaitingFromISR ( QueueHandle_t xQueue)

Return the number of items currently in the queue from ISR context.

Parameters
xQueueHandle of the queue to inspect.
Note
ISR-safe on targets where a size_t-aligned read is atomic.
Returns
Point-in-time snapshot of the message count.

Definition at line 2156 of file freertos_stk.cpp.

2157{
2158 // GetCount() is ISR-safe on targets where a size_t-aligned read is atomic
2159 // (per the STK MessageQueue documentation).
2160 if (xQueue == nullptr)
2161 return 0U;
2162
2163 return static_cast<UBaseType_t>(static_cast<FrtosQueue *>(xQueue)->m_mq.GetCount());
2164}

◆ uxQueueSpacesAvailable()

UBaseType_t uxQueueSpacesAvailable ( QueueHandle_t xQueue)

Return the number of free slots in the queue.

Parameters
xQueueHandle of the queue to inspect.
Returns
Number of items that can still be enqueued without blocking.

Definition at line 2166 of file freertos_stk.cpp.

2167{
2168 if (xQueue == nullptr)
2169 return 0U;
2170
2171 return static_cast<UBaseType_t>(
2172 static_cast<FrtosQueue *>(xQueue)->m_mq.GetSpace());
2173}

◆ uxSemaphoreGetCount()

UBaseType_t uxSemaphoreGetCount ( SemaphoreHandle_t xSemaphore)

Return the current count of a counting semaphore, or 1/0 for a mutex (1 = unlocked, 0 = locked).

Parameters
xSemaphoreHandle of the semaphore or mutex to query.
Returns
Current count value.

Definition at line 2902 of file freertos_stk.cpp.

2903{
2904 if (xSemaphore == nullptr)
2905 return 0U;
2906
2907 FrtosSemaphore *s = static_cast<FrtosSemaphore *>(xSemaphore);
2908
2909 if (s->m_kind == SemKind::Counting)
2910 return static_cast<UBaseType_t>(s->m_sem->GetCount());
2911
2912#if configUSE_MUTEXES
2913 // For a mutex, count = 0 means locked, 1 means unlocked.
2914 return (s->m_mtx->GetOwner() == stk::TID_NONE) ? 1U : 0U;
2915#else
2916 return 0U;
2917#endif
2918}
static constexpr TId TID_NONE
Reserved task/thread id representing zero/none thread id.
Definition stk_common.h:268

References stk::TID_NONE.

◆ uxTaskGetNumberOfTasks()

UBaseType_t uxTaskGetNumberOfTasks ( void )

Return the number of tasks currently under kernel management.

Definition at line 1381 of file freertos_stk.cpp.

1382{
1384 return static_cast<UBaseType_t>(g_StkKernel.GetSwitchStrategy()->GetSize());
1385}

◆ uxTaskGetStackHighWaterMark()

UBaseType_t uxTaskGetStackHighWaterMark ( TaskHandle_t xTask)

Return the unused stack depth high-water mark in Words. Pass NULL for the calling task.

Parameters
xTaskHandle of the task to query, or NULL for the calling task.
Returns
Minimum free stack space observed since task creation, in Words.

Definition at line 1736 of file freertos_stk.cpp.

1737{
1738 const FrtosTask *t = (xTask == nullptr) ? FrtosTaskFromTid(stk::GetTid()) : static_cast<const FrtosTask *>(xTask);
1739
1740 if (t == nullptr)
1741 return 0U;
1742
1743 return static_cast<UBaseType_t>(t->GetStackHighWaterMark());
1744}

References stk::GetTid().

Here is the call graph for this function:

◆ uxTaskGetStackHighWaterMark2()

StackType_t uxTaskGetStackHighWaterMark2 ( TaskHandle_t xTask)

Return the unused stack depth high-water mark in Words. Pass NULL for the calling task.

Parameters
xTaskHandle of the task to query, or NULL for the calling task.
Returns
Minimum free stack space observed since task creation, in Words (returned as configSTACK_DEPTH_TYPE for extended range on 32-bit targets).

< Stack depth word type.

< Stack depth word type.

Definition at line 1746 of file freertos_stk.cpp.

1747{
1748 const FrtosTask *t = (xTask == nullptr) ? FrtosTaskFromTid(stk::GetTid()) : static_cast<const FrtosTask *>(xTask);
1749
1750 if (t == nullptr)
1751 return 0U;
1752
1753 return static_cast<configSTACK_DEPTH_TYPE>(t->GetStackHighWaterMark());
1754}
#define configSTACK_DEPTH_TYPE
Definition FreeRTOS.h:278

References configSTACK_DEPTH_TYPE, and stk::GetTid().

Here is the call graph for this function:

◆ uxTaskGetSystemState()

UBaseType_t uxTaskGetSystemState ( TaskStatus_t * pxTaskStatusArray,
UBaseType_t uxArraySize,
uint32_t * pulTotalRunTime )

Populate an array of TaskStatus_t with a snapshot of every task's state.

Parameters
pxTaskStatusArrayCaller-supplied array of at least uxArraySize elements.
uxArraySizeCapacity of pxTaskStatusArray (should be >= uxTaskGetNumberOfTasks()).
pulTotalRunTimeReceives 0 (STK has no global run-time counter). May be NULL.
Returns
Number of TaskStatus_t entries written. May be less than uxTaskGetNumberOfTasks() if pxTaskStatusArray was too small.

< Stack depth word type.

Definition at line 1756 of file freertos_stk.cpp.

1759{
1760 // STK has no global CPU run-time accumulator; report 0 per the FreeRTOS
1761 // convention for targets that do not implement run-time statistics.
1762 if (pulTotalRunTime != nullptr)
1763 *pulTotalRunTime = 0U;
1764
1765 if ((pxTaskStatusArray == nullptr) || (uxArraySize == 0U))
1766 return 0U;
1767
1768 UBaseType_t filled = 0U;
1769
1770 // Identify the currently running task once, outside the enumeration
1771 // loop, so the eRunning check is consistent across all entries.
1772 const stk::TId running_tid = stk::GetTid();
1773
1774 g_StkKernel.EnumerateTasksT<FREERTOS_STK_MAX_TASKS>([&](stk::ITask *itask) -> bool
1775 {
1776 if (filled >= uxArraySize)
1777 return false; // array full — stop enumeration
1778
1779 const FrtosTask *t = static_cast<const FrtosTask *>(itask);
1780 TaskStatus_t &s = pxTaskStatusArray[filled];
1781
1782 // xHandle — the FrtosTask pointer cast to an opaque handle.
1783 s.xHandle = static_cast<TaskHandle_t>(const_cast<FrtosTask *>(t));
1784
1785 // pcTaskName — direct pointer into the task's name buffer (not a copy).
1786 s.pcTaskName = (t->m_name != nullptr) ? t->m_name : "";
1787
1788 // eCurrentState — mirrors eTaskGetState() logic.
1789 if (t->m_state == FrtosTask::State::Deleted)
1791 else
1792 if (t->m_state == FrtosTask::State::Suspended)
1794 else
1795 if (FrtosTidFromTask(t) == running_tid)
1797 else
1799
1800 // uxCurrentPriority / uxBasePriority — same value: a temporary priority-inheritance boost is
1801 // tracked inside the kernel and is not visible through ITask::GetWeight(), so the base
1802 // priority is reported for both.
1803 s.uxCurrentPriority = StkWeightToFrtosPrio(t->m_weight);
1805
1806 // ulRunTimeCounter — always 0 (STK has no per-task CPU accounting).
1807 s.ulRunTimeCounter = 0U;
1808
1809 // pxStackBase — bottom of the stack array (index 0).
1810 s.pxStackBase = reinterpret_cast<StackType_t *>(t->m_stack);
1811
1812 // usStackHighWaterMark — minimum observed free Words (watermark scan).
1814 static_cast<configSTACK_DEPTH_TYPE>(t->GetStackHighWaterMark());
1815
1816 // xTaskNumber — monotonic serial assigned at construction.
1817 s.xTaskNumber = t->m_task_number;
1818
1819 ++filled;
1820 return true; // continue enumeration
1821 });
1822
1823 return filled;
1824}
#define FREERTOS_STK_MAX_TASKS
Maximum number of concurrent tasks managed by the kernel. Increase if your application creates more t...
Definition FreeRTOS.h:212
uintptr_t StackType_t
Definition FreeRTOS.h:264
void * TaskHandle_t
Definition FreeRTOS.h:317
Word TId
Task (thread) id.
Definition stk_common.h:211
Interface for a user task.
Definition stk_common.h:886
StackType_t * pxStackBase
Definition FreeRTOS.h:378
uint32_t xTaskNumber
Definition FreeRTOS.h:380
eTaskState eCurrentState
Definition FreeRTOS.h:374
TaskHandle_t xHandle
Definition FreeRTOS.h:372
StackType_t usStackHighWaterMark
Definition FreeRTOS.h:379
UBaseType_t uxBasePriority
Definition FreeRTOS.h:376
UBaseType_t uxCurrentPriority
Definition FreeRTOS.h:375
uint32_t ulRunTimeCounter
Definition FreeRTOS.h:377
const char * pcTaskName
Definition FreeRTOS.h:373

References configSTACK_DEPTH_TYPE, TaskStatus_t::eCurrentState, eDeleted, eReady, eRunning, eSuspended, FREERTOS_STK_MAX_TASKS, stk::GetTid(), TaskStatus_t::pcTaskName, TaskStatus_t::pxStackBase, TaskStatus_t::ulRunTimeCounter, TaskStatus_t::usStackHighWaterMark, TaskStatus_t::uxBasePriority, TaskStatus_t::uxCurrentPriority, TaskStatus_t::xHandle, and TaskStatus_t::xTaskNumber.

Here is the call graph for this function:

◆ uxTaskPriorityGet()

UBaseType_t uxTaskPriorityGet ( TaskHandle_t xTask)

Query the priority of a task. Pass NULL xTask for the calling task.

Parameters
xTaskHandle of the task to query, or NULL for the calling task.
Returns
Current priority level of the task.

Definition at line 1663 of file freertos_stk.cpp.

1664{
1665 const FrtosTask *t = (xTask == nullptr) ? FrtosTaskFromTid(stk::GetTid()) : static_cast<const FrtosTask *>(xTask);
1666
1667 if (t == nullptr)
1668 return 0U;
1669
1670 return StkWeightToFrtosPrio(t->m_weight);
1671}

References stk::GetTid().

Referenced by uxTaskPriorityGetFromISR().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ uxTaskPriorityGetFromISR()

UBaseType_t uxTaskPriorityGetFromISR ( TaskHandle_t xTask)

Query the priority of a task from ISR context (ISR-safe).

Parameters
xTaskHandle of the task to query.
Returns
Current priority level of the task.

Definition at line 1673 of file freertos_stk.cpp.

1674{
1675 return uxTaskPriorityGet(xTask); // same implementation; GetTid() is ISR-safe
1676}
UBaseType_t uxTaskPriorityGet(TaskHandle_t xTask)

References uxTaskPriorityGet().

Here is the call graph for this function:

◆ vEventGroupDelete()

void vEventGroupDelete ( EventGroupHandle_t xEventGroup)

Delete an event group and free its memory.

Parameters
xEventGroupHandle of the event group to delete.

Definition at line 3372 of file freertos_stk.cpp.

3373{
3374 if (xEventGroup == nullptr)
3375 return;
3376
3377 ObjFree(static_cast<FrtosEventGroup *>(xEventGroup));
3378}

◆ vMessageBufferDelete()

void vMessageBufferDelete ( MessageBufferHandle_t xMessageBuffer)

Delete a message buffer and free heap resources (if dynamically allocated).

Parameters
xMessageBufferHandle of the message buffer to delete.

Definition at line 4489 of file freertos_stk.cpp.

4490{
4491 if (xMessageBuffer == nullptr)
4492 return;
4493
4494 FrtosMessageBuffer *mb = static_cast<FrtosMessageBuffer *>(xMessageBuffer);
4495
4496 ObjFree(mb);
4497}

◆ vPortEnterCritical()

void vPortEnterCritical ( void )

Enter a critical section by disabling preemption and interrupts. Calls may be nested; each call must be balanced by a matching vPortExitCritical().

Note
Not ISR-safe; must only be called from task context.

Definition at line 1323 of file freertos_stk.cpp.

1324{
1326}
static Session Enter(const Session ses=DEFAULT_SESSION)
Enter a critical section.

References stk::hw::CriticalSection::Enter().

Here is the call graph for this function:

◆ vPortExitCritical()

void vPortExitCritical ( void )

Exit a critical section previously entered with vPortEnterCritical(). Re-enables preemption and interrupts only when the outermost nesting level is exited.

Note
Not ISR-safe; must only be called from task context.

Definition at line 1328 of file freertos_stk.cpp.

1329{
1331}
static void Exit(const Session ses=DEFAULT_SESSION)
Exit a critical section.

References stk::hw::CriticalSection::Exit().

Here is the call graph for this function:

◆ vPortFree()

void vPortFree ( void * pv)

Free a block previously returned by pvPortMalloc().

Parameters
pvPointer to the block to free. NULL is a no-op.
Note
Thread-safe if the underlying MemoryAllocator::Free is.

Definition at line 1249 of file freertos_stk.cpp.

1250{
1252}
static void Free(void *ptr)
Free the memory chunk (checked).

References __stk_weak, and stk::memory::MemoryAllocator::Free().

Here is the call graph for this function:

◆ vPortGetHeapStats()

void vPortGetHeapStats ( HeapStats_t * pxHeapStats)

Fill pxHeapStats with a snapshot of the heap statistics.

Fields that require traversal of the internal free-block list are reported conservatively (see HeapStats_t documentation); all other fields are exact.

Parameters
pxHeapStatsPointer to the HeapStats_t structure to fill. NULL is silently ignored.

Definition at line 1294 of file freertos_stk.cpp.

1295{
1296 if (pxHeapStats == nullptr)
1297 return;
1298
1300 const size_t free_now = snap.GetAvailable();
1301
1302 (*pxHeapStats) = {};
1303
1304 // Fields derived directly from the allocator statistics.
1305 pxHeapStats->xAvailableHeapSpaceInBytes = free_now;
1308 pxHeapStats->xNumberOfSuccessfulFrees = snap.free_count;
1309
1310 // Fields that require free-block-list traversal are unavailable without a
1311 // block-list allocator (we delegate to malloc). Report conservative values:
1312 // - largest free block : current free bytes (treat heap as one region)
1313 // - smallest free block : 0 (unknown subdivision)
1314 // - number of free blocks: 1 (at least one region exists while free > 0)
1315 pxHeapStats->xSizeOfLargestFreeBlockInBytes = free_now;
1316 pxHeapStats->xSizeOfSmallestFreeBlockInBytes = (free_now > 0U) ? 1U : 0U;
1317 pxHeapStats->xNumberOfFreeBlocks = (free_now > 0U) ? 1U : 0U;
1318}
static Stats GetStats()
Get stats of memory allocation (checked).
Snapshot of the memory allocator's statistics.
volatile size_t allocate_count
Number of successful allocations with Allocate().
size_t GetAvailable() const
Get number of bytes currently available for allocation.
volatile size_t free_count
Number of successful frees with Free().
volatile size_t min_ever_free
Minimum free bytes recorded since system start (watermark).
size_t xSizeOfSmallestFreeBlockInBytes
Definition FreeRTOS.h:2165
size_t xMinimumEverFreeBytesRemaining
Definition FreeRTOS.h:2167
size_t xNumberOfSuccessfulAllocations
Definition FreeRTOS.h:2168
size_t xSizeOfLargestFreeBlockInBytes
Definition FreeRTOS.h:2164
size_t xNumberOfFreeBlocks
Definition FreeRTOS.h:2166
size_t xNumberOfSuccessfulFrees
Definition FreeRTOS.h:2169
size_t xAvailableHeapSpaceInBytes
Definition FreeRTOS.h:2163

References stk::memory::MemoryAllocator::Stats::allocate_count, stk::memory::MemoryAllocator::Stats::free_count, stk::memory::MemoryAllocator::Stats::GetAvailable(), stk::memory::MemoryAllocator::GetStats(), stk::memory::MemoryAllocator::Stats::min_ever_free, HeapStats_t::xAvailableHeapSpaceInBytes, HeapStats_t::xMinimumEverFreeBytesRemaining, HeapStats_t::xNumberOfFreeBlocks, HeapStats_t::xNumberOfSuccessfulAllocations, HeapStats_t::xNumberOfSuccessfulFrees, HeapStats_t::xSizeOfLargestFreeBlockInBytes, and HeapStats_t::xSizeOfSmallestFreeBlockInBytes.

Here is the call graph for this function:

◆ vQueueDelete()

void vQueueDelete ( QueueHandle_t xQueue)

Delete a queue and free all associated memory.

Parameters
xQueueHandle of the queue to delete.

Definition at line 2051 of file freertos_stk.cpp.

2052{
2053 if (xQueue == nullptr)
2054 return;
2055
2056 ObjFree(static_cast<FrtosQueue *>(xQueue));
2057}

◆ vSemaphoreDelete()

void vSemaphoreDelete ( SemaphoreHandle_t xSemaphore)

Delete a semaphore or mutex and free its memory.

Parameters
xSemaphoreHandle of the semaphore or mutex to delete.

Definition at line 2749 of file freertos_stk.cpp.

2750{
2751 if (xSemaphore == nullptr)
2752 return;
2753
2754 ObjFree(static_cast<FrtosSemaphore *>(xSemaphore));
2755}

◆ vStreamBufferDelete()

void vStreamBufferDelete ( StreamBufferHandle_t xStreamBuffer)

Delete a stream buffer and free heap resources (if dynamically allocated).

Parameters
xStreamBufferHandle of the stream buffer to delete.

Definition at line 4050 of file freertos_stk.cpp.

4051{
4052 if (xStreamBuffer == nullptr)
4053 return;
4054
4055 FrtosStreamBuffer *sb = static_cast<FrtosStreamBuffer *>(xStreamBuffer);
4056
4057 ObjFree(sb);
4058}

◆ vTaskDelay()

void vTaskDelay ( TickType_t xTicksToDelay)

Block the calling task for a number of ticks.

Parameters
xTicksToDelayNumber of ticks to block. 0 yields without blocking.
Examples
blinky_c-freertos/example.c.

Definition at line 1615 of file freertos_stk.cpp.

1616{
1617 if (IsIrqContext())
1618 return;
1619
1620 stk::Sleep(FrtosTimeoutToStk(xTicksToDelay));
1621}
static bool Sleep(Timeout tick_count)
Put calling process into a sleep state.
Definition stk_helper.h:495

References stk::Sleep().

Referenced by clock_task(), and signal_func().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ vTaskDelayUntil()

void vTaskDelayUntil ( TickType_t * pxPreviousWakeTime,
TickType_t xTimeIncrement )

Block until an absolute tick deadline for drift-free periodic loops. Updates *pxPreviousWakeTime on each call.

Parameters
pxPreviousWakeTimeIn/out: tick count at the last wake point; updated on return.
xTimeIncrementPeriod in ticks between successive wake points.

Definition at line 1623 of file freertos_stk.cpp.

1624{
1625 static_cast<void>(xTaskDelayUntil(pxPreviousWakeTime, xTimeIncrement));
1626}
BaseType_t xTaskDelayUntil(TickType_t *pxPreviousWakeTime, TickType_t xTimeIncrement)

References xTaskDelayUntil().

Here is the call graph for this function:

◆ vTaskDelete()

void vTaskDelete ( TaskHandle_t xTaskToDelete)

Delete a task. Pass NULL to delete the calling task.

Parameters
xTaskToDeleteHandle of the task to delete, or NULL to delete the calling task.

Definition at line 1504 of file freertos_stk.cpp.

1505{
1506 // release the memory of the other deleted tasks which the kernel has already removed
1507 ReapDeletedTasks();
1508
1509 FrtosTask *t = (xTaskToDelete == nullptr) ? static_cast<FrtosTask *>(
1510 FrtosTaskFromTid(stk::GetTid())) :
1511 static_cast<FrtosTask *>(xTaskToDelete);
1512
1513 if (t == nullptr)
1514 return;
1515
1516 if (stk::GetTid() == FrtosTidFromTask(t))
1517 {
1518 // vTaskDelete(NULL) / self-delete does not return: the calling task is switched out and removed by the kernel
1519 stk::ExitTask();
1520 }
1521 else
1522 {
1524
1525 // ScheduleTaskRemoval() only marks the task: the kernel removes it on the next tick and calls OnExit(),
1526 // which queues the task for ReapDeletedTasks(). Do NOT free it here: the kernel still references the TCB
1527 // and the stack.
1528 g_StkKernel.ScheduleTaskRemoval(t);
1529 }
1530}
static void ExitTask()
Terminate the calling task: schedule its removal and switch it out. Does not return.
Definition stk_helper.h:578

References stk::ExitTask(), and stk::GetTid().

Here is the call graph for this function:

◆ vTaskEndScheduler()

void vTaskEndScheduler ( void )

End scheduling (KERNEL_DYNAMIC only). Included for API completeness.

Definition at line 1349 of file freertos_stk.cpp.

1350{
1351 g_StkKernel.EnumerateTasksT<FREERTOS_STK_MAX_TASKS>([&](stk::ITask *task) -> bool
1352 {
1353 g_StkKernel.ScheduleTaskRemoval(task);
1354 return true;
1355 });
1356
1357 stk::Yield();
1358}

References FREERTOS_STK_MAX_TASKS, and stk::Yield().

Here is the call graph for this function:

◆ vTaskGetRunTimeStats()

void vTaskGetRunTimeStats ( char * pcWriteBuffer)

Write a human-readable CPU run-time statistics table into pcWriteBuffer.

Each row contains: task name, absolute run-time counter, and percentage of total run time. Column layout matches the standard FreeRTOS vTaskGetRunTimeStats() output so existing log parsers work unchanged.

Note
STK has no per-task CPU run-time accumulator. This wrapper always emits 0 for both the absolute counter and the percentage, matching the FreeRTOS convention for targets where configGENERATE_RUN_TIME_STATS is not enabled. The function is provided for link compatibility; applications that need real CPU accounting must instrument the target with a free-running hardware counter and replace the two MemoryAllocator definitions in freertos_stk.cpp with the appropriate port-layer calls.
Parameters
pcWriteBufferCaller-allocated destination buffer. A safe minimum is uxTaskGetNumberOfTasks() * 40 bytes.

Definition at line 1952 of file freertos_stk.cpp.

1953{
1954 if (pcWriteBuffer == nullptr)
1955 return;
1956
1957 // Column header matching FreeRTOS vTaskGetRunTimeStats() output format so
1958 // that existing log parsers (SystemView, Tracealyzer, custom scripts) find
1959 // the layout they expect.
1960 int off = snprintf(pcWriteBuffer, 64U,
1961 "%-12s %12s %8s\r\n",
1962 "Task", "Abs Time", "% Time");
1963
1964 if (off < 0) off = 0;
1965 char *p = pcWriteBuffer + off;
1966
1967 g_StkKernel.EnumerateTasksT<FREERTOS_STK_MAX_TASKS>([&](stk::ITask *itask) -> bool
1968 {
1969 const FrtosTask *t = static_cast<const FrtosTask *>(itask);
1970 const char *name = (t->m_name != nullptr) ? t->m_name : "(unnamed)";
1971
1972 // ulRunTimeCounter is always 0: STK has no per-task CPU accounting.
1973 // Percentage is therefore also 0. Emit "<1%" only when a non-zero
1974 // total is available; here total is always 0 so we emit "0%".
1975 int n = snprintf(p, 48U, "%-12s %12lu %7lu%%\r\n",
1976 name,
1977 0UL, // ulRunTimeCounter
1978 0UL); // percentage
1979 if (n > 0) p += n;
1980
1981 return true; // continue enumeration
1982 });
1983
1984 *p = '\0'; // null-terminate
1985}

References FREERTOS_STK_MAX_TASKS.

◆ vTaskList()

void vTaskList ( char * pcWriteBuffer)

Write a human-readable task-status table into pcWriteBuffer.

Each row contains: name, state letter (X/R/B/S/D), priority, stack high-water mark (Words), and a 1-based task number. Column widths match the standard FreeRTOS vTaskList() output so that existing tools and log parsers work without modification.

Parameters
pcWriteBufferCaller-allocated destination buffer. Must be large enough for all active tasks. A safe minimum is uxTaskGetNumberOfTasks() * 40 bytes.
Note
The output is a snapshot; it is not thread-safe with respect to concurrent task creation or deletion.

Definition at line 1881 of file freertos_stk.cpp.

1882{
1883 if (pcWriteBuffer == nullptr)
1884 return;
1885
1886 // Write the column header that FreeRTOS vTaskList() produces, so that
1887 // existing log parsers find what they expect.
1888 int off = snprintf(pcWriteBuffer, 64U,
1889 "%-12s %c %4s %6s %4s\r\n",
1890 "Name", 'S', "Prio", "Stack", "Num");
1891
1892 if (off < 0) off = 0;
1893 char *p = pcWriteBuffer + off;
1894
1895 // Enumerate all tasks and fill one row per task.
1896 UBaseType_t task_num = 0U;
1897
1898 g_StkKernel.EnumerateTasksT<FREERTOS_STK_MAX_TASKS>([&](stk::ITask *itask) -> bool
1899 {
1900 ++task_num;
1901 FrtosTask *t = static_cast<FrtosTask *>(itask);
1902
1903 // Determine state letter, matching FreeRTOS convention:
1904 // X = Running, R = Ready, B = Blocked, S = Suspended, D = Deleted
1905 char state_letter;
1906 if (t->m_state == FrtosTask::State::Deleted)
1907 state_letter = 'D';
1908 else
1909 if (t->m_state == FrtosTask::State::Suspended)
1910 state_letter = 'S';
1911 else
1912 if (stk::GetTid() == FrtosTidFromTask(t))
1913 state_letter = 'X';
1914 else
1915 state_letter = 'R';
1916
1917 const char *name = (t->m_name != nullptr) ? t->m_name : "(unnamed)";
1918 UBaseType_t prio = StkWeightToFrtosPrio(t->m_weight);
1919 size_t hwm = t->GetStackHighWaterMark();
1920
1921 int n = snprintf(p, 48U, "%-12s %c %4u %6u %4u\r\n",
1922 name, state_letter,
1923 static_cast<unsigned>(prio),
1924 static_cast<unsigned>(hwm),
1925 static_cast<unsigned>(task_num));
1926 if (n > 0) p += n;
1927
1928 return true; // continue enumeration
1929 });
1930
1931 *p = '\0'; // null-terminate
1932}

References FREERTOS_STK_MAX_TASKS, and stk::GetTid().

Here is the call graph for this function:

◆ vTaskPrioritySet()

void vTaskPrioritySet ( TaskHandle_t xTask,
UBaseType_t uxNewPriority )

Change the priority of a task. Pass NULL xTask for the calling task.

Parameters
xTaskHandle of the task to modify, or NULL for the calling task.
uxNewPriorityNew priority level (0 = lowest, configMAX_PRIORITIES-1 = highest).

Definition at line 1641 of file freertos_stk.cpp.

1642{
1643 FrtosTask *t = (xTask == nullptr) ? FrtosTaskFromTid(stk::GetTid()) : static_cast<FrtosTask *>(xTask);
1644
1645 if (t == nullptr)
1646 return;
1647
1648 const int32_t weight = FrtosPrioToStkWeight(uxNewPriority);
1649
1650 if (t->m_state != FrtosTask::State::Deleted)
1651 {
1652 // sched::SwitchStrategyFixedPriority keeps its ready lists keyed by the task's (base) weight and the kernel reads
1653 // the weight from its own record, so only IKernelService::SetWeight() moves the task to the new priority
1654 // level (and keeps priority inheritance consistent). It must run BEFORE m_weight is updated: the kernel
1655 // derives the old level from the weight which is still in effect. Writing m_weight alone would leave the
1656 // task in the old list and trip the strategy's list assertions later.
1657 (void)stk::IKernelService::GetInstance()->SetWeight(FrtosTidFromTask(t), weight);
1658 }
1659
1660 t->m_weight = weight; // ITask::GetWeight() / uxTaskPriorityGet() view of the base priority
1661}
static IKernelService * GetInstance()
Get CPU-local instance of the kernel service.

References stk::IKernelService::GetInstance(), and stk::GetTid().

Here is the call graph for this function:

◆ vTaskResume()

void vTaskResume ( TaskHandle_t xTaskToResume)

Resume a previously suspended task.

Parameters
xTaskToResumeHandle of the task to resume.

Definition at line 1553 of file freertos_stk.cpp.

1554{
1555 if (xTaskToResume == nullptr)
1556 return;
1557
1558 FrtosTask *t = static_cast<FrtosTask *>(xTaskToResume);
1559
1561
1562 if (t->m_state != FrtosTask::State::Suspended)
1563 return;
1564
1565 const stk::EResumeResult res = g_StkKernel.ResumeTask(t);
1566 if ((res == stk::RESUME_DONE) || (res == stk::RESUME_LIFTED))
1567 t->m_state = FrtosTask::State::Ready;
1568}
EResumeResult
Result of IKernel::ResumeTask().
Definition stk_common.h:183
@ RESUME_LIFTED
Deferred suspension was cancelled before it took effect.
Definition stk_common.h:187
@ RESUME_DONE
Suspended task has been resumed.
Definition stk_common.h:186

References stk::RESUME_DONE, and stk::RESUME_LIFTED.

◆ vTaskSetThreadLocalStoragePointer()

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

Write a TLS pointer slot for a task.

Parameters
xTaskToSetTask handle, or NULL for the calling task.
xIndexSlot index (0 .. configNUM_THREAD_LOCAL_STORAGE_POINTERS-1).
pvValueValue to store.

< Per-task TLS pointer slots.

Definition at line 3936 of file freertos_stk.cpp.

3939{
3940 if (xIndex < 0 || static_cast<size_t>(xIndex) >= configNUM_THREAD_LOCAL_STORAGE_POINTERS)
3941 return;
3942
3943 // Resolve NULL -> calling task.
3944 if (xTaskToSet == nullptr)
3945 xTaskToSet = xTaskGetCurrentTaskHandle();
3946
3947 if (xTaskToSet == nullptr)
3948 return;
3949
3950 FrtosTask *t = static_cast<FrtosTask *>(xTaskToSet);
3951
3952 // A critical section is not strictly required for a pointer-sized store on
3953 // aligned memory on single-issue cores, but we guard anyway for strict
3954 // correctness on SMP targets (RP2040, dual-core Cortex-M33).
3956 t->m_tls[static_cast<size_t>(xIndex)] = pvValue;
3957}

References configNUM_THREAD_LOCAL_STORAGE_POINTERS, and xTaskGetCurrentTaskHandle().

Here is the call graph for this function:

◆ vTaskStartScheduler()

void vTaskStartScheduler ( void )

Initialise STK and start the scheduler. Does not return for KERNEL_DYNAMIC until all tasks have exited.

Examples
blinky_c-freertos/example.c.

Definition at line 1342 of file freertos_stk.cpp.

1343{
1344 EnsureKernelInitialized();
1345
1346 g_StkKernel.Start(); // does not return for KERNEL_DYNAMIC until all tasks exit
1347}

Referenced by app_run().

Here is the caller graph for this function:

◆ vTaskSuspend()

void vTaskSuspend ( TaskHandle_t xTaskToSuspend)

Suspend a task indefinitely. Pass NULL to suspend the calling task.

Parameters
xTaskToSuspendHandle of the task to suspend, or NULL for the calling task.
Examples
blinky_c-freertos/example.c.

Definition at line 1532 of file freertos_stk.cpp.

1533{
1534 FrtosTask *t = (xTaskToSuspend == nullptr) ? static_cast<FrtosTask *>(
1535 FrtosTaskFromTid(stk::GetTid())) :
1536 static_cast<FrtosTask *>(xTaskToSuspend);
1537
1538 if (t == nullptr)
1539 return;
1540
1541 // Publish the state BEFORE calling the kernel: suspending the calling task does not return until the task
1542 // is resumed, setting the state afterwards would leave vTaskResume() seeing State::Ready and skipping
1543 // ResumeTask() forever. Must not be called inside a critical section (self-suspend would deadlock).
1544 const FrtosTask::State prev = t->m_state;
1545 t->m_state = FrtosTask::State::Suspended;
1546
1547 // SUSPEND_DONE: suspended now. SUSPEND_DEFERRED: sleeping/blocked, suspended when the wait ends.
1548 // SUSPEND_ALREADY: nothing to do, the state is already correct. SUSPEND_FAIL: roll back.
1549 if (g_StkKernel.SuspendTask(t) == stk::SUSPEND_FAIL)
1550 t->m_state = prev;
1551}
@ SUSPEND_FAIL
Task is not bound to the kernel, or is exiting.
Definition stk_common.h:173

References stk::GetTid(), and stk::SUSPEND_FAIL.

Referenced by app_main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ vTaskSuspendAll()

void vTaskSuspendAll ( void )

Suspend the scheduler (disables preemption; interrupts remain enabled).

Definition at line 1360 of file freertos_stk.cpp.

1361{
1363}

References stk::hw::CriticalSection::Enter().

Here is the call graph for this function:

◆ vTimerSetTimerID()

void vTimerSetTimerID ( TimerHandle_t xTimer,
void * pvNewID )

Set the application-defined ID stored in a timer.

Parameters
xTimerHandle of the timer to modify.
pvNewIDNew ID value to store in the timer.

Definition at line 3304 of file freertos_stk.cpp.

3305{
3306 if (xTimer == nullptr)
3307 return;
3308
3309 static_cast<FrtosTimer *>(xTimer)->m_timer_id = pvNewID;
3310}

◆ xEventGroupClearBits()

EventBits_t xEventGroupClearBits ( EventGroupHandle_t xEventGroup,
EventBits_t uxBitsToClear )

Clear one or more bits in an event group (ISR-safe).

Parameters
xEventGroupHandle of the event group to modify.
uxBitsToClearBitmask of bits to clear (ANDed with complement into the current value).
Returns
Value of the bits BEFORE clearing.

Definition at line 3390 of file freertos_stk.cpp.

3392{
3393 if (xEventGroup == nullptr)
3394 return 0U;
3395
3396 // STK Clear() returns the value BEFORE clearing - matches FreeRTOS contract.
3397 uint32_t prev = static_cast<FrtosEventGroup *>(xEventGroup)->m_ef.Clear(uxBitsToClear);
3398 return StkFlagsToFrtos(prev);
3399}

◆ xEventGroupClearBitsFromISR()

EventBits_t xEventGroupClearBitsFromISR ( EventGroupHandle_t xEventGroup,
EventBits_t uxBitsToClear )

Clear event group bits from ISR context.

Parameters
xEventGroupHandle of the event group to modify.
uxBitsToClearBitmask of bits to clear.
Returns
Value of the bits BEFORE clearing.

Definition at line 3451 of file freertos_stk.cpp.

3453{
3454 if (xEventGroup == nullptr)
3455 return 0U;
3456
3457 uint32_t prev = static_cast<FrtosEventGroup *>(xEventGroup)->m_ef.Clear(
3458 static_cast<uint32_t>(uxBitsToClear));
3459 return StkFlagsToFrtos(prev);
3460}

◆ xEventGroupCreate()

EventGroupHandle_t xEventGroupCreate ( void )

Create an event group (all bits initialised to 0).

Returns
Event group handle, or NULL on failure.

Definition at line 3345 of file freertos_stk.cpp.

3346{
3347 if (IsIrqContext())
3348 return nullptr;
3349
3350 FrtosEventGroup *eg = ObjAlloc<FrtosEventGroup>();
3351 return static_cast<EventGroupHandle_t>(eg);
3352}
void * EventGroupHandle_t
Definition FreeRTOS.h:321

◆ xEventGroupCreateStatic()

EventGroupHandle_t xEventGroupCreateStatic ( StaticEventGroup_t * pxEventGroupBuffer)

Create an event group using caller-supplied storage — no heap allocation.

Parameters
pxEventGroupBufferCaller-allocated control block (StaticEventGroup_t). Must remain valid for the lifetime of the event group.
Returns
Event group handle. Never NULL if pxEventGroupBuffer is non-NULL.

Definition at line 3354 of file freertos_stk.cpp.

3355{
3356 if (pxEventGroupBuffer == nullptr)
3357 return nullptr;
3358
3359 if (IsIrqContext())
3360 return nullptr;
3361
3362 STK_STATIC_ASSERT_DESC(sizeof(StaticEventGroup_t) >= sizeof(FrtosEventGroup),
3363 "StaticEventGroup_t is too small to hold FrtosEventGroup. "
3364 "Increase STATIC_EVENT_GROUP_TCB_SIZE_WORDS in freertos_stk.h.");
3365
3366 FrtosEventGroup *eg = new (pxEventGroupBuffer) FrtosEventGroup();
3367 eg->m_cb_owned = false; // caller owns the memory; vEventGroupDelete must not delete it
3368
3369 return static_cast<EventGroupHandle_t>(eg);
3370}
#define STK_STATIC_ASSERT_DESC(X, DESC)
Compile-time assertion with a custom error description. Produces a compilation error if X is false.
Definition stk_defs.h:548

References STK_STATIC_ASSERT_DESC.

◆ xEventGroupGetBits()

EventBits_t xEventGroupGetBits ( EventGroupHandle_t xEventGroup)

Return the current event group bits without blocking or modifying them.

Parameters
xEventGroupHandle of the event group to read.
Returns
Current bitmask value of the event group.

Definition at line 3401 of file freertos_stk.cpp.

3402{
3403 if (xEventGroup == nullptr)
3404 return 0U;
3405
3406 return static_cast<EventBits_t>(static_cast<FrtosEventGroup *>(xEventGroup)->m_ef.Get());
3407}
uint32_t EventBits_t
Definition FreeRTOS.h:387

◆ xEventGroupSetBits()

EventBits_t xEventGroupSetBits ( EventGroupHandle_t xEventGroup,
EventBits_t uxBitsToSet )

Set one or more bits in an event group (ISR-safe).

Parameters
xEventGroupHandle of the event group to modify.
uxBitsToSetBitmask of bits to set (OR'd into the current value).
Returns
Value of the event group bits after the set operation.

Definition at line 3380 of file freertos_stk.cpp.

3382{
3383 if (xEventGroup == nullptr)
3384 return 0U;
3385
3386 uint32_t result = static_cast<FrtosEventGroup *>(xEventGroup)->m_ef.Set(uxBitsToSet);
3387 return StkFlagsToFrtos(result);
3388}

◆ xEventGroupSetBitsFromISR()

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

Set event group bits from ISR context.

Parameters
xEventGroupHandle of the event group to modify.
uxBitsToSetBitmask of bits to set.
pxHigherPriorityTaskWokenSet pdTRUE if a context switch is needed.
Returns
pdPASS on success, pdFAIL on invalid bits argument.

Definition at line 3435 of file freertos_stk.cpp.

3438{
3439 if (xEventGroup == nullptr)
3440 return pdFAIL;
3441
3442 uint32_t result = static_cast<FrtosEventGroup *>(xEventGroup)->m_ef.Set(
3443 static_cast<uint32_t>(uxBitsToSet));
3444
3445 if (pxHigherPriorityTaskWoken != nullptr)
3446 *pxHigherPriorityTaskWoken = pdFALSE;
3447
3448 return stk::sync::EventFlags::IsError(result) ? pdFAIL : pdPASS;
3449}
#define pdPASS
Definition FreeRTOS.h:272
#define pdFAIL
Definition FreeRTOS.h:273
#define pdFALSE
Definition FreeRTOS.h:271
static bool IsError(uint32_t result)

References stk::sync::EventFlagsT< uint32_t >::IsError(), pdFAIL, pdFALSE, and pdPASS.

Here is the call graph for this function:

◆ xEventGroupSync()

EventBits_t xEventGroupSync ( EventGroupHandle_t xEventGroup,
EventBits_t uxBitsToSet,
EventBits_t uxBitsToWaitFor,
TickType_t xTicksToWait )

Task rendezvous / barrier synchronization using an event group.

Atomically sets uxBitsToSet in the event group, then blocks until uxBitsToWaitFor are all set (AND semantics). On success, all bits in uxBitsToWaitFor are atomically cleared before returning.

Note
This is the standard FreeRTOS "event group sync" / barrier primitive. All N participating tasks call xEventGroupSync() with the same uxBitsToWaitFor mask and non-overlapping individual uxBitsToSet masks (one bit per task). The call returns only after every task has set its bit.
The set and the wait are performed without releasing the CPU between them, so no participating task can observe a state in which this task has not yet entered the wait. This matches the FreeRTOS reference implementation guarantee.
Parameters
xEventGroupEvent group handle (must not be NULL).
uxBitsToSetBit(s) this task sets to signal it has reached the sync point (must be a subset of uxBitsToWaitFor).
uxBitsToWaitForBitmask of ALL bits that must be set before any participating task is released (AND semantics).
xTicksToWaitMaximum ticks to wait. portMAX_DELAY = wait forever. NO_WAIT (0) performs a non-blocking test.
Returns
Value of the event group bits at the point the condition was met (before the bits were cleared), or 0 if the timeout expired before all bits were set.
Warning
ISR-unsafe (blocking). Not callable from an ISR context.

Definition at line 3476 of file freertos_stk.cpp.

3480{
3481 // Contract checks that mirror the FreeRTOS reference implementation.
3482 if (xEventGroup == nullptr) return 0U;
3483 if (uxBitsToWaitFor == 0U) return 0U;
3484 if (IsIrqContext()) return 0U; // blocking wait is ISR-unsafe
3485
3486 FrtosEventGroup *eg = static_cast<FrtosEventGroup *>(xEventGroup);
3487 stk::sync::EventFlags &ef = eg->m_ef;
3488
3489 // EventFlags::Sync() sets this task's bit(s) and waits for ALL of uxBitsToWaitFor atomically; the task
3490 // which completes the rendezvous clears uxBitsToWaitFor once and releases every blocked participant.
3491 //
3492 // uxBitsToSet == 0 is legal (observer role). The returned value is the group's flags word at the moment
3493 // the rendezvous completed (before the clear), or the current flags word on timeout.
3494 uint32_t actual = 0U;
3495
3496 (void)ef.Sync(eg->m_sync,
3497 static_cast<uint32_t>(uxBitsToSet),
3498 static_cast<uint32_t>(uxBitsToWaitFor),
3499 FrtosTimeoutToStk(xTicksToWait),
3500 actual);
3501
3502 return static_cast<EventBits_t>(actual);
3503}
EventFlagsT< uint32_t > EventFlags
Default event flags group with a 32-bit flags word (31 usable flags, bit 31 reserved).
EWaitResult Sync(SyncContext &ctx, T set_flags, T wait_flags, Timeout timeout_ticks, T &actual_flags)
Atomically set flags and wait for a group of flags: a multi-task rendezvous (equivalent of FreeRTOS x...

References stk::sync::EventFlagsT< T >::Sync().

Here is the call graph for this function:

◆ xEventGroupWaitBits()

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

Block the calling task until the specified bit condition is met.

Parameters
xEventGroupHandle of the event group to wait on.
uxBitsToWaitForBitmask of bits to watch.
xClearOnExitpdTRUE = atomically clear matched bits on return.
xWaitForAllBitspdTRUE = AND semantics, pdFALSE = OR semantics.
xTicksToWaitMaximum ticks to block. portMAX_DELAY = wait forever.
Returns
Bits that caused unblocking (before optional clear), or 0 on timeout.

Definition at line 3409 of file freertos_stk.cpp.

3414{
3415 if (IsIrqContext() || (xEventGroup == nullptr) || (uxBitsToWaitFor == 0U))
3416 return 0U;
3417
3418 stk::sync::EventFlags &ef = static_cast<FrtosEventGroup *>(xEventGroup)->m_ef;
3419
3420 // The EWaitResult overload reports the status and the flags word separately: 'actual' is the whole
3421 // flags word captured under the same critical section as the wait outcome, before any clear-on-exit.
3422 // This is what FreeRTOS returns both when the condition is met (the group's bits at that moment) and
3423 // on timeout / aborted wait (the bits at the moment the wait ended), so no separate Get() is needed.
3424 const uint32_t opts = BuildStkFlagsOpts(xClearOnExit, xWaitForAllBits);
3425 uint32_t actual = 0U;
3426
3427 (void)ef.WaitEx(static_cast<uint32_t>(uxBitsToWaitFor),
3428 opts,
3429 FrtosTimeoutToStk(xTicksToWait),
3430 actual);
3431
3432 return static_cast<EventBits_t>(actual);
3433}
EWaitResult WaitEx(T flags, uint32_t options, Timeout timeout_ticks, T &actual_flags)
Wait for one or more flags to be set, reporting the outcome via EWaitResult.

References stk::sync::EventFlagsT< T >::WaitEx().

Here is the call graph for this function:

◆ xMessageBufferCreate()

MessageBufferHandle_t xMessageBufferCreate ( size_t xBufferSizeBytes,
size_t xMaxMessageSize )

Create a dynamically allocated message buffer.

Parameters
xBufferSizeBytesTotal storage budget. The implementation derives slot count as floor(xBufferSizeBytes / (AlignBlockSize(xMaxMessageSize)
  • sizeof(envelope))).
xMaxMessageSizeMaximum payload size per message in bytes.
Returns
Handle, or NULL on allocation failure.

Definition at line 4370 of file freertos_stk.cpp.

4371{
4372 if ((xBufferSizeBytes == 0U) || (xMaxMessageSize == 0U))
4373 return nullptr;
4374
4375 const size_t count = MsgBufSlotCount(xBufferSizeBytes, xMaxMessageSize);
4376
4377 if (count == 0U)
4378 return nullptr;
4379
4380 FrtosMessageBuffer *mb = ObjAlloc<FrtosMessageBuffer>(xMaxMessageSize, count);
4381
4382 if (mb == nullptr)
4383 return nullptr;
4384
4385 if (!mb->m_pool.IsStorageValid() || !mb->m_eq.IsStorageValid())
4386 {
4387 ObjFreeRaw(mb);
4388 return nullptr;
4389 }
4390
4391 return static_cast<MessageBufferHandle_t>(mb);
4392}
void * MessageBufferHandle_t
Definition FreeRTOS.h:323
bool IsStorageValid() const
Verify that the backing storage is valid and the pool is ready for use.
bool IsStorageValid() const
Verify that the backing storage is valid and the pool is ready for use.

References stk::memory::BlockMemoryPool::IsStorageValid(), and stk::sync::MessageQueue::IsStorageValid().

Here is the call graph for this function:

◆ xMessageBufferCreateStatic()

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

Create a statically allocated message buffer (no heap).

Parameters
xMaxMessageSizeMaximum payload size per message.
xMessageCountMaximum number of in-flight messages.
pucMessageBufferStorageAreaCaller-supplied flat buffer of at least xMessageCount * (AlignBlockSize(xMaxMessageSize) + sizeof(envelope)) bytes.
pxStaticMessageBufferCaller-supplied TCB (StaticMessageBuffer_t).
Returns
Handle (always non-NULL if arguments are non-NULL).

Definition at line 4394 of file freertos_stk.cpp.

4399{
4400 if ((pucMessageBufferStorageArea == nullptr) ||
4401 (pxStaticMessageBuffer == nullptr) ||
4402 (xMaxMessageSize == 0U) ||
4403 (xMessageCount == 0U))
4404 return nullptr;
4405
4406 const size_t block_size = stk::memory::BlockMemoryPool::AlignBlockSize(xMaxMessageSize);
4407 const size_t storage_size = xMessageCount * (block_size + FrtosMessageBuffer::ENVELOPE_SIZE);
4408
4409 FrtosMessageBuffer *mb = new (pxStaticMessageBuffer)
4410 FrtosMessageBuffer(xMaxMessageSize, xMessageCount,
4411 pucMessageBufferStorageArea, storage_size);
4412
4413 return static_cast<MessageBufferHandle_t>(mb);
4414}
static constexpr size_t AlignBlockSize(size_t raw_size, size_t alignment=ALIGN_DEFAULT)
Round a raw block size up to the nearest multiple of alignment.

References stk::memory::BlockMemoryPool::AlignBlockSize().

Here is the call graph for this function:

◆ xMessageBufferCreateStaticWithCallback()

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

Create a statically-allocated message buffer with optional send/receive callbacks.

Identical to xMessageBufferCreateStatic() but registers per-instance callbacks. Either callback may be NULL.

Parameters
xMaxMessageSizeMaximum payload size per message in bytes.
xMessageCountMaximum number of in-flight messages.
pucMessageBufferStorageAreaCaller-supplied flat storage buffer.
pxStaticMessageBufferCaller-supplied TCB (StaticMessageBuffer_t).
pxSendCompletedCallbackCalled after a message is enqueued (or NULL).
pxReceiveCompletedCallbackCalled after a message is dequeued (or NULL).
Returns
Handle, or NULL on invalid arguments.

Definition at line 4461 of file freertos_stk.cpp.

4468{
4469 if ((pucMessageBufferStorageArea == nullptr) ||
4470 (pxStaticMessageBuffer == nullptr) ||
4471 (xMaxMessageSize == 0U) ||
4472 (xMessageCount == 0U))
4473 return nullptr;
4474
4475 STK_STATIC_ASSERT_DESC(sizeof(StaticMessageBuffer_t) >= sizeof(FrtosMessageBuffer),
4476 "Increase STATIC_MESSAGE_BUFFER_TCB_SIZE_WORDS in FreeRTOS.h.");
4477
4478 const size_t block_size = stk::memory::BlockMemoryPool::AlignBlockSize(xMaxMessageSize);
4479 const size_t storage_size = xMessageCount * (block_size + FrtosMessageBuffer::ENVELOPE_SIZE);
4480
4481 FrtosMessageBuffer *mb = new (pxStaticMessageBuffer)
4482 FrtosMessageBuffer(xMaxMessageSize, xMessageCount,
4483 pucMessageBufferStorageArea, storage_size,
4484 pxSendCompletedCallback, pxReceiveCompletedCallback);
4485
4486 return static_cast<MessageBufferHandle_t>(mb);
4487}

References stk::memory::BlockMemoryPool::AlignBlockSize(), and STK_STATIC_ASSERT_DESC.

Here is the call graph for this function:

◆ xMessageBufferCreateWithCallback()

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

Create a heap-allocated message buffer with optional send/receive callbacks.

Identical to xMessageBufferCreate() but registers per-instance callbacks invoked after a message is successfully enqueued (pxSendCompletedCallback) or dequeued (pxReceiveCompletedCallback). Either callback may be NULL. Callbacks fire outside any critical section, after the transfer completes. The xStreamBuffer argument passed to the callback is the MessageBufferHandle_t cast to StreamBufferHandle_t, matching FreeRTOS convention.

Parameters
xBufferSizeBytesTotal storage budget (slot count derived internally).
xMaxMessageSizeMaximum payload size per message in bytes.
pxSendCompletedCallbackCalled after a message is enqueued (or NULL).
pxReceiveCompletedCallbackCalled after a message is dequeued (or NULL).
Returns
Handle, or NULL on allocation failure.

Definition at line 4427 of file freertos_stk.cpp.

4432{
4433 if ((xBufferSizeBytes == 0U) || (xMaxMessageSize == 0U))
4434 return nullptr;
4435
4436 const size_t block_size = stk::memory::BlockMemoryPool::AlignBlockSize(xMaxMessageSize);
4437 const size_t slot_cost = block_size + FrtosMessageBuffer::ENVELOPE_SIZE;
4438 const size_t count = xBufferSizeBytes / slot_cost;
4439
4440 if (count == 0U)
4441 return nullptr;
4442
4443 FrtosMessageBuffer *mb = ObjAlloc<FrtosMessageBuffer>(
4444 xMaxMessageSize, count,
4445 pxSendCompletedCallback, pxReceiveCompletedCallback);
4446
4447 if (mb == nullptr)
4448 return nullptr;
4449
4450 // Detect heap failure in the envelope buffer allocation performed by the
4451 // heap constructor (m_eq is backed by a separately ObjAllocArray'd byte array).
4452 if (!mb->m_eq.IsStorageValid())
4453 {
4454 ObjFreeRaw(mb);
4455 return nullptr;
4456 }
4457
4458 return static_cast<MessageBufferHandle_t>(mb);
4459}

References stk::memory::BlockMemoryPool::AlignBlockSize(), and stk::sync::MessageQueue::IsStorageValid().

Here is the call graph for this function:

◆ xMessageBufferIsEmpty()

BaseType_t xMessageBufferIsEmpty ( MessageBufferHandle_t xMessageBuffer)

Return pdTRUE if the message buffer contains no messages.

Parameters
xMessageBufferHandle of the message buffer.
Note
ISR-safe.

Definition at line 4590 of file freertos_stk.cpp.

4591{
4592 if (xMessageBuffer == nullptr)
4593 return pdTRUE;
4594
4595 return static_cast<FrtosMessageBuffer *>(xMessageBuffer)->m_eq.IsEmpty()
4596 ? pdTRUE : pdFALSE;
4597}

References pdFALSE, and pdTRUE.

◆ xMessageBufferIsFull()

BaseType_t xMessageBufferIsFull ( MessageBufferHandle_t xMessageBuffer)

Return pdTRUE if no more messages can be enqueued (pool exhausted).

Parameters
xMessageBufferHandle of the message buffer.
Note
ISR-safe.

Definition at line 4599 of file freertos_stk.cpp.

4600{
4601 if (xMessageBuffer == nullptr)
4602 return pdTRUE;
4603
4604 return static_cast<FrtosMessageBuffer *>(xMessageBuffer)->m_pool.IsFull()
4605 ? pdTRUE : pdFALSE;
4606}

References pdFALSE, and pdTRUE.

◆ xMessageBufferNextLengthBytes()

size_t xMessageBufferNextLengthBytes ( MessageBufferHandle_t xMessageBuffer)

Return the byte length of the next message that would be returned by xMessageBufferReceive(), without removing it from the buffer.

Backed by stk::sync::MessageQueue::TryPeek(), which copies the oldest envelope atomically without consuming it. No dequeue-and-reinsert pair is needed; the queue state is left unchanged in a single ISR-safe operation.

Parameters
xMessageBufferHandle of the message buffer.
Returns
Length in bytes of the oldest pending message, or 0 if the buffer is empty.
Note
ISR-safe.

Definition at line 4805 of file freertos_stk.cpp.

4806{
4807 if (xMessageBuffer == nullptr)
4808 return 0U;
4809
4810 FrtosMessageBuffer *mb = static_cast<FrtosMessageBuffer *>(xMessageBuffer);
4811
4812 // TryPeek copies the oldest envelope without consuming it. The internal
4813 // ScopedCriticalSection makes this ISR-safe; no outer CS is required.
4814 FrtosMessageBuffer::MsgEnvelope env = { 0U, nullptr };
4815
4816 if (!mb->m_eq.TryPeek(&env))
4817 return 0U; // buffer is empty — nothing to peek at
4818
4819 return env.len;
4820}
bool TryPeek(void *msg_ptr)
Attempt to peek at the next message without blocking.

References stk::sync::MessageQueue::TryPeek().

Here is the call graph for this function:

◆ xMessageBufferReceive()

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

Receive a message from the message buffer (task context, may block).

Parameters
xMessageBufferHandle of the message buffer to receive from.
pvRxDataDestination buffer.
xBufferLengthBytesCapacity of pvRxData; must be >= the oldest message length.
xTicksToWaitTicks to wait for a message. portMAX_DELAY blocks indefinitely.
Returns
Number of bytes written to pvRxData, or 0 on timeout / size violation.
Warning
ISR-unsafe. Use xMessageBufferReceiveFromISR() from ISR context.

Definition at line 4547 of file freertos_stk.cpp.

4551{
4552 if ((xMessageBuffer == nullptr) || (pvRxData == nullptr) || (xBufferLengthBytes == 0U))
4553 return 0U;
4554
4555 if (IsIrqContext() && (xTicksToWait != 0U))
4556 return 0U;
4557
4558 FrtosMessageBuffer *mb = static_cast<FrtosMessageBuffer *>(xMessageBuffer);
4559
4560 // 1. Dequeue the next envelope.
4561 FrtosMessageBuffer::MsgEnvelope env = { 0U, nullptr };
4562
4563 if (!mb->m_eq.Get(&env, FrtosTimeoutToStk(xTicksToWait)))
4564 return 0U;
4565
4566 // 2. Validate destination capacity.
4567 if (xBufferLengthBytes < env.len)
4568 {
4569 // Destination too small: re-enqueue the envelope so the message is
4570 // not lost (best-effort; if re-enqueue also fails the message is lost).
4571 STK_ASSERT(false); // API contract: pvRxData buffer too small
4572 mb->m_eq.TryPut(&env);
4573 return 0U;
4574 }
4575
4576 // 3. Copy payload out and return the block.
4577 stk::STK_MEMCPY(pvRxData, env.blk, env.len);
4578 mb->m_pool.Free(env.blk);
4579
4580 // Fire receive-complete callback outside any critical section.
4581 if (mb->m_recv_cb != nullptr)
4582 {
4583 BaseType_t woken = pdFALSE;
4584 mb->m_recv_cb(static_cast<StreamBufferHandle_t>(xMessageBuffer), &woken);
4585 }
4586
4587 return env.len;
4588}
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532
void * StreamBufferHandle_t
Definition FreeRTOS.h:322
long BaseType_t
Definition FreeRTOS.h:261
void STK_MEMCPY(void *const dest, const void *const src, size_t size)
Implementation of STK_MEMCPY.
Definition stk_arch.h:788
bool Free(void *ptr)
Return a previously allocated block to the pool.
bool TryPut(const void *msg_ptr)
Attempt to put a message into the back of the queue without blocking.
bool Get(void *msg_ptr, Timeout timeout_ticks=WAIT_INFINITE)
Get a message from the queue.

References stk::memory::BlockMemoryPool::Free(), stk::sync::MessageQueue::Get(), pdFALSE, STK_ASSERT, stk::STK_MEMCPY(), and stk::sync::MessageQueue::TryPut().

Here is the call graph for this function:

◆ xMessageBufferReceiveFromISR()

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

Receive a message from the message buffer from ISR context (non-blocking).

Attempts to dequeue one envelope without blocking. If an envelope is available and fits in the destination buffer the payload is copied out and the pool block is freed.

Parameters
xMessageBufferHandle of the message buffer to receive from.
pvRxDataDestination buffer.
xBufferLengthBytesCapacity of pvRxData; must be >= the oldest message length.
pxHigherPriorityTaskWokenAlways set to pdFALSE; STK handles scheduling.
Returns
Number of bytes written to pvRxData, or 0 if empty / destination too small.
Warning
ISR-safe (non-blocking).

Definition at line 4734 of file freertos_stk.cpp.

4738{
4739 if (pxHigherPriorityTaskWoken != nullptr)
4740 *pxHigherPriorityTaskWoken = pdFALSE;
4741
4742 if ((xMessageBuffer == nullptr) || (pvRxData == nullptr) || (xBufferLengthBytes == 0U))
4743 return 0U;
4744
4745 FrtosMessageBuffer *mb = static_cast<FrtosMessageBuffer *>(xMessageBuffer);
4746
4747 // Step 1: non-blocking dequeue of the oldest envelope.
4748 FrtosMessageBuffer::MsgEnvelope env = { 0U, nullptr };
4749 if (!mb->m_eq.TryGet(&env))
4750 return 0U; // buffer empty
4751
4752 // Step 2: validate destination capacity.
4753 if (xBufferLengthBytes < env.len)
4754 {
4755 // Destination too small: put the envelope back at the front so the
4756 // message is not lost. TryPutFront retreats the tail pointer under
4757 // its own CS — identical to Get never having happened.
4758 STK_ASSERT(false); // API contract: pvRxData buffer too small
4759 mb->m_eq.TryPutFront(&env);
4760 return 0U;
4761 }
4762
4763 // Step 3: copy payload out and release pool block.
4764 stk::STK_MEMCPY(pvRxData, env.blk, env.len);
4765 mb->m_pool.Free(env.blk);
4766
4767 // Fire receive-complete callback outside any critical section.
4768 // pxHigherPriorityTaskWoken is always pdFALSE per STK convention.
4769 if (mb->m_recv_cb != nullptr)
4770 {
4771 BaseType_t woken = pdFALSE;
4772 mb->m_recv_cb(static_cast<StreamBufferHandle_t>(xMessageBuffer), &woken);
4773 }
4774
4775 return env.len;
4776}
bool TryPutFront(const void *msg_ptr)
Attempt to put a message into the front of the queue without blocking.
bool TryGet(void *msg_ptr)
Attempt to get a message from the queue without blocking.

References stk::memory::BlockMemoryPool::Free(), pdFALSE, STK_ASSERT, stk::STK_MEMCPY(), stk::sync::MessageQueue::TryGet(), and stk::sync::MessageQueue::TryPutFront().

Here is the call graph for this function:

◆ xMessageBufferReset()

BaseType_t xMessageBufferReset ( MessageBufferHandle_t xMessageBuffer)

Discard all pending messages, return all blocks to the pool, and reset the envelope queue to the empty state (task context).

Returns
pdPASS always.
Warning
ISR-safe. Prefer xMessageBufferResetFromISR() from interrupt context to properly signal pxHigherPriorityTaskWoken.

Definition at line 4617 of file freertos_stk.cpp.

4618{
4619 if (xMessageBuffer == nullptr)
4620 return pdFAIL;
4621
4622 FrtosMessageBuffer *mb = static_cast<FrtosMessageBuffer *>(xMessageBuffer);
4623
4624 // Drain all pending envelopes and return their blocks to the pool.
4625 FrtosMessageBuffer::MsgEnvelope env = { 0U, nullptr };
4626
4627 while (mb->m_eq.TryGet(&env))
4628 {
4629 if (env.blk != nullptr)
4630 mb->m_pool.Free(env.blk);
4631 }
4632
4633 // Reset the envelope queue (wakes any blocked senders).
4634 mb->m_eq.Reset();
4635
4636 return pdPASS;
4637}
void Reset()
Discard all messages and reset the queue to the empty state.

References stk::memory::BlockMemoryPool::Free(), pdFAIL, pdPASS, stk::sync::MessageQueue::Reset(), and stk::sync::MessageQueue::TryGet().

Here is the call graph for this function:

◆ xMessageBufferResetFromISR()

BaseType_t xMessageBufferResetFromISR ( MessageBufferHandle_t xMessageBuffer,
BaseType_t * pxHigherPriorityTaskWoken )

Discard all pending messages and reset the buffer from ISR context.

Drains every pending envelope, frees its pool block, then resets the envelope queue. Wakes any task blocked in xMessageBufferSend() that was waiting for a free slot.

Parameters
xMessageBufferHandle of the message buffer.
pxHigherPriorityTaskWokenAlways set to pdFALSE; STK handles scheduling.
Returns
pdPASS always.
Warning
ISR-safe.

Definition at line 4778 of file freertos_stk.cpp.

4780{
4781 if (pxHigherPriorityTaskWoken != nullptr)
4782 *pxHigherPriorityTaskWoken = pdFALSE;
4783
4784 if (xMessageBuffer == nullptr)
4785 return pdFAIL;
4786
4787 FrtosMessageBuffer *mb = static_cast<FrtosMessageBuffer *>(xMessageBuffer);
4788
4789 // Drain all pending envelopes, returning every pool block before resetting
4790 // the queue. All three operations are ISR-safe (ScopedCriticalSection).
4791 FrtosMessageBuffer::MsgEnvelope env = { 0U, nullptr };
4792
4793 while (mb->m_eq.TryGet(&env))
4794 {
4795 if (env.blk != nullptr)
4796 mb->m_pool.Free(env.blk);
4797 }
4798
4799 // Reset the envelope queue; wakes any sender blocked on a full pool.
4800 mb->m_eq.Reset();
4801
4802 return pdPASS;
4803}

References stk::memory::BlockMemoryPool::Free(), pdFAIL, pdFALSE, pdPASS, stk::sync::MessageQueue::Reset(), and stk::sync::MessageQueue::TryGet().

Here is the call graph for this function:

◆ xMessageBufferSend()

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

Send a message into the message buffer (task context, may block).

Parameters
xMessageBufferHandle of the message buffer to send to.
pvTxDataPointer to message payload.
xDataLengthBytesPayload size in bytes (must be <= max message size).
xTicksToWaitTicks to wait for a free block + envelope slot. portMAX_DELAY blocks indefinitely.
Returns
xDataLengthBytes on success, 0 on timeout or size violation.
Warning
ISR-unsafe. Use xMessageBufferSendFromISR() from ISR context.

Definition at line 4499 of file freertos_stk.cpp.

4503{
4504 if ((xMessageBuffer == nullptr) || (pvTxData == nullptr) || (xDataLengthBytes == 0U))
4505 return 0U;
4506
4507 FrtosMessageBuffer *mb = static_cast<FrtosMessageBuffer *>(xMessageBuffer);
4508
4509 if (xDataLengthBytes > mb->m_max_msg_size)
4510 {
4511 STK_ASSERT(false); // API contract: message too large for this buffer
4512 return 0U;
4513 }
4514
4515 const stk::Timeout stk_timeout = FrtosTimeoutToStk(xTicksToWait);
4516
4517 // 1. Acquire a payload block (blocks until one is free or timeout).
4518 void *blk = mb->m_pool.TimedAlloc(stk_timeout);
4519 if (blk == nullptr)
4520 return 0U;
4521
4522 // 2. Copy payload into the block.
4523 stk::STK_MEMCPY(blk, pvTxData, xDataLengthBytes);
4524
4525 // 3. Enqueue the envelope (should always succeed: pool and eq are 1:1,
4526 // but guard with NO_WAIT to avoid deadlock if they desync).
4527 FrtosMessageBuffer::MsgEnvelope env = { xDataLengthBytes, blk };
4528
4529 if (!mb->m_eq.Put(&env, stk::NO_WAIT))
4530 {
4531 // Envelope queue unexpectedly full — return block and report failure.
4532 STK_ASSERT(false);
4533 mb->m_pool.Free(blk);
4534 return 0U;
4535 }
4536
4537 // Fire send-complete callback outside any critical section.
4538 if (mb->m_send_cb != nullptr)
4539 {
4540 BaseType_t woken = pdFALSE;
4541 mb->m_send_cb(static_cast<StreamBufferHandle_t>(xMessageBuffer), &woken);
4542 }
4543
4544 return xDataLengthBytes;
4545}
static constexpr Timeout NO_WAIT
Timeout value: return immediately if the synchronization object is not yet signaled (non-blocking pol...
Definition stk_common.h:280
int32_t Timeout
Timeout time (ticks).
Definition stk_common.h:216
void * TimedAlloc(Timeout timeout_ticks=WAIT_INFINITE)
Allocate one block, blocking until one becomes available or the timeout expires.
bool Put(const void *msg_ptr, Timeout timeout_ticks=WAIT_INFINITE)
Put a message into the back of the queue (FIFO order).

References stk::memory::BlockMemoryPool::Free(), stk::NO_WAIT, pdFALSE, stk::sync::MessageQueue::Put(), STK_ASSERT, stk::STK_MEMCPY(), and stk::memory::BlockMemoryPool::TimedAlloc().

Here is the call graph for this function:

◆ xMessageBufferSendFromISR()

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

Send a message into the message buffer from ISR context (non-blocking).

Attempts a single non-blocking pool allocation followed by a non-blocking envelope enqueue. Returns 0 immediately if either resource is unavailable.

Parameters
xMessageBufferHandle of the message buffer to send to.
pvTxDataPointer to message payload.
xDataLengthBytesPayload size (must be <= max message size).
pxHigherPriorityTaskWokenAlways set to pdFALSE; STK handles scheduling.
Returns
xDataLengthBytes on success, 0 if the buffer was full or arguments invalid.
Warning
ISR-safe (non-blocking). Must not be called with a non-zero timeout.

Definition at line 4685 of file freertos_stk.cpp.

4689{
4690 if (pxHigherPriorityTaskWoken != nullptr)
4691 *pxHigherPriorityTaskWoken = pdFALSE;
4692
4693 if ((xMessageBuffer == nullptr) || (pvTxData == nullptr) || (xDataLengthBytes == 0U))
4694 return 0U;
4695
4696 FrtosMessageBuffer *mb = static_cast<FrtosMessageBuffer *>(xMessageBuffer);
4697
4698 if (xDataLengthBytes > mb->m_max_msg_size)
4699 {
4700 STK_ASSERT(false); // API contract: message exceeds max size
4701 return 0U;
4702 }
4703
4704 // Step 1: non-blocking pool allocation.
4705 void *blk = mb->m_pool.TimedAlloc(stk::NO_WAIT);
4706 if (blk == nullptr)
4707 return 0U; // pool full — no block consumed, nothing to free
4708
4709 // Step 2: copy payload.
4710 stk::STK_MEMCPY(blk, pvTxData, xDataLengthBytes);
4711
4712 // Step 3: non-blocking enqueue.
4713 FrtosMessageBuffer::MsgEnvelope env = { xDataLengthBytes, blk };
4714 if (!mb->m_eq.TryPut(&env))
4715 {
4716 // Pool and eq are 1:1, so this should never happen. Defensively free
4717 // the block to avoid a pool leak and report failure.
4718 STK_ASSERT(false);
4719 mb->m_pool.Free(blk);
4720 return 0U;
4721 }
4722
4723 // Fire send-complete callback outside any critical section.
4724 // pxHigherPriorityTaskWoken is always pdFALSE per STK convention.
4725 if (mb->m_send_cb != nullptr)
4726 {
4727 BaseType_t woken = pdFALSE;
4728 mb->m_send_cb(static_cast<StreamBufferHandle_t>(xMessageBuffer), &woken);
4729 }
4730
4731 return xDataLengthBytes;
4732}

References stk::memory::BlockMemoryPool::Free(), stk::NO_WAIT, pdFALSE, STK_ASSERT, stk::STK_MEMCPY(), stk::memory::BlockMemoryPool::TimedAlloc(), and stk::sync::MessageQueue::TryPut().

Here is the call graph for this function:

◆ xMessageBufferSpacesAvailable()

size_t xMessageBufferSpacesAvailable ( MessageBufferHandle_t xMessageBuffer)

Return the number of free envelope slots available for sending.

Parameters
xMessageBufferHandle of the message buffer.
Note
ISR-safe.

Definition at line 4608 of file freertos_stk.cpp.

4609{
4610 if (xMessageBuffer == nullptr)
4611 return 0U;
4612
4613 // Free pool blocks == available envelope slots (they are 1:1).
4614 return static_cast<FrtosMessageBuffer *>(xMessageBuffer)->m_pool.GetFreeCount();
4615}

◆ xPortGetFreeHeapSize()

size_t xPortGetFreeHeapSize ( void )

Return the number of bytes currently available in the heap.

This is a point-in-time snapshot of stk::memory::MemoryAllocator::Stats::GetAvailable() and may not account for in-flight allocations if called from a non-critical context.

Returns
Free bytes remaining.

Definition at line 1284 of file freertos_stk.cpp.

References stk::memory::MemoryAllocator::Stats::GetAvailable(), and stk::memory::MemoryAllocator::GetStats().

Here is the call graph for this function:

◆ xPortGetMinimumEverFreeHeapSize()

size_t xPortGetMinimumEverFreeHeapSize ( void )

Return the minimum number of free heap bytes recorded since system start.

The watermark is updated inside MemoryAllocator::Allocate() after every successful allocation, so it always reflects the worst-case heap pressure observed up to the point of the call.

Returns
Minimum ever free bytes (heap watermark).

Definition at line 1289 of file freertos_stk.cpp.

References stk::memory::MemoryAllocator::GetStats(), and stk::memory::MemoryAllocator::Stats::min_ever_free.

Here is the call graph for this function:

◆ xQueueAddToSet()

BaseType_t xQueueAddToSet ( QueueSetMemberHandle_t xQueueOrSemaphore,
QueueSetHandle_t xQueueSet )

Register a queue or binary/counting semaphore as a member of a queue set.

The member must be empty at the time it is added. Mutexes are not permitted. A member may belong to at most one set at a time.

Parameters
xQueueOrSemaphoreHandle of the queue or semaphore to add.
xQueueSetHandle of the target queue set.
Returns
pdPASS on success, pdFAIL if any precondition is violated.

Definition at line 2425 of file freertos_stk.cpp.

2427{
2428 if ((xQueueOrSemaphore == nullptr) || (xQueueSet == nullptr))
2429 return pdFAIL;
2430
2431 FrtosQueueSet *qs = static_cast<FrtosQueueSet *>(xQueueSet);
2432
2433 // Type discrimination between FrtosQueue and FrtosSemaphore via
2434 // GetSemKindFromHandle(): returns SemKind::None for queues (and any
2435 // unrecognised handle), SemKind::Counting or SemKind::Mutex for semaphores.
2436 {
2437 const SemKind kind = GetSemKindFromHandle(xQueueOrSemaphore);
2438
2439 if (kind != SemKind::None)
2440 {
2441 // Semaphore or mutex path.
2442 FrtosSemaphore *s = static_cast<FrtosSemaphore *>(xQueueOrSemaphore);
2443
2444 // FreeRTOS API contract: mutexes cannot be queue set members.
2445 if (s->m_kind == SemKind::Mutex)
2446 return pdFAIL;
2447
2448 STK_ASSERT(s->m_set == nullptr); // must not already belong to a set
2449 if (s->m_set != nullptr)
2450 return pdFAIL;
2451
2452 STK_ASSERT(s->m_sem->GetCount() == 0U); // must be empty when added
2453 if (s->m_sem->GetCount() != 0U)
2454 return pdFAIL;
2455
2456 s->m_set = qs;
2457 }
2458 else
2459 {
2460 // Queue path.
2461 FrtosQueue *q = static_cast<FrtosQueue *>(xQueueOrSemaphore);
2462
2463 STK_ASSERT(q->m_set == nullptr); // must not already belong to a set
2464 if (q->m_set != nullptr)
2465 return pdFAIL;
2466
2467 STK_ASSERT(q->m_mq.IsEmpty()); // must be empty when added
2468 if (!q->m_mq.IsEmpty())
2469 return pdFAIL;
2470
2471 q->m_set = qs;
2472 }
2473 }
2474
2475 return pdPASS;
2476}
bool IsEmpty() const
Check whether the queue is currently empty.

References stk::sync::MessageQueue::IsEmpty(), pdFAIL, pdPASS, and STK_ASSERT.

Here is the call graph for this function:

◆ xQueueCreate()

QueueHandle_t xQueueCreate ( UBaseType_t uxQueueLength,
UBaseType_t uxItemSize )

Create a queue capable of holding uxQueueLength items of uxItemSize bytes.

Returns
Queue handle, or NULL on allocation failure.

Definition at line 1991 of file freertos_stk.cpp.

1993{
1994 if (IsIrqContext() || (uxQueueLength == 0U) || (uxItemSize == 0U))
1995 return nullptr;
1996
1997 if (uxQueueLength > stk::sync::MessageQueue::CAPACITY_MAX)
1998 return nullptr;
1999
2000 FrtosQueue *q = ObjAlloc<FrtosQueue>(
2001 static_cast<uint32_t>(uxQueueLength),
2002 static_cast<uint32_t>(uxItemSize),
2003 nullptr /* name */);
2004
2005 if (q == nullptr)
2006 return nullptr;
2007
2008 if (!q->m_mq.IsStorageValid())
2009 {
2010 ObjFree(q);
2011 return nullptr;
2012 }
2013
2014 return static_cast<QueueHandle_t>(q);
2015}
void * QueueHandle_t
Definition FreeRTOS.h:318
static const size_t CAPACITY_MAX
Max capacity supported (number of messages).

References stk::sync::MessageQueue::CAPACITY_MAX, and stk::sync::MessageQueue::IsStorageValid().

Here is the call graph for this function:

◆ xQueueCreateSet()

QueueSetHandle_t xQueueCreateSet ( UBaseType_t uxEventQueueLength)

Create a queue set that can supervise up to uxEventQueueLength simultaneous item-available notifications from its member queues and semaphores.

Parameters
uxEventQueueLengthTotal event capacity. Must be >= the sum of the capacities (uxQueueLength or max_count) of all queues and semaphores that will be added.
Returns
Queue set handle, or NULL on failure.

Definition at line 2406 of file freertos_stk.cpp.

2407{
2408 if (IsIrqContext() || (uxEventQueueLength == 0U))
2409 return nullptr;
2410
2411 if (uxEventQueueLength > stk::sync::MessageQueue::CAPACITY_MAX)
2412 return nullptr;
2413
2414 FrtosQueueSet *qs = ObjAlloc<FrtosQueueSet>(uxEventQueueLength);
2415
2416 if ((qs == nullptr) || !qs->IsValid())
2417 {
2418 ObjFree(qs);
2419 return nullptr;
2420 }
2421
2422 return static_cast<QueueSetHandle_t>(qs);
2423}
void * QueueSetHandle_t
Definition FreeRTOS.h:326

References stk::sync::MessageQueue::CAPACITY_MAX.

◆ xQueueCreateStatic()

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

Create a queue using caller-supplied storage — no heap allocation.

Parameters
uxQueueLengthMaximum number of items the queue can hold (>= 1).
uxItemSizeSize of each item in bytes (>= 1).
pucQueueStorageCaller-allocated data buffer of at least uxQueueLength * uxItemSize bytes. Must remain valid for the entire lifetime of the queue.
pxStaticQueueCaller-allocated queue control block (StaticQueue_t). Must remain valid for the entire lifetime of the queue.
Returns
Queue handle. Never NULL if all pointer arguments are non-NULL and uxQueueLength / uxItemSize are within range.

Definition at line 2017 of file freertos_stk.cpp.

2021{
2022 // All pointer arguments are mandatory for static allocation.
2023 if ((pucQueueStorage == nullptr) || (pxStaticQueue == nullptr))
2024 return nullptr;
2025
2026 if (IsIrqContext() || (uxQueueLength == 0U) || (uxItemSize == 0U))
2027 return nullptr;
2028
2029 if (uxQueueLength > stk::sync::MessageQueue::CAPACITY_MAX)
2030 return nullptr;
2031
2032 // Placement-new the FrtosQueue control block into the caller-supplied buffer.
2033 // Static assert guards against the buffer being too small.
2034 STK_STATIC_ASSERT_DESC(sizeof(StaticQueue_t) >= sizeof(FrtosQueue),
2035 "StaticQueue_t is too small to hold FrtosQueue. "
2036 "Increase STATIC_QUEUE_TCB_SIZE_WORDS in freertos_stk.h.");
2037
2038 // Use the external-storage FrtosQueue constructor: no heap allocation for
2039 // either the control block or the data buffer.
2040 FrtosQueue *q = new (pxStaticQueue) FrtosQueue(
2041 static_cast<uint32_t>(uxQueueLength),
2042 static_cast<uint32_t>(uxItemSize),
2043 nullptr /* name */,
2044 pucQueueStorage);
2045
2046 q->m_cb_owned = false; // caller owns the memory; destructor must not delete
2047
2048 return static_cast<QueueHandle_t>(q);
2049}

References stk::sync::MessageQueue::CAPACITY_MAX, and STK_STATIC_ASSERT_DESC.

◆ xQueueGetMutexHolder()

TaskHandle_t xQueueGetMutexHolder ( QueueHandle_t xQueue)

Return the handle of the task that currently holds a mutex-semaphore when that semaphore is referenced by a QueueHandle_t alias.

In the FreeRTOS reference implementation mutex semaphores are built on top of the internal queue structure, so xQueueGetMutexHolder() and xSemaphoreGetMutexHolder() are the same function with different handle types. In this STK wrapper the two object types are separate structs:

This function accepts a QueueHandle_t and uses the same one-byte type-discriminant (offset 0: SemKind ≤ 1 → semaphore, otherwise → queue) already used by the Queue Set implementation to decide which path to take:

  • If the handle actually points to a FrtosSemaphore with SemKind::Mutex, the call is forwarded to xSemaphoreGetMutexHolder() and the owning task handle (or NULL if unlocked) is returned.
  • For a plain FrtosQueue handle, or for a counting/binary semaphore handle, NULL is returned — the owner concept does not apply.
Parameters
xQueueHandle typed as QueueHandle_t. May point to a mutex semaphore in application code that uses the raw queue handle alias (e.g. FreeRTOS+TCP internal usage).
Returns
Handle of the owning task, or NULL if unlocked / not a mutex.
Warning
Not ISR-safe. Use xQueueGetMutexHolderFromISR() from ISR context.
Note
Requires configUSE_MUTEXES == 1.

Definition at line 2349 of file freertos_stk.cpp.

2350{
2351 // Resolve to FrtosSemaphore (Mutex kind) or bail out.
2352 FrtosSemaphore *s = QueueHandleAsMutex(xQueue);
2353 if (s == nullptr)
2354 return nullptr;
2355
2356 // Delegate to the semaphore variant which acquires a ScopedCriticalSection
2357 // to make the TId snapshot consistent with concurrent Unlock() calls.
2358 return xSemaphoreGetMutexHolder(static_cast<SemaphoreHandle_t>(xQueue));
2359}
void * SemaphoreHandle_t
Definition FreeRTOS.h:319
TaskHandle_t xSemaphoreGetMutexHolder(SemaphoreHandle_t xMutex)

References xSemaphoreGetMutexHolder().

Here is the call graph for this function:

◆ xQueueGetMutexHolderFromISR()

TaskHandle_t xQueueGetMutexHolderFromISR ( QueueHandle_t xQueue)

ISR-safe variant of xQueueGetMutexHolder().

Reads the mutex owner field with a single pointer-sized load, which is naturally atomic on all supported STK architectures (Cortex-M and equivalents) without requiring an additional critical section.

Parameters
xQueueHandle typed as QueueHandle_t.
Returns
Handle of the owning task, or NULL if unlocked / not a mutex.
Warning
ISR-safe.
Note
Requires configUSE_MUTEXES == 1.

Definition at line 2361 of file freertos_stk.cpp.

2362{
2363 // Resolve to FrtosSemaphore (Mutex kind) or bail out.
2364 FrtosSemaphore *s = QueueHandleAsMutex(xQueue);
2365 if (s == nullptr)
2366 return nullptr;
2367
2368 // Delegate to the ISR-safe semaphore variant which reads GetOwner() via a
2369 // single pointer-sized atomic load — no additional critical section needed.
2370 return xSemaphoreGetMutexHolderFromISR(static_cast<SemaphoreHandle_t>(xQueue));
2371}
TaskHandle_t xSemaphoreGetMutexHolderFromISR(SemaphoreHandle_t xMutex)

References xSemaphoreGetMutexHolderFromISR().

Here is the call graph for this function:

◆ xQueueIsQueueEmptyFromISR()

BaseType_t xQueueIsQueueEmptyFromISR ( const QueueHandle_t xQueue)

Query whether a queue is empty from ISR context.

Parameters
xQueueHandle of the queue to query.
Note
ISR-safe on targets where a size_t-aligned read is atomic (per stk::sync::MessageQueue::IsEmpty() contract).
Returns
pdTRUE if the queue contains no items, pdFALSE otherwise.

Definition at line 2295 of file freertos_stk.cpp.

2296{
2297 // IsEmpty() reads m_count which is size_t-aligned; ISR-safe on targets
2298 // where such a read is atomic (per stk::sync::MessageQueue contract).
2299 if (xQueue == nullptr)
2300 return pdTRUE;
2301
2302 return static_cast<const FrtosQueue *>(xQueue)->m_mq.IsEmpty() ? pdTRUE : pdFALSE;
2303}

References pdFALSE, and pdTRUE.

◆ xQueueIsQueueFullFromISR()

BaseType_t xQueueIsQueueFullFromISR ( const QueueHandle_t xQueue)

Query whether a queue is full from ISR context.

Parameters
xQueueHandle of the queue to query.
Note
ISR-safe on targets where a size_t-aligned read is atomic (per stk::sync::MessageQueue::IsFull() contract).
Returns
pdTRUE if the queue holds capacity items, pdFALSE otherwise.

Definition at line 2305 of file freertos_stk.cpp.

2306{
2307 // IsFull() reads m_count and m_capacity; both are size_t-aligned and
2308 // m_capacity is const, so the read is ISR-safe on naturally-atomic targets
2309 // (per stk::sync::MessageQueue contract).
2310 if (xQueue == nullptr)
2311 return pdTRUE;
2312
2313 return static_cast<const FrtosQueue *>(xQueue)->m_mq.IsFull() ? pdTRUE : pdFALSE;
2314}

References pdFALSE, and pdTRUE.

◆ xQueueOverwrite()

BaseType_t xQueueOverwrite ( QueueHandle_t xQueue,
const void * pvItemToQueue )

Overwrite the value stored in a queue of length 1 (mailbox pattern). If the queue is already full the existing item is discarded before writing.

Parameters
xQueueHandle of the length-1 queue to overwrite.
pvItemToQueuePointer to the item to write into the queue.
Note
Intended for length-1 queues only; behaviour is undefined for longer queues.
Returns
pdPASS always (the write always succeeds after the discard).

Definition at line 2184 of file freertos_stk.cpp.

2185{
2186 // Mailbox (length-1 queue) overwrite pattern.
2187 // Reset() atomically discards any existing item and wakes blocked producers,
2188 // guaranteeing TryPut() will always find a free slot immediately after.
2189 if ((xQueue == nullptr) || (pvItemToQueue == nullptr))
2190 return pdFAIL;
2191
2192 FrtosQueue *q = static_cast<FrtosQueue *>(xQueue);
2193 {
2194 // Reset + TryPut must be one atomic step, otherwise a concurrent producer can take the slot in between
2196 q->m_mq.Reset();
2197 (void)q->m_mq.TryPut(pvItemToQueue);
2198 }
2199 QueueSetNotify(xQueue, q);
2200
2201 return pdPASS;
2202}

References pdFAIL, pdPASS, stk::sync::MessageQueue::Reset(), and stk::sync::MessageQueue::TryPut().

Here is the call graph for this function:

◆ xQueueOverwriteFromISR()

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

Overwrite the value stored in a length-1 queue from ISR context.

Parameters
xQueueHandle of the length-1 queue to overwrite.
pvItemToQueuePointer to the item to write.
pxHigherPriorityTaskWokenSet pdTRUE if a context switch is needed.
Returns
pdPASS always.

Definition at line 2204 of file freertos_stk.cpp.

2207{
2208 // ISR-safe variant of xQueueOverwrite. Reset() and TryPut() are both
2209 // ISR-safe per the STK MessageQueue contract.
2210 if ((xQueue == nullptr) || (pvItemToQueue == nullptr))
2211 return pdFAIL;
2212
2213 FrtosQueue *q = static_cast<FrtosQueue *>(xQueue);
2214 {
2215 // Reset + TryPut must be one atomic step, otherwise a concurrent producer can take the slot in between
2217 q->m_mq.Reset();
2218 (void)q->m_mq.TryPut(pvItemToQueue);
2219 }
2220 QueueSetNotify(xQueue, q);
2221
2222 if (pxHigherPriorityTaskWoken != nullptr)
2223 *pxHigherPriorityTaskWoken = pdFALSE;
2224
2225 return pdPASS;
2226}

References pdFAIL, pdFALSE, pdPASS, stk::sync::MessageQueue::Reset(), and stk::sync::MessageQueue::TryPut().

Here is the call graph for this function:

◆ xQueuePeek()

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

Peek at the front item without removing it (blocking).

Copies the oldest item into pvBuffer without consuming it, so a subsequent xQueueReceive() will return the same item. The operation is fully atomic — backed by stk::sync::MessageQueue::Peek() which holds an internal critical section for the duration of the copy.

Parameters
xQueueHandle of the queue to peek.
pvBufferDestination buffer; must be at least uxItemSize bytes.
xTicksToWaitTicks to wait if the queue is empty. portMAX_DELAY waits indefinitely.
Returns
pdTRUE if an item was peeked, pdFALSE on timeout.
Warning
ISR-safe only with xTicksToWait = 0 (portNO_WAIT). Use xQueuePeekFromISR() for non-blocking ISR access.

Definition at line 2118 of file freertos_stk.cpp.

2121{
2122 // Delegates to Peek(), which copies the oldest message without consuming
2123 // it. The operation is fully atomic and preserves queue ordering — no
2124 // Get + Put-back workaround required.
2125 if ((xQueue == nullptr) || (pvBuffer == nullptr))
2126 return pdFAIL;
2127
2128 if (IsIrqContext() && (xTicksToWait != 0U))
2129 return pdFAIL;
2130
2131 return static_cast<FrtosQueue *>(xQueue)->m_mq.Peek(
2132 pvBuffer, FrtosTimeoutToStk(xTicksToWait))
2133 ? pdPASS : pdFAIL;
2134}

References pdFAIL, and pdPASS.

◆ xQueuePeekFromISR()

BaseType_t xQueuePeekFromISR ( QueueHandle_t xQueue,
void * pvBuffer )

Peek at the front item from ISR context without removing it (non-blocking).

Copies the oldest item into pvBuffer atomically without consuming it, backed by stk::sync::MessageQueue::TryPeek() which is ISR-safe.

Parameters
xQueueHandle of the queue to peek.
pvBufferDestination buffer; must be at least uxItemSize bytes.
Returns
pdTRUE if an item was available and peeked, pdFALSE if the queue was empty.
Warning
ISR-safe.

Definition at line 2136 of file freertos_stk.cpp.

2138{
2139 // Delegates to TryPeek() (= Peek(NO_WAIT)), which is ISR-safe and copies
2140 // the oldest message atomically without removing it.
2141 if ((xQueue == nullptr) || (pvBuffer == nullptr))
2142 return pdFAIL;
2143
2144 return static_cast<FrtosQueue *>(xQueue)->m_mq.TryPeek(pvBuffer) ? pdPASS : pdFAIL;
2145}

References pdFAIL, and pdPASS.

◆ xQueueReceive()

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

Receive (dequeue) an item from a queue (blocking).

Parameters
xQueueHandle of the source queue.
pvBufferDestination buffer; must be at least uxItemSize bytes.
xTicksToWaitTicks to wait if the queue is empty. portMAX_DELAY = wait forever.
Returns
pdTRUE on success, pdFALSE on timeout.

Definition at line 2104 of file freertos_stk.cpp.

2107{
2108 if ((xQueue == nullptr) || (pvBuffer == nullptr))
2109 return pdFAIL;
2110
2111 if (IsIrqContext() && (xTicksToWait != 0U))
2112 return pdFAIL;
2113
2114 return static_cast<FrtosQueue *>(xQueue)->m_mq.Get(pvBuffer, FrtosTimeoutToStk(xTicksToWait))
2115 ? pdPASS : pdFAIL;
2116}

References pdFAIL, and pdPASS.

◆ xQueueReceiveFromISR()

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

Receive an item from ISR context (non-blocking).

Parameters
xQueueHandle of the source queue.
pvBufferDestination buffer; must be at least uxItemSize bytes.
pxHigherPriorityTaskWokenSet pdTRUE if a context switch is needed.
Returns
pdTRUE if received, pdFALSE if the queue was empty.

Definition at line 2250 of file freertos_stk.cpp.

2253{
2254 if ((xQueue == nullptr) || (pvBuffer == nullptr))
2255 return pdFAIL;
2256
2257 bool ok = static_cast<FrtosQueue *>(xQueue)->m_mq.TryGet(pvBuffer);
2258
2259 if (pxHigherPriorityTaskWoken != nullptr)
2260 *pxHigherPriorityTaskWoken = pdFALSE;
2261
2262 return ok ? pdPASS : pdFAIL;
2263}

References pdFAIL, pdFALSE, and pdPASS.

◆ xQueueRemoveFromSet()

BaseType_t xQueueRemoveFromSet ( QueueSetMemberHandle_t xQueueOrSemaphore,
QueueSetHandle_t xQueueSet )

Unregister a queue or semaphore from a queue set.

The member must be empty at the time it is removed.

Parameters
xQueueOrSemaphoreHandle of the queue or semaphore to remove.
xQueueSetHandle of the queue set it currently belongs to.
Returns
pdPASS on success, pdFAIL if the member does not belong to this set or is not empty.

Definition at line 2478 of file freertos_stk.cpp.

2480{
2481 if ((xQueueOrSemaphore == nullptr) || (xQueueSet == nullptr))
2482 return pdFAIL;
2483
2484 {
2485 const SemKind kind = GetSemKindFromHandle(xQueueOrSemaphore);
2486
2487 if (kind != SemKind::None)
2488 {
2489 FrtosSemaphore *s = static_cast<FrtosSemaphore *>(xQueueOrSemaphore);
2490
2491 // API contract: member must belong to this specific set.
2492 STK_ASSERT(s->m_set == static_cast<FrtosQueueSet *>(xQueueSet));
2493 if (s->m_set != static_cast<FrtosQueueSet *>(xQueueSet))
2494 return pdFAIL;
2495
2496 // API contract: semaphore must be empty when removed.
2497 STK_ASSERT(s->m_sem->GetCount() == 0U);
2498 if (s->m_sem->GetCount() != 0U)
2499 return pdFAIL;
2500
2501 s->m_set = nullptr;
2502 }
2503 else
2504 {
2505 FrtosQueue *q = static_cast<FrtosQueue *>(xQueueOrSemaphore);
2506
2507 STK_ASSERT(q->m_set == static_cast<FrtosQueueSet *>(xQueueSet));
2508 if (q->m_set != static_cast<FrtosQueueSet *>(xQueueSet))
2509 return pdFAIL;
2510
2511 // API contract: queue must be empty when removed.
2512 STK_ASSERT(q->m_mq.IsEmpty());
2513 if (!q->m_mq.IsEmpty())
2514 return pdFAIL;
2515
2516 q->m_set = nullptr;
2517 }
2518 }
2519
2520 return pdPASS;
2521}

References stk::sync::MessageQueue::IsEmpty(), pdFAIL, pdPASS, and STK_ASSERT.

Here is the call graph for this function:

◆ xQueueReset()

BaseType_t xQueueReset ( QueueHandle_t xQueue)

Reset a queue to the empty state, discarding all pending items.

Parameters
xQueueHandle of the queue to reset.
Returns
pdPASS.

Definition at line 2175 of file freertos_stk.cpp.

2176{
2177 if (xQueue == nullptr)
2178 return pdFAIL;
2179
2180 static_cast<FrtosQueue *>(xQueue)->m_mq.Reset();
2181 return pdPASS;
2182}

References pdFAIL, and pdPASS.

◆ xQueueSelectFromSet()

QueueSetMemberHandle_t xQueueSelectFromSet ( QueueSetHandle_t xQueueSet,
TickType_t xTicksToWait )

Block until any member of the queue set receives an item, then return the handle of the member that fired.

After xQueueSelectFromSet() returns a non-NULL handle, the caller must call xQueueReceive() or xSemaphoreTake() on that handle to actually consume the item. The set only unblocks once per item deposited; if multiple items arrive before the caller drains them, xQueueSelectFromSet() will return the same member handle multiple times.

Parameters
xQueueSetHandle of the queue set to wait on.
xTicksToWaitMaximum time to wait. portMAX_DELAY = wait forever, 0 = non-blocking poll.
Returns
Handle of the member that has an item available, or NULL on timeout.
Warning
ISR-safe only with xTicksToWait = 0.

Definition at line 2523 of file freertos_stk.cpp.

2525{
2526 if (xQueueSet == nullptr)
2527 return nullptr;
2528
2529 if (IsIrqContext() && (xTicksToWait != 0U))
2530 return nullptr;
2531
2532 FrtosQueueSet *qs = static_cast<FrtosQueueSet *>(xQueueSet);
2533
2534 // Block until a member handle arrives in the token FIFO or timeout fires.
2535 void *handle = nullptr;
2536 if (!qs->m_token_mq->Get(&handle, FrtosTimeoutToStk(xTicksToWait)))
2537 return nullptr; // timeout or aborted wait (xTaskAbortDelay)
2538
2539 return static_cast<QueueSetMemberHandle_t>(handle);
2540}
void * QueueSetMemberHandle_t
Definition FreeRTOS.h:327

References stk::sync::MessageQueue::Get().

Here is the call graph for this function:

◆ xQueueSelectFromSetFromISR()

QueueSetMemberHandle_t xQueueSelectFromSetFromISR ( QueueSetHandle_t xQueueSet)

Non-blocking ISR-safe variant of xQueueSelectFromSet.

Returns immediately with the handle of a ready member, or NULL if no member currently has an item available.

Parameters
xQueueSetHandle of the queue set to poll.
Returns
Handle of a ready member, or NULL if no member is ready.
Note
ISR-safe.

Definition at line 2542 of file freertos_stk.cpp.

2543{
2544 if (xQueueSet == nullptr)
2545 return nullptr;
2546
2547 FrtosQueueSet *qs = static_cast<FrtosQueueSet *>(xQueueSet);
2548
2549 // Non-blocking: TryGet() is ISR-safe per the STK MessageQueue contract.
2550 void *handle = nullptr;
2551 if (!qs->m_token_mq->TryGet(&handle))
2552 return nullptr; // set is empty
2553
2554 return static_cast<QueueSetMemberHandle_t>(handle);
2555}

References stk::sync::MessageQueue::TryGet().

Here is the call graph for this function:

◆ xQueueSend()

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

Post an item to the back of a queue (blocking).

Parameters
xQueueHandle of the target queue.
pvItemToQueuePointer to the item to copy into the queue.
xTicksToWaitTicks to wait if full. portMAX_DELAY = wait forever.
Returns
pdTRUE on success, pdFALSE on timeout.

Definition at line 2059 of file freertos_stk.cpp.

2062{
2063 if ((xQueue == nullptr) || (pvItemToQueue == nullptr))
2064 return pdFAIL;
2065
2066 if (IsIrqContext() && (xTicksToWait != 0U))
2067 return pdFAIL;
2068
2069 FrtosQueue *q = static_cast<FrtosQueue *>(xQueue);
2070
2071 if (!q->m_mq.Put(pvItemToQueue, FrtosTimeoutToStk(xTicksToWait)))
2072 return pdFAIL;
2073
2074 QueueSetNotify(xQueue, q);
2075 return pdPASS;
2076}

References pdFAIL, pdPASS, and stk::sync::MessageQueue::Put().

Referenced by xQueueSendToBack().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xQueueSendFromISR()

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

Post an item from ISR context (non-blocking).

Parameters
xQueueHandle of the target queue.
pvItemToQueuePointer to the item to copy into the queue.
pxHigherPriorityTaskWokenSet pdTRUE if a context switch is needed.
Returns
pdTRUE if posted, pdFALSE if the queue was full.

Definition at line 2228 of file freertos_stk.cpp.

2231{
2232 if ((xQueue == nullptr) || (pvItemToQueue == nullptr))
2233 return pdFAIL;
2234
2235 FrtosQueue *q = static_cast<FrtosQueue *>(xQueue);
2236 bool ok = q->m_mq.TryPut(pvItemToQueue);
2237
2238 if (ok)
2239 QueueSetNotify(xQueue, q);
2240
2241 // STK handles the wake-up internally; the wrapper does not need to
2242 // request an explicit yield from ISR because the scheduler re-evaluates on the
2243 // next tick. Set the flag to pdFALSE to avoid spurious portYIELD_FROM_ISR.
2244 if (pxHigherPriorityTaskWoken != nullptr)
2245 *pxHigherPriorityTaskWoken = pdFALSE;
2246
2247 return ok ? pdPASS : pdFAIL;
2248}

References pdFAIL, pdFALSE, pdPASS, and stk::sync::MessageQueue::TryPut().

Referenced by xQueueSendToBackFromISR().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xQueueSendToBack()

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

Post an item to the back of a queue (alias of xQueueSend).

Parameters
xQueueHandle of the target queue.
pvItemToQueuePointer to the item to copy into the queue.
xTicksToWaitTicks to wait if full. portMAX_DELAY = wait forever.
Returns
pdTRUE on success, pdFALSE on timeout.

Definition at line 2078 of file freertos_stk.cpp.

2081{
2082 return xQueueSend(xQueue, pvItemToQueue, xTicksToWait);
2083}
BaseType_t xQueueSend(QueueHandle_t xQueue, const void *pvItemToQueue, TickType_t xTicksToWait)

References xQueueSend().

Here is the call graph for this function:

◆ xQueueSendToBackFromISR()

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

Post an item to the back of a queue from ISR context (non-blocking). Equivalent to xQueueSendFromISR(); provided for source compatibility with code that explicitly names the insertion end.

Parameters
xQueueHandle of the target queue.
pvItemToQueuePointer to the item to copy into the queue.
pxHigherPriorityTaskWokenSet pdTRUE if a context switch is needed.
Returns
pdTRUE if posted, pdFALSE if the queue was full.

Definition at line 2265 of file freertos_stk.cpp.

2268{
2269 // Send-to-back from ISR is identical to xQueueSendFromISR: TryPut()
2270 // appends to the back of the ring buffer.
2271 return xQueueSendFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken);
2272}
BaseType_t xQueueSendFromISR(QueueHandle_t xQueue, const void *pvItemToQueue, BaseType_t *pxHigherPriorityTaskWoken)

References xQueueSendFromISR().

Here is the call graph for this function:

◆ xQueueSendToFront()

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

Post an item to the front of a queue (blocking). The item becomes the next item returned by xQueueReceive().

Parameters
xQueueHandle of the target queue.
pvItemToQueuePointer to the item to copy into the queue.
xTicksToWaitTicks to wait if full. portMAX_DELAY = wait forever.
Returns
pdTRUE on success, pdFALSE on timeout.

Definition at line 2085 of file freertos_stk.cpp.

2088{
2089 if ((xQueue == nullptr) || (pvItemToQueue == nullptr))
2090 return pdFAIL;
2091
2092 if (IsIrqContext() && (xTicksToWait != 0U))
2093 return pdFAIL;
2094
2095 FrtosQueue *q = static_cast<FrtosQueue *>(xQueue);
2096
2097 if (!q->m_mq.PutFront(pvItemToQueue, FrtosTimeoutToStk(xTicksToWait)))
2098 return pdFAIL;
2099
2100 QueueSetNotify(xQueue, q);
2101 return pdPASS;
2102}
bool PutFront(const void *msg_ptr, Timeout timeout_ticks=WAIT_INFINITE)
Put a message into the front of the queue (LIFO / priority-insert order).

References pdFAIL, pdPASS, and stk::sync::MessageQueue::PutFront().

Here is the call graph for this function:

◆ xQueueSendToFrontFromISR()

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

Post an item to the front of a queue from ISR context (non-blocking).

The item becomes the next item returned by xQueueReceive() / xQueuePeek(). Backed by stk::sync::MessageQueue::TryPutFront() which retreats the tail pointer atomically under an internal critical section.

Parameters
xQueueHandle of the target queue.
pvItemToQueuePointer to the item to copy into the queue.
pxHigherPriorityTaskWokenAlways set to pdFALSE; STK handles scheduling.
Returns
pdTRUE if posted, pdFALSE if the queue was full.
Warning
ISR-safe.

Definition at line 2274 of file freertos_stk.cpp.

2277{
2278 if ((xQueue == nullptr) || (pvItemToQueue == nullptr))
2279 return pdFAIL;
2280
2281 FrtosQueue *q = static_cast<FrtosQueue *>(xQueue);
2282 bool ok = q->m_mq.TryPutFront(pvItemToQueue);
2283
2284 if (ok)
2285 QueueSetNotify(xQueue, q);
2286
2287 // STK handles the wake-up internally; set the flag to pdFALSE to avoid
2288 // spurious portYIELD_FROM_ISR.
2289 if (pxHigherPriorityTaskWoken != nullptr)
2290 *pxHigherPriorityTaskWoken = pdFALSE;
2291
2292 return ok ? pdPASS : pdFAIL;
2293}

References pdFAIL, pdFALSE, pdPASS, and stk::sync::MessageQueue::TryPutFront().

Here is the call graph for this function:

◆ xSemaphoreCreateBinary()

SemaphoreHandle_t xSemaphoreCreateBinary ( void )

Create a binary semaphore (initial count = 0, max = 1).

Returns
Semaphore handle, or NULL on failure.

Definition at line 2563 of file freertos_stk.cpp.

2564{
2565 // Binary semaphore: max count = 1, initial count = 0.
2566 FrtosSemaphore *s = ObjAlloc<FrtosSemaphore>(
2567 SemKind::Counting,
2568 static_cast<UBaseType_t>(0U),
2569 static_cast<UBaseType_t>(1U));
2570
2571 if ((s == nullptr) || (s->m_sem == nullptr))
2572 {
2573 ObjFree(s);
2574 return nullptr;
2575 }
2576 return static_cast<SemaphoreHandle_t>(s);
2577}

◆ xSemaphoreCreateBinaryStatic()

SemaphoreHandle_t xSemaphoreCreateBinaryStatic ( StaticSemaphore_t * pxSemaphoreBuffer)

Create a binary semaphore using caller-supplied storage — no heap allocation.

Parameters
pxSemaphoreBufferCaller-allocated control block (StaticSemaphore_t). Must remain valid for the lifetime of the semaphore.
Returns
Semaphore handle. Never NULL if pxSemaphoreBuffer is non-NULL.

Definition at line 2579 of file freertos_stk.cpp.

2580{
2581 if (pxSemaphoreBuffer == nullptr)
2582 return nullptr;
2583
2584 // Static assert guards against the buffer being too small.
2585 STK_STATIC_ASSERT_DESC(sizeof(StaticSemaphore_t) >= sizeof(FrtosSemaphore),
2586 "StaticSemaphore_t is too small to hold FrtosSemaphore. "
2587 "Increase STATIC_SEMAPHORE_TCB_SIZE_WORDS in freertos_stk.h.");
2588
2589 // Placement-new the FrtosSemaphore control block into the caller-supplied
2590 // buffer. Binary semaphore: max count = 1, initial count = 0.
2591 // The inner FrtosSemCounter is a value type embedded inside
2592 // FrtosSemaphore, so no additional heap allocation is needed.
2593 FrtosSemaphore *s = new (pxSemaphoreBuffer) FrtosSemaphore(
2594 SemKind::Counting,
2595 static_cast<UBaseType_t>(0U),
2596 static_cast<UBaseType_t>(1U));
2597
2598 if (s->m_sem == nullptr)
2599 {
2600 s->~FrtosSemaphore(); // clean up without freeing
2601 return nullptr;
2602 }
2603
2604 s->m_cb_owned = false; // caller owns the memory; destructor must not delete
2605
2606 return static_cast<SemaphoreHandle_t>(s);
2607}

References STK_STATIC_ASSERT_DESC.

◆ xSemaphoreCreateCounting()

SemaphoreHandle_t xSemaphoreCreateCounting ( UBaseType_t uxMaxCount,
UBaseType_t uxInitialCount )

Create a counting semaphore.

Parameters
uxMaxCountMaximum count value.
uxInitialCountInitial count value (must be <= uxMaxCount).
Returns
Semaphore handle, or NULL on failure.

Definition at line 2611 of file freertos_stk.cpp.

2613{
2614 if (uxMaxCount == 0U || uxInitialCount > uxMaxCount)
2615 return nullptr;
2616
2617 // the counter can hold up to COUNT_MAX (maximum value of UBaseType_t minus one): clamp the maximum and
2618 // reject an initial count which does not fit instead of silently altering it
2619 if (uxMaxCount > FrtosSemCounter::COUNT_MAX)
2620 uxMaxCount = FrtosSemCounter::COUNT_MAX;
2621
2622 if (uxInitialCount > uxMaxCount)
2623 return nullptr;
2624
2625 FrtosSemaphore *s = ObjAlloc<FrtosSemaphore>(
2626 SemKind::Counting,
2627 uxInitialCount,
2628 uxMaxCount);
2629
2630 if ((s == nullptr) || (s->m_sem == nullptr))
2631 {
2632 ObjFree(s);
2633 return nullptr;
2634 }
2635 return static_cast<SemaphoreHandle_t>(s);
2636}

◆ xSemaphoreCreateCountingStatic()

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

Create a counting semaphore using caller-supplied storage — no heap allocation.

Parameters
uxMaxCountMaximum count value.
uxInitialCountInitial count value (must be <= uxMaxCount).
pxSemaphoreBufferCaller-allocated control block (StaticSemaphore_t). Must remain valid for the lifetime of the semaphore.
Returns
Semaphore handle. Never NULL if pxSemaphoreBuffer is non-NULL and count arguments are valid.

Definition at line 2638 of file freertos_stk.cpp.

2641{
2642 if (pxSemaphoreBuffer == nullptr)
2643 return nullptr;
2644
2645 if (uxMaxCount == 0U || uxInitialCount > uxMaxCount)
2646 return nullptr;
2647
2648 // the counter can hold up to COUNT_MAX (maximum value of UBaseType_t minus one): clamp the maximum and
2649 // reject an initial count which does not fit instead of silently altering it
2650 if (uxMaxCount > FrtosSemCounter::COUNT_MAX)
2651 uxMaxCount = FrtosSemCounter::COUNT_MAX;
2652
2653 if (uxInitialCount > uxMaxCount)
2654 return nullptr;
2655
2656 STK_STATIC_ASSERT_DESC(sizeof(StaticSemaphore_t) >= sizeof(FrtosSemaphore),
2657 "StaticSemaphore_t is too small to hold FrtosSemaphore. "
2658 "Increase STATIC_SEMAPHORE_TCB_SIZE_WORDS in freertos_stk.h.");
2659
2660 FrtosSemaphore *s = new (pxSemaphoreBuffer) FrtosSemaphore(
2661 SemKind::Counting,
2662 uxInitialCount,
2663 uxMaxCount);
2664
2665 if (s->m_sem == nullptr)
2666 {
2667 s->~FrtosSemaphore();
2668 return nullptr;
2669 }
2670
2671 s->m_cb_owned = false;
2672 return static_cast<SemaphoreHandle_t>(s);
2673}

References STK_STATIC_ASSERT_DESC.

◆ xSemaphoreCreateMutex()

SemaphoreHandle_t xSemaphoreCreateMutex ( void )

Create a mutex.

Note
STK Mutex is always recursive; osMutexRecursive is always effective.
Returns
Mutex handle, or NULL on failure.

Definition at line 2723 of file freertos_stk.cpp.

2724{
2725 // Non-recursive: backed by stk::sync::FastMutex.
2726 return CreateMutexInternal(false);
2727}
static SemaphoreHandle_t CreateMutexInternal(bool recursive)

References CreateMutexInternal().

Here is the call graph for this function:

◆ xSemaphoreCreateMutexStatic()

SemaphoreHandle_t xSemaphoreCreateMutexStatic ( StaticSemaphore_t * pxMutexBuffer)

Create a mutex using caller-supplied storage — no heap allocation.

Parameters
pxMutexBufferCaller-allocated control block (StaticSemaphore_t). Must remain valid for the lifetime of the mutex.
Returns
Mutex handle. Never NULL if pxMutexBuffer is non-NULL.

Definition at line 2729 of file freertos_stk.cpp.

2730{
2731 // Non-recursive: backed by stk::sync::FastMutex.
2732 return CreateMutexStaticInternal(pxMutexBuffer, false);
2733}
static SemaphoreHandle_t CreateMutexStaticInternal(StaticSemaphore_t *pxMutexBuffer, bool recursive)

References CreateMutexStaticInternal().

Here is the call graph for this function:

◆ xSemaphoreCreateRecursiveMutex()

SemaphoreHandle_t xSemaphoreCreateRecursiveMutex ( void )

Create a recursive mutex (same implementation as xSemaphoreCreateMutex).

Definition at line 2735 of file freertos_stk.cpp.

2736{
2737 // Recursive: backed by stk::sync::Mutex.
2738 return CreateMutexInternal(true);
2739}

References CreateMutexInternal().

Here is the call graph for this function:

◆ xSemaphoreCreateRecursiveMutexStatic()

SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic ( StaticSemaphore_t * pxMutexBuffer)

Create a recursive mutex using caller-supplied storage — no heap allocation.

Parameters
pxMutexBufferCaller-allocated control block (StaticSemaphore_t). Must remain valid for the lifetime of the mutex.
Returns
Mutex handle. Never NULL if pxMutexBuffer is non-NULL.

Definition at line 2741 of file freertos_stk.cpp.

2742{
2743 // Recursive: backed by stk::sync::Mutex.
2744 return CreateMutexStaticInternal(pxMutexBuffer, true);
2745}

References CreateMutexStaticInternal().

Here is the call graph for this function:

◆ xSemaphoreGetMutexHolder()

TaskHandle_t xSemaphoreGetMutexHolder ( SemaphoreHandle_t xMutex)

Return the handle of the task that currently holds a mutex.

Reads the owner field of the underlying stk::sync::Mutex under a ScopedCriticalSection so the snapshot is consistent even if a concurrent Unlock() is in progress.

Parameters
xMutexHandle of a mutex created by xSemaphoreCreateMutex() or xSemaphoreCreateRecursiveMutex(). Passing a counting or binary semaphore handle always returns NULL.
Returns
Handle of the owning task, or NULL if the mutex is unlocked or xMutex is not a mutex kind.
Warning
Not ISR-safe. Use xSemaphoreGetMutexHolderFromISR() from ISR context.

Definition at line 2922 of file freertos_stk.cpp.

2923{
2924 // Returns the task that currently owns the mutex, or NULL if the mutex
2925 // is unlocked or xMutex is not a mutex-kind semaphore.
2926 //
2927 // FreeRTOS documents this function as not ISR-safe and requiring the
2928 // scheduler to be running. We guard it with a ScopedCriticalSection
2929 // so that the TId snapshot is consistent: if Unlock() is executing
2930 // concurrently, we see either the old owner or TID_NONE, never a torn
2931 // pointer.
2932 //
2933 // TId -> TaskHandle_t: STK stores task pointers as TId values via
2934 // TId = stk::GetTidFromUserTask(task_ptr)
2935 // so the inverse is:
2936 // task_ptr = FrtosTaskFromTid(tid)
2937 // TID_NONE maps to nullptr (TaskHandle_t == nullptr means "no owner").
2938 if (xMutex == nullptr)
2939 return nullptr;
2940
2941 FrtosSemaphore *s = static_cast<FrtosSemaphore *>(xMutex);
2942
2943 if (s->m_kind != SemKind::Mutex)
2944 return nullptr; // not a mutex — owner concept does not apply
2945
2947
2948 const stk::TId owner = s->m_mtx->GetOwner();
2949
2950 if (owner == stk::TID_NONE)
2951 return nullptr; // mutex is currently unlocked
2952
2953 return static_cast<TaskHandle_t>(FrtosTaskFromTid(owner));
2954}

References stk::TID_NONE.

Referenced by xQueueGetMutexHolder().

Here is the caller graph for this function:

◆ xSemaphoreGetMutexHolderFromISR()

TaskHandle_t xSemaphoreGetMutexHolderFromISR ( SemaphoreHandle_t xMutex)

Return the handle of the task that currently holds a mutex (ISR-safe).

Reads the owner field of the underlying stk::sync::Mutex with a single pointer-sized load, which is naturally atomic on all supported STK architectures (Cortex-M and equivalents). No additional critical section is acquired beyond what the caller already holds.

Parameters
xMutexHandle of a mutex. Passing a non-mutex semaphore returns NULL.
Returns
Handle of the owning task, or NULL if the mutex is unlocked or xMutex is not a mutex kind.
Warning
ISR-safe.

Definition at line 2956 of file freertos_stk.cpp.

2957{
2958 // ISR-safe variant. GetOwner() reads a single TId (pointer-sized, aligned)
2959 // which is an atomic read on all supported STK architectures, so no
2960 // ScopedCriticalSection is needed here beyond what the caller already holds.
2961 // We still validate the handle and the semaphore kind before touching the
2962 // mutex state.
2963 if (xMutex == nullptr)
2964 return nullptr;
2965
2966 FrtosSemaphore *s = static_cast<FrtosSemaphore *>(xMutex);
2967
2968 if (s->m_kind != SemKind::Mutex)
2969 return nullptr;
2970
2971 const stk::TId owner = s->m_mtx->GetOwner();
2972
2973 if (owner == stk::TID_NONE)
2974 return nullptr;
2975
2976 return static_cast<TaskHandle_t>(FrtosTaskFromTid(owner));
2977}

References stk::TID_NONE.

Referenced by xQueueGetMutexHolderFromISR().

Here is the caller graph for this function:

◆ xSemaphoreGive()

BaseType_t xSemaphoreGive ( SemaphoreHandle_t xSemaphore)

Give (release) a semaphore or mutex.

Parameters
xSemaphoreHandle of the semaphore or mutex to release.
Returns
pdTRUE on success, pdFALSE if max count would be exceeded.

Definition at line 2823 of file freertos_stk.cpp.

2824{
2825 if (xSemaphore == nullptr)
2826 return pdFAIL;
2827
2828 FrtosSemaphore *s = static_cast<FrtosSemaphore *>(xSemaphore);
2829
2830 if (s->m_kind == SemKind::Mutex)
2831 {
2832#if configUSE_MUTEXES
2833 // FreeRTOS: only the holder can give a mutex back (otherwise pdFAIL). The check is enforced in all
2834 // build configurations, the kernel itself only asserts the ownership in debug builds.
2835 const stk::TId owner = s->m_mtx->GetOwner();
2836 if ((owner == stk::TID_NONE) || (owner != stk::GetTid()))
2837 return pdFAIL;
2838
2839 s->m_mtx->Give();
2840 // Mutexes are not eligible for queue sets (FreeRTOS API contract),
2841 // so no QueueSetNotify call is needed here.
2842 return pdPASS;
2843#else
2844 return pdFAIL;
2845#endif
2846 }
2847 else
2848 {
2849 // FreeRTOS: giving a semaphore which is already full (count == max) fails with errQUEUE_FULL (pdFAIL),
2850 // it is not an error of the caller. TrySignal() checks the per-object maximum and increments the count
2851 // atomically (a waiting task always gets the token directly), so a binary semaphore given twice is
2852 // rejected here instead of tripping the assertion of Signal() in a debug build.
2853 if (!s->m_sem->TrySignal())
2854 return pdFAIL;
2855
2856 QueueSetNotify(xSemaphore, s);
2857 return pdPASS;
2858 }
2859}

References stk::GetTid(), pdFAIL, pdPASS, and stk::TID_NONE.

Referenced by xSemaphoreGiveRecursive().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xSemaphoreGiveFromISR()

BaseType_t xSemaphoreGiveFromISR ( SemaphoreHandle_t xSemaphore,
BaseType_t * pxHigherPriorityTaskWoken )

Give a binary or counting semaphore from ISR context.

Note
Mutex give from ISR is not permitted and returns pdFALSE.
Parameters
xSemaphoreHandle of the semaphore to release.
pxHigherPriorityTaskWokenSet pdTRUE if a context switch is needed.
Returns
pdTRUE on success, pdFALSE on error or max-count overflow.

Definition at line 2879 of file freertos_stk.cpp.

2881{
2882 if (xSemaphore == nullptr)
2883 return pdFAIL;
2884
2885 FrtosSemaphore *s = static_cast<FrtosSemaphore *>(xSemaphore);
2886
2887 if (s->m_kind == SemKind::Mutex)
2888 return pdFAIL; // Mutex give from ISR is not permitted.
2889
2890 // semaphore already full (count == max): pdFAIL as in FreeRTOS, see xSemaphoreGive(); TrySignal() is ISR-safe
2891 if (!s->m_sem->TrySignal())
2892 return pdFAIL;
2893
2894 QueueSetNotify(xSemaphore, s);
2895
2896 if (pxHigherPriorityTaskWoken != nullptr)
2897 *pxHigherPriorityTaskWoken = pdFALSE;
2898
2899 return pdPASS;
2900}

References pdFAIL, pdFALSE, and pdPASS.

◆ xSemaphoreGiveRecursive()

BaseType_t xSemaphoreGiveRecursive ( SemaphoreHandle_t xMutex)

Give a recursive mutex.

Parameters
xMutexHandle of the recursive mutex to release.
Returns
pdTRUE on success, pdFALSE if the calling task does not own the mutex.

Definition at line 2861 of file freertos_stk.cpp.

2862{
2863 if (xMutex == nullptr)
2864 return pdFAIL;
2865
2866#if configUSE_MUTEXES
2867 const FrtosSemaphore *s = static_cast<const FrtosSemaphore *>(xMutex);
2868
2869 // FreeRTOS API contract: only handles created by xSemaphoreCreateRecursiveMutex[Static]() are allowed.
2870 if ((s->m_kind != SemKind::Mutex) || !s->m_mtx->IsRecursive())
2871 return pdFAIL;
2872
2873 return xSemaphoreGive(xMutex);
2874#else
2875 return pdFAIL;
2876#endif
2877}
BaseType_t xSemaphoreGive(SemaphoreHandle_t xSemaphore)

References pdFAIL, and xSemaphoreGive().

Here is the call graph for this function:

◆ xSemaphoreTake()

BaseType_t xSemaphoreTake ( SemaphoreHandle_t xSemaphore,
TickType_t xTicksToWait )

Take (acquire) a semaphore or mutex (blocking).

Parameters
xSemaphoreHandle of the semaphore or mutex to acquire.
xTicksToWaitTicks to wait. portMAX_DELAY = wait forever.
Returns
pdTRUE if acquired, pdFALSE on timeout.

Definition at line 2757 of file freertos_stk.cpp.

2758{
2759 if (xSemaphore == nullptr)
2760 return pdFAIL;
2761
2762 if (IsIrqContext() && (xTicksToWait != 0U))
2763 return pdFAIL;
2764
2765 FrtosSemaphore *s = static_cast<FrtosSemaphore *>(xSemaphore);
2766 stk::Timeout tmo = FrtosTimeoutToStk(xTicksToWait);
2767
2768 if (s->m_kind == SemKind::Mutex)
2769 {
2770#if configUSE_MUTEXES
2771 return s->m_mtx->Take(tmo) ? pdPASS : pdFAIL;
2772#else
2773 return pdFAIL;
2774#endif
2775 }
2776 else
2777 return s->m_sem->Wait(tmo) ? pdPASS : pdFAIL;
2778}

References pdFAIL, and pdPASS.

Referenced by xSemaphoreTakeRecursive().

Here is the caller graph for this function:

◆ xSemaphoreTakeFromISR()

BaseType_t xSemaphoreTakeFromISR ( SemaphoreHandle_t xSemaphore,
BaseType_t * pxHigherPriorityTaskWoken )

Take (acquire) a binary or counting semaphore from ISR context (non-blocking).

Note
Mutex take from ISR is not permitted and returns pdFALSE.
Parameters
xSemaphoreHandle of the semaphore to acquire.
pxHigherPriorityTaskWokenSet pdTRUE if a context switch is needed.
Returns
pdTRUE if acquired, pdFALSE if the count was zero.

Definition at line 2780 of file freertos_stk.cpp.

2782{
2783 if (xSemaphore == nullptr)
2784 return pdFAIL;
2785
2786 FrtosSemaphore *s = static_cast<FrtosSemaphore *>(xSemaphore);
2787
2788 // Mutex take from ISR is not permitted — mirrors xSemaphoreGiveFromISR.
2789 if (s->m_kind == SemKind::Mutex)
2790 return pdFAIL;
2791
2792 // TryWait() is Wait(NO_WAIT): decrement count if > 0, return immediately.
2793 // ISR-safe per the STK Semaphore contract.
2794 bool ok = s->m_sem->TryWait();
2795
2796 // STK handles priority re-evaluation internally on the next tick.
2797 // Set pdFALSE to avoid spurious portYIELD_FROM_ISR, matching the
2798 // pattern used by xQueueReceiveFromISR and xSemaphoreGiveFromISR.
2799 if (pxHigherPriorityTaskWoken != nullptr)
2800 *pxHigherPriorityTaskWoken = pdFALSE;
2801
2802 return ok ? pdPASS : pdFAIL;
2803}

References pdFAIL, pdFALSE, and pdPASS.

◆ xSemaphoreTakeRecursive()

BaseType_t xSemaphoreTakeRecursive ( SemaphoreHandle_t xMutex,
TickType_t xTicksToWait )

Take a recursive mutex (blocking).

Parameters
xMutexHandle of the recursive mutex to acquire.
xTicksToWaitTicks to wait. portMAX_DELAY = wait forever.
Returns
pdTRUE if the mutex was acquired, pdFALSE on timeout.

Definition at line 2805 of file freertos_stk.cpp.

2806{
2807 if (xMutex == nullptr)
2808 return pdFAIL;
2809
2810#if configUSE_MUTEXES
2811 const FrtosSemaphore *s = static_cast<const FrtosSemaphore *>(xMutex);
2812
2813 // FreeRTOS API contract: only handles created by xSemaphoreCreateRecursiveMutex[Static]() are allowed.
2814 if ((s->m_kind != SemKind::Mutex) || !s->m_mtx->IsRecursive())
2815 return pdFAIL;
2816
2817 return xSemaphoreTake(xMutex, xTicksToWait);
2818#else
2819 return pdFAIL;
2820#endif
2821}
BaseType_t xSemaphoreTake(SemaphoreHandle_t xSemaphore, TickType_t xTicksToWait)

References pdFAIL, and xSemaphoreTake().

Here is the call graph for this function:

◆ xStreamBufferBytesAvailable()

size_t xStreamBufferBytesAvailable ( StreamBufferHandle_t xStreamBuffer)

Return the number of bytes currently available to read.

Parameters
xStreamBufferHandle of the stream buffer to query.
Returns
Number of bytes that can be read without blocking.

Definition at line 4176 of file freertos_stk.cpp.

4177{
4178 if (xStreamBuffer == nullptr)
4179 return 0U;
4180
4181 return static_cast<FrtosStreamBuffer *>(xStreamBuffer)->m_pipe.GetCount();
4182}

Referenced by xStreamBufferIsEmpty(), and xStreamBufferNextMessageLengthBytes().

Here is the caller graph for this function:

◆ xStreamBufferCreate()

StreamBufferHandle_t xStreamBufferCreate ( size_t xBufferSizeBytes,
size_t xTriggerLevelBytes )

Create a dynamically allocated stream buffer.

Parameters
xBufferSizeBytesTotal byte capacity of the ring buffer.
xTriggerLevelBytesMinimum bytes that must be present before a blocking Receive() wakes (1 = wake on any byte).
Returns
Handle, or NULL on allocation failure.

Definition at line 4004 of file freertos_stk.cpp.

4006{
4007 if (xBufferSizeBytes == 0U)
4008 return nullptr;
4009
4010 uint8_t *buf = ObjAllocArray<uint8_t>(xBufferSizeBytes);
4011 if (buf == nullptr)
4012 return nullptr;
4013
4014 FrtosStreamBuffer *sb = ObjAlloc<FrtosStreamBuffer>(buf, xBufferSizeBytes, xTriggerLevelBytes);
4015 if (sb == nullptr)
4016 {
4017 ObjFreeArray(buf);
4018 return nullptr;
4019 }
4020
4021 sb->m_buf_owned = true;
4022 sb->m_cb_owned = true;
4023
4024 return static_cast<StreamBufferHandle_t>(sb);
4025}

◆ xStreamBufferCreateStatic()

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

Create a statically allocated stream buffer (no heap).

Parameters
xBufferSizeBytesTotal byte capacity.
xTriggerLevelBytesMinimum bytes for Receive() to unblock.
pucStreamBufferStorageAreaCaller-supplied data buffer of at least xBufferSizeBytes bytes.
pxStaticStreamBufferCaller-supplied TCB (StaticStreamBuffer_t).
Returns
Handle (always non-NULL if arguments are non-NULL).

Definition at line 4027 of file freertos_stk.cpp.

4032{
4033 if ((pucStreamBufferStorageArea == nullptr) ||
4034 (pxStaticStreamBuffer == nullptr) ||
4035 (xBufferSizeBytes == 0U))
4036 return nullptr;
4037
4038 STK_STATIC_ASSERT_DESC(sizeof(StaticStreamBuffer_t) >= sizeof(FrtosStreamBuffer),
4039 "Increase STATIC_STREAM_BUFFER_TCB_SIZE_WORDS in FreeRTOS.h.");
4040
4041 FrtosStreamBuffer *sb = new (pxStaticStreamBuffer)
4042 FrtosStreamBuffer(pucStreamBufferStorageArea,
4043 xBufferSizeBytes,
4044 xTriggerLevelBytes);
4045
4046 // m_buf_owned = false, m_cb_owned = false already set by the ctor
4047 return static_cast<StreamBufferHandle_t>(sb);
4048}

References STK_STATIC_ASSERT_DESC.

◆ xStreamBufferCreateStaticWithCallback()

StreamBufferHandle_t xStreamBufferCreateStaticWithCallback ( size_t xBufferSizeBytes,
size_t xTriggerLevelBytes,
uint8_t * pucStreamBufferStorageArea,
StaticStreamBuffer_t * pxStaticStreamBuffer,
StreamBufferCallbackFunction_t pxSendCompletedCallback,
StreamBufferCallbackFunction_t pxReceiveCompletedCallback )

Create a statically-allocated stream buffer with optional send/receive callbacks.

Identical to xStreamBufferCreateStatic() but registers per-instance callbacks. Either callback may be NULL.

Parameters
xBufferSizeBytesCapacity of the data buffer in bytes.
xTriggerLevelBytesMinimum bytes before Receive() unblocks.
pucStreamBufferStorageAreaCaller-supplied data buffer (>= xBufferSizeBytes bytes).
pxStaticStreamBufferCaller-supplied TCB (StaticStreamBuffer_t).
pxSendCompletedCallbackCalled after bytes are written (or NULL).
pxReceiveCompletedCallbackCalled after bytes are read (or NULL).
Returns
Handle, or NULL on invalid arguments.

Definition at line 4316 of file freertos_stk.cpp.

4323{
4324 if ((pucStreamBufferStorageArea == nullptr) ||
4325 (pxStaticStreamBuffer == nullptr) ||
4326 (xBufferSizeBytes == 0U))
4327 return nullptr;
4328
4329 STK_STATIC_ASSERT_DESC(sizeof(StaticStreamBuffer_t) >= sizeof(FrtosStreamBuffer),
4330 "Increase STATIC_STREAM_BUFFER_TCB_SIZE_WORDS in FreeRTOS.h.");
4331
4332 FrtosStreamBuffer *sb = new (pxStaticStreamBuffer)
4333 FrtosStreamBuffer(pucStreamBufferStorageArea,
4334 xBufferSizeBytes,
4335 xTriggerLevelBytes,
4336 pxSendCompletedCallback,
4337 pxReceiveCompletedCallback);
4338 // m_buf_owned = false, m_cb_owned = false already set by ctor
4339 return static_cast<StreamBufferHandle_t>(sb);
4340}

References STK_STATIC_ASSERT_DESC.

◆ xStreamBufferCreateWithCallback()

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

Create a heap-allocated stream buffer with optional send/receive callbacks.

Identical to xStreamBufferCreate() but registers per-instance callbacks invoked after data is successfully written (pxSendCompletedCallback) or read (pxReceiveCompletedCallback). Either callback may be NULL. Callbacks fire outside any critical section, after the transfer completes.

Parameters
xBufferSizeBytesCapacity of the data buffer in bytes.
xTriggerLevelBytesMinimum bytes before Receive() unblocks.
pxSendCompletedCallbackCalled after bytes are written (or NULL).
pxReceiveCompletedCallbackCalled after bytes are read (or NULL).
Returns
Handle, or NULL on allocation failure.

Definition at line 4284 of file freertos_stk.cpp.

4289{
4290 if (xBufferSizeBytes == 0U)
4291 return nullptr;
4292
4293 uint8_t *buf = ObjAllocArray<uint8_t>(xBufferSizeBytes);
4294 if (buf == nullptr)
4295 return nullptr;
4296
4297 FrtosStreamBuffer *sb = ObjAlloc<FrtosStreamBuffer>(
4298 buf,
4299 xBufferSizeBytes,
4300 xTriggerLevelBytes,
4301 pxSendCompletedCallback,
4302 pxReceiveCompletedCallback);
4303
4304 if (sb == nullptr)
4305 {
4306 ObjFreeArray(buf);
4307 return nullptr;
4308 }
4309
4310 sb->m_buf_owned = true;
4311 sb->m_cb_owned = true;
4312
4313 return static_cast<StreamBufferHandle_t>(sb);
4314}

◆ xStreamBufferGetTriggerLevel()

size_t xStreamBufferGetTriggerLevel ( StreamBufferHandle_t xStreamBuffer)

Return the trigger level currently set on a stream buffer.

Parameters
xStreamBufferHandle returned by xStreamBufferCreate[Static][WithCallback]().
Returns
Current trigger level in bytes (always >= 1), or 0 if handle is NULL.
Note
ISR-safe.

Definition at line 4242 of file freertos_stk.cpp.

4243{
4244 if (xStreamBuffer == nullptr)
4245 return 0U;
4246
4247 // m_trigger is a plain size_t written only under ScopedCriticalSection
4248 // (in xStreamBufferSetTriggerLevel). A size_t-aligned read is atomic on
4249 // all Cortex-M targets — same rationale as Pipe::GetCount().
4250 return static_cast<const FrtosStreamBuffer *>(xStreamBuffer)->m_trigger;
4251}

◆ xStreamBufferIsEmpty()

BaseType_t xStreamBufferIsEmpty ( StreamBufferHandle_t xStreamBuffer)

Return pdTRUE if the stream buffer contains no data.

Parameters
xStreamBufferHandle of the stream buffer to query.
Returns
pdTRUE if empty, pdFALSE if at least one byte is available.

Definition at line 4192 of file freertos_stk.cpp.

4193{
4194 return (xStreamBufferBytesAvailable(xStreamBuffer) == 0U) ? pdTRUE : pdFALSE;
4195}
size_t xStreamBufferBytesAvailable(StreamBufferHandle_t xStreamBuffer)

References pdFALSE, pdTRUE, and xStreamBufferBytesAvailable().

Here is the call graph for this function:

◆ xStreamBufferIsFull()

BaseType_t xStreamBufferIsFull ( StreamBufferHandle_t xStreamBuffer)

Return pdTRUE if the stream buffer is full (no write space remaining).

Parameters
xStreamBufferHandle of the stream buffer to query.
Returns
pdTRUE if full, pdFALSE if at least one byte of write space remains.

Definition at line 4197 of file freertos_stk.cpp.

4198{
4199 return (xStreamBufferSpacesAvailable(xStreamBuffer) == 0U) ? pdTRUE : pdFALSE;
4200}
size_t xStreamBufferSpacesAvailable(StreamBufferHandle_t xStreamBuffer)

References pdFALSE, pdTRUE, and xStreamBufferSpacesAvailable().

Here is the call graph for this function:

◆ xStreamBufferNextMessageLengthBytes()

size_t xStreamBufferNextMessageLengthBytes ( StreamBufferHandle_t xStreamBuffer)

Return the number of bytes available to read from a stream buffer without blocking.

For a stream buffer (pure unframed byte stream) this is equivalent to xStreamBufferBytesAvailable(): the entire readable span is the "next message" because stream buffers carry no length-prefix framing. The function is provided for source compatibility with code written against the FreeRTOS stream/message buffer API where both buffer kinds are used interchangeably.

Parameters
xStreamBufferHandle returned by xStreamBufferCreate[Static][WithCallback]().
Returns
Number of bytes currently available to read (0 if empty or handle is NULL).
Note
ISR-safe (delegates to Pipe::GetCount() which is ISR-safe on targets where a size_t-aligned read is atomic).

Definition at line 4268 of file freertos_stk.cpp.

4269{
4270 // Delegates to xStreamBufferBytesAvailable() which performs the NULL guard
4271 // and returns Pipe::GetCount() — ISR-safe on all supported targets.
4272 return xStreamBufferBytesAvailable(xStreamBuffer);
4273}

References xStreamBufferBytesAvailable().

Here is the call graph for this function:

◆ xStreamBufferReceive()

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

Read bytes from the stream buffer, blocking until trigger level is reached.

Parameters
xStreamBufferHandle.
pvRxDataDestination buffer.
xBufferLengthBytesMaximum bytes to read.
xTicksToWaitTicks to block until at least trigger bytes are available.
Returns
Number of bytes actually read (0 on timeout or empty buffer).

Definition at line 4113 of file freertos_stk.cpp.

4117{
4118 if ((xStreamBuffer == nullptr) || (pvRxData == nullptr) || (xBufferLengthBytes == 0U))
4119 return 0U;
4120
4121 if (IsIrqContext() && (xTicksToWait != 0U))
4122 return 0U;
4123
4124 FrtosStreamBuffer *sb = static_cast<FrtosStreamBuffer *>(xStreamBuffer);
4125
4126 // ReadBulkTriggered handles all cases in one call:
4127 // - NO_WAIT (xTicksToWait == 0): trigger not enforced, returns whatever
4128 // is available immediately (guaranteed by CV NO_WAIT fast-path).
4129 // - Blocking with trigger: waits until m_trigger bytes are present, then
4130 // drains up to xBufferLengthBytes in one atomic CS pass.
4131 // - Timeout before trigger: drains whatever arrived, possibly 0.
4132 const size_t total = sb->m_pipe.ReadBulkTriggered(
4133 static_cast<uint8_t *>(pvRxData),
4134 sb->m_trigger,
4135 xBufferLengthBytes,
4136 FrtosTimeoutToStk(xTicksToWait));
4137
4138 // Fire receive-complete callback outside any critical section.
4139 if ((total > 0U) && (sb->m_recv_cb != nullptr))
4140 {
4141 BaseType_t woken = pdFALSE;
4142 sb->m_recv_cb(xStreamBuffer, &woken);
4143 }
4144
4145 return total;
4146}
size_t ReadBulkTriggered(void *dst, size_t trigger, size_t max_count, Timeout timeout_ticks=WAIT_INFINITE)
Read at least trigger elements, then drain up to max_count without blocking.

References pdFALSE, and stk::sync::Pipe::ReadBulkTriggered().

Here is the call graph for this function:

◆ xStreamBufferReceiveFromISR()

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

Read bytes from ISR context (non-blocking, NO_WAIT).

Parameters
xStreamBufferHandle of the stream buffer to read from.
pvRxDataDestination buffer.
xBufferLengthBytesMaximum bytes to read.
pxHigherPriorityTaskWokenAlways set to pdFALSE.
Returns
Number of bytes actually read.

Definition at line 4148 of file freertos_stk.cpp.

4152{
4153 if (pxHigherPriorityTaskWoken != nullptr)
4154 *pxHigherPriorityTaskWoken = pdFALSE;
4155
4156 if ((xStreamBuffer == nullptr) || (pvRxData == nullptr) || (xBufferLengthBytes == 0U))
4157 return 0U;
4158
4159 FrtosStreamBuffer *sb = static_cast<FrtosStreamBuffer *>(xStreamBuffer);
4160
4161 const size_t received = sb->m_pipe.TryReadBulk(
4162 static_cast<uint8_t *>(pvRxData),
4163 xBufferLengthBytes);
4164
4165 // Fire receive-complete callback outside any critical section.
4166 // pxHigherPriorityTaskWoken is always pdFALSE per STK convention.
4167 if ((received > 0U) && (sb->m_recv_cb != nullptr))
4168 {
4169 BaseType_t woken = pdFALSE;
4170 sb->m_recv_cb(xStreamBuffer, &woken);
4171 }
4172
4173 return received;
4174}
size_t TryReadBulk(void *dst, size_t count)
Attempt to read multiple elements from the pipe without blocking.

References pdFALSE, and stk::sync::Pipe::TryReadBulk().

Here is the call graph for this function:

◆ xStreamBufferReset()

BaseType_t xStreamBufferReset ( StreamBufferHandle_t xStreamBuffer)

Discard all data and reset the stream buffer to the empty state.

Parameters
xStreamBufferHandle of the stream buffer to reset.
Returns
pdPASS always.

Definition at line 4202 of file freertos_stk.cpp.

4203{
4204 if (xStreamBuffer == nullptr)
4205 return pdFAIL;
4206
4207 static_cast<FrtosStreamBuffer *>(xStreamBuffer)->m_pipe.Reset();
4208 return pdPASS;
4209}

References pdFAIL, and pdPASS.

◆ xStreamBufferResetFromISR()

BaseType_t xStreamBufferResetFromISR ( StreamBufferHandle_t xStreamBuffer,
BaseType_t * pxHigherPriorityTaskWoken )

Reset a stream buffer to empty from ISR context.

Delegates to Pipe::Reset() which holds a ScopedCriticalSection internally. Data in the buffer is discarded; tasks blocked in xStreamBufferSend() that were waiting for space are woken.

Parameters
xStreamBufferHandle of the stream buffer to reset.
pxHigherPriorityTaskWokenAlways set to pdFALSE; STK handles scheduling.
Returns
pdPASS on success, pdFAIL if the handle is NULL.
Note
ISR-safe.

Definition at line 4228 of file freertos_stk.cpp.

4230{
4231 if (pxHigherPriorityTaskWoken != nullptr)
4232 *pxHigherPriorityTaskWoken = pdFALSE;
4233
4234 if (xStreamBuffer == nullptr)
4235 return pdFAIL;
4236
4237 // Pipe::Reset() acquires ScopedCriticalSection internally — ISR-safe.
4238 static_cast<FrtosStreamBuffer *>(xStreamBuffer)->m_pipe.Reset();
4239 return pdPASS;
4240}

References pdFAIL, pdFALSE, and pdPASS.

◆ xStreamBufferSend()

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

Write bytes into the stream buffer.

Parameters
xStreamBufferHandle.
pvTxDataPointer to source data.
xDataLengthBytesNumber of bytes to write.
xTicksToWaitTicks to wait for space (0 = non-blocking).
Returns
Number of bytes actually written (may be less than requested on timeout).

Definition at line 4060 of file freertos_stk.cpp.

4064{
4065 if ((xStreamBuffer == nullptr) || (pvTxData == nullptr) || (xDataLengthBytes == 0U))
4066 return 0U;
4067
4068 FrtosStreamBuffer *sb = static_cast<FrtosStreamBuffer *>(xStreamBuffer);
4069
4070 const size_t sent = sb->m_pipe.WriteBulk(
4071 static_cast<const uint8_t *>(pvTxData),
4072 xDataLengthBytes,
4073 FrtosTimeoutToStk(xTicksToWait));
4074
4075 // Fire send-complete callback outside any critical section.
4076 if ((sent > 0U) && (sb->m_send_cb != nullptr))
4077 {
4078 BaseType_t woken = pdFALSE;
4079 sb->m_send_cb(xStreamBuffer, &woken);
4080 }
4081
4082 return sent;
4083}
size_t WriteBulk(const void *src, size_t count, Timeout timeout_ticks=WAIT_INFINITE)
Write multiple elements to the pipe.

References pdFALSE, and stk::sync::Pipe::WriteBulk().

Here is the call graph for this function:

◆ xStreamBufferSendFromISR()

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

Write bytes from ISR context (non-blocking, NO_WAIT).

Parameters
xStreamBufferHandle of the stream buffer to write to.
pvTxDataPointer to source data.
xDataLengthBytesNumber of bytes to write.
pxHigherPriorityTaskWokenAlways set to pdFALSE (STK handles scheduling).
Returns
Number of bytes actually written.

Definition at line 4085 of file freertos_stk.cpp.

4089{
4090 if (pxHigherPriorityTaskWoken != nullptr)
4091 *pxHigherPriorityTaskWoken = pdFALSE;
4092
4093 if ((xStreamBuffer == nullptr) || (pvTxData == nullptr) || (xDataLengthBytes == 0U))
4094 return 0U;
4095
4096 FrtosStreamBuffer *sb = static_cast<FrtosStreamBuffer *>(xStreamBuffer);
4097
4098 const size_t sent = sb->m_pipe.TryWriteBulk(
4099 static_cast<const uint8_t *>(pvTxData),
4100 xDataLengthBytes);
4101
4102 // Fire send-complete callback outside any critical section.
4103 // pxHigherPriorityTaskWoken is always pdFALSE per STK convention.
4104 if ((sent > 0U) && (sb->m_send_cb != nullptr))
4105 {
4106 BaseType_t woken = pdFALSE;
4107 sb->m_send_cb(xStreamBuffer, &woken);
4108 }
4109
4110 return sent;
4111}
size_t TryWriteBulk(const void *src, size_t count)
Attempt to write multiple elements to the pipe without blocking.

References pdFALSE, and stk::sync::Pipe::TryWriteBulk().

Here is the call graph for this function:

◆ xStreamBufferSetTriggerLevel()

BaseType_t xStreamBufferSetTriggerLevel ( StreamBufferHandle_t xStreamBuffer,
size_t xTriggerLevelBytes )

Change the trigger level for a stream buffer.

Parameters
xStreamBufferHandle of the stream buffer to modify.
xTriggerLevelBytesNew minimum bytes for Receive() to unblock (>= 1).
Returns
pdTRUE on success, pdFALSE if xTriggerLevelBytes > buffer capacity.

Definition at line 4211 of file freertos_stk.cpp.

4213{
4214 if (xStreamBuffer == nullptr)
4215 return pdFALSE;
4216
4217 FrtosStreamBuffer *sb = static_cast<FrtosStreamBuffer *>(xStreamBuffer);
4218
4219 if (xTriggerLevelBytes > sb->m_pipe.GetCapacity())
4220 return pdFALSE;
4221
4223 sb->m_trigger = (xTriggerLevelBytes >= 1U ? xTriggerLevelBytes : 1U);
4224
4225 return pdTRUE;
4226}
size_t GetCapacity() const
Get the maximum number of elements the pipe can hold.

References stk::sync::Pipe::GetCapacity(), pdFALSE, and pdTRUE.

Here is the call graph for this function:

◆ xStreamBufferSpacesAvailable()

size_t xStreamBufferSpacesAvailable ( StreamBufferHandle_t xStreamBuffer)

Return the number of free bytes available for writing.

Parameters
xStreamBufferHandle of the stream buffer to query.
Returns
Number of bytes that can be written without blocking.

Definition at line 4184 of file freertos_stk.cpp.

4185{
4186 if (xStreamBuffer == nullptr)
4187 return 0U;
4188
4189 return static_cast<FrtosStreamBuffer *>(xStreamBuffer)->m_pipe.GetSpace();
4190}

Referenced by xStreamBufferIsFull().

Here is the caller graph for this function:

◆ xTaskAbortDelay()

BaseType_t xTaskAbortDelay ( TaskHandle_t xTask)

Abort a delay that the target task is currently blocked in (vTaskDelay, vTaskDelayUntil, or any timed sync primitive wait). The task is made immediately runnable; its next Wait/Sleep will not be affected.

Parameters
xTaskHandle of the task whose delay is to be aborted.
Returns
pdPASS if the task was in a delayed state and the abort was issued, pdFAIL if the task was not delayed.
Note
ISR-safe (delegates to stk::AbortSleep which is ISR-safe).

Definition at line 1590 of file freertos_stk.cpp.

1591{
1592 if (xTask == nullptr)
1593 return pdFALSE;
1594
1595 // Resolve NULL -> calling task (same convention used throughout the wrapper).
1596 const stk::TId tid = FrtosTidFromTask(static_cast<const FrtosTask *>(xTask));
1597
1598 const FrtosTask *t = static_cast<const FrtosTask *>(xTask);
1599 if (t->m_state != FrtosTask::State::Ready)
1600 return pdFAIL; // suspended or otherwise not in a delay-able state
1601
1602 // FreeRTOS: only a task in the Blocked state can have its delay aborted. The calling task is
1603 // running by definition, so it can never be blocked (and SleepCancel() would be a no-op for it).
1604 if (tid == stk::GetTid())
1605 return pdFAIL;
1606
1607 // Ends a vTaskDelay()/vTaskDelayUntil() sleep, and also a blocking wait on a sync object
1608 // (xQueueReceive/xQueueSend, xSemaphoreTake, xEventGroupWaitBits, xTaskNotifyWait, ...): the
1609 // wait ends with WAIT_RESULT_CANCELED, which the wrapper reports exactly like a timeout
1610 // (pdFAIL / nullptr / 0 / flags snapshot), as FreeRTOS does for an aborted delay.
1611 stk::SleepCancel(tid);
1612 return pdPASS;
1613}
static void SleepCancel(TId task_id)
Cancel sleep of the task.
Definition stk_helper.h:539

References stk::GetTid(), pdFAIL, pdFALSE, pdPASS, and stk::SleepCancel().

Here is the call graph for this function:

◆ xTaskCreate()

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

Create a new dynamic task.

Parameters
pvTaskCodeTask function pointer.
pcNameDescriptive name for debugging.
usStackDepthStack depth in Words (not bytes).
pvParametersArgument passed to pvTaskCode.
uxPriorityPriority: 0 = lowest, configMAX_PRIORITIES-1 = highest.
pxCreatedTaskOptional: receives the handle of the created task.
Returns
pdPASS on success, pdFAIL if the task could not be created.
Examples
blinky_c-freertos/example.c.

Definition at line 1405 of file freertos_stk.cpp.

1411{
1412 if (pvTaskCode == nullptr)
1413 return pdFAIL;
1414
1415 // release the memory of the deleted tasks which the kernel has already removed (FreeRTOS does it in the idle task)
1416 ReapDeletedTasks();
1417
1418 FrtosTask *t = ObjAlloc<FrtosTask>();
1419 if (t == nullptr)
1420 return pdFAIL;
1421
1422 t->m_func = pvTaskCode;
1423 t->m_argument = pvParameters;
1424 t->m_name = pcName;
1425 t->m_weight = FrtosPrioToStkWeight(uxPriority);
1426
1427 // Determine stack size in Words.
1428 size_t stack_words = (usStackDepth > 0U) ? static_cast<size_t>(usStackDepth) :
1430
1431 if (stack_words < FREERTOS_STK_MIN_STACK_WORDS)
1432 stack_words = FREERTOS_STK_MIN_STACK_WORDS;
1433
1434 t->m_stack = ObjAllocArray<stk::Word>(stack_words);
1435 if (t->m_stack == nullptr)
1436 {
1437 ObjFree(t);
1438 return pdFAIL;
1439 }
1440
1441 t->m_stack_size = stack_words;
1442 t->m_stack_owned = true;
1443
1444 EnsureKernelInitialized();
1445
1446 // KERNEL_DYNAMIC: a failure (out of kernel task slots, or the task/stack is already added) is returned,
1447 // not asserted: release the TCB and the stack (the kernel never referenced them) and report the failure
1448 if (g_StkKernel.AddTask(t) != stk::ADD_OK)
1449 {
1450 ObjFree(t);
1451 return pdFAIL;
1452 }
1453
1454 if (pxCreatedTask != nullptr)
1455 *pxCreatedTask = static_cast<TaskHandle_t>(t);
1456
1457 return pdPASS;
1458}
#define FREERTOS_STK_MIN_STACK_WORDS
#define FREERTOS_STK_DEFAULT_STACK_WORDS
Default stack depth in Words when the caller passes usStackDepth = 0.
Definition FreeRTOS.h:219
@ ADD_OK
Task was added.
Definition stk_common.h:153

References stk::ADD_OK, FREERTOS_STK_DEFAULT_STACK_WORDS, FREERTOS_STK_MIN_STACK_WORDS, pdFAIL, and pdPASS.

Referenced by app_main(), app_run(), and xTaskCreateRestricted().

Here is the caller graph for this function:

◆ xTaskCreateRestricted()

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

Create a task with optional MPU region descriptors, allocating the TCB and stack from the heap (source-compatible with the FreeRTOS heap variant of xTaskCreateRestricted).

Note
STK does not implement MPU support. This function extracts pvTaskCode, usStackDepth, pvParameters, and uxPriority from pxTaskDefinition and delegates to xTaskCreate(), silently ignoring puxStackBuffer (a heap stack is allocated instead) and the xRegions table. When STK gains MPU support the implementation will be extended to program the region descriptors.
Parameters
pxTaskDefinitionPointer to a TaskParameters_restricted_t descriptor. Must not be NULL.
pxCreatedTaskOptional: receives the handle of the created task.
Returns
pdPASS on success, pdFAIL if pxTaskDefinition is NULL or heap allocation fails.

Definition at line 1858 of file freertos_stk.cpp.

1860{
1861 // Mandatory pointer guard (only pvTaskCode is required; the caller need not
1862 // supply puxStackBuffer or pxTaskBuffer — both are heap-allocated here).
1863 if ((pxTaskDefinition == nullptr) ||
1864 (pxTaskDefinition->pvTaskCode == nullptr))
1865 return pdFAIL;
1866
1867 // STK does not implement MPU support. Forward to xTaskCreate() which
1868 // heap-allocates both the TCB and the task stack, accepting but ignoring
1869 // the xRegions MPU region table.
1870 // TODO: program pxTaskDefinition->xRegions into the MPU when STK gains
1871 // hardware MPU support.
1872 return xTaskCreate(
1873 pxTaskDefinition->pvTaskCode,
1874 pxTaskDefinition->pcName,
1875 pxTaskDefinition->usStackDepth,
1876 pxTaskDefinition->pvParameters,
1877 pxTaskDefinition->uxPriority,
1878 pxCreatedTask);
1879}
BaseType_t xTaskCreate(TaskFunction_t pvTaskCode, const char *pcName, uint32_t usStackDepth, void *pvParameters, UBaseType_t uxPriority, TaskHandle_t *pxCreatedTask)
TaskFunction_t pvTaskCode
Definition FreeRTOS.h:592

References TaskParameters_restricted_t::pcName, pdFAIL, TaskParameters_restricted_t::pvParameters, TaskParameters_restricted_t::pvTaskCode, TaskParameters_restricted_t::usStackDepth, TaskParameters_restricted_t::uxPriority, and xTaskCreate().

Here is the call graph for this function:

◆ xTaskCreateRestrictedStatic()

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

Create a task with caller-supplied static memory and optional MPU region descriptors (source-compatible with xTaskCreateRestricted).

Note
STK does not implement MPU support. This function is a forward- compatibility stub: it extracts the function, stack, priority, and pxTaskBuffer from pxTaskDefinition and delegates to xTaskCreateStatic(), silently ignoring the xRegions table. When STK gains MPU support the implementation will be extended to program the region descriptors.
Parameters
pxTaskDefinitionPointer to a TaskParameters_restricted_t descriptor. Must not be NULL. puxStackBuffer and pxTaskBuffer inside the struct must also be non-NULL.
pxCreatedTaskOptional: receives the handle of the created task.
Returns
pdPASS on success, pdFAIL if any mandatory pointer is NULL.

Definition at line 1826 of file freertos_stk.cpp.

1828{
1829 // Mandatory pointer guard.
1830 if ((pxTaskDefinition == nullptr) ||
1831 (pxTaskDefinition->pvTaskCode == nullptr) ||
1832 (pxTaskDefinition->puxStackBuffer == nullptr) ||
1833 (pxTaskDefinition->pxTaskBuffer == nullptr))
1834 return pdFAIL;
1835
1836 // STK does not implement MPU support. Forward to xTaskCreateStatic(),
1837 // accepting but ignoring the xRegions MPU region table.
1838 // TODO: program pxTaskDefinition->xRegions into the MPU when STK gains
1839 // hardware MPU support.
1841 pxTaskDefinition->pvTaskCode,
1842 pxTaskDefinition->pcName,
1843 pxTaskDefinition->usStackDepth,
1844 pxTaskDefinition->pvParameters,
1845 pxTaskDefinition->uxPriority,
1846 pxTaskDefinition->puxStackBuffer,
1847 pxTaskDefinition->pxTaskBuffer);
1848
1849 if (h == nullptr)
1850 return pdFAIL;
1851
1852 if (pxCreatedTask != nullptr)
1853 *pxCreatedTask = h;
1854
1855 return pdPASS;
1856}
TaskHandle_t xTaskCreateStatic(TaskFunction_t pvTaskCode, const char *pcName, uint32_t ulStackDepth, void *pvParameters, UBaseType_t uxPriority, StackType_t *puxStackBuffer, StaticTask_t *pxTaskBuffer)
StackType_t * puxStackBuffer
Definition FreeRTOS.h:597
StaticTask_t * pxTaskBuffer
Definition FreeRTOS.h:598

References TaskParameters_restricted_t::pcName, pdFAIL, pdPASS, TaskParameters_restricted_t::puxStackBuffer, TaskParameters_restricted_t::pvParameters, TaskParameters_restricted_t::pvTaskCode, TaskParameters_restricted_t::pxTaskBuffer, TaskParameters_restricted_t::usStackDepth, TaskParameters_restricted_t::uxPriority, and xTaskCreateStatic().

Here is the call graph for this function:

◆ xTaskCreateStatic()

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

Create a task using caller-supplied stack and TCB memory (no heap allocation).

Parameters
pvTaskCodeTask function pointer.
pcNameDescriptive name for debugging.
ulStackDepthStack depth in Words (not bytes). Must be >= configMINIMAL_STACK_SIZE.
pvParametersArgument passed to pvTaskCode.
uxPriorityPriority: 0 = lowest, configMAX_PRIORITIES-1 = highest.
puxStackBufferCaller-allocated stack buffer of ulStackDepth Words. Must remain valid for the lifetime of the task.
pxTaskBufferCaller-allocated TCB buffer (StaticTask_t). Must remain valid for the lifetime of the task.
Returns
Task handle. Never NULL if all pointer arguments are non-NULL.

Definition at line 1460 of file freertos_stk.cpp.

1467{
1468 // All three pointer arguments are mandatory for static allocation.
1469 if ((pvTaskCode == nullptr) || (puxStackBuffer == nullptr) || (pxTaskBuffer == nullptr))
1470 return nullptr;
1471
1472 // Placement-new the FrtosTask control block into the caller-supplied TCB
1473 // buffer. Static assert guards against the buffer being too small.
1474 STK_STATIC_ASSERT_DESC(sizeof(StaticTask_t) >= sizeof(FrtosTask),
1475 "StaticTask_t is too small to hold FrtosTask. "
1476 "Increase STATIC_TASK_TCB_SIZE_WORDS in freertos_stk.h.");
1477
1478 FrtosTask *t = new (pxTaskBuffer) FrtosTask();
1479
1480 t->m_func = pvTaskCode;
1481 t->m_argument = pvParameters;
1482 t->m_name = pcName;
1483 t->m_weight = FrtosPrioToStkWeight(uxPriority);
1484 t->m_stack = static_cast<stk::Word *>(static_cast<void *>(puxStackBuffer));
1485 t->m_stack_size = (ulStackDepth >= FREERTOS_STK_MIN_STACK_WORDS)
1486 ? static_cast<size_t>(ulStackDepth)
1488 t->m_stack_owned = false; // caller owns both the stack and the TCB
1489 t->m_cb_owned = false; // destructor must not delete — caller owns memory
1490
1491 EnsureKernelInitialized();
1492
1493 // KERNEL_DYNAMIC: a failure is returned, not asserted. The TCB and the stack belong to the caller:
1494 // only destroy the object and return NULL as FreeRTOS does when the task can not be created
1495 if (g_StkKernel.AddTask(t) != stk::ADD_OK)
1496 {
1497 t->~FrtosTask();
1498 return nullptr;
1499 }
1500
1501 return static_cast<TaskHandle_t>(t);
1502}
uintptr_t Word
Native processor word type.
Definition stk_common.h:206

References stk::ADD_OK, FREERTOS_STK_MIN_STACK_WORDS, and STK_STATIC_ASSERT_DESC.

Referenced by xTaskCreateRestrictedStatic().

Here is the caller graph for this function:

◆ xTaskDelayUntil()

BaseType_t xTaskDelayUntil ( TickType_t * pxPreviousWakeTime,
TickType_t xTimeIncrement )

Delay until an absolute tick deadline (FreeRTOS 10.2+ name for vTaskDelayUntil). Updates *pxPreviousWakeTime on each call.

Parameters
pxPreviousWakeTimeIn/out: tick count at the last wake point; updated on return.
xTimeIncrementPeriod in ticks between successive wake points.
Returns
pdTRUE if the task delayed, pdFALSE if the deadline had already passed before the call was made (the task did not block).

Definition at line 1628 of file freertos_stk.cpp.

1629{
1630 if (IsIrqContext() || (pxPreviousWakeTime == nullptr))
1631 return pdFALSE;
1632
1633 const stk::Ticks wake_at = static_cast<stk::Ticks>(*pxPreviousWakeTime) +
1634 static_cast<stk::Ticks>(xTimeIncrement);
1635
1636 *pxPreviousWakeTime = static_cast<TickType_t>(wake_at);
1637
1638 return stk::SleepUntil(wake_at) ? pdTRUE : pdFALSE;
1639}
int64_t Ticks
Ticks value.
Definition stk_common.h:221
static bool SleepUntil(Ticks timestamp)
Put calling process into a sleep state until the specified timestamp.
Definition stk_helper.h:523

References pdFALSE, pdTRUE, and stk::SleepUntil().

Referenced by vTaskDelayUntil().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskGetCurrentTaskHandle()

TaskHandle_t xTaskGetCurrentTaskHandle ( void )

Return the handle of the currently executing task.

Returns
Handle of the task that is currently running on the CPU.

Definition at line 1698 of file freertos_stk.cpp.

1699{
1700 if (IsIrqContext())
1701 return nullptr;
1702
1703 return static_cast<TaskHandle_t>(FrtosTaskFromTid(stk::GetTid()));
1704}

References stk::GetTid().

Referenced by pvTaskGetThreadLocalStoragePointer(), and vTaskSetThreadLocalStoragePointer().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskGetHandle()

TaskHandle_t xTaskGetHandle ( const char * pcNameToQuery)

Look up a task handle by name string (O(n) scan).

Parameters
pcNameToQueryName string to search for (exact match).
Returns
Handle of the first matching task, or NULL if not found.

Definition at line 1706 of file freertos_stk.cpp.

1707{
1708 if (pcNameToQuery == nullptr)
1709 return nullptr;
1710
1711 // Enumerate all tasks and compare names.
1712 TaskHandle_t found = nullptr;
1713
1714 g_StkKernel.EnumerateTasksT<FREERTOS_STK_MAX_TASKS>([&](stk::ITask *task) -> bool
1715 {
1716 if ((task->GetTraceName() != nullptr) &&
1717 (FreertosStrcmp(task->GetTraceName(), pcNameToQuery) == 0))
1718 {
1719 found = static_cast<TaskHandle_t>(task);
1720 return false; // stop iteration
1721 }
1722 return true;
1723 });
1724
1725 return found;
1726}

References FREERTOS_STK_MAX_TASKS.

◆ xTaskGetSchedulerState()

BaseType_t xTaskGetSchedulerState ( void )

Return the current state of the FreeRTOS/STK scheduler.

Returns
One of taskSCHEDULER_NOT_STARTED, taskSCHEDULER_RUNNING, or taskSCHEDULER_SUSPENDED.

< Scheduler is running normally (STATE_RUNNING).

< Scheduler is suspended via vTaskSuspendAll() (STATE_SUSPENDED).

< Scheduler has not yet been started (STATE_INACTIVE / STATE_READY).

Definition at line 1387 of file freertos_stk.cpp.

1388{
1389 // Map the four STK kernel states onto the three FreeRTOS scheduler states:
1390 // STATE_INACTIVE / STATE_READY -> NOT_STARTED (scheduler never ran)
1391 // STATE_RUNNING -> RUNNING
1392 // STATE_SUSPENDED -> SUSPENDED
1393 switch (g_StkKernel.GetState())
1394 {
1397 default: return taskSCHEDULER_NOT_STARTED;
1398 }
1399}
#define taskSCHEDULER_NOT_STARTED
Definition FreeRTOS.h:445
#define taskSCHEDULER_SUSPENDED
Definition FreeRTOS.h:447
#define taskSCHEDULER_RUNNING
Definition FreeRTOS.h:446
@ KSTATE_RUNNING
Initialized and running, IKernel::Start() was called successfully.
@ KSTATE_SUSPENDED
Scheduling is suspended with IKernelService::Suspend().

References stk::IKernel::KSTATE_RUNNING, stk::IKernel::KSTATE_SUSPENDED, taskSCHEDULER_NOT_STARTED, taskSCHEDULER_RUNNING, and taskSCHEDULER_SUSPENDED.

◆ xTaskGetTickCount()

TickType_t xTaskGetTickCount ( void )

Return the tick count since the scheduler started.

Definition at line 1371 of file freertos_stk.cpp.

1372{
1373 return static_cast<TickType_t>(stk::GetTicks());
1374}
static Ticks GetTicks()
Get number of ticks elapsed since kernel start.
Definition stk_helper.h:448

References stk::GetTicks().

Here is the call graph for this function:

◆ xTaskGetTickCountFromISR()

TickType_t xTaskGetTickCountFromISR ( void )

Return the tick count from ISR context (ISR-safe).

Definition at line 1376 of file freertos_stk.cpp.

1377{
1378 return static_cast<TickType_t>(stk::GetTicks()); // GetTicks() is ISR-safe
1379}

References stk::GetTicks().

Here is the call graph for this function:

◆ xTaskNotify()

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

Send a notification to a task (slot 0) with a specific action on its value.

Parameters
xTaskToNotifyHandle of the task to notify (must not be NULL).
ulValueValue applied according to eAction.
eActionHow ulValue is applied to the task's notification value.
Returns
pdPASS, or pdFAIL if eSetValueWithoutOverwrite and already pending.
Examples
blinky_c-freertos/example.c.

Definition at line 3682 of file freertos_stk.cpp.

3685{
3686 return xTaskNotifyIndexed(xTaskToNotify, 0U, ulValue, eAction);
3687}
BaseType_t xTaskNotifyIndexed(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction)

References xTaskNotifyIndexed().

Referenced by app_main(), and signal_func().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskNotifyAndQuery()

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

Send a notification to a task (slot 0) and return the previous notification value before the action was applied.

Parameters
xTaskToNotifyTarget task handle (must not be NULL).
ulValueValue applied according to eAction.
eActionHow ulValue is applied to the notification value.
pulPreviousNotifyValueReceives the slot value before the action is applied. May be NULL.
Returns
pdPASS, or pdFAIL if eSetValueWithoutOverwrite and notification was already pending.
Note
ISR-safe.

Definition at line 3770 of file freertos_stk.cpp.

3774{
3775 return xTaskNotifyAndQueryIndexed(xTaskToNotify, 0U, ulValue, eAction,
3776 pulPreviousNotifyValue);
3777}
BaseType_t xTaskNotifyAndQueryIndexed(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue)

References xTaskNotifyAndQueryIndexed().

Here is the call graph for this function:

◆ xTaskNotifyAndQueryFromISR()

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

ISR-safe variant of xTaskNotifyAndQuery (slot 0).

Parameters
xTaskToNotifyTarget task handle (must not be NULL).
ulValueValue applied according to eAction.
eActionHow ulValue is applied to the task's notification value.
pulPreviousNotifyValueReceives the slot value before the action is applied. May be NULL.
pxHigherPriorityTaskWokenAlways set to pdFALSE (STK handles wake internally).
Returns
pdPASS, or pdFAIL if eSetValueWithoutOverwrite and notification was already pending.
Note
ISR-safe.

Definition at line 3804 of file freertos_stk.cpp.

3809{
3810 return xTaskNotifyAndQueryFromISRIndexed(xTaskToNotify, 0U, ulValue, eAction,
3811 pulPreviousNotifyValue,
3812 pxHigherPriorityTaskWoken);
3813}
BaseType_t xTaskNotifyAndQueryFromISRIndexed(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue, BaseType_t *pxHigherPriorityTaskWoken)

References xTaskNotifyAndQueryFromISRIndexed().

Here is the call graph for this function:

◆ xTaskNotifyAndQueryFromISRIndexed()

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

ISR-safe indexed variant of xTaskNotifyAndQuery.

Parameters
xTaskToNotifyTarget task handle (must not be NULL).
uxIndexToNotifyNotification slot index (0 .. configTASK_NOTIFICATION_ARRAY_ENTRIES-1).
ulValueValue applied according to eAction.
eActionHow ulValue is applied to the slot's notification value.
pulPreviousNotifyValueReceives the slot value before the action is applied. May be NULL.
pxHigherPriorityTaskWokenAlways set to pdFALSE.
Returns
pdPASS, or pdFAIL if eSetValueWithoutOverwrite and notification was already pending.
Note
ISR-safe.

Definition at line 3783 of file freertos_stk.cpp.

3789{
3790 BaseType_t result = xTaskNotifyAndQueryIndexed(xTaskToNotify, uxIndexToNotify,
3791 ulValue, eAction,
3792 pulPreviousNotifyValue);
3793
3794 if (pxHigherPriorityTaskWoken != nullptr)
3795 *pxHigherPriorityTaskWoken = pdFALSE; // STK handles the context switch internally
3796
3797 return result;
3798}

References pdFALSE, and xTaskNotifyAndQueryIndexed().

Referenced by xTaskNotifyAndQueryFromISR().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskNotifyAndQueryIndexed()

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

Indexed variant of xTaskNotifyAndQuery.

Parameters
xTaskToNotifyTarget task handle (must not be NULL).
uxIndexToNotifyNotification slot index (0 .. configTASK_NOTIFICATION_ARRAY_ENTRIES-1).
ulValueValue applied according to eAction.
eActionHow ulValue is applied to the slot's notification value.
pulPreviousNotifyValueReceives the slot value before the action is applied. May be NULL.
Returns
pdPASS, or pdFAIL if eSetValueWithoutOverwrite and notification was already pending.
Note
ISR-safe.

Definition at line 3736 of file freertos_stk.cpp.

3741{
3742 FrtosTask *t = ResolveNotifyTarget(xTaskToNotify, uxIndexToNotify);
3743 if (t == nullptr)
3744 return pdFAIL;
3745
3746 FrtosTask::NotifySlot &slot = t->m_notify[uxIndexToNotify];
3747 BaseType_t result = pdPASS;
3748
3749 {
3751
3752 // Snapshot the value *before* the action — this is the only difference
3753 // from xTaskNotifyIndexed.
3754 if (pulPreviousNotifyValue != nullptr)
3755 *pulPreviousNotifyValue = slot.value;
3756
3757 result = NotifyApplyAction(slot, ulValue, eAction);
3758 }
3759
3760 if (result == pdPASS)
3761 (void)slot.sem.TrySignal(); // binary wake flag, a repeated notification is not an error
3762
3763 return result;
3764}

References pdFAIL, pdPASS, and stk::sync::SemaphoreT< T >::TrySignal().

Referenced by xTaskNotifyAndQuery(), and xTaskNotifyAndQueryFromISRIndexed().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskNotifyFromISR()

BaseType_t xTaskNotifyFromISR ( TaskHandle_t xTaskToNotify,
uint32_t ulValue,
eNotifyAction eAction,
BaseType_t * pxHigherPriorityTaskWoken )

Send a notification (slot 0) from ISR context.

Parameters
xTaskToNotifyHandle of the task to notify (must not be NULL).
ulValueValue applied according to eAction.
eActionHow ulValue is applied to the task's notification value.
pxHigherPriorityTaskWokenSet pdTRUE if a context switch is needed (always pdFALSE in STK wrapper).
Returns
pdPASS, or pdFAIL if eSetValueWithoutOverwrite and a notification was already pending.

Definition at line 3698 of file freertos_stk.cpp.

3702{
3703 return xTaskNotifyFromISRIndexed(xTaskToNotify, 0U, ulValue, eAction,
3704 pxHigherPriorityTaskWoken);
3705}
BaseType_t xTaskNotifyFromISRIndexed(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken)

References xTaskNotifyFromISRIndexed().

Here is the call graph for this function:

◆ xTaskNotifyFromISRIndexed()

BaseType_t xTaskNotifyFromISRIndexed ( TaskHandle_t xTaskToNotify,
UBaseType_t uxIndexToNotify,
uint32_t ulValue,
eNotifyAction eAction,
BaseType_t * pxHigherPriorityTaskWoken )

Send a notification to a specific slot from ISR context.

Parameters
xTaskToNotifyHandle of the task to notify (must not be NULL).
uxIndexToNotifyNotification slot index (0 .. configTASK_NOTIFICATION_ARRAY_ENTRIES-1).
ulValueValue applied according to eAction.
eActionHow ulValue is applied to the slot's notification value.
pxHigherPriorityTaskWokenAlways set to pdFALSE (STK handles wake internally).
Returns
pdPASS, or pdFAIL if eSetValueWithoutOverwrite and notification was already pending.

Definition at line 3654 of file freertos_stk.cpp.

3659{
3660 BaseType_t result = xTaskNotifyIndexed(xTaskToNotify, uxIndexToNotify, ulValue, eAction);
3661
3662 if (pxHigherPriorityTaskWoken != nullptr)
3663 *pxHigherPriorityTaskWoken = pdFALSE;
3664
3665 return result;
3666}

References pdFALSE, and xTaskNotifyIndexed().

Referenced by xTaskNotifyFromISR().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskNotifyGive()

BaseType_t xTaskNotifyGive ( TaskHandle_t xTaskToNotify)

Send a notification to a task (slot 0), incrementing its notification value by 1. Equivalent to xTaskNotify(xTaskToNotify, 0, eIncrement).

Parameters
xTaskToNotifyHandle of the task to notify (must not be NULL).
Returns
pdPASS.

Definition at line 3672 of file freertos_stk.cpp.

3673{
3674 return xTaskNotifyGiveIndexed(xTaskToNotify, 0U);
3675}
BaseType_t xTaskNotifyGiveIndexed(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify)

References xTaskNotifyGiveIndexed().

Here is the call graph for this function:

◆ xTaskNotifyGiveIndexed()

BaseType_t xTaskNotifyGiveIndexed ( TaskHandle_t xTaskToNotify,
UBaseType_t uxIndexToNotify )

Send a notification to a specific slot of a task, incrementing the slot's value by 1.

Parameters
xTaskToNotifyHandle of the task to notify (must not be NULL).
uxIndexToNotifyNotification slot index (0 .. configTASK_NOTIFICATION_ARRAY_ENTRIES-1).
Returns
pdPASS, or pdFAIL if the index is out of range.

Definition at line 3531 of file freertos_stk.cpp.

3533{
3534 FrtosTask *t = ResolveNotifyTarget(xTaskToNotify, uxIndexToNotify);
3535 if (t == nullptr)
3536 return pdFAIL;
3537
3538 FrtosTask::NotifySlot &slot = t->m_notify[uxIndexToNotify];
3539
3540 {
3541 // counting semantics: every give increments the notification value, the semaphore is only a binary
3542 // wake-up flag (TrySignal() is idempotent, Signal() would assert once the flag is already set)
3544 slot.value++;
3545 (void)slot.sem.TrySignal(); // ISR-safe
3546 }
3547
3548 return pdPASS;
3549}

References pdFAIL, pdPASS, and stk::sync::SemaphoreT< T >::TrySignal().

Referenced by xTaskNotifyGive().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskNotifyIndexed()

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

Send a notification to a specific slot of a task with a chosen action.

Parameters
xTaskToNotifyHandle of the task to notify (must not be NULL).
uxIndexToNotifyNotification slot index (0 .. configTASK_NOTIFICATION_ARRAY_ENTRIES-1).
ulValueValue applied according to eAction.
eActionHow ulValue is applied to the slot's value.
Returns
pdPASS, or pdFAIL on bad index or eSetValueWithoutOverwrite conflict.

Definition at line 3592 of file freertos_stk.cpp.

3596{
3597 FrtosTask *t = ResolveNotifyTarget(xTaskToNotify, uxIndexToNotify);
3598 if (t == nullptr)
3599 return pdFAIL;
3600
3601 FrtosTask::NotifySlot &slot = t->m_notify[uxIndexToNotify];
3602 BaseType_t result = pdPASS;
3603
3604 {
3606 result = NotifyApplyAction(slot, ulValue, eAction);
3607 }
3608
3609 if (result == pdPASS)
3610 (void)slot.sem.TrySignal(); // binary wake flag, a repeated notification is not an error
3611
3612 return result;
3613}

References pdFAIL, pdPASS, and stk::sync::SemaphoreT< T >::TrySignal().

Referenced by xTaskNotify(), and xTaskNotifyFromISRIndexed().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskNotifyStateClear()

BaseType_t xTaskNotifyStateClear ( TaskHandle_t xTask)

Clear the pending notification state for slot 0 of a task.

If a notification was pending (i.e. the task had been notified but had not yet called xTaskNotifyWait() or ulTaskNotifyTake() to consume it), this function clears the pending state and returns pdTRUE. If no notification was pending it returns pdFALSE.

Parameters
xTaskHandle of the task whose notification state is to be cleared. NULL selects the calling task.
Returns
pdTRUE if a notification was pending and has been cleared, pdFALSE if no notification was pending.
Note
ISR-safe.

Definition at line 3873 of file freertos_stk.cpp.

3874{
3875 return xTaskNotifyStateClearIndexed(xTask, 0U);
3876}
BaseType_t xTaskNotifyStateClearIndexed(TaskHandle_t xTask, UBaseType_t uxIndexToClear)

References xTaskNotifyStateClearIndexed().

Here is the call graph for this function:

◆ xTaskNotifyStateClearIndexed()

BaseType_t xTaskNotifyStateClearIndexed ( TaskHandle_t xTask,
UBaseType_t uxIndexToClear )

Indexed variant of xTaskNotifyStateClear.

Parameters
xTaskHandle of the task. NULL selects the calling task.
uxIndexToClearNotification slot index (0 .. configTASK_NOTIFICATION_ARRAY_ENTRIES-1).
Returns
pdTRUE if a notification was pending, pdFALSE otherwise.
Note
ISR-safe.

Definition at line 3838 of file freertos_stk.cpp.

3840{
3841 FrtosTask *t = ResolveNotifyTarget(xTask, uxIndexToClear);
3842 if (t == nullptr)
3843 return pdFALSE;
3844
3845 FrtosTask::NotifySlot &slot = t->m_notify[uxIndexToClear];
3846
3848
3849 // Determine whether a notification was pending before we clear anything.
3850 // A notification is considered "pending" when the semaphore has a count
3851 // (i.e. Signal() was called but Wait/Take has not yet consumed it) OR
3852 // when the value-without-overwrite guard flag is set.
3853 const bool was_pending = (slot.sem.GetCount() != 0U) || slot.pending;
3854
3855 if (was_pending)
3856 {
3857 // Drain the semaphore (binary, at most 1 token to consume).
3858 slot.sem.TryWait();
3859
3860 // Clear the eSetValueWithoutOverwrite pending guard so that a
3861 // subsequent xTaskNotify(eSetValueWithoutOverwrite) can write a new
3862 // value without being rejected.
3863 slot.pending = false;
3864 }
3865
3866 return was_pending ? pdTRUE : pdFALSE;
3867}
T GetCount() const
Get current counter value.
bool TryWait()
Poll the semaphore without blocking (decrement counter if available).

References stk::sync::SemaphoreT< T >::GetCount(), pdFALSE, pdTRUE, and stk::sync::SemaphoreT< T >::TryWait().

Referenced by xTaskNotifyStateClear().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskNotifyWait()

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

Wait for a notification (slot 0), with optional bit-masking on entry and exit.

Parameters
ulBitsToClearOnEntryBits cleared before blocking.
ulBitsToClearOnExitBits cleared before returning.
pulNotificationValueReceives the value before the exit-clear (may be NULL).
xTicksToWaitTicks to wait.
Returns
pdTRUE if notified, pdFALSE on timeout.
Examples
blinky_c-freertos/example.c.

Definition at line 3689 of file freertos_stk.cpp.

3693{
3694 return xTaskNotifyWaitIndexed(0U, ulBitsToClearOnEntry, ulBitsToClearOnExit,
3695 pulNotificationValue, xTicksToWait);
3696}
BaseType_t xTaskNotifyWaitIndexed(UBaseType_t uxIndexToWait, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait)

References xTaskNotifyWaitIndexed().

Referenced by clock_task(), phaseA(), phaseB(), phaseC(), and phaseD().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskNotifyWaitIndexed()

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

Wait for a notification on a specific slot of the calling task.

Parameters
uxIndexToWaitNotification slot index.
ulBitsToClearOnEntryBits cleared in the slot value before blocking.
ulBitsToClearOnExitBits cleared in the slot value before returning.
pulNotificationValueReceives the slot value before the exit-clear (may be NULL).
xTicksToWaitTicks to wait.
Returns
pdTRUE if notified, pdFALSE on timeout or bad index.

Definition at line 3615 of file freertos_stk.cpp.

3620{
3621 if (IsIrqContext())
3622 return pdFAIL;
3623
3624 FrtosTask *t = ResolveNotifyTarget(nullptr, uxIndexToWait);
3625 if (t == nullptr)
3626 return pdFAIL;
3627
3628 FrtosTask::NotifySlot &slot = t->m_notify[uxIndexToWait];
3629
3630 // Clear entry bits before blocking.
3631 {
3633 slot.value &= ~ulBitsToClearOnEntry;
3634 }
3635
3636 // Block until notified or timeout.
3637 if (!slot.sem.Wait(FrtosTimeoutToStk(xTicksToWait)))
3638 return pdFAIL;
3639
3640 // Read and apply exit-clear.
3641 {
3643
3644 if (pulNotificationValue != nullptr)
3645 *pulNotificationValue = slot.value;
3646
3647 slot.value &= ~ulBitsToClearOnExit;
3648 slot.pending = false;
3649 }
3650
3651 return pdPASS;
3652}

References pdFAIL, pdPASS, and stk::sync::SemaphoreT< T >::Wait().

Referenced by xTaskNotifyWait().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ xTaskResumeAll()

BaseType_t xTaskResumeAll ( void )

Resume a previously suspended scheduler.

Returns
pdTRUE if a context switch is pending, pdFALSE otherwise.

Definition at line 1365 of file freertos_stk.cpp.

1366{
1368 return pdFALSE; // no pending switch tracked at wrapper level
1369}

References stk::hw::CriticalSection::Exit(), and pdFALSE.

Here is the call graph for this function:

◆ xTaskResumeFromISR()

BaseType_t xTaskResumeFromISR ( TaskHandle_t xTaskToResume)

Resume a previously suspended task from ISR context.

Parameters
xTaskToResumeHandle of the task to resume.
Returns
pdTRUE if the task was successfully resumed.

Definition at line 1570 of file freertos_stk.cpp.

1571{
1572 if (xTaskToResume == nullptr)
1573 return pdFALSE;
1574
1575 FrtosTask *t = static_cast<FrtosTask *>(xTaskToResume);
1576
1578
1579 if (t->m_state != FrtosTask::State::Suspended)
1580 return pdFALSE;
1581
1582 const stk::EResumeResult res = g_StkKernel.ResumeTask(t);
1583 if ((res != stk::RESUME_DONE) && (res != stk::RESUME_LIFTED))
1584 return pdFALSE;
1585
1586 t->m_state = FrtosTask::State::Ready;
1587 return pdTRUE;
1588}

References pdFALSE, pdTRUE, stk::RESUME_DONE, and stk::RESUME_LIFTED.

◆ xTimerChangePeriod()

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

Change the period of a timer and restart it immediately.

Parameters
xTimerHandle of the timer to modify.
xNewPeriodNew timer period in ticks (must be > 0).
xTicksToWaitAccepted for API compatibility; ignored (command queue write is non-blocking).
Returns
pdPASS on success.

Definition at line 3101 of file freertos_stk.cpp.

3104{
3105 if ((xTimer == nullptr) || (xNewPeriod == 0U))
3106 return pdFAIL;
3107
3108 FrtosTimer *t = static_cast<FrtosTimer *>(xTimer);
3109 t->m_period = xNewPeriod;
3110
3111 return xTimerStart(xTimer, xTicksToWait);
3112}
BaseType_t xTimerStart(TimerHandle_t xTimer, TickType_t)

References pdFAIL, and xTimerStart().

Here is the call graph for this function:

◆ xTimerChangePeriodFromISR()

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

Change the period of a timer and restart it from ISR context.

Parameters
xTimerHandle of the timer to modify.
xNewPeriodNew timer period in ticks (must be > 0).
pxHigherPriorityTaskWokenAlways set to pdFALSE.
Returns
pdPASS on success, pdFAIL if the command queue is full or arguments are invalid.

Definition at line 3171 of file freertos_stk.cpp.

3174{
3175 if (pxHigherPriorityTaskWoken != nullptr)
3176 *pxHigherPriorityTaskWoken = pdFALSE;
3177
3178 if ((xTimer == nullptr) || (xNewPeriod == 0U) || (g_TimerHost == nullptr))
3179 return pdFAIL;
3180
3181 FrtosTimer *t = static_cast<FrtosTimer *>(xTimer);
3182 t->m_period = xNewPeriod;
3183
3184 // Restart with the new period, taking effect immediately.
3185 uint32_t period = t->m_auto_reload ? static_cast<uint32_t>(xNewPeriod) : 0U;
3186
3187 return TimerResToFrtos(g_TimerHost->Restart(*t, static_cast<uint32_t>(xNewPeriod), period));
3188}

References pdFAIL, and pdFALSE.

◆ xTimerCreate()

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

Create a software timer.

Parameters
pcTimerNameName for debugging.
xTimerPeriodInTicksPeriod in ticks (must be > 0).
uxAutoReloadpdTRUE = periodic, pdFALSE = one-shot.
pvTimerIDApplication-defined value stored in the timer.
pxCallbackFunctionCallback invoked on expiry.
Returns
Timer handle, or NULL on failure.

Definition at line 2987 of file freertos_stk.cpp.

2992{
2993 if (IsIrqContext() || (pxCallbackFunction == nullptr) || (xTimerPeriodInTicks == 0U))
2994 return nullptr;
2995
2996 if (!FrtosTimer::EnsureTimerHost())
2997 return nullptr;
2998
2999 FrtosTimer *t = ObjAlloc<FrtosTimer>(
3000 pcTimerName,
3001 xTimerPeriodInTicks,
3002 (uxAutoReload == pdTRUE),
3003 pvTimerID,
3004 pxCallbackFunction);
3005
3006 return static_cast<TimerHandle_t>(t);
3007}
void * TimerHandle_t
Definition FreeRTOS.h:320

References pdTRUE.

◆ xTimerCreateStatic()

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

Create a software timer using caller-supplied storage — no heap allocation.

Parameters
pcTimerNameName for debugging.
xTimerPeriodInTicksPeriod in ticks (must be > 0).
uxAutoReloadpdTRUE = periodic, pdFALSE = one-shot.
pvTimerIDApplication-defined value stored in the timer.
pxCallbackFunctionCallback invoked on expiry.
pxTimerBufferCaller-allocated control block (StaticTimer_t). Must remain valid for the lifetime of the timer.
Returns
Timer handle. Never NULL if pxTimerBuffer is non-NULL, pxCallbackFunction is non-NULL and xTimerPeriodInTicks > 0.

Definition at line 3009 of file freertos_stk.cpp.

3015{
3016 if (pxTimerBuffer == nullptr)
3017 return nullptr;
3018
3019 if (IsIrqContext() || (pxCallbackFunction == nullptr) || (xTimerPeriodInTicks == 0U))
3020 return nullptr;
3021
3022 if (!FrtosTimer::EnsureTimerHost())
3023 return nullptr;
3024
3025 STK_STATIC_ASSERT_DESC(sizeof(StaticTimer_t) >= sizeof(FrtosTimer),
3026 "StaticTimer_t is too small to hold FrtosTimer. "
3027 "Increase STATIC_TIMER_TCB_SIZE_WORDS in freertos_stk.h.");
3028
3029 // Placement-new the FrtosTimer into the caller-supplied buffer.
3030 FrtosTimer *t = new (pxTimerBuffer) FrtosTimer(
3031 pcTimerName,
3032 xTimerPeriodInTicks,
3033 (uxAutoReload == pdTRUE),
3034 pvTimerID,
3035 pxCallbackFunction);
3036
3037 t->m_cb_owned = false; // caller owns the memory; xTimerDelete must not delete it
3038
3039 return static_cast<TimerHandle_t>(t);
3040}

References pdTRUE, and STK_STATIC_ASSERT_DESC.

◆ xTimerDelete()

BaseType_t xTimerDelete ( TimerHandle_t xTimer,
TickType_t xTicksToWait )

Delete a software timer and free its memory.

Parameters
xTimerHandle of the timer to delete.
xTicksToWaitAccepted for API compatibility; ignored (command queue write is non-blocking).
Returns
pdPASS.

Definition at line 3042 of file freertos_stk.cpp.

3043{
3044 if (xTimer == nullptr)
3045 return pdFAIL;
3046
3047 if (IsIrqContext())
3048 return pdFAIL; // API contract: not available from an ISR
3049
3050 FrtosTimer *t = static_cast<FrtosTimer *>(xTimer);
3051
3052 if (g_TimerHost != nullptr)
3053 {
3054 // StopSync() waits until the tick task executed the command, no queued reference to the timer is left
3055 // in the host and no callback of it is running (a callback of this very timer is not waited for).
3056 // The storage may only be released after that, the asynchronous Stop() would leave a window where the
3057 // host still holds the timer. Anything else (RES_QUEUED: kernel not running yet, RES_NOT_READY, ...)
3058 // means the timer may still be referenced, do not free it (FreeRTOS: delete failed).
3059 const stk::time::TimerHost::EResult res = g_TimerHost->StopSync(*t);
3060
3062 return pdFAIL;
3063 }
3064
3065 ObjFree(t);
3066 return pdPASS;
3067}
EResult
Outcome of a command: returned by the asynchronous API (Start(), Stop(), ...) and by the synchronous ...
@ RES_INACTIVE
The timer is not active, but the command requires it to be active (stop, reset).
@ RES_OK
Sync: the command was executed. Async: the command was accepted into the command queue.

References pdFAIL, pdPASS, stk::time::TimerHost::RES_INACTIVE, and stk::time::TimerHost::RES_OK.

◆ xTimerGetExpiryTime()

TickType_t xTimerGetExpiryTime ( TimerHandle_t xTimer)

Return the absolute tick count at which the timer will next expire. Returns 0 if the timer is not currently running.

Parameters
xTimerHandle of the timer to query.
Returns
Absolute tick value of the next expiry, or 0 if the timer is stopped.

Definition at line 3328 of file freertos_stk.cpp.

3329{
3330 if ((xTimer == nullptr) || (g_TimerHost == nullptr))
3331 return 0U;
3332
3333 FrtosTimer *t = static_cast<FrtosTimer *>(xTimer);
3334 return t->IsActive() ? static_cast<TickType_t>(t->GetDeadline()) : 0U;
3335}

◆ xTimerGetPeriod()

TickType_t xTimerGetPeriod ( TimerHandle_t xTimer)

Return the period of a timer in ticks.

Parameters
xTimerHandle of the timer to query.
Returns
Timer period in ticks as set at creation or by xTimerChangePeriod().

Definition at line 3320 of file freertos_stk.cpp.

3321{
3322 if (xTimer == nullptr)
3323 return 0U;
3324
3325 return static_cast<FrtosTimer *>(xTimer)->m_period;
3326}

◆ xTimerIsTimerActive()

BaseType_t xTimerIsTimerActive ( TimerHandle_t xTimer)

Query whether a timer is currently active (running).

Parameters
xTimerHandle of the timer to query.
Returns
pdTRUE if active, pdFALSE if stopped or expired.

Definition at line 3288 of file freertos_stk.cpp.

3289{
3290 if (xTimer == nullptr)
3291 return pdFALSE;
3292
3293 return static_cast<FrtosTimer *>(xTimer)->IsActive() ? pdTRUE : pdFALSE;
3294}

References pdFALSE, and pdTRUE.

◆ xTimerPendFunctionCall()

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

Defer execution of a function to the timer-task context (task-context variant).

Writes a PendCall record {xFunctionToPend, pvParameter1, ulParameter2} into the static g_PendCallPipe (PipeT<PendCall, FREERTOS_STK_PEND_CALL_QUEUE_SIZE>). The TimerHost handler task drains the pipe on each wake cycle and invokes every callback directly — no heap allocation is performed, no self-deleting timer object is created.

Note
Requires the TimerHost to have been started (at least one timer created or xTimerPendFunctionCall called after vTaskStartScheduler). If the TimerHost has not yet been initialized this function initializes it implicitly, matching FreeRTOS behaviour.
If the static pipe is full this function blocks for up to xTicksToWait ticks waiting for a free slot (PipeT::Write blocking semantics). Pass 0 for a non-blocking attempt.
Parameters
xFunctionToPendCallback to invoke in the timer-task context. Signature: void cb(void *pvParam1, uint32_t ulParam2).
pvParameter1First argument forwarded to the callback.
ulParameter2Second argument forwarded to the callback.
xTicksToWaitTicks to wait if the pipe is full. portMAX_DELAY blocks indefinitely.
Returns
pdPASS on success, pdFAIL if the pipe was full and the timeout expired.
Warning
ISR-unsafe. Use xTimerPendFunctionCallFromISR() from interrupt context.

Definition at line 3226 of file freertos_stk.cpp.

3230{
3231 // API contract: must not be called from ISR context.
3232 if (IsIrqContext())
3233 return pdFAIL;
3234
3235 if (xFunctionToPend == nullptr)
3236 return pdFAIL;
3237
3238 // Ensure the TimerHost (and hence the drainer's scheduling context) exists.
3239 if (!FrtosTimer::EnsureTimerHost())
3240 return pdFAIL;
3241
3242 // Write the call record into the static pipe (blocking with timeout).
3243 // PipeT::Write() acquires a ScopedCriticalSection internally.
3244 const PendCall call = { xFunctionToPend, pvParameter1, ulParameter2 };
3245 if (!g_PendCallPipe.Write(call, FrtosTimeoutToStk(xTicksToWait)))
3246 return pdFAIL;
3247
3248 // (Re-)arm the singleton drainer so it wakes within 1 tick: enqueue FIRST, arm afterwards (the other order
3249 // would let the drainer run before the record is visible). If arming fails (host not ready) the record
3250 // stays queued and is executed with the next successful arm, the call is reported as failed.
3251 if (!EnsurePendDrainer())
3252 return pdFAIL;
3253
3254 return pdPASS;
3255}

References pdFAIL, and pdPASS.

◆ xTimerPendFunctionCallFromISR()

BaseType_t xTimerPendFunctionCallFromISR ( PendedFunction_t xFunctionToPend,
void * pvParameter1,
uint32_t ulParameter2,
BaseType_t * pxHigherPriorityTaskWoken )

Defer execution of a function to the timer-task context (ISR-safe variant).

Identical in effect to xTimerPendFunctionCall() but safe to call from an interrupt service routine. The call record is written into a static PipeT<PendCall, FREERTOS_STK_PEND_CALL_QUEUE_SIZE> with NO_WAIT semantics — no heap allocation is performed. If the pipe is full the function returns pdFAIL immediately.

Parameters
xFunctionToPendCallback to invoke in the timer-task context.
pvParameter1First argument forwarded to the callback.
ulParameter2Second argument forwarded to the callback.
pxHigherPriorityTaskWokenAlways set to pdFALSE (STK wakes the timer task internally; no manual yield required).
Returns
pdPASS on success, pdFAIL if the static queue was full.

Definition at line 3257 of file freertos_stk.cpp.

3261{
3262 // STK wakes the tick task internally; no manual context switch needed.
3263 if (pxHigherPriorityTaskWoken != nullptr)
3264 *pxHigherPriorityTaskWoken = pdFALSE;
3265
3266 if (xFunctionToPend == nullptr)
3267 return pdFAIL;
3268
3269 // From ISR the TimerHost must already be running (a timer was created
3270 // before the ISR fired — the only realistic usage pattern).
3271 if (g_TimerHost == nullptr)
3272 return pdFAIL;
3273
3274 // Arm the drainer FIRST: it can not run before this ISR returns, so the record written below is visible when
3275 // it fires. This way a failed arm (command queue full, drainer not created yet) fails the call without
3276 // leaving an undrained record behind. If the write fails the one-shot drainer just finds an empty pipe.
3277 if (!KickPendDrainerFromISR())
3278 return pdFAIL;
3279
3280 // Non-blocking enqueue: TryWrite() holds a ScopedCriticalSection internally, ISR-safe, no blocking.
3281 const PendCall call = { xFunctionToPend, pvParameter1, ulParameter2 };
3282 if (!g_PendCallPipe.TryWrite(call))
3283 return pdFAIL;
3284
3285 return pdPASS;
3286}

References pdFAIL, pdFALSE, and pdPASS.

◆ xTimerReset()

BaseType_t xTimerReset ( TimerHandle_t xTimer,
TickType_t xTicksToWait )

Reset a timer (restart its period from the current tick).

Parameters
xTimerHandle of the timer to reset.
xTicksToWaitAccepted for API compatibility; ignored (command queue write is non-blocking).
Returns
pdPASS on success.

Definition at line 3096 of file freertos_stk.cpp.

3097{
3098 return xTimerStart(xTimer, xTicksToWait); // Restart restarts from now
3099}

References xTimerStart().

Here is the call graph for this function:

◆ xTimerResetFromISR()

BaseType_t xTimerResetFromISR ( TimerHandle_t xTimer,
BaseType_t * pxHigherPriorityTaskWoken )

Reset (restart the period of) a timer from ISR context.

Parameters
xTimerHandle of the timer to reset.
pxHigherPriorityTaskWokenAlways set to pdFALSE.
Returns
pdPASS on success, pdFAIL if the command queue is full or handle is invalid.

Definition at line 3164 of file freertos_stk.cpp.

3166{
3167 // Reset = Restart from now, same as xTimerStart.
3168 return xTimerStartFromISR(xTimer, pxHigherPriorityTaskWoken);
3169}
BaseType_t xTimerStartFromISR(TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken)

References xTimerStartFromISR().

Here is the call graph for this function:

◆ xTimerStart()

BaseType_t xTimerStart ( TimerHandle_t xTimer,
TickType_t xTicksToWait )

Start (or restart) a timer from the current tick.

Parameters
xTimerHandle of the timer to start.
xTicksToWaitAccepted for API compatibility; ignored (command queue write is non-blocking).
Returns
pdPASS on success, pdFAIL on error.

Definition at line 3069 of file freertos_stk.cpp.

3070{
3071 if (IsIrqContext() || (xTimer == nullptr) || (g_TimerHost == nullptr))
3072 return pdFAIL;
3073
3074 FrtosTimer *t = static_cast<FrtosTimer *>(xTimer);
3075
3076 uint32_t period = t->m_auto_reload
3077 ? static_cast<uint32_t>(t->m_period)
3078 : 0U; // 0 = one-shot (no reload period)
3079
3080 // synchronous variant: the exact outcome is known when it returns (task context)
3081 return TimerResToFrtos(g_TimerHost->RestartSync(*t, static_cast<uint32_t>(t->m_period), period));
3082}

References pdFAIL.

Referenced by xTimerChangePeriod(), and xTimerReset().

Here is the caller graph for this function:

◆ xTimerStartFromISR()

BaseType_t xTimerStartFromISR ( TimerHandle_t xTimer,
BaseType_t * pxHigherPriorityTaskWoken )

Start (or restart) a timer from ISR context.

Parameters
xTimerHandle of the timer to start.
pxHigherPriorityTaskWokenAlways set to pdFALSE.
Returns
pdPASS on success, pdFAIL if the command queue is full or handle is invalid.

Definition at line 3135 of file freertos_stk.cpp.

3137{
3138 if (pxHigherPriorityTaskWoken != nullptr)
3139 *pxHigherPriorityTaskWoken = pdFALSE;
3140
3141 if ((xTimer == nullptr) || (g_TimerHost == nullptr))
3142 return pdFAIL;
3143
3144 FrtosTimer *t = static_cast<FrtosTimer *>(xTimer);
3145 uint32_t period = t->m_auto_reload ? static_cast<uint32_t>(t->m_period) : 0U;
3146
3147 return TimerResToFrtos(g_TimerHost->Restart(*t, static_cast<uint32_t>(t->m_period), period));
3148}

References pdFAIL, and pdFALSE.

Referenced by xTimerResetFromISR().

Here is the caller graph for this function:

◆ xTimerStop()

BaseType_t xTimerStop ( TimerHandle_t xTimer,
TickType_t xTicksToWait )

Stop a running timer.

Parameters
xTimerHandle of the timer to stop.
xTicksToWaitAccepted for API compatibility; ignored (command queue write is non-blocking).
Returns
pdPASS on success, pdFAIL if the timer was not running.

Definition at line 3084 of file freertos_stk.cpp.

3085{
3086 if (IsIrqContext() || (xTimer == nullptr) || (g_TimerHost == nullptr))
3087 return pdFAIL;
3088
3089 FrtosTimer *t = static_cast<FrtosTimer *>(xTimer);
3090
3091 // no IsActive() pre-check: the flag is advisory and lags behind a just issued Start. Stopping a dormant timer
3092 // is not an error in FreeRTOS.
3093 return TimerResToFrtos(g_TimerHost->StopSync(*t), true);
3094}

References pdFAIL.

◆ xTimerStopFromISR()

BaseType_t xTimerStopFromISR ( TimerHandle_t xTimer,
BaseType_t * pxHigherPriorityTaskWoken )

Stop a running timer from ISR context.

Parameters
xTimerHandle of the timer to stop.
pxHigherPriorityTaskWokenAlways set to pdFALSE.
Returns
pdPASS on success, pdFAIL if the timer is not running or handle is invalid.

Definition at line 3150 of file freertos_stk.cpp.

3152{
3153 if (pxHigherPriorityTaskWoken != nullptr)
3154 *pxHigherPriorityTaskWoken = pdFALSE;
3155
3156 if ((xTimer == nullptr) || (g_TimerHost == nullptr))
3157 return pdFAIL;
3158
3159 FrtosTimer *t = static_cast<FrtosTimer *>(xTimer);
3160
3161 return TimerResToFrtos(g_TimerHost->Stop(*t), true); // RES_INACTIVE: already dormant, nothing queued
3162}

References pdFAIL, and pdFALSE.