RTOS debug with STM32CubeIDE

[mattias norlander]

Hi Community,

Today you will provide the answers, and I will ask the questions!

Looking at the statistics gathered by our tools (assuming customer consent given), we can see the huge popularity of designing software relying on an RTOS. FreeRTOS is widely used, and we assume that the adoption Azure ThreadX will also spread quickly.

As CubeIDE tools guys, we have invested some effort in RTOS debug features. To quickly summarize the RTOS debug offer, let's make a list:

• Window > Show > View > Other > FreeRTOS / ThreadX
  • Provides views to visualize kernel objects for the 2 RTOSes
• Debug config > Debugger > Enable RTOS Proxy
  • Will allow the debugger to unwind and display the full call stack for ALL threads in the RTOS, not only the one currently in context!
• For Azure ThreadX CubeIDE 1.8.0 can also conveniently export trace logs to be visualized "offline" in Microsoft TraceX tool

In our view the RTOS support is now quite decent! ;)

What is puzzling is the lack of feedback and bug reports on these tools.

We don't want to invest time in features which very few customer need or care about!

Please use this thread to share your thoughts/feedback/experience with us!

[ArnoutDekimo]

And lastly (I cannot edit my posts, so I'll just create new ones), what would really be interesting, is to show the design of the rtosproxy somewhere in some documents. Perhaps making the blackbox binary instead of doing the work in openOCD and using the -rtos option there made sense in order to avoid others from using your work for other MCU's. Fine, no problem, but explaining this in a simple diagram, showing the communication interfaces between the processes (you undoubtably have that documentation internally) somehwere in a userguide would make it alot more accessible to devs. (anyway, just some feedback, since you guys asked:)

[Garnett.Robert]

Hi Mattias,

 

I have used this feature and appreciate your efforts.

 

I think that as users we miss the introduction of new features because we are too focused on the immediate problems and don't look at release notes etc. so when the new features appear we aren't aware of them.  I only noticed the addition of the FreeRTOS stuff in the project properties debug screen when I started a new project.

 

I use FreeRTOS in nearly all my projects except for the really tiny processors with small memories.

 

The support from Richard B and his off-sider is excellent, the documentation is good and it's easy to use. Being able to poke around in the source code is also very handy as you can learn how to do things.  I use ST Arm processors for all my projects and an very happy with them.

 

Best regards

Rob

 

[jcmoreau]

Is it possible to invoke the RTOS proxy from a terminal so that I can use it with VSCode? I am using STLink server with VSCode currently.

[rlk1]

I am trying to use the RTOS debug proxy to view the task stacks in the debugger. CUBE IDE version 1.18.0 with NUCLEO-F303K8 and FreeRTOS as supplied with the STM32 toolset. I am using the ST-LINK GDB server. In the console I see:

STMicroelectronics RTOS Proxy. Version 0.17.0
Copyright (c) 2025, STMicroelectronics. All rights reserved.

'arm-none-eabi-readelf' is not recognized as an internal or external command,
operable program or batch file.
Failed generate debug info
Loading RTOS driver... FreeRTOS
Connecting to GDB server 127.0.0.1 on port 61234 ... Connected
Listen for GDB connection on port: 60000 ... Connected
Unknown data structure layoutxLIST
Update threads. Failed collecting threads.
Unknown data structure layoutxLIST
Update threads. Failed collecting threads.

and only Thread #1 shows up in the debug view. configUSE_PORT_OPTIMISED_TASK_SELECTION is set to 0.

I also tried disabling live expressions, but nothing changes.

I have found people with the Failed collecting threads issue, but not the layoutxLIST issues, so I assume this may be a newly introduced problem. I have been able to get this to work in the past with an older version of CUBE IDE.

 

 

[DeeFuse]

I have the same problem since at least early 2024. Even installing CubeIDE on a fresh Windows installation did not fix this problem. The message about the "readelf" command can be circumvented by adding the path to the toolchain to the System or User %PATH% ( e.g. C:\ST\STM32CubeIDE\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.13.3.rel1.win32_1.0.0.202411081344\tools\bin\)

but the errors about the "layoutxLIST" and "Failed collecting threads" remains.

[rlk1]

Using IDE version 1.18.1 I have found the problem to be inconsistent. I have one project using a Nucleo-G431KB where debugging FreeRTOS works fine, although initially I ran into these issues.

I have another project using an STM32F401 on a custom board where nothing I do gets rid of the layoutxLIST and "Failed collecting threads" errors. I have tried using an STLINK v2 and STLINK v3 with this board with the same result. I don't know where the layoutxLIST it is looking for comes from since on neither project is that symbol listed in the map file for the executable.

Debugging a FreeRTOS application without a thread aware debugger is difficult and it would be really nice if ST fixed this so it just works.

Edit: For the heck of it, I tried debugging the STM32F401 with a J-Link. I selected the J-Link proxy option (RTOSPlugin_FreeRTOS) and it worked! Seems like maybe ST should just contract with Segger to do their debug probes and debuggers.

[DeeFuse]

I got some new insight into the KernelAware debugger problem not beeing able to find the layoutxLIST.
The first one is a typo in the log message missing a space between "layout" and "xLIST"

The "xLIST" can be found in FreeRTOS "list.h" on line 164 (typedef struct xLIST)
These lists are used for example for "pxReadyTasksLists" which the debugger might want to read from.

If you search for "pxReadyTasksLists" in the Build Explorer you most likely will be able to find it with no problems.
But something with the way the RtosProxy reads the address of the symbol using arm-none-eabi-readelf is not able to find that symbol when it is defined as "static".

On Line 105 of "tasks.c" there is a check for "#ifdef portREMOVE_STATIC_QUALIFIER" with a remark that some debuggers might not be able to find the symbols if they are defined static.

So if you add "#define portREMOVE_STATIC_QUALIFIER" to your "FreeRTOSConfig.h" inside a USER CODE section the debugging should work with ST-Link and GDB as usual.