Getting started with FreeRTOS

FreeRTOSConfig.h is the central configuration file that customizes the FreeRTOS kernel for user specific project, MCU, and requirements. It defines:

  • Scheduler behavior and tick rate.

  • Number of priorities and stack sizes.

  • Enabled kernel features: timers, event groups, mutexes, hooks, etc.

  • Memory allocation model and heap size.

  • Interrupt priority scheme and ISR-safe API usage.

  • Every project typically has a custom FreeRTOSConfig.h tuned to its performance, memory, and safety requirements.

Configuration file

FreeRTOSConfig.h is project-specific . It controls which features are compiled and how the kernel behaves. It is included indirectly by FreeRTOS.h.

Typical configuration items:

  • Scheduler options:

    • configUSE_PREEMPTION

    • configUSE_TIME_SLICING

    • configUSE_TICKLESS_IDLE

  • Timing and priorities:

    • configTICK_RATE_HZ

    • configMAX_PRIORITIES

    • configMINIMAL_STACK_SIZE

    • configUSE_16_BIT_TICKS

  • Enabling/disabling features:

    • configUSE_MUTEXES

    • configUSE_RECURSIVE_MUTEXES

    • configUSE_COUNTING_SEMAPHORES

    • configUSE_TIMERS

    • configUSE_EVENT_GROUPS

    • Hook functions (idle hook, tick hook, etc.).

  • Memory allocation:

    • configSUPPORT_STATIC_ALLOCATION

    • configSUPPORT_DYNAMIC_ALLOCATION

    • configTOTAL_HEAP_SIZE (for heap_1/2/4/5).

  • Port-specific settings (for example, Cortex-M interrupt priorities):

    • configKERNEL_INTERRUPT_PRIORITY

    • configMAX_SYSCALL_INTERRUPT_PRIORITY

    • configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY

Configuration options & files

This table lists commonly used configuration macros from FreeRTOSConfig.h with a short description, typical values, and links to the official FreeRTOS documentation.

Macro

Description

Link

configCPU_CLOCK_HZ

CPU clock frequency in Hz, used by the port layer (SysTick, timers). Example: SystemCoreClock or a literal (e.g. 168000000).

link

configTICK_RATE_HZ

RTOS tick frequency in Hz. Defines the tick period and timing granularity. Common values: 100 – 1000 (e.g. 1000 for 1 ms tick).

link

configMAX_PRIORITIES

Number of priority levels available for tasks. Typical: 5 – 7 or more, depending on project complexity.

link

configMINIMAL_STACK_SIZE

Stack size (in words, not bytes) for the Idle task and small tasks. Depends on MCU/port; e.g. 128 or 256 on Cortex‑M.

link

configTOTAL_HEAP_SIZE

Total heap size used by pvPortMalloc() (for heap_1/2/4/5). Example: (20 * 1024) for 20 KB, adjust per project.

link

configUSE_PREEMPTION

Enable (1) or disable (0) preemptive scheduling. Typically 1 (preemptive scheduler enabled).

link

configUSE_IDLE_HOOK

If 1, calls vApplicationIdleHook() on each idle task iteration. Use 1 when you need custom idle processing (e.g. low‑power).

link

configUSE_TICK_HOOK

If 1, calls vApplicationTickHook() on each tick interrupt. Use with care and keep the hook very short.

link

configUSE_MALLOC_FAILED_HOOK

If 1, calls vApplicationMallocFailedHook() when memory allocation fails. Recommended to set to 1 and implement the hook.

link

configCHECK_FOR_STACK_OVERFLOW

Enable stack overflow checking. 0 = disabled, 1/2 = different methods. Recommended 1 or 2 Requires a hook implementation in debug configurations.

link

configUSE_TIME_SLICING

Enable time slicing between tasks of the same priority. Usually 1 (enabled).

link

configUSE_16_BIT_TICKS

Use 16‑bit tick type instead of 32‑bit to save memory on small MCUs. Typically 0 on 32‑bit MCUs (Cortex‑M).

link

configUSE_MUTEXES

Enable mutex support (priority inheritance). Typically 1 (for shared resource protection).

link

configUSE_RECURSIVE_MUTEXES

Enable recursive mutexes. Set to 1 if needed; otherwise 0 to reduce code size.

link

configUSE_COUNTING_SEMAPHORES

Enable counting semaphores. Typically 1 if used in the project.

link

configUSE_QUEUE_SETS

Enable queue sets (multiplexing queues/semaphores). Set to 1 only when this feature is required.

link

configUSE_TIMERS

Enable software timers and the timer service task. Typically 1 if your project uses software timers.

link

configTIMER_TASK_PRIORITY

Priority of the timer service task (when configUSE_TIMERS = 1). Often medium priority (e.g. configMAX_PRIORITIES - 2).

link

configTIMER_TASK_STACK_DEPTH

Stack depth (in words) for the timer service task. Depends on callbacks; e.g. configMINIMAL_STACK_SIZE * 2.

link

configTIMER_QUEUE_LENGTH

Length of the timer command queue. Example: 10 or more, depending on number of timers.

link

INCLUDE_vTaskDelay

Control inclusion of vTaskDelay() in the build. Typically 1 (almost always needed).

link

INCLUDE_vTaskDelayUntil

Control inclusion of vTaskDelayUntil(). 1 if you use periodic tasks based on absolute time.

link

INCLUDE_vTaskDelete

Control inclusion of vTaskDelete(). 1 if tasks can be deleted at runtime.

link

INCLUDE_vTaskSuspend

Control inclusion of vTaskSuspend() / vTaskResume(). 1 if you use task suspension/resume.

link

INCLUDE_uxTaskPriorityGet

Control inclusion of uxTaskPriorityGet(). 1 when you need to inspect task priorities.

link

configUSE_IDLE_TASK_NOTIFICATION

Enable direct‑to‑task notifications for the idle task. Optional, depending on design.

link

configUSE_TASK_NOTIFICATIONS

Enable direct‑to‑task notification API. Typically 1 (recommended, lightweight sync primitive).

link

configUSE_TRACE_FACILITY

Enable trace and debug functions like vTaskList(). 1 in debug builds; can be 0 in production.

link

configGENERATE_RUN_TIME_STATS

Enable generation of run‑time stats per task. 1 in debug/profiling builds (requires a timing source).

link

configUSE_TICKLESS_IDLE

Enable tickless idle (low‑power) mode when the system is idle. Often 1 for low‑power STM32 designs.

link

configMAX_SYSCALL_INTERRUPT_PRIORITY

Max interrupt priority (Cortex‑M) from which FreeRTOS API can be called. Must match NVIC config; typical: 5 << (8 - configPRIO_BITS).

link

configLIBRARY_LOWEST_INTERRUPT_PRIORITY

Lowest NVIC priority used by the system (Cortex‑M helper macro). Used with ST/CMSIS macros (e.g. 15 for 4 bits of priority).

link

configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY

Highest NVIC priority allowed to call FreeRTOS API (Cortex‑M helper). Example: 5 in many ST examples; must match NVIC setup.

link

configKERNEL_INTERRUPT_PRIORITY

Kernel interrupt priority (legacy style on some ports). Usually derived from configLIBRARY_LOWEST_INTERRUPT_PRIORITY.

link

FreeRTOS APIs description

FreeRTOS API Functions

Description

Link

xTaskCreate() / xTaskCreateStatic()

Create a new task (dynamic or static allocation).

link

vTaskDelete()

Delete a task.

link

vTaskDelay()

Delay a task for a relative time period.

link

vTaskDelayUntil()

Implement periodic execution using an absolute reference time.

link

vTaskPrioritySet() / uxTaskPriorityGet()

Change or retrieve a task’s priority.

link

vTaskSuspend() / vTaskResume()

Suspend and resume a task.

link

uxTaskGetStackHighWaterMark()

Get the minimum ever free stack space for a task (stack high-water mark).

link

vTaskStartScheduler()

Start the RTOS scheduler (should not return).

link

vTaskEndScheduler()

End the scheduler (supported only on some ports).

link

xQueueCreate() / xQueueCreateStatic()

Create a message queue (dynamic or static allocation).

link

xQueueSend() / xQueueSendToBack() / xQueueSendToFront()

Send an item to a queue from a task.

link

xQueueReceive()

Receive an item from a queue.

link

xQueueSendFromISR() / xQueueReceiveFromISR()

Queue send/receive operations from an ISR.

link

xSemaphoreCreateBinary() / vSemaphoreDelete()

Create and delete a binary semaphore.

link

xSemaphoreCreateCounting()

Create a counting semaphore.

link

xSemaphoreTake() / xSemaphoreGive()

Take and give a semaphore from a task context.

link

xSemaphoreGiveFromISR()

Give a semaphore from an ISR context.

link

xSemaphoreCreateMutex() / xSemaphoreCreateRecursiveMutex()

Create a mutex (standard or recursive) with priority inheritance.

link

xSemaphoreTakeRecursive() / xSemaphoreGiveRecursive()

Take and give a recursive mutex.

link

xEventGroupCreate() / xEventGroupSetBits() / xEventGroupWaitBits()

Create and use event groups for task synchronization.

link

xTimerCreate() / xTimerCreateStatic()

Create a software timer (dynamic or static allocation).

link

xTimerStart() / xTimerStop() / xTimerChangePeriod()

Start, stop or change the period of a software timer.

link

xTaskNotify() / xTaskNotifyFromISR() / xTaskNotifyWait()

Direct-to-task notifications (lightweight event/queue alternative).

link

pvPortMalloc() / vPortFree()

Allocate and free memory from the FreeRTOS heap.

link

vTaskList()

Generate a human-readable table of task states and stack usage.

link

vTaskGetRunTimeStats()

Get run-time statistics (CPU usage) for each task.

link