Sections
You are here: Home → Documentation → Tutorials → Debug with OpenOCD

Debug with OpenOCD

Note: Return to tutorial view.

This tutorial will go over how to do in-circuit debugging with OpenOCD via JTAG.

Overview

A bit about OpenOCD and the tools we need in order to use it.
OpenOCD (Open On Chip Debugger) is an open source tool by Dominic Rath that allows for breakpoint debugging of the Make Controller, and many other microcontrollers.  With a piece of JTAG hardware and the open source Eclipse development environment, we can get set up to do single step break pointing in code written on the Make Controller for free.

Note: this tutorial is a bit of a work in progress.  There is definitely scope for improving some of the configuration, etc.

One of the big caveats is that this is a Windows-centric setup at the moment.  Ideally, OpenOCD and the requisite Eclipse plug-ins should be able to be compiled to run on OS X and other *nix platforms as well, but currently the pre-built releases of these programs support mainly Windows.  Sorry.  If you have some success building them for other platforms, please let us know!

In setting up to debug the Make Controller with open source tools, there are a few other resources and tutorials that are also quite useful:

Now, on to the setup.

Hardware

Before we can do anything at all, we need the device that allows our PC to connect to the debug port on the Make Controller.  The JTAG debug port is the 2x10 pin connector near the USB port. 

This tutorial will detail how to get OpenOCD set up using the ARM-USB-OCD JTAG device from Olimex.  OpenOCD supports a handful of other JTAG devices as well, but this seems to be one of the nicer ones, and works over both serial and USB connections.  At the time of this writing, these devices are available for about $72 from SparkFun.
ARM_USB_OCD
Olimex's ARM-USB-OCD debugger

Downloads

There are a handful of downloads that will be necessary for us to get up and running.  Fortunately, they each have an installer, so it's pretty easy to get set up. 

Eclipse is normally a Java development environment, but there are many, many plugins that extend its functionality to other languages and much more.  There is an extension called CDT (C Development Tools) that allows for C/C++ development in Eclipse, which would normally be all we'd need to build firmware for the Make Controller.  However, to debug it we need to grab a modified version of CDT that incorporates the debugging functionality.  This was contributed by Zylin - thanks!

If you haven't already installed the YAGARTO tools, check the Build Firmware on Windows how-to.  In addition to those installations, we'll also need to install OpenOCD itself.

Once you've installed all of these, we're ready to move on an set up our tools in Eclipse.

Configure Eclipse

How to install and configure Eclipse properly in order to debug with OpenOCD.
We'll need to set up our project and several tools in Eclipse to streamline our debugging experience.  First, open up the version of Eclipse that you just installed.

New Project

We need to set up a new project in Eclipse to debug our program.  Follow the steps in the Eclipse how-to to set up your project.  This should get you to a point where you can compile new firmware versions.


External Tools

The way that our debugging will generally work is:
  1. Build new code that we want to test
  2. Upload our newly compiled code to the board
  3. Start the OpenOCD daemon - this will wait for connections from a GDB debug session running in Eclipse, and send those debug messages to the board via our ARM-USB-OCD JTAG device.
  4. Start our debug session in Eclipse and step around through the code.

Eclipse provides a nice way for us to fire up these processes at the click of a button, but of course there's a little setup involved.  We're already set up to build new code, so we'll move on to uploading our new code to the board.

Upload New Code via ARM-USB-OCD

In your project, click the little arrow on the right-hand side of the External Tools icon in the menu bar, and select External Tools...
  • Create a New Configuration, and name it whatever you like. I've chosen OpenOCD - upload to distinguish it from the OpenOCD - debug configuration that we'll create in just a moment.
  • In Location, specify the path to your openocd tool
  • In Working Directory, specify the path to the directory with the OpenOCD scripts
  • In Arguments, specify that OpenOCD should use the makeController-uploadFirmware.cfg configuration script
  • Click the Common tab, and check the box in Display in Favorites Menu to add this configuration to the menu bar for easy access
  • Click Close
Your external tool configuration should look something like the image below:

OpenOCD - upload
The OpenOCD - upload tool configuration

Fire Up the OpenOCD Daemon

  • Open the External Tools menu item again
  • Create a New Configuration, and name it whatever you like. I've chosen OpenOCD - debug.
  • In Location, specify the path to your openocd tool
  • In Working Directory, specify the path to the directory with the OpenOCD scripts
  • In Arguments, specify that OpenOCD should use the makeController-debug.cfg configuration script
  • Click the Common tab, and check the box in Display in Favorites Menu to add this configuration to the menu bar for easy access
  • Click Close
Your external tool configuration should look something like the image below:

OpenOCD - debug
The OpenOCD - debug configuration

If you want to test out the debugger, click the External Tools icon in the menu bar and select OpenOCD - debug.  You should get some output in the Console that looks like:
Info:    openocd.c:82 main(): Open On-Chip Debugger (2006-10-12 18:00 CEST)
Warning: arm7_9_common.c:683 arm7_9_assert_reset(): srst resets test logic, too
The OpenOCD daemon is now sitting there waiting for a debug session to start up.

Set Up the Debug Session

To set this up, click on the little arrow next to the bug icon in the menu bar, and select Debug...
  • Create a new Embedded debug (Native) configuration, and name it whatever you like. I've simply chosen heavy.
  • In Project, click Browse and select your current project
  • In C/C++ Application, click Search Project... and select the heavy.elf file.  You need to have already built the project once in order to create heavy.elf.
The main tab should look like:

debug-main
The Debug Main tab

  • Click the Debugger tab
  • Leave the Stop on startup checkbox checked
  • In GDB debugger, select the YAGARTO arm-elf-gdb executable
  • Clear out the GDB command file field
The debugger tab should look like:

debug-debugger
The Debugger tab

  • Click the Commands tab
  • Copy and paste the following commands into the Commands text field:
target remote localhost:3333
monitor reset
monitor wait 500
monitor soft_reset_halt
monitor arm7_9 force_hw_bkpts enable
The commands tab should look like:

debug-commands
The Commands tab

  • Finally, select the Common tab, and check the Debug checkbox within Display in favorites menu

We're all set.

 

Debugging

We finally get to actually stepping through our code.
Finally we're ready to start debugging.  As mentioned previously, the workflow is going to be as follows:
  1. Compile and upload new code.
  2. Fire up the OpenOCD daemon
  3. Debug the new program
Document Actions
Log in


Forgot your password?
New user?