FreeRTOS Thread Debugging with Eclipse and OpenOCD

Posted on April 9, 2016 by Erich Styger

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

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

WhatI need is this:

OpenOCD (e.g. with CMSIS-DAP). For using this with Segger J-Link see http://jacobjennin.gs/post/142301106015/eclipse-thread-awareness-with-freertos-and-j-link
The correct OpenOCD settings
and a small tweak in FreeRTOS

Installation

Download the OpenOCD (binaries, or sources if you want to build it yourself) from http://gnuarmeclipse.github.io/openocd/releases/

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

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 http://gnuarmeclipse.github.io/debug/openocd/ for details.

I’m using this configuration:

OpenOCD Debug Configuration

This is the path to the openOCD executable:

${eclipse_home}../openocd_0_10_0/bin/openocd

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:

NXP FRDM-KL46Z Board

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 http://openocd.org/doc/html/GDB-and-OpenOCD.html):

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

Earlier versions of FreeRTOS had this symbol defined. So either add a helper file to your application (see https://github.com/arduino/OpenOCD/blob/master/contrib/rtos-helpers/FreeRTOS-openocd.c) 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

Summary

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”

Karibe on April 9, 2016 at 12:35 said:

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.

LikeLike

Reply ↓
- Erich Styger on April 9, 2016 at 12:58 said:
  
  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.
  
  LikeLiked by 1 person
  
  Reply ↓
  - Karibe on April 9, 2016 at 13:22 said:
    
    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: https://sourceforge.net/projects/openocd/
    
    LikeLike
    
    Reply ↓
    - Erich Styger on April 9, 2016 at 15:19 said:
      
      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.
      
      LikeLike
    - Karibe on April 11, 2016 at 12:16 said:
      
      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: https://sourceforge.net/p/openocd/mailman/message/28952546/. 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.
      
      LikeLike
Peter on April 11, 2016 at 10:35 said:

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.

LikeLike

Reply ↓
- Erich Styger on April 11, 2016 at 12:31 said:
  
  Hi Peter,
  yes, this is true: if using OpenOCD, then all the good Segger things like the SystemView are not operational.
  
  LikeLike
  
  Reply ↓
jacobjennings on July 1, 2016 at 22:53 said:

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

LikeLike

Reply ↓
Paul Fertser on December 28, 2016 at 15:58 said:

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!

LikeLike

Reply ↓
- Erich Styger on December 28, 2016 at 16:53 said:
  
  Hi Paul,
  thanks for pointing out the 0.10.0 release candidate!
  Erich
  
  LikeLike
  
  Reply ↓
Pingback: P&E ARM Cortex-M Debugging with FreeRTOS Thread Awareness and Real Time Expressions for GDB and Eclipse | MCU on Eclipse
Pingback: Better FreeRTOS Debugging in Eclipse | MCU on Eclipse
Gustavo Cardoso on March 21, 2017 at 13:54 said:

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:

http://forum.segger.com/index.php?page=Thread&postID=12422

and also a patch to the OpenOCD:
https://sourceforge.net/p/openocd/mailman/openocd-commit/thread/From_openocd-gerrit@users.sourceforge.net_Wed_May_04_21%3A40%3A13_2016/

Now my thread list in eclipse always shows all tasks 😉

LikeLike

Reply ↓
- Gustavo Cardoso on March 21, 2017 at 13:59 said:
  
  Oh, nevermind, you are already linking to the openOCD repository, so your freertos helper file is already updated
  
  (Earlier versions didn’t have “- 1”)
  
  LikeLike
  
  Reply ↓
Pingback: Troubleshooting Tips for FreeRTOS Thread Aware Debugging in Eclipse | MCU on Eclipse
Pierre Gradot on May 14, 2018 at 12:33 said:

Hello,

The following link appears twice in the article but it is broken: https://github.com/gnuarmeclipse/openocd/tree/gnuarmeclipse-dev/contrib/rtos-helpers

This file can be used instead: https://github.com/arduino/OpenOCD/blob/master/contrib/rtos-helpers/FreeRTOS-openocd.c

See you!
Pierre

LikeLike

Reply ↓
- Erich Styger on May 14, 2018 at 20:17 said:
  
  Hi Pierre,
  thank you! I have updated the two links.
  Merci!
  Erich
  
  LikeLiked by 1 person
  
  Reply ↓
Pierre Gradot on May 14, 2018 at 12:35 said:

Reblogged this on Pierre Gradot and commented:
Si vous utilisez FreeRTOS et que votre IDE est Eclipse et que vous vous connectez à votre carte grâce à OpenOCD, ceci devrait vous intéresser !

LikeLike

Reply ↓
Thomas Jespersen on December 17, 2018 at 18:45 said:

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

LikeLike

Reply ↓
- Erich Styger on December 18, 2018 at 05:53 said:
  
  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.
  
  LikeLike
  
  Reply ↓
  - Thomas Jespersen on December 18, 2018 at 14:18 said:
    
    I have tried with the two following versions, both without luck:
    0.10.0-dev-00015-gaaf1808
    0.10.0-10-20181020-0522
    
    LikeLike
    
    Reply ↓
    - Erich Styger on December 18, 2018 at 17:27 said:
      
      I believe this would have to be reported to the OpenOCD community.
      
      LikeLike
Pingback: Running FreeRTOS on the VEGA RISC-V Board | MCU on Eclipse
Pingback: OpenOCD with MCU-Link | MCU on Eclipse