In-Depth Understanding of FreeRTOS Configuration

FreeRTOS configuration is implemented through macro definitions to control the behavior of the FreeRTOS kernel, with parameters designed in FreeRTOSConfig.h. Below is a detailed explanation of commonly used configurations.

Scheduling Method

Whether to enable preemptive scheduling
#define configUSE_PREEMPTION 1 : Enables preemptive scheduling (preemptive scheduling), allowing higher priority tasks to interrupt lower priority tasks.
#define configUSE_PREEMPTION 0 : Disables preemption, using cooperative scheduling (cooperative scheduling), where tasks must explicitly yield the CPU (e.g., by calling taskYIELD()).
Typically set to 1 for real-time responsiveness.

Idle Task

Whether to enable the idle task hook function
#define configUSE_IDLE_HOOK 1 : Enables, periodically calling vApplicationIdleHook()
#define configUSE_IDLE_HOOK 0 : Disables
The idle hook is suitable for entering low power modes or background tasks.

Tick Hook Function

Whether to enable the tick hook function
#define configUSE_TICK_HOOK 1 : Enables, called on each system tick interrupt by vApplicationTickHook().
#define configUSE_TICK_HOOK 0 : Disables
Can be used for periodic processing, such as software timers, LED blinking, etc.

CPU Clock

Used to set the CPU clock frequency, in Hz
#define configCPU_CLOCK_HZ ( ( unsigned long ) system_core_clock )

system_core_clock is a user-defined variable representing the MCU main frequency.
For example, for a 72 MHz STM32, system_core_clock = 72000000

Number of Task Priorities

Used to set the number of available task priorities
#define configMAX_PRIORITIES ( 5 )

Indicates priority levels from 0 to 4, totaling 5 levels.
The higher the priority, the sooner the task runs.

If there are too many tasks and not enough priorities, this can be increased appropriately.

Minimum Stack Size

#define configMINIMAL_STACK_SIZE ( ( unsigned short ) 128 )
Used to set the default minimum stack size for idle tasks and other small tasks (in words).

If uint32_t is 4 bytes, then 128 means the stack is 512 bytes.
Should be adjusted based on the MCU architecture and function call depth.

Dynamic Memory

Whether to support dynamic memory allocation (e.g., pvPortMalloc)

#define configSUPPORT_DYNAMIC_ALLOCATION 1 : Supports
#define configSUPPORT_DYNAMIC_ALLOCATION 0 : Does not support (only static allocation is allowed)

If tasks, queues, semaphores, etc., are created at runtime, this option must be enabled.

Total Heap Size

#define configTOTAL_HEAP_SIZE ( ( size_t ) ( 8 * 1024 ) )

Used to set the total heap size available to FreeRTOS (in bytes).
Used for dynamically allocating task stacks, control blocks, queues, and other resources.

Insufficient size may lead to malloc failed.

Task Name Length

#define configMAX_TASK_NAME_LEN ( 16 )

Maximum length of task names (including the null terminator \0).
16 means the longest task name can be 15 characters.

Used for task debugging, status monitoring, etc.

Tick Counter

Whether to use a 16-bit Tick counter

#define configUSE_16_BIT_TICKS 0 : Uses 32-bit Tick (recommended, supports longer delays)
#define configUSE_16_BIT_TICKS 1 : Uses 16-bit Tick (saves memory, but maximum delay is 65535 ticks)

For high-frequency systems, 32-bit Tick should be used.

Same Priority Tasks

Whether the idle task yields the CPU when there are other tasks of the same priority

#define configIDLE_SHOULD_YIELD 1 : The idle task will call taskYIELD(), allowing other ready tasks to run.
#define configIDLE_SHOULD_YIELD 0 : The idle task will not actively yield the CPU.

Suitable for running certain low-priority but real-time demanding tasks.

Co-routine Enable

Whether to enable Co-routines (coroutines)

#define configUSE_CO_ROUTINES 1 : Enables coroutines (uses fewer resources but has limited functionality).
#define configUSE_CO_ROUTINES 0 : Disables coroutine functionality (generally not used in modern projects).

Coroutines are suitable for use on extremely resource-constrained 8-bit microcontrollers. However, compared to tasks, they do not support parallel stacks and have weaker execution capabilities.

Co-routine Priority Count

Sets the number of priorities for coroutines

#define configMAX_CO_ROUTINE_PRIORITIES ( 2 )
Only effective when configUSE_CO_ROUTINES == 1.
Sets the available levels of coroutine priority, here it is 2, i.e., levels 0 and 1.

API Function Enable Switch

FreeRTOS allows enabling/disabling certain API functions as needed to reduce code size. Each macro starting with INCLUDE_ controls whether a function is available.

Dynamic Task Priority Modification

Control macro:#define INCLUDE_vTaskPrioritySet 1 : Enables
Function:vTaskPrioritySet(TaskHandle_t xTask, UBaseType_t uxNewPriority)

Get Current Priority of Specified Task

Control macro:#define INCLUDE_uxTaskPriorityGet 1 : Enables
Function:uxTaskPriorityGet(TaskHandle_t xTask)

Task Deletion

Control macro:#define INCLUDE_vTaskDelete 1 : Enables
Function:vTaskDelete(TaskHandle_t xTask)
This function is used to delete itself or other tasks.

Resource Cleanup

Control macro:#define INCLUDE_vTaskCleanUpResources 0 : Disables
Function:vTaskCleanUpResources()
Deprecated or only used for some special applications to manually clean up resources, generally not needed.

Task Suspension and Resumption

Control macro:#define INCLUDE_vTaskSuspend 1 : Enables
Task suspension:vTaskSuspend(TaskHandle_t xTask)
Task resumption:vTaskResume()

Task Delay

Control macro:#define INCLUDE_vTaskDelay 1 : Enables
Function:vTaskDelay(const TickType_t xTicksToDelay)
Used to delay the current task for a period of time, it is the most commonly used delay function.

Periodic Task Delay

Control macro:#define INCLUDE_vTaskDelayUntil 1 : Enables
Function:vTaskDelayUntil(TickType_t * const pxPreviousWakeTime, const TickType_t xTimeIncrement)
Used for precise timing delays of periodic tasks, it can prevent periodic drift (more suitable for periodic tasks than vTaskDelay()).

Get Task Handle

Control macro:#define INCLUDE_xTaskGetCurrentTaskHandle 1 : Enables
Function:xTaskGetCurrentTaskHandle()
Used to get the handle of the currently running task, very useful for implementing some task management logic, such as recording the current task status.

Interrupt Priority

Control macro:#define configPRIO_BITS 4
Configuration method:

#ifdef __NVIC_PRIO_BITS
  #define configPRIO_BITS           __NVIC_PRIO_BITS
#else
  #define configPRIO_BITS           4        /* 15 priority levels */
#endif

If __NVIC_PRIO_BITS is not defined, it defaults to using 4-bit priority, i.e., 16 priority levels.
If using the CMSIS standard header file (i.e., the chip support package provided by ARM), it usually defines a macro __NVIC_PRIO_BITS
This macro defines the number of interrupt priority bits supported by the current MCU, common values include:

__NVIC_PRIO_BITS = 2 : 4 available interrupt priorities
__NVIC_PRIO_BITS = 3 : 8 available interrupt priorities
__NVIC_PRIO_BITS = 4 : 16 available interrupt priorities

Functionality:

5 << (8 - configPRIO_BITS) // i.e., 5 << 4 = 0x50

FreeRTOS needs to know the number of interrupt priority bits when using interrupt nesting control (e.g., configMAX_SYSCALL_INTERRUPT_PRIORITY).
#define configMAX_SYSCALL_INTERRUPT_PRIORITY 5 : This value is actually placed in the high bits of the NVIC priority register, for example, in a 4-bit priority system, the value 5 is actually represented in hardware as
FreeRTOS kernel needs to use this information to correctly mask or allow interrupts to enter, to prevent being interrupted in critical sections.

Lowest Priority

Background Knowledge

In the ARM Cortex-M architecture (especially common embedded chips using FreeRTOS), interrupt priority is a numerical value.

The smaller the number → the higher the priority (faster response)
The larger the number → the lower the priority (slower response)

However, these numbers are not directly written in FreeRTOS macros like configMAX_SYSCALL_INTERRUPT_PRIORITY, but need to be left-shifted to align with the NVIC 8-bit register (because the actual register is 8-bit, but you can only use a few high bits, with the low bits fixed at 0).

Configuration Description

Control macro:#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY 0x0f

0x0f in decimal is 15, representing the lowest priority (maximum value).
This is not the actual value written to the NVIC register, but a logical “priority level”.
Generally used in conjunction with configPRIO_BITS (e.g., 4).
The actual value written to NVIC is 0x0f << (8 - configPRIO_BITS) // 0x0f << 4 = 0xf0

Key Rules

Highest Priority

Control macro:#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 0x01 same principle as above.
All interrupt service routines (ISR) that call FreeRTOS interrupt-safe APIs must have interrupt priorities that are “lower than” this value (i.e., numerical values greater than or equal to this macro value).

Why Interrupts with Priority 0 Cannot Call FreeRTOS Interrupt-Safe APIs

In the ARM Cortex-M architecture (e.g., STM32, etc.), interrupt priority is a mechanism where the smaller the numerical value, the higher the priority.
The priority value is written into the NVIC (Nested Vectored Interrupt Controller), each interrupt has a priority value.
A priority value of 0 indicates the highest interrupt priority, meaning:

It can interrupt all other interrupts (non-maskable).
It may even interrupt critical sections of FreeRTOS kernel code.

FreeRTOS is a preemptive RTOS, internally protecting shared resources through the **critical section** mechanism.

These critical sections are implemented by disabling **”low priority interrupts”**.
But if an interrupt has a priority of 0 (highest), it cannot be masked in any way, including FreeRTOS critical sections.
Therefore, during the execution of such interrupts, FreeRTOS cannot prevent them from accessing queues, semaphores, and other shared resources, leading to race conditions, deadlocks, and memory corruption.

FreeRTOS controls the allowed interrupt priorities that can call APIs through these two macros.

#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 0x01
#define configMAX_SYSCALL_INTERRUPT_PRIORITY (configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY « (8 - configPRIO_BITS))
Only interrupts with a priority of 1 (or lower, larger numerical value) can call interrupt-safe FreeRTOS APIs, while those with a priority of 0 cannot.

Summary

Do not call FreeRTOS APIs in ISRs.
In ISRs, only set a volatile flag.
Let lower priority tasks poll this flag or communicate through message queues.

Interrupt-Safe Priority

Control macro:#define configMAX_SYSCALL_INTERRUPT_PRIORITY ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY « (8 - configPRIO_BITS) )
Function: Defines the maximum priority (minimum numerical value) of interrupts allowed to call FreeRTOS interrupt-safe APIs.
Note: Cannot be 0!

Kernel Interrupt Priority

Control macro: #define configKERNEL_INTERRUPT_PRIORITY ( configLIBRARY_LOWEST_INTERRUPT_PRIORITY « (8 - configPRIO_BITS) )
Function: Sets the interrupt priority used by the FreeRTOS kernel itself (e.g., SysTick, PendSV).
Note: Generally uses the lowest priority, will not disturb other higher priority tasks.

Summary

Cortex-M interrupt priorities are in the NVIC register with an 8-bit width, but not all are used.
In the ARM Cortex-M series, the number of interrupt priority bits actually used by NVIC is defined by the macro provided by CMSIS as #define __NVIC_PRIO_BITS.
This macro is generally defined in the core_cmx.h file.
The value of this macro is defined by the chip manufacturer, commonly 3 or 4 bits.

Assert Macro Definition

Control macro:#define configASSERT( x ) if( ( x ) == 0 ) { taskDISABLE_INTERRUPTS(); for( ;; ); }
Function: Checks at runtime whether a certain condition holds; if not, interrupts program execution for debugging.
Note: When the assertion condition holds, all interrupts are disabled, and the program enters an infinite loop at the current position, allowing the use of JTAG/SWD debuggers to view the error location and stack.
Extension: You can add system logging, system reboot, etc., in this definition to enhance program adaptability.

Interrupt Functions

FreeRTOS uses three interrupt functions, namely:

#define vPortSVCHandler SVC_Handler
#define xPortPendSVHandler PendSV_Handler
#define xPortSysTickHandler SysTick_Handler

These three interrupt functions are implemented by FreeRTOS code. Specifically, we generally use SysTick_Handler to implement the function interface for obtaining system ticks; this interrupt function cannot be used externally.

SVC_Handler

Interrupt type: Instruction interrupt function Supervisor Call, SVC
Purpose: Used to perform privileged operations, such as task switching, first scheduling after task creation, etc.

PendSV_Handler

Interrupt type:PendSV (pending system service call) interrupt
Purpose: The main interrupt handling function for task switching. It is used every time a task is scheduled (context switch).

SysTick_Handler

Interrupt type:SysTick timer interrupt
Purpose: Used to generate system clock ticks, the scheduler decides whether to perform task switching based on it.

Scheduling Method

Idle Task

Tick Hook Function

CPU Clock

Number of Task Priorities

Minimum Stack Size

Dynamic Memory

Total Heap Size

Task Name Length

Tick Counter

Same Priority Tasks

Co-routine Enable

Co-routine Priority Count

API Function Enable Switch

Interrupt Priority

Lowest Priority

Background Knowledge

Configuration Description

Key Rules

Highest Priority

Why Interrupts with Priority 0 Cannot Call FreeRTOS Interrupt-Safe APIs

Summary

Interrupt-Safe Priority

Kernel Interrupt Priority

Summary

Assert Macro Definition

Interrupt Functions

SVC_Handler

PendSV_Handler

SysTick_Handler

Related posts

Leave a Comment Cancel reply