vApplicationIdleHook()

The idle task hook is a user-defined callback function that FreeRTOS executes repeatedly whenever no other task is ready to run. It is implemented as vApplicationIdleHook() and enabled by setting configUSE_IDLE_HOOK to 1 in FreeRTOSConfig.h. The hook can be used for low-priority background operations, such as entering a low-power mode, collecting system statistics, or performing simple maintenance tasks. It must never block, call functions that may block, or perform lengthy processing, because doing so prevents the idle task from running normally and may delay the cleanup of deleted tasks.

void vApplicationIdleHook(void)

// ---------------------- Example ----------------------

#define configUSE_TICKLESS_IDLE    0  
#define configUSE_IDLE_HOOK        1
#define configIDLE_SHOULD_YIELD    1 

void BeforeEnterSleep(void)
{
    __HAL_RCC_GPIOB_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOC_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOD_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOE_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOF_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOG_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOH_CLK_SLEEP_DISABLE();
}

void AfterExitSleep(void)
{
    __HAL_RCC_GPIOB_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOC_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOD_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOE_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOF_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOG_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOH_CLK_SLEEP_ENABLE();
}

void vApplicationIdleHook(void)
{
    BeforeEnterSleep();
    __DSB();  
    __WFI();  
    __ISB();  
    AfterExitSleep();
}

void vApplicationIdleHook(void)

// ---------------------- Example ----------------------

#define configUSE_TICKLESS_IDLE    0  
#define configUSE_IDLE_HOOK        1
#define configIDLE_SHOULD_YIELD    1 

void BeforeEnterSleep(void)
{
    __HAL_RCC_GPIOB_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOC_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOD_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOE_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOF_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOG_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOH_CLK_SLEEP_DISABLE();
}

void AfterExitSleep(void)
{
    __HAL_RCC_GPIOB_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOC_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOD_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOE_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOF_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOG_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOH_CLK_SLEEP_ENABLE();
}

void vApplicationIdleHook(void)
{
    BeforeEnterSleep();
    __DSB();  
    __WFI();  
    __ISB();  
    AfterExitSleep();
}

vApplicationTickHook()

vApplicationTickHook() is a user-defined FreeRTOS hook function that is called from the RTOS tick interrupt each time the system tick occurs. To enable it, set configUSE_TICK_HOOK to 1 in FreeRTOSConfig.h. It is typically used for short, periodic operations such as incrementing counters, updating software timing variables, or triggering lightweight monitoring functions. Because it executes in interrupt context, the hook must run quickly, must not block, and may only call FreeRTOS API functions that are safe to use from an ISR.

void vApplicationTickHook(void)

// ---------------------- Example ----------------------

#define configUSE_TICK_HOOK    1

volatile uint32_t ulTickHookCounter = 0;
volatile BaseType_t xOneSecondElapsed = pdFALSE;

void vApplicationTickHook(void) {
    ulTickHookCounter++;

    // Set a flag approximately once every second
    if (ulTickHookCounter >= configTICK_RATE_HZ)
    {
        ulTickHookCounter = 0;
        xOneSecondElapsed = pdTRUE;
    }
}

void vApplicationTickHook(void)

// ---------------------- Example ----------------------

#define configUSE_TICK_HOOK    1

volatile uint32_t ulTickHookCounter = 0;
volatile BaseType_t xOneSecondElapsed = pdFALSE;

void vApplicationTickHook(void) {
    ulTickHookCounter++;

    // Set a flag approximately once every second
    if (ulTickHookCounter >= configTICK_RATE_HZ)
    {
        ulTickHookCounter = 0;
        xOneSecondElapsed = pdTRUE;
    }
}

vApplicationMallocFailedHook()

vApplicationMallocFailedHook() is a user-defined FreeRTOS hook function that is called whenever a dynamic memory allocation request fails, such as when pvPortMalloc(), xTaskCreate(), or another kernel object creation function cannot obtain enough heap memory. To enable it, set configUSE_MALLOC_FAILED_HOOK to 1 in FreeRTOSConfig.h. The hook is commonly used to record diagnostic information, trigger an assertion, illuminate an error indicator, or halt execution for debugging. Because the system may have very little memory remaining, the hook should avoid performing additional dynamic memory allocations.

void vApplicationMallocFailedHook(void)

// ---------------------- Example ----------------------

#define configUSE_MALLOC_FAILED_HOOK    1

void vApplicationMallocFailedHook(void) 
{
    taskDISABLE_INTERRUPTS();
    for (;;) {}
}

void vApplicationMallocFailedHook(void)

// ---------------------- Example ----------------------

#define configUSE_MALLOC_FAILED_HOOK    1

void vApplicationMallocFailedHook(void) 
{
    taskDISABLE_INTERRUPTS();
    for (;;) {}
}

vApplicationStackOverflowHook()

vApplicationStackOverflowHook() is a user-defined FreeRTOS hook function that is called when the kernel detects that a task has exceeded its allocated stack space. To enable stack-overflow checking, set configCHECK_FOR_STACK_OVERFLOW to 1 or 2 in FreeRTOSConfig.h, with 2 providing more thorough checking. The hook receives the handle and name of the affected task, allowing the application to record diagnostic information, trigger an assertion, illuminate an error LED, or halt execution for debugging. Because stack corruption may already have occurred, the hook should avoid complex operations and should normally stop the system so the cause can be investigated.

void vApplicationStackOverflowHook(TaskHandle_t xTask, 
                                   char *pcTaskName)

// ---------------------- Example ----------------------

#define INCLUDE_uxTaskGetStackHighWaterMark    1
#define configCHECK_FOR_STACK_OVERFLOW			   2    

volatile const char *g_overflow_task_name = NULL;
volatile TaskHandle_t g_overflow_task_handle = NULL;

void vApplicationStackOverflowHook(TaskHandle_t xTask, 
                                   char *pcTaskName) 
{
    g_overflow_task_handle = xTask;
    g_overflow_task_name = pcTaskName; // points to the task name string

    taskDISABLE_INTERRUPTS();
    for (;;) {
        __NOP(); // set breakpoint here and inspect g_overflow_task_name
                 // LED may also be turned on or toggled here
    }
}

TaskHandle_t taskHandler;
UBaseType_t uxRemainingWords;
uxRemainingWords = uxTaskGetStackHighWaterMark(taskHandler);
printf("Unused stack: %lu words (%lu bytes)\r\n",
       (unsigned long)uxRemainingWords,
       (unsigned long)uxRemainingWords * sizeof(StackType_t));

void vApplicationStackOverflowHook(TaskHandle_t xTask, 
                                   char *pcTaskName)

// ---------------------- Example ----------------------

#define INCLUDE_uxTaskGetStackHighWaterMark    1
#define configCHECK_FOR_STACK_OVERFLOW			   2    

volatile const char *g_overflow_task_name = NULL;
volatile TaskHandle_t g_overflow_task_handle = NULL;

void vApplicationStackOverflowHook(TaskHandle_t xTask, 
                                   char *pcTaskName) 
{
    g_overflow_task_handle = xTask;
    g_overflow_task_name = pcTaskName; // points to the task name string

    taskDISABLE_INTERRUPTS();
    for (;;) {
        __NOP(); // set breakpoint here and inspect g_overflow_task_name
                 // LED may also be turned on or toggled here
    }
}

TaskHandle_t taskHandler;
UBaseType_t uxRemainingWords;
uxRemainingWords = uxTaskGetStackHighWaterMark(taskHandler);
printf("Unused stack: %lu words (%lu bytes)\r\n",
       (unsigned long)uxRemainingWords,
       (unsigned long)uxRemainingWords * sizeof(StackType_t));

vApplicationDaemonTaskStartupHook()

vApplicationDaemonTaskStartupHook() is a user-defined FreeRTOS hook function that is called once when the daemon task, also known as the timer service task, begins running after the scheduler starts. To enable it, set configUSE_DAEMON_TASK_STARTUP_HOOK to 1 in FreeRTOSConfig.h. It is typically used to perform application initialization that must occur after the scheduler is active, such as creating synchronization objects, starting software timers, or initializing components that depend on FreeRTOS services. Because the hook executes in the context of the daemon task, lengthy or blocking operations should be avoided so that software timers and deferred callback processing are not delayed.

void vApplicationDaemonTaskStartupHook(void)

// ---------------------- Example ----------------------

#define configUSE_DAEMON_TASK_STARTUP_HOOK    1
#define configUSE_TIMERS				              1

TimerHandle_t OneShotTimer_Handle;

OneShotTimer_Handle = 
  xTimerCreate((const char*			       ) "OneShotTimer",
			         (TickType_t			       ) 3000,
							 (UBaseType_t			       ) pdFALSE,
							 (void*				           ) 1,
							 (TimerCallbackFunction_t) OneShotTimerCallback);

void vApplicationDaemonTaskStartupHook(void) {
    BaseType_t xResult;
    xResult = xTimerStart(OneShotTimer_Handle, 0);
    configASSERT(xResult == pdPASS);
}

void OneShotTimerCallback(TimerHandle_t xTimer) {
	static TickType_t xTimeNow;
	xTimeNow = xTaskGetTickCount();
	printf("One-shot timer callback executing: %d\r\n", (int)xTimeNow);
}

void vApplicationDaemonTaskStartupHook(void)

// ---------------------- Example ----------------------

#define configUSE_DAEMON_TASK_STARTUP_HOOK    1
#define configUSE_TIMERS				              1

TimerHandle_t OneShotTimer_Handle;

OneShotTimer_Handle = 
  xTimerCreate((const char*			       ) "OneShotTimer",
			         (TickType_t			       ) 3000,
							 (UBaseType_t			       ) pdFALSE,
							 (void*				           ) 1,
							 (TimerCallbackFunction_t) OneShotTimerCallback);

void vApplicationDaemonTaskStartupHook(void) {
    BaseType_t xResult;
    xResult = xTimerStart(OneShotTimer_Handle, 0);
    configASSERT(xResult == pdPASS);
}

void OneShotTimerCallback(TimerHandle_t xTimer) {
	static TickType_t xTimeNow;
	xTimeNow = xTaskGetTickCount();
	printf("One-shot timer callback executing: %d\r\n", (int)xTimeNow);
}

configUSE_TICKLESS_IDLE

configUSE_TICKLESS_IDLE enables FreeRTOS tickless idle mode, which reduces power consumption when no application task is ready to run. Normally, the periodic RTOS tick interrupt continues waking the processor even while the Idle task is running. When tickless idle is enabled, FreeRTOS temporarily stops the tick interrupt, places the processor into a low-power state, and sleeps until an interrupt occurs or a blocked task is due to wake. After waking, the kernel adjusts its tick count to account for the elapsed time. Set it to 0 to disable tickless idle, 1 to use the port’s built-in implementation when supported, or 2 to provide a custom portSUPPRESS_TICKS_AND_SLEEP() implementation.

#define configUSE_TICKLESS_IDLE    1                       

// FreeRTOSConfig.h
extern void PreSleepProcessing(uint32_t ulExpectedIdleTime);
extern void PostSleepProcessing(uint32_t ulExpectedIdleTime);
#define configPRE_SLEEP_PROCESSING  PreSleepProcessing	 
#define configPOST_SLEEP_PROCESSING  PostSleepProcessing	 

// main.c
void PreSleepProcessing(uint32_t ulExpectedIdleTime)
{
    (void)ulExpectedIdleTime;

    // Disable GPIO clocks that are not needed during sleep
    __HAL_RCC_GPIOB_CLK_DISABLE();
    __HAL_RCC_GPIOC_CLK_DISABLE();
    __HAL_RCC_GPIOD_CLK_DISABLE();
    __HAL_RCC_GPIOE_CLK_DISABLE();
    __HAL_RCC_GPIOF_CLK_DISABLE();
    __HAL_RCC_GPIOG_CLK_DISABLE();
    __HAL_RCC_GPIOH_CLK_DISABLE();
}

void PostSleepProcessing(uint32_t ulExpectedIdleTime)
{
    (void)ulExpectedIdleTime;

    // Re-enable GPIO clocks after waking up
    __HAL_RCC_GPIOB_CLK_ENABLE();
    __HAL_RCC_GPIOC_CLK_ENABLE();
    __HAL_RCC_GPIOD_CLK_ENABLE();
    __HAL_RCC_GPIOE_CLK_ENABLE();
    __HAL_RCC_GPIOF_CLK_ENABLE();
    __HAL_RCC_GPIOG_CLK_ENABLE();
    __HAL_RCC_GPIOH_CLK_ENABLE();
}

#define configUSE_TICKLESS_IDLE    1                       

// FreeRTOSConfig.h
extern void PreSleepProcessing(uint32_t ulExpectedIdleTime);
extern void PostSleepProcessing(uint32_t ulExpectedIdleTime);
#define configPRE_SLEEP_PROCESSING  PreSleepProcessing	 
#define configPOST_SLEEP_PROCESSING  PostSleepProcessing	 

// main.c
void PreSleepProcessing(uint32_t ulExpectedIdleTime)
{
    (void)ulExpectedIdleTime;

    // Disable GPIO clocks that are not needed during sleep
    __HAL_RCC_GPIOB_CLK_DISABLE();
    __HAL_RCC_GPIOC_CLK_DISABLE();
    __HAL_RCC_GPIOD_CLK_DISABLE();
    __HAL_RCC_GPIOE_CLK_DISABLE();
    __HAL_RCC_GPIOF_CLK_DISABLE();
    __HAL_RCC_GPIOG_CLK_DISABLE();
    __HAL_RCC_GPIOH_CLK_DISABLE();
}

void PostSleepProcessing(uint32_t ulExpectedIdleTime)
{
    (void)ulExpectedIdleTime;

    // Re-enable GPIO clocks after waking up
    __HAL_RCC_GPIOB_CLK_ENABLE();
    __HAL_RCC_GPIOC_CLK_ENABLE();
    __HAL_RCC_GPIOD_CLK_ENABLE();
    __HAL_RCC_GPIOE_CLK_ENABLE();
    __HAL_RCC_GPIOF_CLK_ENABLE();
    __HAL_RCC_GPIOG_CLK_ENABLE();
    __HAL_RCC_GPIOH_CLK_ENABLE();
}

Task notifications enable direct communication between tasks without requiring separate kernel objects such as queues, semaphores, or event groups.

• Pending: When a task receives a notification, its notification state is set to pending.
• Not pending: When the task processes the notification, its notification state is cleared to not pending.

Advantages: Faster than using queues, semaphore and event groups to perform an equivalent operation. Requires significantly less RAM than using a queue, semaphore or an event group.

Limitations: Unlike queues, semaphores and event groups, task notifications cannot be used to send events or data from a task to an ISR, although they can be used to send events or data from an ISR to a task. Unlike queues, semaphores and event groups, task notifications cannot be sent to multiple tasks.

// FreeRTOSConfig.h
#define configUSE_TASK_NOTIFICATIONS   1 

// FreeRTOSConfig.h
#define configUSE_TASK_NOTIFICATIONS   1 

xTaskNotify()

xTaskNotify() sends a task notification to another task and updates the receiving task’s notification value according to the selected eNotifyAction. It can set specific bits, increment the value, overwrite the existing value, update it only when no unread notification is pending, or generate a notification event without modifying the value. If the receiving task is blocked waiting for the notification, it is moved to the Ready state. The function normally returns pdPASS; however, when eSetValueWithoutOverwrite is used, it returns pdFAIL if a previous notification is still pending.

BaseType_t xTaskNotify(TaskHandle_t xTaskToNotify,
                       uint32_t ulValue,
                       eNotifyAction eAction)
                       
// ---------------------- Example ---------------------- 

TaskHandle_t ReceiverTask_Handler;
uint8_t keyState;
BaseType_t err;
err = xTaskNotify((TaskHandle_t	) ReceiverTask_Handler,
							    (uint32_t		  ) keyState,
							    (eNotifyAction) eSetValueWithOverwrite);

BaseType_t xTaskNotify(TaskHandle_t xTaskToNotify,
                       uint32_t ulValue,
                       eNotifyAction eAction)
                       
// ---------------------- Example ---------------------- 

TaskHandle_t ReceiverTask_Handler;
uint8_t keyState;
BaseType_t err;
err = xTaskNotify((TaskHandle_t	) ReceiverTask_Handler,
							    (uint32_t		  ) keyState,
							    (eNotifyAction) eSetValueWithOverwrite);

xTaskNotifyFromISR()

xTaskNotifyFromISR() is the interrupt-safe version of xTaskNotify(). It supports the same notification actions and includes the pxHigherPriorityTaskWoken parameter, which is set to pdTRUE if the notification unblocks a task with a higher priority than the currently running task. This variable must be initialized to pdFALSE before the function is called. If it is set to pdTRUE, portYIELD_FROM_ISR() should be called before exiting the ISR to request an immediate context switch.

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

TaskHandle_t EventGroupTask_Handler;
#define EVENTBIT_0	 (1 << 0)

BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xTaskNotifyFromISR((TaskHandle_t ) EventGroupTask_Handler,
						       (uint32_t	   ) EVENTBIT_0,
						       (eNotifyAction) eSetBits,
						       (BaseType_t*	 ) &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

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

TaskHandle_t EventGroupTask_Handler;
#define EVENTBIT_0	 (1 << 0)

BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xTaskNotifyFromISR((TaskHandle_t ) EventGroupTask_Handler,
						       (uint32_t	   ) EVENTBIT_0,
						       (eNotifyAction) eSetBits,
						       (BaseType_t*	 ) &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

xTaskNotifyGive()

xTaskNotifyGive() increments the target task’s notification value by one and marks the notification as pending. It is equivalent to calling xTaskNotify() with the eIncrement action and is typically paired with ulTaskNotifyTake(). Together, these functions provide a lightweight alternative to a binary or counting semaphore when an event needs to be delivered to a single specific task. xTaskNotifyGive() must be called from task context; use vTaskNotifyGiveFromISR() when sending the notification from an ISR.

BaseType_t xTaskNotifyGive(TaskHandle_t xTaskToNotify)

// ---------------------- Example ---------------------- 

TaskHandle_t SemapGiveTask_Handler;
xTaskNotifyGive(SemapTakeTask_Handler);
printf("TaskNotifyGive!\r\n");

BaseType_t xTaskNotifyGive(TaskHandle_t xTaskToNotify)

// ---------------------- Example ---------------------- 

TaskHandle_t SemapGiveTask_Handler;
xTaskNotifyGive(SemapTakeTask_Handler);
printf("TaskNotifyGive!\r\n");

vTaskNotifyGiveFromISR()

vTaskNotifyGiveFromISR() safely increments a task’s notification value from an interrupt service routine and marks the notification as pending. It is commonly used to unblock a task responsible for deferred interrupt processing, such as handling received data or processing a completed DMA transfer. The pxHigherPriorityTaskWoken parameter indicates whether the notification unblocked a task with a higher priority than the interrupted task. If it is set to pdTRUE, portYIELD_FROM_ISR() should be called before exiting the ISR to request an immediate context switch.

void vTaskNotifyGiveFromISR(TaskHandle_t xTaskHandle, 
                            BaseType_t * pxHigherPriorityTaskWoken)
                            
// ---------------------- Example ----------------------

TaskHandle_t DataProcess_Handler;
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
vTaskNotifyGiveFromISR(DataProcess_Handler, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

void vTaskNotifyGiveFromISR(TaskHandle_t xTaskHandle, 
                            BaseType_t * pxHigherPriorityTaskWoken)
                            
// ---------------------- Example ----------------------

TaskHandle_t DataProcess_Handler;
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
vTaskNotifyGiveFromISR(DataProcess_Handler, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

xTaskNotifyAndQuery()

xTaskNotifyAndQuery() performs the same notification and value-update operation as xTaskNotify(), while also returning the target task’s previous notification value through pulPreviousNotifyValue. The previous value is captured atomically before the selected eNotifyAction modifies it. This is useful when the sending task needs to inspect and update the notification value in a single operation, such as checking previously set event bits or reading a counter before incrementing or overwriting it. The function must be called from task context.

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

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

xTaskNotifyAndQueryFromISR()

xTaskNotifyAndQueryFromISR() is the interrupt-safe version of xTaskNotifyAndQuery(). It sends a notification to the target task, updates its notification value according to the selected eNotifyAction, and returns the value that existed before the update through pulPreviousNotifyValue. The pxHigherPriorityTaskWoken parameter indicates whether the notification unblocked a higher-priority task, allowing the ISR to request an immediate context switch with portYIELD_FROM_ISR(). The function normally returns pdPASS; however, when eSetValueWithoutOverwrite is used, it returns pdFAIL if an unread notification is already pending.

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

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

ulTaskNotifyTake()

ulTaskNotifyTake() allows the calling task to block until its notification value becomes nonzero or the specified timeout expires. When a notification is received, setting xClearCountOnExit to pdTRUE clears the notification value to zero, providing binary-semaphore behavior. Setting it to pdFALSE decrements the value by one, providing counting-semaphore behavior. The function returns the notification value before it is cleared or decremented, or 0 if the wait period expires without a notification.

uint32_t ulTaskNotifyTake(BaseType_t xClearCountOnExit, 
                          TickType_t xTicksToWait)
                          
// ---------------------- Example ----------------------

uint32_t NotifyValue;
NotifyValue = ulTaskNotifyTake(pdTRUE, portMAX_DELAY);

uint32_t ulTaskNotifyTake(BaseType_t xClearCountOnExit, 
                          TickType_t xTicksToWait)
                          
// ---------------------- Example ----------------------

uint32_t NotifyValue;
NotifyValue = ulTaskNotifyTake(pdTRUE, portMAX_DELAY);

xTaskNotifyWait()

xTaskNotifyWait() blocks the calling task until a notification becomes pending or the specified timeout expires. It can clear selected bits in the task’s notification value before waiting and clear additional bits after the received value has been copied to pulNotificationValue. This makes it well suited for receiving event flags or a 32-bit mailbox value sent through xTaskNotify(). The function returns pdTRUE when a notification is received and pdFALSE if the wait period expires without one.

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

uint32_t NotifyValue;
BaseType_t err;
err = xTaskNotifyWait((uint32_t	 ) 0x00,		       // Clear no bits before waiting
							        (uint32_t	 ) ULONG_MAX,	     // Clear all bits after receiving
							        (uint32_t* ) &NotifyValue,   // Store the received notification value  
							        (TickType_t) portMAX_DELAY); // Wait indefinitely                           

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

uint32_t NotifyValue;
BaseType_t err;
err = xTaskNotifyWait((uint32_t	 ) 0x00,		       // Clear no bits before waiting
							        (uint32_t	 ) ULONG_MAX,	     // Clear all bits after receiving
							        (uint32_t* ) &NotifyValue,   // Store the received notification value  
							        (TickType_t) portMAX_DELAY); // Wait indefinitely                           

FreeRTOS (Scheduler): FreeRTOS provides core RTOS primitives, tasks, semaphores, queues, and software timers. It leaves driver implementation, networking, and hardware configuration up to you or your target MCU’s vendor HAL.

Zephyr (Platform): Zephyr takes a batteries-included approach. It includes unified driver models, a shell interface, power management, filesystems, and security modules built directly into the tree.

Configuration & Developer Workflow

FreeRTOS: Configuration is managed through a single FreeRTOSConfig.h file. You can easily integrate it into almost any vendor IDE (Keil, IAR, STM32CubeIDE) or custom Makefile/CMake environment.

Zephyr: Mimics the Linux kernel build process. Hardware is described using Devicetree (.dts), while software components are toggled using Kconfig (prj.conf). The meta-tool west manages repositories and builds, offering high cross-platform portability at the cost of a steeper initial learning curve.

Memory Protection & Performance

FreeRTOS: Has lower context-switching and interrupt overhead because of its lean execution model. Tasks generally execute in a single shared memory space.

Zephyr: Emphasizes safety and isolation. On supported hardware, it separates kernel mode from user mode and enforces hardware stack protection and memory partitions using the Memory Protection Unit (MPU).

FreeRTOS API vs. Zephyr API

Event Groups

Event groups allow a task to wait in the blocked state for a combination of one of more events to occur. Event groups unblock all the tasks that were waiting for the same event, or combination of events, when the event occurs. Event groups reduce RAM usage by allowing us to replace multiple binary semaphores with a single event group.

• Synchronizing tasks
• Broadcasting events to multiple tasks

Event Bits

When configUSE_16_BIT_TICKS is set to 0, TickType_t is a 32-bit data type, so EventBits_t is also a 32-bit data type. A variable of type EventBits_t can store 24 event bits, while the upper 8 bits are reserved for internal use. Event bit 0 is stored in bit 0 of the variable, event bit 1 is stored in bit 1, and so on. For STM32 devices, an event group can therefore contain up to 24 usable event bits.

• An event group is a set of event flags
• An event flag is a boolean value (1 or 0) used to indicate whether an event has occurred or not
• An event flag is stored in a single bit and the state of all event flags can be stored in a single variable

xEventGroupCreate()

xEventGroupCreate() dynamically allocates the required memory and creates a new event group. It returns an EventGroupHandle_t for use with other event-group functions, or NULL if memory allocation fails. This function is available only when configSUPPORT_DYNAMIC_ALLOCATION is enabled. When the event group is no longer needed, call vEventGroupDelete() to free the allocated memory.

EventGroupHandle_t xEventGroupCreate(void)

// ---------------------- Example ----------------------

EventGroupHandle_t xEventGroupHandler;
xEventGroupHandler = xEventGroupCreate();

EventGroupHandle_t xEventGroupCreate(void)

// ---------------------- Example ----------------------

EventGroupHandle_t xEventGroupHandler;
xEventGroupHandler = xEventGroupCreate();

xEventGroupCreateStatic()

xEventGroupCreateStatic() creates an event group using memory supplied by the application rather than allocating memory from the FreeRTOS heap. The application must provide a StaticEventGroup_t variable that remains valid for the entire lifetime of the event group. This function is useful in systems that require deterministic memory usage or do not permit dynamic allocation, and it is available only when configSUPPORT_STATIC_ALLOCATION is enabled.

EventGroupHandle_t xEventGroupCreateStatic(StaticEventGroup_t *pxEventGroupBuffer)

EventGroupHandle_t xEventGroupCreateStatic(StaticEventGroup_t *pxEventGroupBuffer)

xEventGroupClearBits()

xEventGroupClearBits() clears one or more specified bits in an event group from task context. The bits are selected using a bit mask: each bit set to 1 in the mask is cleared, while all other bits remain unchanged. The function returns the event-group value before the bits were cleared, allowing the task to inspect the previous event state. It must not be called from an interrupt service routine.

EventBits_t xEventGroupClearBits(EventGroupHandle_t xEventGroup, 
                                 const EventBits_t uxBitsToClear)

EventBits_t xEventGroupClearBits(EventGroupHandle_t xEventGroup, 
                                 const EventBits_t uxBitsToClear)

xEventGroupClearBitsFromISR()

xEventGroupClearBitsFromISR() requests that one or more specified event bits be cleared from interrupt context. Because clearing event bits may unblock multiple waiting tasks, the operation is deferred to the FreeRTOS timer daemon task rather than performed directly within the ISR. The function returns pdPASS if the request is successfully posted to the timer command queue, or pdFAIL if the queue is full.

BaseType_t xEventGroupClearBitsFromISR(EventGroupHandle_t xEventGroup, 
                                       const EventBits_t uxBitsToSet)

BaseType_t xEventGroupClearBitsFromISR(EventGroupHandle_t xEventGroup, 
                                       const EventBits_t uxBitsToSet)

xEventGroupSetBits()

xEventGroupSetBits() sets one or more specified bits in an event group from task context. Tasks waiting for those bits are then evaluated and may be moved from the Blocked state to the Ready state. Multiple bits can be set simultaneously by combining them with the bitwise OR operator. The function returns the event-group value after the bits have been set and any automatically cleared bits have been processed.

EventBits_t xEventGroupSetBits(EventGroupHandle_t xEventGroup, 
                               const EventBits_t uxBitsToSet)

// ---------------------- Example ---------------------- 

#define EVENTBIT_0	 (1 << 0)
#define EVENTBIT_1	 (1 << 1)
#define EVENTBIT_2	 (1 << 2)
#define EVENTBIT_ALL (EVENTBIT_0 | EVENTBIT_1 | EVENTBIT_2)
                              
xEventGroupSetBits(xEventGroupHandler, EVENTBIT_1);
xEventGroupSetBits(xEventGroupHandler, EVENTBIT_2);                               

EventBits_t xEventGroupSetBits(EventGroupHandle_t xEventGroup, 
                               const EventBits_t uxBitsToSet)

// ---------------------- Example ---------------------- 

#define EVENTBIT_0	 (1 << 0)
#define EVENTBIT_1	 (1 << 1)
#define EVENTBIT_2	 (1 << 2)
#define EVENTBIT_ALL (EVENTBIT_0 | EVENTBIT_1 | EVENTBIT_2)
                              
xEventGroupSetBits(xEventGroupHandler, EVENTBIT_1);
xEventGroupSetBits(xEventGroupHandler, EVENTBIT_2);                               

xEventGroupSetBitsFromISR()

xEventGroupSetBitsFromISR() requests that one or more event bits be set from an interrupt service routine. Because setting event bits may unblock multiple tasks and is not a constant-time operation, the request is deferred to the FreeRTOS timer daemon task. The xHigherPriorityTaskWoken parameter indicates whether processing the request may make a higher-priority task ready to run. The function returns pdPASS if the request is successfully posted to the timer command queue, or pdFAIL if the queue is full.

BaseType_t xEventGroupSetBitsFromISR(EventGroupHandle_t xEventGroup, 
                                     const EventBits_t uxBitsToSet, 
                                     BaseType_t * pxHigherPriorityTaskWoken)
                                     
// ---------------------- Example ----------------------

BaseType_t YieldRequired = pdFALSE;
BaseType_t xHigherPriorityTaskWoken;

YieldRequired = xEventGroupSetBitsFromISR(xEventGroupHandler,
    											                EVENTBIT_0,
												                  &xHigherPriorityTaskWoken);	
												                  
if(YieldRequired != pdFAIL) {
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}                                      

BaseType_t xEventGroupSetBitsFromISR(EventGroupHandle_t xEventGroup, 
                                     const EventBits_t uxBitsToSet, 
                                     BaseType_t * pxHigherPriorityTaskWoken)
                                     
// ---------------------- Example ----------------------

BaseType_t YieldRequired = pdFALSE;
BaseType_t xHigherPriorityTaskWoken;

YieldRequired = xEventGroupSetBitsFromISR(xEventGroupHandler,
    											                EVENTBIT_0,
												                  &xHigherPriorityTaskWoken);	
												                  
if(YieldRequired != pdFAIL) {
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}                                      

xEventGroupGetBits()

xEventGroupGetBits() reads and returns the current value of an event group from task context without modifying any bits. The returned EventBits_t value can be tested with bit masks to determine which events are currently set. Because another task or interrupt may change the event group immediately afterward, the returned value should be treated as a snapshot of its state at the time of the call.

EventBits_t xEventGroupGetBits(EventGroupHandle_t xEventGroup)

// ---------------------- Example ----------------------

EventBits_t newValue;
newValue = xEventGroupGetBits(xEventGroupHandler);

EventBits_t xEventGroupGetBits(EventGroupHandle_t xEventGroup)

// ---------------------- Example ----------------------

EventBits_t newValue;
newValue = xEventGroupGetBits(xEventGroupHandler);

xEventGroupGetBitsFromISR()

xEventGroupGetBitsFromISR() reads and returns the current value of an event group from interrupt context without modifying any bits. It provides an ISR-safe way to check which event conditions are currently set. Like xEventGroupGetBits(), the returned value is only a snapshot of the event group at the time of the call and may change immediately afterward.

EventBits_t xEventGroupGetBitsFromISR(EventGroupHandle_t xEventGroup)

EventBits_t xEventGroupGetBitsFromISR(EventGroupHandle_t xEventGroup)

xEventGroupWaitBits()

xEventGroupWaitBits() allows a task to wait for one or more specified event bits. The task can be configured to unblock when either any requested bit is set or all requested bits are set. It can also automatically clear the matched bits before returning and wait indefinitely or for a specified timeout. The function returns the event-group value that caused the task to unblock, or the value present when the timeout expired.

EventBits_t xEventGroupWaitBits(EventGroupHandle_t xEventGroup,
                                const EventBits_t uxBitsToWaitFor,
                                const BaseType_t xClearOnExit,
                                const BaseType_t xWaitForAllBits,
                                const TickType_t xTicksToWait)
                                
// ---------------------- Example ----------------------

EventBits_t EventValue;

// This code blocks the current FreeRTOS task until all event bits
// specified by EVENTBIT_ALL are set
EventValue = xEventGroupWaitBits((EventGroupHandle_t) xEventGroupHandler,
						     				         (EventBits_t		    ) EVENTBIT_ALL,
										             (BaseType_t		    ) pdTRUE,
										             (BaseType_t		    ) pdTRUE,
								                 (TickType_t		    ) portMAX_DELAY);   

// This call blocks the current task until any bit defined in EVENTBIT_ALL becomes set, 
// then clears the matched event bits and stores the previous event-group value in EventValue
EventValue = xEventGroupWaitBits((EventGroupHandle_t) xEventGroupHandler, // Event group to monitor
						     				         (EventBits_t		    ) EVENTBIT_ALL,       // Bit mask to wait for
										             (BaseType_t		    ) pdTRUE,             // Clear matched bits before returning
										             (BaseType_t		    ) pdFALSE,            // Wait for ANY bit, not all bits
								                 (TickType_t		    ) portMAX_DELAY);     // Wait indefinitely     								                                              

EventBits_t xEventGroupWaitBits(EventGroupHandle_t xEventGroup,
                                const EventBits_t uxBitsToWaitFor,
                                const BaseType_t xClearOnExit,
                                const BaseType_t xWaitForAllBits,
                                const TickType_t xTicksToWait)
                                
// ---------------------- Example ----------------------

EventBits_t EventValue;

// This code blocks the current FreeRTOS task until all event bits
// specified by EVENTBIT_ALL are set
EventValue = xEventGroupWaitBits((EventGroupHandle_t) xEventGroupHandler,
						     				         (EventBits_t		    ) EVENTBIT_ALL,
										             (BaseType_t		    ) pdTRUE,
										             (BaseType_t		    ) pdTRUE,
								                 (TickType_t		    ) portMAX_DELAY);   

// This call blocks the current task until any bit defined in EVENTBIT_ALL becomes set, 
// then clears the matched event bits and stores the previous event-group value in EventValue
EventValue = xEventGroupWaitBits((EventGroupHandle_t) xEventGroupHandler, // Event group to monitor
						     				         (EventBits_t		    ) EVENTBIT_ALL,       // Bit mask to wait for
										             (BaseType_t		    ) pdTRUE,             // Clear matched bits before returning
										             (BaseType_t		    ) pdFALSE,            // Wait for ANY bit, not all bits
								                 (TickType_t		    ) portMAX_DELAY);     // Wait indefinitely     								                                              

xEventGroupSync()

xEventGroupSync() synchronizes multiple tasks at a common execution point. It atomically sets the event bits specified by uxBitsToSet, then blocks the calling task until all bits in uxBitsToWaitFor are set or the timeout expires. The function returns the event-group value that caused the task to unblock, allowing the task to determine whether synchronization was completed successfully.

EventBits_t xEventGroupSync(EventGroupHandle_t xEventGroup, 
                            const EventBits_t uxBitsToSet, 
                            const EventBits_t uxBitsToWaitFor, 
                            TickType_t xTicksToWait)
                            
// ---------------------- Example ----------------------

#define TASK1_BIT (1UL << 0UL)
#define TASK2_BIT (1UL << 1UL)
#define TASK3_BIT (1UL << 2UL)

EventGroupHandle_t xEventGroup;
EventBits_t uxAllSyncBits = (TASK1_BIT | TASK2_BIT | TASK3_BIT);

xEventGroup = xEventGroupCreate();

void vTask1Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK1_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
		}
	}
}

void vTask2Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK2_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
		}
	}
}

void vTask3Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK3_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
			printf("All tasks set \r\n");
			vTaskDelay(_200ms);
		}
	}
}                            

EventBits_t xEventGroupSync(EventGroupHandle_t xEventGroup, 
                            const EventBits_t uxBitsToSet, 
                            const EventBits_t uxBitsToWaitFor, 
                            TickType_t xTicksToWait)
                            
// ---------------------- Example ----------------------

#define TASK1_BIT (1UL << 0UL)
#define TASK2_BIT (1UL << 1UL)
#define TASK3_BIT (1UL << 2UL)

EventGroupHandle_t xEventGroup;
EventBits_t uxAllSyncBits = (TASK1_BIT | TASK2_BIT | TASK3_BIT);

xEventGroup = xEventGroupCreate();

void vTask1Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK1_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
		}
	}
}

void vTask2Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK2_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
		}
	}
}

void vTask3Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK3_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
			printf("All tasks set \r\n");
			vTaskDelay(_200ms);
		}
	}
}                            

One-shot timer: once started, it will execute its callback function once only. It can be restarted manually, but will not restart itself

Auto-reload timer: once started, it will re-start itself each time it expires, resulting in periodic execution of its callback function

#define configUSE_TIMERS              1 
#define configTIMER_TASK_PRIORITY     (configMAX_PRIORITIES-1) 
#define configTIMER_QUEUE_LENGTH      5
#define configTIMER_TASK_STACK_DEPTH  (configMINIMAL_STACK_SIZE*2)

#define configUSE_TIMERS              1 
#define configTIMER_TASK_PRIORITY     (configMAX_PRIORITIES-1) 
#define configTIMER_QUEUE_LENGTH      5
#define configTIMER_TASK_STACK_DEPTH  (configMINIMAL_STACK_SIZE*2)

xTimerCreate()

Creates a FreeRTOS software timer using dynamically allocated memory from the FreeRTOS heap. It defines the timer name, period, one-shot or auto-reload mode, timer ID, and callback function. The newly created timer remains dormant until it is started.

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

TimerHandle_t OneShotTimer_Handle;
TimerHandle_t AutoReloadTimer_Handle;

void OneShotTimerCallback(TimerHandle_t xTimer);    
void AutoReloadTimerCallback(TimerHandle_t xTimer); 

OneShotTimer_Handle = xTimerCreate("OneShotTimer",
			                     	       mainONE_SHOT_TIMER_PERIOD,
								                   pdFALSE,
								                   0,
								                   OneShotTimerCallback);
								                   
AutoReloadTimer_Handle = xTimerCreate("AutoReloadTimer",
									                    mainAUTO_RELOAD_TIMER_PERIOD,
									                    pdTRUE,
									                    0,
									                    AutoReloadTimerCallback);

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

TimerHandle_t OneShotTimer_Handle;
TimerHandle_t AutoReloadTimer_Handle;

void OneShotTimerCallback(TimerHandle_t xTimer);    
void AutoReloadTimerCallback(TimerHandle_t xTimer); 

OneShotTimer_Handle = xTimerCreate("OneShotTimer",
			                     	       mainONE_SHOT_TIMER_PERIOD,
								                   pdFALSE,
								                   0,
								                   OneShotTimerCallback);
								                   
AutoReloadTimer_Handle = xTimerCreate("AutoReloadTimer",
									                    mainAUTO_RELOAD_TIMER_PERIOD,
									                    pdTRUE,
									                    0,
									                    AutoReloadTimerCallback);

xTimerCreateStatic()

Creates a software timer using a StaticTimer_t memory buffer supplied by the application. Unlike xTimerCreate(), it does not allocate memory from the FreeRTOS heap, making memory usage predictable and suitable for systems that avoid dynamic allocation.

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

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

xTimerStart()

Starts a previously created software timer from normal task context. After the specified timer period expires, the timer’s callback function executes. For an auto-reload timer, this repeats periodically; for a one-shot timer, it occurs only once.

BaseType_t xTimerStart(TimerHandle_t xTimer, 
                       TickType_t xTicksToWait)
                       
// ---------------------- Example ----------------------

TimerHandle_t OneShotTimer_Handle;
TimerHandle_t AutoReloadTimer_Handle;

xTimerStart(OneShotTimer_Handle, 0);
xTimerStart(AutoReloadTimer_Handle, 0);

BaseType_t xTimerStart(TimerHandle_t xTimer, 
                       TickType_t xTicksToWait)
                       
// ---------------------- Example ----------------------

TimerHandle_t OneShotTimer_Handle;
TimerHandle_t AutoReloadTimer_Handle;

xTimerStart(OneShotTimer_Handle, 0);
xTimerStart(AutoReloadTimer_Handle, 0);

xTimerStartFromISR()

Starts or restarts a software timer from an interrupt service routine. It sends a start command to the timer command queue and uses pxHigherPriorityTaskWoken to indicate whether a context switch should occur when the ISR exits.

BaseType_t xTimerStartFromISR(TimerHandle_t xTimer,
                              BaseType_t * pxHigherPriorityTaskWoken)

BaseType_t xTimerStartFromISR(TimerHandle_t xTimer,
                              BaseType_t * pxHigherPriorityTaskWoken)

xTimerStop()

Stops an active software timer from normal task context. Once stopped, the timer will not expire or execute its callback function, but the timer object remains valid and can be started again later.

BaseType_t xTimerStop(TimerHandle_t xTimer, 
                      TickType_t xTicksToWait)

// ---------------------- Example ----------------------

TimerHandle_t AutoReloadTimer_Handle;
xTimerStop(AutoReloadTimer_Handle, 0);

BaseType_t xTimerStop(TimerHandle_t xTimer, 
                      TickType_t xTicksToWait)

// ---------------------- Example ----------------------

TimerHandle_t AutoReloadTimer_Handle;
xTimerStop(AutoReloadTimer_Handle, 0);

xTimerStopFromISR()

Stops an active software timer from an interrupt service routine. It is the interrupt-safe version of xTimerStop() and can request a context switch through the pxHigherPriorityTaskWoken parameter.

BaseType_t xTimerStopFromISR(TimerHandle_t xTimer,
                             BaseType_t * pxHigherPriorityTaskWoken)

BaseType_t xTimerStopFromISR(TimerHandle_t xTimer,
                             BaseType_t * pxHigherPriorityTaskWoken)

xTimerReset()

Resets a timer’s expiration time from normal task context. If the timer is active, it restarts the full timer period from the moment the reset is requested; if it is dormant, the reset operation also starts it.

BaseType_t xTimerReset(TimerHandle_t xTimer, 
                       TickType_t xTicksToWait)

BaseType_t xTimerReset(TimerHandle_t xTimer, 
                       TickType_t xTicksToWait)

xTimerResetFromISR()

Resets or starts a software timer from an interrupt service routine. It recalculates the expiration time from the moment it is called and uses pxHigherPriorityTaskWoken to indicate whether an ISR-level context switch is required.

BaseType_t xTimerResetFromISR(TimerHandle_t xTimer,
                              BaseType_t * pxHigherPriorityTaskWoken)

BaseType_t xTimerResetFromISR(TimerHandle_t xTimer,
                              BaseType_t * pxHigherPriorityTaskWoken)

External Memory Interface (EMIF)

This EMIF memory controller is compliant with the JESD21-C SDR SDRAM memories utilizing a 32-bit/16-bit data bus. The purpose of this EMIF is to provide a means for the CPU to connect to a variety of external devices including:

• Single data rate (SDR) SDRAM
• Asynchronous devices including NOR Flash and SRAM

A common use for the EMIF is to interface with both a flash device and an SDRAM device simultaneously.

Interfacing to SDRAM

The EMIF supports a glueless interface to SDRAM devices with the following characteristics:

• Pre-charge bit is A[10]
• The number of column address bits is 8, 9, 10, or 11
• The number of row address bits is 13, 14, 15, or 16
• The number of internal banks is 1, 2, or 4

Interfacing to Asynchronous Memory

The EMIF easily interfaces to a variety of asynchronous devices including NOR Flash and SRAM. It can be operated in two major modes

• Normal Mode
• Select Strobe Mode

EMIF Performance

Reference

[1] TMS320F2837xD Microcontroller Workshop

(1) The task calls xSemaphoreTake() to acquire the semaphore. Since the semaphore is unavailable, Task is placed into the Blocked state until the semaphore becomes available.

(2) An interrupt occurs, and the interrupt service routine (ISR) calls xSemaphoreGiveFromISR() to give the semaphore. As a result, the semaphore becomes available.

(3) Because the semaphore is now available, Task successfully acquires it using xSemaphoreTake(). The task transitions from the Blocked state to the Running (or Ready, depending on the scheduler) state and begins executing the associated processing.

(4) Since a task function typically runs in an infinite loop, after completing the required processing it calls xSemaphoreTake() again to wait for the semaphore. Because the semaphore became unavailable after Step 3, the task enters the Blocked state once again, just as it did in Step 1. It remains blocked until another interrupt occurs and the interrupt service routine (ISR) calls xSemaphoreGiveFromISR() to give the semaphore.

xSemaphoreCreateBinary()

Creates a binary semaphore using memory dynamically allocated from the FreeRTOS heap. A binary semaphore has only two states: available and unavailable, internally represented by a count of 1 or 0. The semaphore is created in the unavailable/empty state, so xSemaphoreGive() must normally be called before the first successful xSemaphoreTake(). It is commonly used for task-to-task or interrupt-to-task synchronization. The function returns a semaphore handle on success or NULL if memory allocation fails.

SemaphoreHandle_t xSemaphoreCreateBinary(void)

// ---------------------- Example ----------------------

SemaphoreHandle_t xBinarySemaphore;
xBinarySemaphore = xSemaphoreCreateBinary();
xSemaphoreGive(xBinarySemaphore);

xSemaphoreTake(xBinarySemaphore, portMAX_DELAY);
xSemaphoreGive(xBinarySemaphore);

SemaphoreHandle_t xSemaphoreCreateBinary(void)

// ---------------------- Example ----------------------

SemaphoreHandle_t xBinarySemaphore;
xBinarySemaphore = xSemaphoreCreateBinary();
xSemaphoreGive(xBinarySemaphore);

xSemaphoreTake(xBinarySemaphore, portMAX_DELAY);
xSemaphoreGive(xBinarySemaphore);

xSemaphoreCreateBinaryStatic()

Creates a binary semaphore without using the FreeRTOS heap. The application provides a StaticSemaphore_t object that stores the semaphore’s internal control information. This buffer must remain valid for the entire lifetime of the semaphore, so it should normally be global or declared with static. Like the dynamically created version, the semaphore starts empty and must be given before it can be taken. Static creation is useful in safety-critical or memory-constrained systems where dynamic allocation is undesirable.

SemaphoreHandle_t xSemaphoreCreateBinaryStatic(StaticSemaphore_t *pxSemaphoreBuffer)

SemaphoreHandle_t xSemaphoreCreateBinaryStatic(StaticSemaphore_t *pxSemaphoreBuffer)

xSemaphoreCreateCounting()

Creates a dynamically allocated counting semaphore. uxMaxCount specifies the largest value the semaphore count can reach, while uxInitialCount specifies its starting value and must not exceed the maximum. Every successful xSemaphoreGive() increases the count, and every successful xSemaphoreTake() decreases it. Counting semaphores are commonly used either to count pending events or to manage a pool of identical resources. The function returns a valid handle on success or NULL if allocation fails.

SemaphoreHandle_t xSemaphoreCreateCounting(UBaseType_t uxMaxCount, 
                                           UBaseType_t uxInitialCount)
                                           
// ---------------------- Example ----------------------

SemaphoreHandle_t xCountSemaphore; 
xCountSemaphore = xSemaphoreCreateCounting(255, 0);

SemaphoreHandle_t xSemaphoreCreateCounting(UBaseType_t uxMaxCount, 
                                           UBaseType_t uxInitialCount)
                                           
// ---------------------- Example ----------------------

SemaphoreHandle_t xCountSemaphore; 
xCountSemaphore = xSemaphoreCreateCounting(255, 0);

xSemaphoreCreateCountingStatic()

Creates a counting semaphore using memory supplied by the application. It behaves like xSemaphoreCreateCounting(), but no FreeRTOS heap allocation is performed. The caller provides a persistent StaticSemaphore_t buffer that stores the semaphore’s control structure. The initial count must be less than or equal to the maximum count. This version is useful when all RTOS objects must have deterministic, statically allocated memory.

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

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

xSemaphoreCreateMutex()

Creates a dynamically allocated mutex for protecting a shared resource, such as a UART, SPI peripheral, file system, or shared data structure. Unlike a newly created binary semaphore, a newly created mutex starts in the available state and can immediately be taken. A mutex records which task owns it and provides priority inheritance to reduce priority-inversion problems. The task that successfully takes the mutex must be the task that gives it back. Mutexes must not be used from interrupt service routines.

SemaphoreHandle_t xSemaphoreCreateMutex(void)

// ---------------------- Example ----------------------

SemaphoreHandle_t xMutexSemaphore;
xMutexSemaphore = xSemaphoreCreateMutex();

SemaphoreHandle_t xSemaphoreCreateMutex(void)

// ---------------------- Example ----------------------

SemaphoreHandle_t xMutexSemaphore;
xMutexSemaphore = xSemaphoreCreateMutex();

xSemaphoreCreateMutexStatic()

Creates a mutex using a user-provided StaticSemaphore_t buffer instead of dynamically allocating memory. It provides the same ownership tracking, mutual-exclusion behavior, and priority inheritance as xSemaphoreCreateMutex(). The buffer must remain allocated for as long as the mutex exists. The mutex is initially available, so no initial xSemaphoreGive() is required. This function is suitable for applications that prohibit heap allocation after startup.

SemaphoreHandle_t xSemaphoreCreateMutexStatic(StaticSemaphore_t *pxMutexBuffer)

SemaphoreHandle_t xSemaphoreCreateMutexStatic(StaticSemaphore_t *pxMutexBuffer)

xSemaphoreGive()

Releases a semaphore from task context. For a binary semaphore, it changes the state from unavailable to available. For a counting semaphore, it increases the current count by one, provided the maximum count has not already been reached. For a mutex, it releases ownership so another waiting task can acquire the protected resource. The function returns pdTRUE when successful and pdFALSE when the semaphore is already full or cannot be released. It must not be called from an interrupt; use xSemaphoreGiveFromISR() instead.

BaseType_t xSemaphoreGive(xSemaphore)

// ---------------------- Example ----------------------

xSemaphoreGive(xBinarySemaphore);

BaseType_t xSemaphoreGive(xSemaphore)

// ---------------------- Example ----------------------

xSemaphoreGive(xBinarySemaphore);

xSemaphoreGiveFromISR()

Releases a binary or counting semaphore from an interrupt service routine. If giving the semaphore unblocks a task whose priority is higher than that of the currently running task, *pxHigherPriorityTaskWoken is set to pdTRUE. The ISR should then request a context switch with the port-specific macro, commonly portYIELD_FROM_ISR(). The variable should normally be initialized to pdFALSE before the call. This function cannot be used with mutexes because mutex ownership and priority inheritance require task context.

BaseType_t xSemaphoreGiveFromISR(SemaphoreHandle_t xSemaphore,
                                 BaseType_t * pxHigherPriorityTaskWoken)
                                 
// ---------------------- Example ----------------------

SemaphoreHandle_t xBinarySemaphore;
xBinarySemaphore = xSemaphoreCreateBinary();

BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xSemaphoreGiveFromISR(BinarySemaphore, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

BaseType_t xSemaphoreGiveFromISR(SemaphoreHandle_t xSemaphore,
                                 BaseType_t * pxHigherPriorityTaskWoken)
                                 
// ---------------------- Example ----------------------

SemaphoreHandle_t xBinarySemaphore;
xBinarySemaphore = xSemaphoreCreateBinary();

BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xSemaphoreGiveFromISR(BinarySemaphore, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

xSemaphoreTake()

Attempts to obtain a binary semaphore, counting semaphore, or standard mutex from task context. If the object is available, the operation succeeds immediately and its count is decreased. If it is unavailable, the calling task can enter the Blocked state for up to xTicksToWait ticks. A value of 0 performs a nonblocking check, while portMAX_DELAY can be used for an indefinite wait when the relevant FreeRTOS configuration permits it. The function returns pdTRUE when the semaphore is obtained and pdFALSE if the waiting time expires.

BaseType_t xSemaphoreTake(SemaphoreHandle_t xSemaphore,
                          TickType_t xBlockTime)

// ---------------------- Example ----------------------

xSemaphoreTake(xBinarySemaphore, portMAX_DELAY);

BaseType_t xSemaphoreTake(SemaphoreHandle_t xSemaphore,
                          TickType_t xBlockTime)

// ---------------------- Example ----------------------

xSemaphoreTake(xBinarySemaphore, portMAX_DELAY);

xSemaphoreTakeFromISR()

Attempts to obtain a binary or counting semaphore from an interrupt service routine. It cannot wait or block, so it succeeds only if the semaphore count is already greater than zero. A successful operation decreases the semaphore count and returns pdTRUE; otherwise, it returns pdFALSE. It must not be used with mutexes or recursive mutexes. In most interrupt-to-task synchronization designs, the ISR gives the semaphore and the task takes it, so this function is used less frequently than xSemaphoreGiveFromISR().

BaseType_t xSemaphoreTakeFromISR(SemaphoreHandle_t xSemaphore,
                                 BaseType_t * pxHigherPriorityTaskWoken)                         

BaseType_t xSemaphoreTakeFromISR(SemaphoreHandle_t xSemaphore,
                                 BaseType_t * pxHigherPriorityTaskWoken)                         

xSemaphoreCreateRecursiveMutex()

Creates a dynamically allocated recursive mutex. A recursive mutex allows its owning task to take the same mutex multiple times without blocking itself. FreeRTOS maintains an internal recursion count that records how many times the owner has successfully taken it. The task must give the mutex exactly the same number of times before another task can acquire it. Recursive mutexes are useful when a protected function calls another function that needs the same lock. They must be used with xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive(), not the standard take and give functions.

SemaphoreHandle_t xSemaphoreCreateRecursiveMutex(void)

SemaphoreHandle_t xSemaphoreCreateRecursiveMutex(void)

xSemaphoreCreateRecursiveMutexStatic()

Creates a recursive mutex using application-provided static memory. Its behavior is identical to the dynamically created recursive mutex, including ownership tracking, priority inheritance, and recursive nesting count. The supplied StaticSemaphore_t buffer must remain valid throughout the mutex’s lifetime. This function avoids heap allocation while still allowing the same task to lock a resource repeatedly. Recursive mutex support must be enabled in FreeRTOSConfig.h.

SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic(StaticSemaphore_t *pxMutexBuffer)

SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic(StaticSemaphore_t *pxMutexBuffer)

xSemaphoreTakeRecursive()

Obtains a mutex created specifically as a recursive mutex. The first successful call assigns ownership to the calling task. Additional calls from the same task succeed immediately and increase the recursive nesting count. Calls from other tasks block for up to xTicksToWait while the mutex remains owned. The function returns pdTRUE when the mutex is obtained and pdFALSE if the waiting time expires. It must not be used with a standard mutex created by xSemaphoreCreateMutex().

#define xSemaphoreTakeRecursive(xMutex, xBlockTime)
  xQueueTakeMutexRecursive(xMutex, xBlockTime)

#define xSemaphoreTakeRecursive(xMutex, xBlockTime)
  xQueueTakeMutexRecursive(xMutex, xBlockTime)

xSemaphoreGiveRecursive()

Releases one level of ownership of a recursive mutex. Each call decreases the mutex’s recursive nesting count by one. The mutex becomes available to other tasks only when the count reaches zero. Therefore, every successful call to xSemaphoreTakeRecursive() must eventually have a matching call to xSemaphoreGiveRecursive(). Only the task that owns the recursive mutex may give it, and the function must not be called from an ISR.

#define xSemaphoreGiveRecursive(xMutex)
  xQueueGiveMutexRecursive(xMutex)

#define xSemaphoreGiveRecursive(xMutex)
  xQueueGiveMutexRecursive(xMutex)

Queue Send & Receive

Queue Definition

typedef struct QueueDefinition 
{
	int8_t *pcHead;					
	int8_t *pcWriteTo;	

	union
	{
		QueuePointers_t xQueue;		
		SemaphoreData_t xSemaphore;
	} u;

	List_t xTasksWaitingToSend;		
	List_t xTasksWaitingToReceive;	

	volatile UBaseType_t uxMessagesWaiting;
	UBaseType_t uxLength;			
	UBaseType_t uxItemSize;			

	volatile int8_t cRxLock;		
	volatile int8_t cTxLock;	

	#if( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && \
	     ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
		uint8_t ucStaticallyAllocated;
	#endif

	#if ( configUSE_QUEUE_SETS == 1 )
		struct QueueDefinition *pxQueueSetContainer;
	#endif

	#if ( configUSE_TRACE_FACILITY == 1 )
		UBaseType_t uxQueueNumber;
		uint8_t ucQueueType;
	#endif

} xQUEUE;

typedef xQUEUE Queue_t;

typedef struct QueueDefinition 
{
	int8_t *pcHead;					
	int8_t *pcWriteTo;	

	union
	{
		QueuePointers_t xQueue;		
		SemaphoreData_t xSemaphore;
	} u;

	List_t xTasksWaitingToSend;		
	List_t xTasksWaitingToReceive;	

	volatile UBaseType_t uxMessagesWaiting;
	UBaseType_t uxLength;			
	UBaseType_t uxItemSize;			

	volatile int8_t cRxLock;		
	volatile int8_t cTxLock;	

	#if( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && \
	     ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
		uint8_t ucStaticallyAllocated;
	#endif

	#if ( configUSE_QUEUE_SETS == 1 )
		struct QueueDefinition *pxQueueSetContainer;
	#endif

	#if ( configUSE_TRACE_FACILITY == 1 )
		UBaseType_t uxQueueNumber;
		uint8_t ucQueueType;
	#endif

} xQUEUE;

typedef xQUEUE Queue_t;

xQueueCreate()

xQueueCreate() creates a queue using dynamically allocated memory from the FreeRTOS heap. It specifies the maximum number of items the queue can hold and the size of each item. The function returns a valid queue handle when creation succeeds or NULL if there is insufficient heap memory.

QueueHandle_t xQueueCreate(UBaseType_t uxQueueLength,
                           UBaseType_t uxItemSize)

// ---------------------- Example ----------------------
                           
#define MESSAGE_Q_NUM  5
QueueHandle_t msgQueue;
msgQueue = xQueueCreate(MESSAGE_Q_NUM, sizeof(uint32_t));                           

QueueHandle_t xQueueCreate(UBaseType_t uxQueueLength,
                           UBaseType_t uxItemSize)

// ---------------------- Example ----------------------
                           
#define MESSAGE_Q_NUM  5
QueueHandle_t msgQueue;
msgQueue = xQueueCreate(MESSAGE_Q_NUM, sizeof(uint32_t));                           

xQueueCreateStatic()

xQueueCreateStatic() creates a queue using memory supplied by the application rather than memory allocated from the FreeRTOS heap. The application provides a storage buffer for the queue items and a StaticQueue_t structure for the queue control data. The function returns a queue handle when creation succeeds or NULL if the parameters are invalid.

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

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

xQueueSend()

xQueueSend() sends an item to the back of a FreeRTOS queue. The item is copied into the queue, and the calling task can optionally wait for available space if the queue is full. The function returns pdPASS when the item is successfully added or errQUEUE_FULL if the operation fails.

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

const TickType_t wait_time = pdMS_TO_TICKS(200);
BaseType_t qStatus = xQueueSend(msgQueue, &valToSend, wait_time);

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

const TickType_t wait_time = pdMS_TO_TICKS(200);
BaseType_t qStatus = xQueueSend(msgQueue, &valToSend, wait_time);

xQueueSendToBack()

xQueueSendToBack() copies an item to the back of a FreeRTOS queue. If the queue is full, the calling task can wait for a specified number of ticks until space becomes available. The function returns pdPASS on success or errQUEUE_FULL if the item cannot be added.

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

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

xQueueSendToFront()

xQueueSendToFront() copies an item to the front of a FreeRTOS queue, allowing it to be received before existing items. If the queue is full, the calling task can wait for a specified number of ticks until space becomes available. It returns pdPASS on success or errQUEUE_FULL if the item cannot be added.

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

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

xQueueOverwrite()

xQueueOverwrite() copies an item into a queue even when the queue is already full, replacing the existing item. It is intended for queues with a length of one, such as those storing the latest sensor value or system state. The function returns pdPASS and must not be called from an interrupt service routine.

BaseType_t xQueueOverwrite(QueueHandle_t xQueue,
                           const void * pvItemToQueue)
                           
// ---------------------- Example ----------------------

#define KEYMSG_Q_NUM  1
QueueHandle_t keyQueue;
keyQueue = xQueueCreate(KEYMSG_Q_NUM, sizeof(uint8_t));

uint8_t keyState = HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0);
BaseType_t qStatus = xQueueOverwrite(keyQueue, &keyState);

BaseType_t xQueueOverwrite(QueueHandle_t xQueue,
                           const void * pvItemToQueue)
                           
// ---------------------- Example ----------------------

#define KEYMSG_Q_NUM  1
QueueHandle_t keyQueue;
keyQueue = xQueueCreate(KEYMSG_Q_NUM, sizeof(uint8_t));

uint8_t keyState = HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0);
BaseType_t qStatus = xQueueOverwrite(keyQueue, &keyState);

xQueueSendFromISR()

xQueueSendFromISR() copies an item to the back of a FreeRTOS queue from within an interrupt service routine. It does not block if the queue is full, and the pxHigherPriorityTaskWoken parameter indicates whether sending the item unblocked a higher-priority task that may require a context switch. It returns pdPASS on success or errQUEUE_FULL if the item cannot be added.

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

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

xQueueSendToBackFromISR()

xQueueSendToBackFromISR() copies an item to the back of a FreeRTOS queue from within an interrupt service routine. It never blocks if the queue is full, and pxHigherPriorityTaskWoken indicates whether a higher-priority task was unblocked and a context switch may be required. The function returns pdPASS on success or errQUEUE_FULL if the item cannot be added.

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

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

xQueueSendToFrontFromISR()

xQueueSendToFrontFromISR() copies an item to the front of a FreeRTOS queue from within an interrupt service routine, allowing it to be received before existing items. It does not block if the queue is full, and pxHigherPriorityTaskWoken indicates whether a higher-priority task was unblocked and a context switch may be required. The function returns pdPASS on success or errQUEUE_FULL if the item cannot be added.

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

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

xQueueOverwriteFromISR()

xQueueOverwriteFromISR() writes an item to a queue from within an interrupt service routine, replacing the existing item if the queue is already full. It is intended for queues with a length of one and never blocks. The pxHigherPriorityTaskWoken parameter indicates whether a higher-priority task was unblocked and a context switch may be required.

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

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

xQueueReceive()

xQueueReceive() removes an item from the front of a FreeRTOS queue and copies it into a user-provided buffer. If the queue is empty, the calling task can wait for a specified number of ticks until an item becomes available. The function returns pdPASS on success or errQUEUE_EMPTY if no item is received.

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

BaseType_t qStatus = xQueueReceive(msgQueue, &valToReceive, 0);              

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

BaseType_t qStatus = xQueueReceive(msgQueue, &valToReceive, 0);              

xQueuePeek()

xQueuePeek() copies an item from the front of a FreeRTOS queue without removing it, allowing the same item to be read again later. If the queue is empty, the calling task can wait for a specified number of ticks until an item becomes available. The function returns pdPASS on success or errQUEUE_EMPTY if no item is available.

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

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

xQueueReceiveFromISR()

xQueueReceiveFromISR() removes an item from the front of a FreeRTOS queue and copies it into a user-provided buffer from within an interrupt service routine. It never blocks if the queue is empty, and pxHigherPriorityTaskWoken indicates whether receiving the item unblocked a higher-priority task that may require a context switch. The function returns pdPASS on success or pdFAIL if the queue is empty.

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

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

xQueuePeekFromISR()

xQueuePeekFromISR() copies an item from the front of a FreeRTOS queue into a user-provided buffer from within an interrupt service routine without removing it from the queue. It never blocks if the queue is empty and returns pdPASS when an item is successfully read or pdFAIL if no item is available.

BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue,
                             void * pvBuffer)

BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue,
                             void * pvBuffer)

uxQueueSpacesAvailable()

uxQueueSpacesAvailable() returns the number of free spaces currently available in a FreeRTOS queue.

UBaseType_t uxQueueSpacesAvailable(const QueueHandle_t xQueue)

UBaseType_t uxQueueSpacesAvailable(const QueueHandle_t xQueue)

uxQueueMessagesWaiting()

uxQueueMessagesWaiting() returns the number of items currently stored in a FreeRTOS queue.

UBaseType_t uxQueueMessagesWaiting(const QueueHandle_t xQueue)

UBaseType_t uxQueueMessagesWaiting(const QueueHandle_t xQueue)

xQueueCreateSet()

xQueueCreateSet() creates a queue set that can contain multiple queues and semaphores, allowing a task to block until any member becomes ready. The length of set should be large enough to hold the total number of items that all member queues and semaphores may contain.

QueueSetHandle_t xQueueCreateSet(const UBaseType_t uxEventQueueLength)

// ---------------------- Example ----------------------

QueueSetHandle_t xQueueSet = NULL;
QueueHandle_t xQueue1 = NULL, xQueue2 = NULL;
xQueue1 = xQueueCreate(1, sizeof(char*));
xQueue2 = xQueueCreate(1, sizeof(char*));
xQueueSet = xQueueCreateSet(1*2);

QueueSetHandle_t xQueueCreateSet(const UBaseType_t uxEventQueueLength)

// ---------------------- Example ----------------------

QueueSetHandle_t xQueueSet = NULL;
QueueHandle_t xQueue1 = NULL, xQueue2 = NULL;
xQueue1 = xQueueCreate(1, sizeof(char*));
xQueue2 = xQueueCreate(1, sizeof(char*));
xQueueSet = xQueueCreateSet(1*2);

xQueueAddToSet()

xQueueAddToSet() adds a queue, semaphore, or mutex to an existing queue set so a task can monitor it together with other set members. The member should be empty when added, and the function returns pdPASS if successful or pdFAIL if it cannot be added.

BaseType_t xQueueAddToSet(QueueSetMemberHandle_t xQueueOrSemaphore,
                          QueueSetHandle_t xQueueSet)

// ---------------------- Example ----------------------

xQueueAddToSet(xQueue1, xQueueSet);
xQueueAddToSet(xQueue2, xQueueSet);                          

BaseType_t xQueueAddToSet(QueueSetMemberHandle_t xQueueOrSemaphore,
                          QueueSetHandle_t xQueueSet)

// ---------------------- Example ----------------------

xQueueAddToSet(xQueue1, xQueueSet);
xQueueAddToSet(xQueue2, xQueueSet);                          

xQueueSelectFromSet()

xQueueSelectFromSet() blocks for a specified time until a queue or semaphore in a queue set becomes ready, then returns the handle of the ready member. A return value of NULL indicates that the timeout expired before any member became available.

QueueSetMemberHandle_t xQueueSelectFromSet(QueueSetHandle_t xQueueSet, 
                                           TickType_t const xTicksToWait)

// ---------------------- Example ----------------------

QueueHandle_t xQueueThatContainsData;
xQueueThatContainsData = 
    (QueueHandle_t)xQueueSelectFromSet(xQueueSet, portMAX_DELAY);                                           

QueueSetMemberHandle_t xQueueSelectFromSet(QueueSetHandle_t xQueueSet, 
                                           TickType_t const xTicksToWait)

// ---------------------- Example ----------------------

QueueHandle_t xQueueThatContainsData;
xQueueThatContainsData = 
    (QueueHandle_t)xQueueSelectFromSet(xQueueSet, portMAX_DELAY);                                           

Control Law Accelerator (CLA)

The CLA is an independent, fully programmable, 32-bit floating-point math processor. It executes algorithms independently and in parallel with the CPU. This extends the capabilities of the C28x CPU by adding parallel processing. The CLA has direct access to the ADC result registers. Additionally, the CLA has access to all ePWM, high-resolution PWM, eCAP, eQEP, CMPSS, DAC, SDFM, SPI, McBSP, uPP and GPIO data registers. This allows the CLA to read ADC samples just-intime and significantly reduces the ADC sample to output delay enabling faster system response and higher frequency operation. The CLA responds to peripheral interrupts independently of the CPU. Utilizing the CLA for time-critical tasks frees up the CPU to perform other system, diagnostics, and communication functions concurrently.

CLA Memory and Register Access

The CLA has access to the LSx RAM blocks and each memory block can be configured to be either dedicated to the CPU or shared between the CPU and CLA. After reset the memory block is mapped to the CPU, where it can be initialized by the CPU before being shared with the CLA. Once it is shared between the CPU and CLA it then can be configured to be either program memory or data memory. When configured as program memory it contains the CLA program code, and when configured as data memory it contains the variable and coefficients that are used by the CLA program code. Additionally, dedicated message RAMs are used to pass data between the CPU and CLA, and CLA and CPU.

CLA Tasks

Programming the CLA consists of initialization code, which is performed by the CPU, and tasks. A task is similar to an interrupt service routine, and once started it runs to completion. Tasks can be written in C or assembly code, where typically the user will use assembly code for high performance time-critical tasks, and C for non-critical tasks. Each task is capable of being triggered by a variety of peripherals without CPU intervention, which makes the CLA very efficient since it does not use interrupts for hardware synchronization, nor must the CLA do any context switching. Unlike the traditional interrupt-based scheme, the CLA approach becomes deterministic. The CLA supports eight independent tasks and each is mapped back to an event trigger. Since the CLA is a software programmable accelerator, it is very flexible and can be modified for different applications.

CLA Control and Execution Registers

CLA Registers

CLA Initialization

Set the Specify CLA support project option to cla1

CLA Task Programming

• Can be written in C or assembly code
• Assembly code will give best performance for time-critical tasks
• Writing in assembly may not be so bad
  • CLA programs in floating point
  • Often not that much code in a task
• The user will use assembly for critical tasks, and C for non-critical tasks

CLA C Language Implementation and Restrictions

CLA Assembly Language Implementation

CLA Code Debugging

Reference

[1] TMS320F2837xD Microcontroller Workshop