FreeRTOS SysTick Handler issue after migration in STM32CubeIDE 1.17

[FrankRidder]

Background, We have projects where the SYS timebase is set to a peripheral timer. Currently, this no longer works with the new cubeMX version.

In STM32CubeIDE 1.17, migrating projects to the updated CubeMX version (6.12.0 -> 6.13.0) modifies the FreeRTOSConfig.h file in Core/Inc. Specifically, the following changes occur:

Old lines (140–143):

/* IMPORTANT: This define is commented when used with STM32Cube firmware, when the timebase source is SysTick, to prevent overwriting SysTick_Handler defined within STM32Cube HAL */

#define xPortSysTickHandler SysTick_Handler

New lines (144–146):

/* IMPORTANT: After 10.3.1 update, Systick_Handler comes from NVIC (if SYS timebase = systick), otherwise from cmsis_os2.c */

#define USE_CUSTOM_SYSTICK_HANDLER_IMPLEMENTATION 0

The old configuration ensured that FreeRTOS used its SysTick implementation from port.c. Specifically, xPortSysTickHandler in port.c was renamed to SysTick_Handler, matching the function name in the startup file's interrupt vector.

With the new configuration, this renaming no longer happens. If the SYS timebase is configured to use a timer peripheral (instead of SysTick), there is no implementation of the SysTick_Handler function, leaving the interrupt unhandled. As a result, the Default_Handler is used, which prevents FreeRTOS from switching tasks. 

If the SYS timebase is configured to use SysTick in the .ioc file, an implementation of SysTick_Handler is generated in stm32f3xx_it.c. This generated function calls both HAL_IncTick and xPortSysTickHandler. This indicates that ST assumes the SYS timebase is always set to SysTick and that the use of a timer peripheral as the SYS timebase is no longer supported.

Effectively, FreeRTOS no longer works when using a timer peripheral as the SYS timebase in STM32CubeIDE 1.17 after migrating the project.

[Pavel A.]

Yes, in early FreeRTOS it contained the SysTick handler, but later they added co-existence with other software such as the STM32 "HAL" and assume that the handler exists in external code. So we have to keep an eye on this and fix whenever necessary.

[FrankRidder]

I did some research and found that the latest STM firmware package available (STM32Cube_FW_F3_V1.11.5) for our target MCU STM32F302 contains an old version of FreeRTOS (10.0.1) and CMSIS (V5.0.2). Other firmware packages for other MCUs are already at FreeRTOS 10.3.1 with a newer version of the CMSIS_V2 interface.

In the newer CMSIS_V2 interface, which appears to be bundled with FreeRTOS 10.3.1 in the STM firmware packages, the define CMSIS_device_header is implemented in freertos_os2.h (source: freertos_os2.h on GitHub). This new header file is included by cmsis_os2.c and ensures that, through the CMSIS_device_header, the SysTick is defined. As a result, the SysTick_Handler is defined in cmsis_os2.c.

In version STM32Cube_FW_F3_V1.11.5, this is missing. Consequently, the CMSIS_V2 interface does not know that the SysTick is defined, and the SysTick_Handler from cmsis_os2.c is not created. This results in a broken setup.

Preferred Solution:
STM should update the CMSIS_V2 interface to support the define CMSIS_device_header so that the CMSIS_V2 interface can define the SysTick_Handler as explained in the comment in FreeRTOSConfig.h:
/* IMPORTANT: After 10.3.1 update, Systick_Handler comes from NVIC (if SYS timebase = systick), otherwise from cmsis_os2.c */.

Temporary Solution:
For those facing the same issue, add the following line to the User Code section in FreeRTOSConfig.h:

/* USER CODE BEGIN Defines */ 

/* Section where parameter definitions can be added (for instance, to override default ones in FreeRTOS.h) */

#include CMSIS_device_header

/* USER CODE END Defines */

Since cmsis_os2.c includes FreeRTOS.h and FreeRTOS.h includes FreeRTOSConfig.h, this ensures your specific board file is included and the SysTick is defined.