Table of Contents


gdb is the one and only standard debugger for the GNU toolchain. Learning and understanding gdb will not only help you do source level debugging on kernel, driver, libraries and applications, but will also improve your productivity. While graphical front ends like DDD, insight and eclipse simplify the interface to gdb, understanding gdb at a command line will also help you run the graphical front ends better.

gdb is not the only way to resolve issues -- check out debugging_applications for other methods.

gdb is part of the Blackfin toolchain and can be found on the Blackfin Linux website here. Click on the Files tab to obtain the latest release of gdb. To install gdb (for Ethernet or serial), since it is not packaged separately, check the instructions on installing the Blackfin toolchain to either build from source, or use a pre-compiled rpm for your system. If you want gdb for jtag you must install that separately. See the gdb/jtag site for more information.

There are two main types of code which need to be debugged:

Debugging Single Applications

For more information see Compiling the Kernel and Adding User Applications.

To debug your program, the uClinux distribution must be build in a specific manner:

  1. add the program gdbserver as well as the application you wish to debug.
    • gdbserver is found in the Application Configuration window (displayed by choosing Customize Vendor/User Settings) under the Miscellaneous Applications category. This is normally set by default in the Analog Devices configurations (the entry may be marked as (old) and help text saying “mk68k targets only”- but this entry is OK).
  2. make the uImage.
  3. load this memory image onto the target system and boot the kernel and distribution.
  4. compile the application to debug with the ”-g” flag. This adds debugging information which GDB can work with. Also - to improve debug, set the optimization level to zero: ”-O0”.
  5. Load symbols into GDB from:
    1. if user-app is built into FLAT binary (bfin-uclinux-gcc), use the user-app.gdb file.
    2. if user-app is built into fdpic ELF binary (bfin-linux-uclibc-gcc), use the user-app directly
  6. since gdbserver can communicate with the host computer through a serial connection or through an Ethernet connection, you must decide which you want to do.

Debugging Via Serial Port

The following instruction explain how to remotely debug uClinux programs via the serial port.

This assumes you are connecting to gdb through the device ttyS1 on the target system.

Once gdb is running on the Linux host type the following command at the gdb prompt to connect to the target system: gdb) target remote /dev/ttyS0 (This assumes you are connecting to gdbserver through the device ttyS0 on the Linux host)

From the gdb prompt on the Linux host computer you should now be able to enter any standard gdb command.

Debugging Via Ethernet

The following instruction explain how to remotely debug uClinux programs via an Ethernet connection.

Once gdb is running on the Linux host type the following command at the gdb prompt to connect to the target system:

gdb) target remote <IP address of target system>:3456

(The port number must be the same as the port number that was specified when starting gdbserver)

From the gdb prompt on the Linux host computer you should now be able to enter any standard gdb command.

Debugging Dynamic Object Libraries

The way to debug dynamic object library by GDB is nearly the same as that of application. Only several differences:

  1. User object library should be compiled with flag ”-shared -mfdpic -g -ldl”.
  2. User application usertest should be compiled with flag ”-mfdpic -g”.
  3. Library and should be copied to folder “lib” in the root file system image first. User application “usertest” should be copied to a proper position in the same image.
  4. Start GDB on host with the user application.
     /> bfin-uclinux-gdb usertest
  5. Don't forget to set GDB environment variable solib-search-path to the library folders, where and can be found.
    (gdb) set solib-search-path /library-directory/
    In case there are multiple library paths to be searched: 
    (To be safe you need to set solib-absolute-prefix to some non-exist directory so GDB only use solib-search-path).
    (gdb) set solib-absolute-prefix /non_exist_dir
    (gdb) set solib-search-path /home/test/toolchain/bfin-linux-uclibc/bfin-linux-uclibc/runtime/lib:/home/test/kernel/uclinux-dist/staging/usr/lib
    (gdb) info sharedlibrary 
    From        To          Syms Read   Shared Object Library
    0x00248c78  0x00269b34  Yes         /home/test/kernel/uclinux-dist/staging/usr/lib/
    0x00c88310  0x00c8834c  Yes         /home/test/toolchain/bfin-linux-uclibc/bfin-linux-uclibc/runtime/lib/
    0x02628490  0x02682ae4  Yes         /home/test/kernel/uclinux-dist/staging/usr/lib/
  6. Run application on target board and connect gdb to it.

Debugging Kernel

Kernel debugging can be done similar to application debugging. The host based tools are exactly the same, and are installed in the same manner. However, the choice is to do kernel level debugging over ethernet/UART (using KGDB) or JTAG (using gdbproxy).

Debugging with KGDB

In the 2008R1.5 release and older, you need to patch the kernel with the KGDB patch before start debugging. Refer to kgdb_2008R1.5.

In the 2009R1+ release, kgdb has been supported in mainline kernel already, no additional patch is needed. Refer to kgdb.

Debugging via Jtag (gdbproxy)

Normally, most people are satisfied with debugging with gdb via Ethernet or serial as described above, but in some circumstances (debugging some kernel drivers, or debugging boot loaders), lower level debugging is required. JTAG debugging supports this need. Please refer to gdbproxy

Common gdb Commands

A summary of some common gdb commands are given below:

gdb provides much more functionality that cannot be covered here. Click here for the gdb manual.

There are some advanced time saving gdb scripts, which can be used with kgdb and gdb. Check out the gdb snippets section.

Using a Graphical Debugger

Insight Insight is a graphical user interface to GDB, the GNU Debugger written in TCL/Tk by people working at Red Hat, Inc. and Cygnus Solutions. It is combined together with GDB, and built together with GDB.

Starting with the 2007R2 toolchain, insight has been integrated into the normal toolchain build. Invoking one of bfin-elf-insight or bfin-linux-uclibc-insight or bfin-uclinux-insight will start the Insight.


Data Display Debugger (ddd) is a graphical front-end for command-line debuggers such as bfin-uclinux-gdb. For most distributions of Linux, ddd can be installed through the host package manager; alternately, the source code for ddd is available here for you to compile yourself. The complete ddd manual can be found formatted in html or as a pdf. The problem with DDD is that the upstream development is not terribly active. However, it is usable, especially for people who are not familiar with GDB commands.

Once ddd is installed you must ensure that the correct gdb program will be used. To remotely debug uClinux programs, the Blackfin bfin-uclinux-gdb program described earlier must be used. To remotely debug the kernel, the Blackfin bfin-elf-gdb program should be used. To use ddd with either, invoke ddd with the -debugger option.

ddd –debugger bfin-uclinux-gdb

An overview of the main ddd window is given below. It's also an example of the beginning of a typical debugging session. See the command line window of ddd in the following screen shot for using file and target remote to connect to the target board:

Source Text Window

This window shows your source code along with any breakpoints you have inserted. The arrow indicates the next line of source code to be executed.

GDB Console

This window shows the output from the gdb program. You can also enter gdb commands in this window.

Command Buttons

These buttons execute some common ddd and gdb commands.

Argument Field

This text field sets the value for the argument () which is passed to the commands executed by the command buttons. In this example clicking on the breakpoint command button would clear the breakpoint at myprog.c:5 (myprog.c line 5) as this is the value in the argument field. The current line or text selection in the source text window is written to this field. You may also type a value into this field.


Eclipse is an excellent IDE framework. It supports a lot of plug-ins and the eclipse community keeps growing. In another page debugging_using_eclipse, we introduced how to set up eclipse for debugging on Blackfin uClinux. Since Eclipse is written in Java, it requires more memory for development system. Eclipse talks with GDB using Machine Interface, while DDD is using command interface. Machine Interface is considered to be more stable.

The GNAT Programming Studio (GPS) GPS, the GNAT Programming Studio, is a Free Software IDE. With its intuitive interface, GPS is easy to use, simplifying source navigation and highlighting the fundamental ideas in the program.

Compared the DDD, the debugging interface looks much like modern IDEs.

GPS is invoked the same way as DDD:

ddd –debugger bfin-uclinux-gdb

And here is a snap shot:

External Resources