OpenOCD with ChibiOS/RT thread support

This guide is still under construction but should include most information. Please try it out and give feedback =)


There is currently RTOS support being added to OpenOCD. Instead of only seeing the current thread of execution, this allows you to see all current threads while debugging your ChibiOS/RT project.

Eclipse using openOCD with ChibiOS support

You can check the latest developments in this forum thread.

Please note: Hardware FPU on the Cortex M3 is currently NOT supported.

Inner workings

OpenOCD includes the ability to detect Real Time Operating systems and provide the thread information to GDB. This architectural design has several limitations, the most severe one: openOCD can only query memory addresses of symbols - it cannot get the offset inside data structures and the size of objects.

Normally this problem is solved by coding those magic numbers/offsets directly into openOCD and select them depending on the target type, i.e. cortex-m3. However, this solution is not possible for ChibiOS, due to the very compact and customizable layout which changes depending on build-time options.

To get around this problem, the ChibiOS/RT memory signature record has been in the latest development versions (see os/kernel/include/chregistry.h). OpenOCD will read back this configuration structure and automatically adjust for the target system.

Installing OpenOCD with ChibiOS/RT support

This chapter assumes you are using Linux and have all required development utilities installed.

Under Debian/Ubuntu you should get away with:

sudo apt-get install build-essential libftdi-dev
sudo apt-get build-dep openocd
Getting the code

All code has been accepted upstream. You can obtain a copy from git:// via git.

Configure and compile

Once you got the code, point your favorite terminal the the openocd directory. You will have to bootstrab openocd first. You can do this by simply calling:


After bootstrapping finished, you can continue configuring as usual. I recommend using

./configure --enable-maintainer-mode --enable-ft2232_libftdi --prefix=/home/USER/bin/oocd

but feel free to modify it as you please. (Do not forget to change the USER name in above command.)

The prefix is optional, but since you are playing with bleeding edge software here, it is a good idea to install it to somewhere local.

Now you are ready to compile and install openocd:

make install

You should now have a working installation of OpenOCD on your computer.

Using OpenOCD with ChibiOS/RT

One problem with the default OpenOCD configuration is that RTOS support is disabled by default. OpenOCD can automatically detect if and what RTOS is running.

You can enable the RTOS by appending -c ”{TARGET_NAME}.cpu configure -rtos auto;” where target name stands for your CPU. i.e. stm32f4x. It is also typically displayed on openocd connection to your target.

Preparing your project to be debugged

Starting with ChibiOS SVN Rev. 4722 or Git 35acf78f, the ChibiOS/RT memory signature record is automatically included if CH_USE_REGISTRY is set to TRUE. Without this symbol ChibiOS/RT will only be partially detected and you will see a error message in OpenOCD.

You can check if your project file does include the signature record by calling

arm-none-eabi-nm build/ch.elf | grep ch_debug | wc -l

If the result is 1, your project will be detected by openOCD as ChibiOS/RT. If it is 0, go back and find out what is wrong.

For debugging, also remember to decrease/disable optimization for better readability.

Debug with threads


Apart from some quirks, Eclipse integrates nicely with openocd thread support. There is one problem however: As explained above, openocd must be able to resolve symbol names to memory addresses. This is only possible if the symbols are correctly loaded into gdb in the first place.

Now, Eclipse uses some strange gdb command voodoo to load the .elf file by default - which makes the symbol lookup fail. Fortunately, you can also use the file command in Eclipse. For this keep the “Load image” and “Load symbols” checkboxes in your GDB hardware debugging configuration under the Startup tab. Insert a “file full/path/build/ch.elf” to the beginning of the Initialization commands (Remember to change the path to your project elf file if it is different).

In addition, make sure that you use “Standard GDB Hardware Debugging Launcher”. The “GDB (DSF) Hardware Debugging Launcher ” behaves strangely and is also not supported by the ChibiOS Eclipse Plugin.

Using gdb bare metal

If you are using gdb with bare metal you will not notice any difference at first, since the threads are hidden at first. You can query them with the info threads command:

(gdb) info  threads 
  8 Thread 536907216 (shell :  : WTQUEUE)  chSchGoSleepS (newstate=32 ' ') at ../../os/kernel/src/chschd.c:122
  7 Thread 536904464 (http :  : WTSEM)  chSchGoSleepS (newstate=32 ' ') at ../../os/kernel/src/chschd.c:122
  6 Thread 536905776 (No Name :  : WTSEM)  chSchGoSleepS (newstate=32 ' ') at ../../os/kernel/src/chschd.c:122
  5 Thread 536901760 (lwipthread :  : WTOREVT)  chSchGoSleepS (newstate=32 ' ') at ../../os/kernel/src/chschd.c:122
  4 Thread 536899024 (blinker :  : SLEEPING)  chSchGoSleepS (newstate=32 ' ') at ../../os/kernel/src/chschd.c:122
  3 Thread 536901456 (usb_lld_pump :  : SUSPENDED)  chSchGoSleepS (newstate=32 ' ') at ../../os/kernel/src/chschd.c:122
  2 Thread 536899336 (idle :  : CURRENT)  _idle_thread (p=0x0) at ../../os/kernel/src/chsys.c:61
* 1 Thread 536873296 (main :  : WTOREVT)  chSchGoSleepS (newstate=32 ' ') at ../../os/kernel/src/chschd.c:122

Notice how each thread has an internal gdb id (first column) and a thread id (which coincidences with the location of the Thread structure in the target memory). Also note that gdb gives the the thread name (if defined) and the current thread state.

Let's say we want to investigate the backtrace of thread lwipthread, which has the internal gdb id 8:

(gdb) thread apply 8 bt
Thread 5 (Thread 536901760):
#0  chSchGoSleepS (newstate=8 '\b') at ../../os/kernel/src/chschd.c:122
#1  0x080022e8 in chEvtWaitAny (mask=4294967295) at ../../os/kernel/src/chevents.c:380
#2  0x0800fbd4 in lwip_thread (p=0x0) at ../../os/various/lwip_bindings/lwipthread.c:275
#3  0x0800048c in _port_thread_start () at ../../os/ports/GCC/ARMCMx/chcore_v7m.c:255
Backtrace stopped: frame did not save the PC

If you are interested in all backtraces, you can replace 8 by all.

Frequently asked questions

Will this code be pushed upstream?

YES - and it is already all included in the upstream openocd repository.

Will it be included in OpenOCD 0.7?

It is already in master and will be released with the next stable release. So go forth and test it, so that there are no more errors left. ;-)

Why is RTOS not enabled by default

Good question. Because if the RTOS symbols are detected, openOCD will directly start snooping around in the memory. This might fail if the memory controller is not yet set up. So the OpenOCD developers fear negative side effects.

What targets are supported?

Currently, support is implemented only for cortex m devices. If you have another processor which is supported by openocd, please give me a call. It's very easy to implement your device too - it just needs testing.

Eclipse does not display thread names and state?

Somewhere I've read that Eclipse versions before Juno do not display these information. Upgrade you Eclipse installation if this bugs you.

What happens if OpenOCD does detect ChibiOS but it is not yet initialized (i.e. because you inserted a breakpoint on main)?

What happens if I got a stack overflow which corrupted thread registry?

In those cases the ChibiOS rtos code will fake one single thread which is named Current Execution and has a warning in it's extra text. OpenOCD will also output more detailed error messages.

Is the OpenOCD ChibiOS code future prove for newer ChibiOS code?

Yes. Since all target and ChibiOS specific offsets are saved in the ChibiOS/RT memory signature record. Even if the record is extended in the future, the ChibiOS code will assume compatibility and continue working.

I get the message: Info : It looks like the target might be running ChibiOS without ch_debug.

The ChibiOS/RT memory signature record is not included in your build. This is either because:

  1. Your ChibiOS/RT version is too old.
  2. ch_debug has been removed by gcc garbage collection
  3. Some other error I cannot think of

I get the message: Memory signature identifier does not contain magic bytes.

This message mostly pops up if program debugged with gdb (the elf file) does not match the flash memory of the controller. Make sure you flash the program.

More background: The loaded elf file does contain the symbol of the memory signature record. But when openocd tries to read the signature at the given location on the target, it does not contain the magic sequence of bytes.

My thread list is all garbled and the threads do not show the current point of execution, not to speak of a correct backtrace

Do you use hardware FPU on Cortex M4? If yes, do not - it will mix up the stacking order. If no, please report it as a bug.

chibios/community/setup/openocd_chibios.txt · Last modified: 2012/11/06 17:44 by mabl
Except where otherwise noted, content on this wiki is licensed under the following license:GNU Free Documentation License 1.3