Debugging User Application in PetaLinux

TracNav menu

Overview

This document describes how to debug user applications under the uClinux operating system for Xilinx MicroBlaze. The GDB debugger (and Insight graphical interface) is available for debugging applications on the MicroBlaze Linux target. To do so, it is first necessary to build the gdbserver helper application. gdbserver runs on the MicroBlaze, and acts as an interface between GDB running on the host, and the target application.

The debug scenario is illustrated in Figure 1.

Figure 1 PetaLinux Application Debugging Overview

Assumptions

The following assumptions were made in the preparation of this tutorial:

  • Basic familiarity with the PetaLinux development methodology
  • Existence of a working PetaLinux MicroBlaze system, including TCP/IP networking

Building the gdbserver application

Before debugging applications, the gdbserver helper tool must be built.

Gdbserver is a standard application provided as part of the PetaLinux distribution. Enable it in the PetaLinux menu-configuration process as follows:

Start the Kernel config tool. 

$ cd $PETALINUX/software/petalinux-dist
$ make menuconfig

Select the Customize Vendor/User Settings menu 

  ┌─────────────────── Kernel/Library/Defaults Selection ───────────────────
  │  Arrow keys navigate the menu.  <Enter> selects submenus --->.          │
  │  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, │
  │  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help.     │
  │  Legend: [*] built-in  [ ] excluded  <M> module  < > module capable     │
  │ ┌─────────────────────────────────────────────────────────────────────┐ │
  │ │             (linux-2.6.x) Kernel Version                            │ │
  │ │             (None) Libc Version                                     │ │
  │ │             [ ] Default all settings (lose changes)                 │ │
  │ │             [ ] Customize Kernel Settings                           │ │
  │ │             [*] Customize Vendor/User Settings (NEW)                │ │
  │ │             [ ] Update Default Vendor Settings                      │ │
  │ │                                                                     │ │
  │ └─────────────────────────────────────────────────────────────────────┘ │
  ├─────────────────────────────────────────────────────────────────────────┤
  │                    <Select>    < Exit >    < Help >                     │
  └─────────────────────────────────────────────────────────────────────────┘

Save and Exit from the menu.

Under the Miscellaneous Applications menu, select the gdbserver option. 

  ┌──────────────────────────────── Main Menu ────────────────────────────────┐
  │  Arrow keys navigate the menu.  <Enter> selects submenus --->.            │
  │  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes,   │
  │  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help.       │
  │  Legend: [*] built-in  [ ] excluded  <M> module  < > module capable       │
  │ ┌───────────────^(-)────────────────────────────────────────────────────┐ │
  │ │               Core Applications  --->                                 │ │
  │ │               Library Configuration  --->                             │ │
  │ │               Flash Tools  --->                                       │ │
  │ │               Filesystem Applications  --->                           │ │
  │ │               Network Applications  --->                              │ │
  │ │               Miscellaneous Applications  --->                        │ │
  │ │               BusyBox  --->                                           │ │
  │ │               Tinylogin  --->                                         │ │
  │ │               MicroWindows  --->                                      │ │
  │ │               Games  --->                                             │ │
  │ │               Miscellaneous Configuration  --->                       │ │
  │ └───────────────┴(+)────────────────────────────────────────────────────┘ │
  ├───────────────────────────────────────────────────────────────────────────┤
  │                     <Select>    < Exit >    < Help >                      │
  └───────────────────────────────────────────────────────────────────────────┘

Save and Exit from the menu.

Make sure the application you wish to debug, is also selected. Build and boot the system in the usual manner.

Debugging on the Target

On the MicroBlaze system, use the gdbserver application to launch your application 

# gdbserver host:1234 /bin/myapp
Process /bin/myapp created; pid = 50
Listening on port 1234

This tells gdbserver to listen on TCP/IP port 1234 for a remote debugging connection. You can pass any parameters to your application by appending them to the gdbserver command line, e.g: 

# gdbserver host:1234 /bin/myapp param1 param2 param3 …

Next, on the host development workstation, change into the directory where the application was built, e.g. 

[host]$ cd $PETALINUX/software/user-apps/myapp

Among the files in this directory, will be a file myapp.gdb – this is a special version of your application that helps the gdb debugger to work.

Launch the uClinux application debugger: 

[host]$ microblaze-uclinux-gdb myapp.gdb

!

When debugging uClinux applications, you must use the special version of the gdb debugging – `microblaze-uclinux-gdb`

Do not confuse this debugger with the “standalone” MicroBlaze debugger, `mb-gdb`.

GDB will start, and present a window similar to Figure 2.

Figure 2 MicroBlaze uClinux GDB start screen

Next, select File → Target Settings from the main menu. This will open the Target Settings Dialog box. The settings must match those shown in Figure 3 below, except for the IP address field, which must correspond to the IP address of your MicroBlaze target board (192.168.0.10 in this example). Finally, press OK to close the Target Settings dialog box.

Figure 3 GDB Target Settings dialog box

Now, press the “run” icon. GDB will connect with gdbserver on the MicroBlaze, and run your application until the start of the main() function.

You will see the following output on your MicroBlaze console, showing that the connection has been made (192.168.0.1 is the IP address of the host computer in this example): 

Remote debugging from host 192.168.0.1

A green highlight illustrates the current (yet to be executed) code line (Figure 4).

Figure 4 GDB ready for debugging

You can now use the various GDB control buttons to step into, over, and through function calls. The View menu allows you to display windows to inspect local variables, function parameters, memory and so on.

Clicking the mouse on the dash (‘-’) character to the very left of a source line will place a breakpoint, indicated by a red square (■). Figure 5 shows the program stopped at the first line of a function func1().

Figure 5 GDB stopped at a breakpoint

Any console I/O from the program will take place on the MicroBlaze console.

Finally, when the program terminates, gdbserver will display the output code and exit back to the shell: 

Child exited with retcode = 10

Child exited with status 16
GDBserver exiting
#

To debug the program again, start gdbserver again on the target, as before. You should also exit, and restart, the microblaze-uclinux-gdb application on the host, when starting a new debug session. The target settings, any breakpoints, and display windows will all be retained between sessions.

i

When C programs are compiled with optimisations enabled, the compiler typically performs code optimisations and re-ordering that can make debugging confusing, if not impossible. Therefore, it is recommend that if you wish to debug your application, you compile it with no optimisations (-O0).

In PetaLinux, this is best achieved by adding the following line at the top of the application’s Makefile

CFLAGS += -O0

Command line debugging

The debugger may also be used in command line mode, by starting it on the host with the “-nw” parameter: 

[host]# microblaze-uclinux-gdb –nw myapp.gdb

Start gdbserver on the target in the normal way. Connect by entering the following command on the gdb console (substituting the correct IP address as necessary): 

gdb% target remote 192.168.0.10:1234

Breakpoints are set with the break command, e.g. to set a breakpoint at the start of the main() function: 

gdb% break main

To single step, use the step command: 

gdb% step

To step over functions, use the next command: 

gdb% next

Going further

For more information on the gdb tool, consult the GNU manual, available online at http://www.gnu.org/software/gdb/documentation/

Attachments