Debugging

Using gdb

Some boards provide a JTAG interface, which makes it feasible to perform live debugging via gdb. These platforms usually provide an additional target in the Makefile system called debug, so that simply calling make debug should start a debugging session. Sometime this starts only a remote target to be used with gdb as explained, for example, here for the IoT-LAB_M3.

debugging a RIOT application which spawns a shell with gdb

If you have a RIOT application which uses the shell for interactive input, and still want to use the gdb debugger to step through something caused by that interaction, you can do so using the program parameter. Let's go through this step by step, using the default app that can be found in RIOT/examples/default:

In terminal window #1, compile and start your RIOT application.

make
sudo ./bin/native/default.elf tap0

In terminal window #2,
use pgrep to find out the PID of your RIOT app.

pgrep default
> 2987

Then, instruct gdb to attach to that program

gdb program 2987

(If you are positive that there is only one instance of your app running, you can also run gdb program $(pgrep default) instead.)

Now, you can set your breakpoints in gdb as usual. If you're done with your preparation, type

continue

into your gdb window.
Switching back to terminal window #1, you can now use you RIOT app as usual. (Until a breakpoint is hit, then you'll have to type continue into gdb again to “un-freeze” the app)

Using printf

On other platforms, such as the MSB-A2, or when you don't have physical access to the JTAG interface, there's no other possibility to debug your code than using printf-debugging. In order to help you with that RIOT provides the macros DEBUG and DEBUGF that can be enabled on a per file basis, by adding something like this at the beginning of the file:

#define ENABLE_DEBUG  (1)
#include "debug.h"

You will find this pattern already in several RIOT files. When ENABLE_DEBUG is set to a positive value, DEBUG is a simple replacement for printf(), while DEBUGF adds the information about the file and line number to the beginning of the output. When building with DEVELHELP the macros additionally check if the stack size of the currently running thread is big enough to call printf.

If ENABLE_DEBUG is set to zero, the macros are ignored.

Please note: As written, this kind of debugging works intentionally only per file. You have to define ENABLE_DEBUG in every file you want to debug.