FreeRTOS – Core API Overview

• • Task management is the foundation for building concurrent programs.
• • Queues, semaphores, and mutexes: are solutions for inter-task communication and synchronization issues.
• • Event groups and task notifications: provide solutions for handling more complex synchronization scenarios.
• • Software timers: address the need for low-overhead handling of numerous timed events.
• • Critical sections/scheduler locks: provide the lowest level of mutual exclusion protection.
• • Memory management: ensures the stable operation of the system.

FreeRTOS Core API Quick Reference

1. Task Management

Core: The basic execution unit of the system.

Function	API Function Prototype	Core Parameter Description
Create Task	<span>BaseType_t xTaskCreate( TaskFunction_t pvTaskCode, const char * const pcName, const configSTACK_DEPTH_TYPE usStackDepth, void * const pvParameters, UBaseType_t uxPriority, TaskHandle_t * const pxCreatedTask );</span>	<span>pvTaskCode</span>: Task function pointer<span>pcName</span>: Task name (for debugging)<span>usStackDepth</span>: Task stack size (in Words)<span>pvParameters</span>: Parameters passed to the task<span>uxPriority</span>: Task priority (0 is the lowest)<span>pxCreatedTask</span>: (optional) returned task handle
Delete Task	<span>void vTaskDelete( TaskHandle_t xTaskToDelete );</span>	<span>xTaskToDelete</span>: Task handle to delete (<span>NULL</span> to delete itself)
Relative Delay	<span>void vTaskDelay( const TickType_t xTicksToDelay );</span>	<span>xTicksToDelay</span>: Number of ticks to delay
Absolute Delay	<span>void vTaskDelayUntil( TickType_t * const pxPreviousWakeTime, const TickType_t xTimeIncrement );</span>	<span>pxPreviousWakeTime</span>: Pointer to the last wake time<span>xTimeIncrement</span>: Fixed time increment (Ticks). Used for precise periodic tasks
Suspend/Resume	<span>void vTaskSuspend( TaskHandle_t xTaskToSuspend );</span><span>void vTaskResume( TaskHandle_t xTaskToResume );</span>	<span>xTaskTo...</span>: Task handle to operate on (<span>NULL</span> for itself)
Resume (ISR)	<span>void vTaskResumeFromISR( TaskHandle_t xTaskToResume );</span>	<span>xTaskToResume</span>: Task handle to resume

2. Queue Management

Core: A “pipeline” for data transfer between tasks, achieving asynchronous decoupling.

Function	API (Task Context)	API (Interrupt Context – ISR)	Core Parameter Description
Create	<span>QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength, UBaseType_t uxItemSize );</span>	–	<span>uxQueueLength</span>: Maximum number of items the queue can hold<span>uxItemSize</span>: Size of each item (in bytes)
Send to Back	<span>xQueueSendToBack( xQueue, pvItem, xTicksToWait )</span>	<span>xQueueSendToBackFromISR( xQueue, pvItem, pxWoken )</span>	<span>xQueue</span>: Queue handle<span>pvItem</span>: Pointer to the data to send<span>xTicksToWait</span>: Blocking time when the queue is full<span>pxWoken</span>: Pointer to the scheduling request flag
Send to Front	<span>xQueueSendToFront( xQueue, pvItem, xTicksToWait )</span>	<span>xQueueSendToFrontFromISR( xQueue, pvItem, pxWoken )</span>	(same as above)
Receive	<span>xQueueReceive( xQueue, pvBuffer, xTicksToWait )</span>	<span>xQueueReceiveFromISR( xQueue, pvBuffer, pxWoken )</span>	<span>pvBuffer</span>: Pointer to the buffer for received data
Delete	<span>void vQueueDelete( QueueHandle_t xQueue );</span>	–	<span>xQueue</span>: Queue handle to delete

3. Semaphores & Mutexes

Core: Used for synchronization and mutual exclusion between tasks.

Function	API Function/Macro	Core Parameter/Description
Create Binary Semaphore	<span>SemaphoreHandle_t xSemaphoreCreateBinary();</span>	Creates a “doorbell”, initially unavailable.
Create Counting Semaphore	<span>SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount );</span>	<span>uxMaxCount</span>: Maximum count value<span>uxInitialCount</span>: Initial count value
Create Mutex	<span>SemaphoreHandle_t xSemaphoreCreateMutex();</span>	Creates a “resource key”, initially available,with priority inheritance.
Create Recursive Mutex	<span>SemaphoreHandle_t xSemaphoreCreateRecursiveMutex();</span>	Creates a “reentrant key”.
Take	<span>xSemaphoreTake( xSemaphore, xTicksToWait )</span>	Take semaphore/lock.<span>xTicksToWait</span> is the blocking time.
Take (Recursive)	<span>xSemaphoreTakeRecursive( xMutex, xTicksToWait )</span>	Take recursive lock, can be taken multiple times by the same task.
Give	<span>xSemaphoreGive( xSemaphore )</span>	Release semaphore/lock.
Give (Recursive)	<span>xSemaphoreGiveRecursive( xMutex )</span>	Release recursive lock, must be paired with<span>Take</span> calls.
Give (ISR)	<span>xSemaphoreGiveFromISR( xSemaphore, pxWoken )</span>	Only for semaphores, strictly prohibited for mutexes!

4. Event Groups

Core: Implement complex “AND/OR” logic waiting for multiple events.

Function	API (Task Context)	API (Interrupt Context – ISR)	Core Parameter Description
Create	<span>EventGroupHandle_t xEventGroupCreate();</span>	–	–
Wait for Event Bits	<span>EventBits_t xEventGroupWaitBits( xEventGroup, uxBitsToWaitFor, xClearOnExit, xWaitForAllBits, xTicksToWait );</span>	–	<span>uxBitsToWaitFor</span>: Event bits to wait for (mask)<span>xClearOnExit</span>: <span>pdTRUE</span>= automatically clear bits after success<span>xWaitForAllBits</span>: <span>pdTRUE</span>= wait for all bits, <span>pdFALSE</span>= wait for any bit<span>xTicksToWait</span>: Blocking time
Set Event Bits	<span>EventBits_t xEventGroupSetBits( xEventGroup, uxBitsToSet );</span>	<span>xEventGroupSetBitsFromISR( xEventGroup, uxBitsToSet, pxWoken );</span>	<span>uxBitsToSet</span>: Event bits to set (mask)
Clear Event Bits	<span>EventBits_t xEventGroupClearBits( xEventGroup, uxBitsToClear );</span>	<span>xEventGroupClearBitsFromISR( xEventGroup, uxBitsToClear );</span>	<span>uxBitsToClear</span>: Event bits to clear (mask)
Delete	<span>void vEventGroupDelete( EventGroupHandle_t xEventGroup );</span>	–	<span>xEventGroup</span>: Event group handle to delete

5. Task Notifications

Core: Lightweight, zero-overhead, point-to-point direct communication between tasks.

Function	API (Task Context)	API (Interrupt Context – ISR)	Core Parameter/Description
Send (General)	<span>xTaskNotify( xTaskToNotify, ulValue, eAction )</span>	<span>xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxWoken )</span>	<span>xTaskToNotify</span>: Target task handle<span>ulValue</span>: 32-bit notification value<span>eAction</span>: Action type (overwrite, or, add, etc.)
Wait	<span>xTaskNotifyWait( ulBitsToClearOnEntry, ulBitsToClearOnExit, *pulNotifiedValue, xTicksToWait );</span>	–	<span>pulNotifiedValue</span>: (optional) receive notification valuethe other parameters are for bit operations, used for event groups
Send (as Semaphore)	<span>xTaskNotifyGive( xTaskToNotify )</span>	<span>vTaskNotifyGiveFromISR( xTaskToNotify, pxWoken )</span>	Each call increments the notification value by 1.
Receive (as Semaphore)	<span>ulTaskNotifyTake( xClearOnExit, xTicksToWait )</span>	–	<span>xClearOnExit</span>: <span>pdTRUE</span>= clear to zero after receiving, <span>pdFALSE</span>= decrement by 1 after receiving

6. Software Timers

Core: Achieve a large number of periodic or one-time timed events with low resource overhead.

Function	API (Task Context)	API (Interrupt Context – ISR)	Core Parameter Description
Create	<span>TimerHandle_t xTimerCreate( pcName, xPeriod, uxAutoReload, pvTimerID, pxCallback );</span>	–	<span>xPeriod</span>: Period (Ticks)<span>uxAutoReload</span>: <span>pdTRUE</span>= periodic, <span>pdFALSE</span>= one-time<span>pxCallback</span>: Callback function (blocking is prohibited)
Start/Reset	<span>xTimerStart( xTimer, xTicksToWait )</span> / <span>xTimerReset(...)</span>	<span>xTimerStartFromISR( xTimer, pxWoken )</span> / <span>xTimerResetFromISR(...)</span>	<span>xTimer</span>: Timer handle<span>xTicksToWait</span>: Command queue blocking time
Stop	<span>xTimerStop( xTimer, xTicksToWait )</span>	<span>xTimerStopFromISR( xTimer, pxWoken )</span>	(same as above)
Delete	<span>xTimerDelete( xTimer, xTicksToWait )</span>	–	(same as above)

7. Memory & Scheduler Control

Core: Low-level operations for critical section protection and system state management.

Function	API Macro	Core Description
Critical Section	<span>taskENTER_CRITICAL()</span> / <span>taskEXIT_CRITICAL()</span>	Enable/disable interrupts, used to protect very short critical code, will increase interrupt latency.
Suspend Scheduler	<span>vTaskSuspendAll()</span> / <span>xTaskResumeAll()</span>	Only prevents task switching, interrupts can still respond. Used to protect longer code segments.
Memory Allocation	<span>void *pvPortMalloc( size_t xSize );</span>	Thread-safe memory allocation provided by RTOS.
Memory Free	<span>void vPortFree( void *pv );</span>	Thread-safe memory deallocation provided by RTOS.
Check Stack Watermark	<span>UBaseType_t uxTaskGetStackHighWaterMark( xTask );</span>	Debugging tool, returns the minimum historical remaining value of the task stack, used to determine if the stack is sufficient.