1. Introduction

OpenOCD is a free open-source JTAG debugger for microprocessors with ARM7, ARM9 and related cores written by Dominic Rath. Some of the microcontrollers known to work with OpenOCD are ADuC7xxx, AT91R40008, AT91SAM7, AT91SAM9, AT91RM9200, EP93xx, LM3S811, LPC21xx, LPC22xx, LPC3xxx, STR7xx, STR9xx, STM32, XScale and many others using the ARM architecture.

OpenOCD is an ideal complement for the GNU GCC toolchain for ARM processors. It can be controlled from the GNU debugger GDB and from a Telnet commandline interface. OpenOCD is capable of driving a variety of open homebuilt or commercial JTAG hardware interfaces and can easily be adapted to new interfaces. It is licensed under the General Public License (GPL).

The following figure shows how OpenOCD fits in the overall picture. OpenOCD provides network connections for the GNU Debugger gdb and for an optional Telnet client. You can either run GDB and Telnet on the same machine on which OpenOCD runs or on different machines according to the networking nature of both protocols.

img/overall.png

OpenOCD talks to the target board by a JTAG interface. A number of open and commercial interfaces exist for plugging into the USB or Parallel Port and it is easy to add new interfaces. Most of the available interfaces are listed in section 5.

On startup OpenOCD reads one or more configuration files containing target specific configuration information. While the program is running it writes log messages to a logfile.

OpenOCD is available for Linux and Windows. This text will focus on Linux. Windows users should get the Yagarto distribution [3] containing a comprehensive and easy to install set of tools including OpenOCD and Eclipse.

2. Getting OpenOCD

OpenOCD is contained in the package pool of the major Linux distributions. For example the Debian package is available here:

http://packages.debian.org/unstable/embedded/openocd

The binary packages are very easy to install, on Debian e.g. with apt-get install openocd. However the version of these packages is sometimes a bit outdated. If you want the current release, you can easily check it out from the code repository with the Subversion command

svn co http://svn.berlios.de/svnroot/repos/openocd

To compile the software follow the build instructions in file openocd/trunk/INSTALL.

3. How to work with OpenOCD

All files needed to follow this short demo are available at [7]. I use an Olimex SAM7-P64 board ("target") and a USB JTAG adaptor.

The basic work with OpenOCD is very simple:

  1. Connect a JTAG cable between the PC and the target 20-pin JTAG header. Easiest is an USB to JTAG cable, see section 5.

  2. Optionally connect a RS-232 cable between the PC serial port and the target. Note that some JTAG adaptors also have a separate UART or RS-232 channel.

  3. Connect target to power (may also work over USB).

  4. Start OpenOCD 

       sudo openocd -f sam7s-oocdlink.cfg

    The configuration file oocd-demo.cfg contains some settings which OpenOCD needs to correctly start, the most important are

    1. JTAG adaptor type and speed

    2. Port numbers for telnet and gdb services

    3. Details of the reset signals for ARM controller and JTAG port

    4. Details of the JTAG chain

    5. Startup behaviour of the OpenOCD server

  5. Start a user interface to interact with the target. In the simplest case this will be a telnet connection established with 

      telnet localhost 4444

    The number 4444 is the port number of the telnet server built into OpenOCD. After telnet is running, about 90 commands can be entered from the telnet commandline (enter help at the telnet prompt).

    + From the telnet user interface one can do many tasks, e.g. download the program to RAM or Flash, run it, stop it and display registers. However, if it comes to source level debugging, you will need to run a real debugger:

      arm-none-eabi-gdb -x init.gdb

    The gdb configuration file init.gdb contains at least the port number of the GDB server, which is a part of the OpenOCD server and the name of the program which shall be loaded in the target.

    Gdb provides only a spartanic commandline user interface (though it is quite effective to use). Some more comfort provides the Data Display Debugger graphical front end to gdb. DDD is invoked as follows:

    ddd --debugger arm-elf-gdb --command=init.gdb main.elf

    DDD's home is at http://www.gnu.org/software/ddd

    Another nice front end is cgdb, which has a character-based GUI (http://cgdb.sourceforge.net). Run it with

    cgdb -d arm-none-eabi-gdb --command=init.gdb

  6. Start a terminal program

User interaction with the target board can easiest be achieved by using a serial connection ("UART", "RS-232"). On the development computer you need a terminal program to communicate over a serial line. One very easy to use terminal program is picocom. Start it with

  sudo picocom -b 9600 /dev/ttyUSB1

The -b option specifies the baud rate and the /dev/ttyUSB1 argument is the serial port device. In this case my USB JTAG adaptor has beside the JTAG port also a RS-232 interface — I highly recommend this! Some other often used terminal programs are ckermit, cutecom and minicom.

4. Screen

Usually you will have multiple windows open on your embedded development PC running the tools shown in the following figure:

img/windows.png

How the various windows are arranged and managed is left to the preferences of the user. I recommend to use the screen utility for this purpose. The following text describes how to use it.

The screen utility is capable to run multiple applications in one console window. Here is a part of the screen configuration file which starts all the necessary applications:

screen -t shell   1 bash
screen -t emacs   2 emacs -nw --load emacs.el
screen -t openocd 3 bash --rcfile startoocd.sh
screen -t gdb     4 bash --rcfile startgdb.sh
screen -t telnet  5 bash --rcfile starttelnet.sh
screen -t uart    6 bash --rcfile startpicocomm.sh

The following figure shows a screen-controlled console window. Look at the status line (bottom) showing all active tools:

img/screen.png

The screen homepage is at http://www.gnu.org/software/screen/screen.html.

5. Configuration files

Example: A sample configuration file for OpenOCD
# sam7s-oocdlink.cfg
# Openocd configuration for OpenOCD-USB connected to an AT91SAM7S64
# 2008-04-26 <Hubert.Hoegl@hs-augsburg.de>

#daemon configuration
telnet_port 4444
gdb_port 3333

#interface
interface ft2232
ft2232_device_desc "Dual RS232"
ft2232_layout oocdlink
ft2232_vid_pid 0x0403 0x6010
jtag_speed 4
reset_config trst_and_srst

#jtag scan chain
#   format L IRC IRCM IDCODE (Length, IR Capture, IR Capture Mask, IDCODE)
jtag_device 4 0x1 0xf 0xe

#target configuration
daemon_startup reset
#target arm7tdmi <endian> <reset mode> <chainpos> <variant>
target arm7tdmi little run_and_halt 0 arm7tdmi_r4
run_and_halt_time 0 30
Example: A sample GDB command file init.gdb
target remote localhost:3333
add-symbol-file bin/main.elf 0x200000
load bin/main.elf

6. JTAG Adaptors

Table: JTAG Adaptors
JTAG Adaptor Manufacturer Interface UART ca. Price (Euro) Business Model
OOCD-Link [a] USB (FT2232) yes - Open
USBJTAG [b] USB (FT2232) yes - Open
USBprog [f] USB (USBN9604) no 30 Open
JTGkey Amontec [d] USB (FT2232) no 129 Closed (Commercial)
JTAGkey-Tiny Amontec USB (FT2232) no 29 Closed (Commercial)
Chameleon Amontec Parallelport no 119 Closed (Commercial)
ARM-USB-OCD Olimex [e] USB (FT2232) yes 55 Closed (Commercial)
ARM-USB-TINY Olimex [e] USB (FT2232) no 40 Closed (Commercial)
Wiggler [c] Parallelport no 10 Open

[a] Will soon be available at http://www.embedded-projects.de.

[b] My attempts to build a USB-to-JTAG interface. PCB is not available but you can have all PCB data (http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html).

[c] The Wiggler cable is described here (beside others): http://wiki.openwrt.org/OpenWrtDocs/Customizing/Hardware/JTAG_Cable. It is available e.g. from [4].

[d] Amontec http://www.amontec.com

[e] Olimex http://www.olimex.com

[f] This one is the only USB-to-JTAG connector for OpenOCD which does not use an FT2232. Instead it uses a USB bridge USBN9604 and an Atmel AVR Mega32. The project home is http://www.embedded-projects.net.

Note that the FT2232 has two independent channels. While channel one is always used for JTAG debugging, the second channel can freely be used for another purpose, e.g. for driving the target serial port. Not all JTAG adaptors in the above table have the second channel available for use (see above table, column "UART").

7. References

[1] Home http://openocd.berlios.de

[2] Forum (Sparkfun). http://forum.sparkfun.com/viewforum.php?f=18

[3] Yargarto. http://www.yagarto.de

[4] Embedded Projects. http://www.embedded-projects.net, http://shop.embedded-projects.net.

[5] Reasonably priced target boards. Some firms building reasonably priced target boards usable with OpenOCD are Olimex (http://www.olimex.com), Embeddedartists (http://www.embeddedartists.com), Makingthings (http://www.makingthings.com), Embest (http://www.embedinfo.com) and Propox (http://www.propox.com). ARM products from Olimex are also available from [4].

[6] Documentation. The OpenOCD source tree contains a manual in GNU Texinfo format (see directory /doc/). From this file other formats can be created which can be used for online reading on the screen (info, html) or for reading on paper (pdf).

[7] Sample project. http://www.hs-augsburg.de/~hhoegl/proj/oocd-starter/index.html