Upgrading FreeRTOS from v10.3.1 (from CubeMX ) to v11.2.0 (from freeRTOS repository)

[eyalmeschel]

Hello ST Community,

I'm working on an STM32H753VIT6 project and need to upgrade FreeRTOS from v10.3.1 to v11.2.0 due to cybersecurity requirements. I've encountered several integration challenges that I'd like to share and seek guidance on.

Background

Current Setup:

• Working on an STM32H753VIT6 microcontroller
• FreeRTOS v10.3.1 with CMSIS-RTOS v2 wrapper automatically generated using CubeMX which works seamlessly out of the box

Target:

• Using the newest FreeRTOS v11.2.0 from official repository (preferably without the CMSIS wrapper so future upgrading will be easier): https://github.com/FreeRTOS/FreeRTOS-Kernel/releases/tag/V11.2.0

The process:

So I followed some guides from the FreeRTOS forums and the ST community forums.

Like this one: https://community.st.com/t5/stm32cubemx-mcus/is-there-a-way-to-disable-the-automatic-default-task-creation-when-c-2560/td-p/256903

where I've been told there is no other way of upgrading (at least for my STM32H753VIT6) than deactivating the FreeRTOS from within the CubeMX, then downloading the lib from FreeRTOS repository and replacing it. So I followed this guide, and my first problem was duplicate definitions of some interrupt handler functions like PendSV_Handler and SVC_Handler, which were autogenerated by MX in stm32h7xx_it.c and in Port.c in the freertos libs. I found a way to disable the generation of these handlers in MX by unchecking some configuration in the NVIC window under the Code Generation tab (unchecked the "Generate IRQ handler" options for "Pendable request for system service" and "System service call via SWI instruction").

After solving this issue, I compiled successfully, but when I tried to run the code, it got stuck. After debugging, I realized the problem was related to the initialization process. With the CMSIS-RTOS wrapper in v10.3.1, there were two functions: osKernelInitialize() and osKernelStart(). The osKernelInitialize() function prepared the FreeRTOS environment, allowing some FreeRTOS API calls (like vTaskDelay() and timer functions) to work even before osKernelStart() was called.

Additionally, I encountered missing hook function errors:

undefined reference to `vApplicationIdleHook`

undefined reference to `vApplicationGetIdleTaskMemory`

undefined reference to `vApplicationGetTimerTaskMemory`

 

and many more Hard Fault and assertions erros caused by my code not intgrating well with the new freertos lib without the cmsis warpper

And I found the upgrading process extermly diffcult and full of uncertenties  

 

Questions for ST

1. So is there a “best practice” approach for upgradig an already exist project to a newer freertos version ?
2. About the CMSIS warpper what are the benfits I get from using it ? is it better to work with or without ?

Thank you for any guidance you can provide!

[Ghofrane GSOURI]

Hello @eyalmeschel 

I am transferring your post to the Embedded Software team for their technical support.

THX

Ghofrane

[Khaled_DHIF]

Hello @eyalmeschel ,

Thank you for your questions. Let me clarify both the role of the CMSIS-RTOS wrapper and the recommended approach for upgrading FreeRTOS in an existing project.

CMSIS-RTOS Wrapper: 

The CMSIS-RTOS wrapper is a solution provided by ARM as part of the CMSIS (Cortex Microcontroller Software Interface Standard) ecosystem. Its main purpose is to abstract the underlying RTOS kernel and provide a standardized API for ARM-based platforms to access RTOS functionalities such as thread management, timers, synchronization primitives, and message queues.

This abstraction layer allows application developers to write code that is portable across different RTOS kernels without needing to rewrite or adapt the RTOS-specific parts. It also facilitates integration with middleware and tools like STM32CubeMX, which generate CMSIS-RTOS-compliant code automatically.

Best Practice Approach for Upgrading FreeRTOS with CMSIS-RTOS Wrapper

When upgrading FreeRTOS in a project that uses the CMSIS-RTOS wrapper, the goal is to preserve the existing application behavior and API usage while benefiting from the improvements in the newer FreeRTOS kernel version. Here is the recommended approach:

1. Verify Middleware File Architecture

   • Review the FreeRTOS middleware folder structure, and if updating kernel source files (e.g., tasks.c, queue.c, timers.c, and the portable directory), ensure your project and build system correctly reference the new files.
   • Do not modify CubeMX-generated CMSIS-RTOS wrapper files (cmsis_os2.c, cmsis_os2.h), as they manage the abstraction layer.

2. Consult CMSIS-RTOS v2 API Documentation

   • Review the official CMSIS-RTOS v2 documentation at this link to understand any API changes, deprecated functions, or new features introduced since your previous version. 

3. Review and Align FreeRTOSConfig.h

   • The FreeRTOSConfig.h file is critical in defining which FreeRTOS features and hooks are enabled or disabled.

   • For example, in your current setup, you have enabled the configUSE_IDLE_HOOK from this set of macros:

/* Set the following configUSE_* constants to 1 to include the named hook
 * functionality in the build. Set to 0 to exclude the hook functionality from the
 * build. The application writer is responsible for providing the hook function
 * for any set to 1. See https://www.freertos.org/a00016.html. */
#define configUSE_IDLE_HOOK 0
#define configUSE_TICK_HOOK 0
#define configUSE_MALLOC_FAILED_HOOK 0
#define configUSE_DAEMON_TASK_STARTUP_HOOK 0

• If any of these hooks are enabled (set to 1), you must implement the corresponding hook functions in your source code. Otherwise, the linker will generate undefined reference errors like the ones you have encountered. Conversely, if you do not implement the hooks, ensure they are disabled in this config file.

• Expect Minimal Impact on Application Behavior

  • Upgrading FreeRTOS typically does not alter your application's behavior but improves stability, performance, security, and maintainability. Existing tasks and synchronization should work unchanged if APIs and configurations remain consistent.

Please let me know if you would like assistance reviewing your project files or verifying your configuration to ensure a smooth upgrade.

Kind regards, 

DHIF Khaled

[Orion33]

Hello.

As far as I know, X-CUBE-FREERTOS is recommended for the new H series processors. But I only have F103 and G473, so I can't share my experience.

 

However, I have successfully ported a CubeMX project to the latest version of FreeRTOS. In general, I followed this guide: https://blog.hesimsek.com/posts/stm32_freertos_config_without_cmsis/. However, the author did not mention two things:

1. Your FreeRTOSConfig.h must contain the following definitions

 

/* Definitions that map the FreeRTOS port interrupt handlers to their CMSIS standard names. */

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

 

2. System interrupts have a default priority of 0, which will not work. CubeMX with FreeRTOS enabled generates code in which all system interrupts have a priority no higher than 5.

 

[Khaled_DHIF]

Hello @Orion33 ,

Yes, the points described must be applied:

- Interrupt handler mapping macros in FreeRTOSConfig.h are essential to correctly link FreeRTOS handlers to the CMSIS standard names, as you have already configured. Additionally, ensure that the corresponding IRQ calls generated by CubeMX are disabled or removed, as highlighted in your tutorial, to avoid conflicts.

- The configMAX_SYSCALL_INTERRUPT_PRIORITY macro sets the highest interrupt priority from which FreeRTOS API calls can be safely made. System interrupts must have their priority set to that value or to a lower priority level.

- For example, if configMAX_SYSCALL_INTERRUPT_PRIORITY is 5, then:

NVIC_SetPriority(SVCall_IRQn, 5);
NVIC_SetPriority(PendSV_IRQn, 5);
NVIC_SetPriority(SysTick_IRQn, 5);

This ensures proper interrupt nesting and stable FreeRTOS operation.

Tip: It is best to use the FreeRTOSConfig.h template from one of the official FreeRTOS demo projects as a starting point, as it includes all necessary configurations tailored for the target MCU.

Kind regards, 

DHIF Khaled