FreeRTOS Thread Debugging with Eclipse and OpenOCD

FreeRTOS is probably the number one RTOS used, and Eclipse is likely the most popular IDE I can think of. But debugging FreeRTOS applications with Eclipse and GDB is somewhat limited? What I would like to get at the minimum is this: ability to see all the different threads in the Eclipse debug view like this:

FreeRTOS Threads in Eclipse with OpenOCD

FreeRTOS Threads in Eclipse with OpenOCD

As you might guess from that screenshot: this post is about how to make FreeRTOS tread debugging possible with Eclipse and GDB :-).

FreeRTOS Debugging

I wrote in “DIY Free Toolchain for Kinetis: Part 5 – FreeRTOS Eclipse Kernel Awareness with GDB” how to add task list and other views to Eclipse which is very useful. Still, it is not possible to switch easily between FreeRTOS threads.

Then I wrote in “FreeRTOS ARM Thread Debugging with Eclipse and GDB” how to use GDB scripts at least manually between threads. Still ok, but not very usesr friendly.

There is a better way, but as far as I know for the moment only for OpenOCD. With this I’m able to show all the FreeRTOS threads in the Eclipse debug view and can switch between them:

FreeRTOS Threads in Eclipse with OpenOCD

FreeRTOS Threads in Eclipse with OpenOCD

WhatI need is this:


Download the OpenOCD (binaries, or sources if you want to build it yourself) from

In this article I’m using it Kinetis Design Studio V3.2.0 () and with the “v0.10.0-20160110*-dev” version:

GNU ARM Eclipse OpenOCD Releases

GNU ARM Eclipse OpenOCD Releases

I have used the binary files with the installer. Then run the installer.

OpenOCD Binaries Location

The OpenOCD which comes with Kinetis Design Studio is installed in

<KDS Installation Path>\OpenOCD

Because I want to use that version of OpenOCD in parallel to the new openOCD v0.10.0, I have installed it here:

<KDS Installation Path>\openocd_0_10_0

OpenOCD Debug Configurations

There are multiple ways how to configure the path to the OpenOCD binary, see for details.

I’m using this configuration:

OpenOCD Debug Configuration

OpenOCD Debug Configuration

This is the path to the openOCD executable:


As configuration I specify the board configuration file:

-f board/frdm-kl46z.cfg

In this article, I’m debugging a FreeRTOS application on a NXP FRDM-KL46Z Board with CMSIS-DAP as OpenSDA application:



OpenOCD Configuration

In order to show the FreeRTOS tasks, I need to tell OpenOCD that I’m using an RTOS. For this I need to add

-rtos auto


-rtos FreeRTOS

to the $_TARGETNAME configure line (see “RTOS Support” in

FreeRTOS Support in OpenOCD configuration file

FreeRTOS Support in OpenOCD configuration file

FreeRTOS Symbols

For the RTOS support in OpenOCD to work, the OpenOCD needs to know about RTOS symbols.

If you are getting this error message:

Error: FreeRTOS: uxTopUsedPriority is not defined, consult the OpenOCD manual for a work-around
OpenOCD Error about FreeRTOS Symbol not defined

OpenOCD Error about FreeRTOS Symbol not defined

Earlier versions of FreeRTOS had this symbol defined. So either add a helper file to your application (see or use the FreeRTOS I have released a few days ago. This release includes that symbol defined.

With this all the FreeRTOS tasks/threads are shown in the Eclipse Debug view. Clicking on the task will show the thread in the Source view:

Tread Aware Debugging with FreeRTOS in Eclipse Kinetis Design Studio

Tread Aware Debugging with FreeRTOS in Eclipse Kinetis Design Studio


With using OpenOCD I’m now able to do FreeRTOS thread debugging with GDB and Eclipse. I’m not very happy with the stability and speed of OpenOCD: both P&E and Segger are much faster and stable solutions. But they do not (yet?) provide that thread feature. I can switch back and forth the debugging connection, but long-term this is kind of painful. So I hope that professional debug solutions would pick that feature up to make me and many others happy :-).



24 thoughts on “FreeRTOS Thread Debugging with Eclipse and OpenOCD

  1. The thing I love most about this post, is the mention of OpenOCD. I don’t know why its reported as not stable most of the time by users, some iterations of openOCD were more stable than others in my experience, and its hard to understand why later versions don’t maintain the stability of older versions. If it was as stable as P&E it would be the best. I only use OpenOCD with the TWR-K60N512 for introductory lab, osbdm interface seems stable, and FRDM-KL25Z cmsis-dap, other boards like the FRDM-K64F are quite unhappy with it. I don’t know why. Thanks for sharing.


    • Unfortunately, it is not only the stability of OpenOCD which bothers me: it is as well the download/flash programming speed. I mean a speed of 1-2 kByte per second is only ok for very small programs. But the programs the students have to develop and download are in the range of 120-180 kByte. It is a huge waste of time to wait always several minutes until you can start debugging. My measurement shows that openOCD is about 10 times slower than the solutions of P&E and Segger, that alone makes OpenOCD not attractive. The other thing is that frequently it fails connecting, but that’s maybe more of a problem of the configuration files (I need to write a post about this, as well inspired by a comment you made earlier on that, but I have run into that again recently). The other challenge maybe related to what you say: not every device is supported, and there is some luck behind it if a device works or does not work. Not sure why.
      The other thing is that OpenOCD seems very monolithic to me: you need to rebuild the binaries, and not everyone (especially on Windows) want and can do this. Lukily there are binary provides like Liviu (GNU ARM Eclipse) which makes it easier to use OpenOCD for the Windows world.
      I hear good and bad things about pyOCD too, while it seems to be more on the positive side. But as long as there is not place where I can go and get the binaries, I won’t use it in my classes: the P&E and Segger solutions are free of charge too with OpenOCD, stable, reliable, fast and support all the devices. And personally I rather spend the $50-60 for a Segger EDU than wasting my time with something else. I feel sad for the efforts the OpenOCD community does on this project.

      Liked by 1 person

      • I haven’t tested the latest release, version 0.9.0 I am still using version 0.8.0-dev, released march 2015, the changelog seems to address some of the issues and the device list has really grown but like you said, I build most of my binaries from source (trust issues), and its easier coz I use Linux, not trivial on windows. The release on sourceforge is a tarbar:


        • The 0.8.0 which is in KDS v2.x and KDS v3.x works reasonable for some boards e.g. the FRDM-KL25Z and FRDM-K64F, but mostly fails on anything else. I tried a while back the 0.9.0 and it was a huge step back in my view, pretty much nothing seemed to work. Now with the 0.10.0 things seem to recover again, but still it is very, very slow. Good for experimenting with it, but not for daily usage.
          I’m wondering if this is only true for NXP parts, as it seems that for STM parts the support seems to be better with OpenOCD.


        • I also realized the same, for other silicon vendors, support seems better. May be we need one of us to join the bandwagon and push some changes for programming Kinetis ( and other NxP) devices. I didn’t know version 0.10.0 is out… will test on Linux. meanwhile, I read this: It could be the reason it works relatively better on TWRK60. Fragmentation problems in openOCD, we need someone taking a look at the NxP device support.


  2. Hi,

    thanks for your write-up.
    Maybe it’s worth mentioning, that it’s not possible to use Segger SystemView when a OpenOCD session is running.
    This is a major downside, too.


  3. It seems that only four ‘threads’ appear even though I have more than that running. Selection seems random. Anyone else experience this?


  4. Hello,
    Regarding modifying of the upstream configs, you do not really need to because you can add $_TARGETNAME configure -rtos auto to the end of your openocd.cfg or to the command line via -c parameter (just make sure it comes after sourcing of the target config).
    Regarding speed, 0.8.0 had a really very slow CMSIS-DAP driver but it was basically rewritten since then and the speed should be about as fast as it can get.
    Regarding regressions and stability, 0.9.0 got very positive feedback, so I’m unsure what exactly do you have in mind. Please do report the issues you face to the bugtracker or to the devel mailing list! The majority of OpenOCD developers do not use Kinetis parts so it’s not getting tested “automatically”, the project depends a lot on the feedback and contributions from the community. One question would go to Freescale: why did they fork OpenOCD instead of contributing nice code upstream?..
    Please feel free to test 0.10.0-rc1, J-Link users will find SWO support and there were plenty of other good changes. If you face any regressions, please report!


  5. Pingback: P&E ARM Cortex-M Debugging with FreeRTOS Thread Awareness and Real Time Expressions for GDB and Eclipse | MCU on Eclipse

  6. Pingback: Better FreeRTOS Debugging in Eclipse | MCU on Eclipse

  7. Hi Erich,

    I’ve noted that some of my tasks were missing in the list (typically tasks with more time paused) and I found a correction to the code:

    const int USED uxTopUsedPriority = configMAX_PRIORITIES – 1;

    seens like this happens because of the way OpenOCD uses the number in uxTopUsedPriority to access an array, causing an out of bound access, explained better in this thread:

    and also a patch to the OpenOCD:

    Now my thread list in eclipse always shows all tasks 😉


    • Oh, nevermind, you are already linking to the openOCD repository, so your freertos helper file is already updated

      (Earlier versions didn’t have “- 1”)


  8. Pingback: Troubleshooting Tips for FreeRTOS Thread Aware Debugging in Eclipse | MCU on Eclipse

  9. Hi Eric.
    Thanks for a nice writeup.

    I am struggling to get this to work with my STM32H7 device and FreeRTOS 9.0
    I am getting the following error from OpenOCD after all initialization seems to complete fine:
    >> Error: Error: null stack pointer in thread
    >> Error: RTOS: failed to get register list

    Any clues?

    Best regards
    Thomas Jespersen


    • Hi Thomas,
      Which version of OpenOCD are you using? It looks like OpenOCD does not correctly identify the task descriptor and its fields. I have seen many of these problems with OpenOCD and that’s why I pretty much not use it any more, and using P&E and SEGGER instead which works fine.


  10. Pingback: Running FreeRTOS on the VEGA RISC-V Board | MCU on Eclipse

  11. Pingback: OpenOCD with MCU-Link | MCU on Eclipse

What do you think?

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.