HOWTO: Reflash using JTAG and OpenOCD

Introduction to OpenOCD
OpenOCD (Open On-Chip Debugger) is an open source JTAG and debugging interface for ARM processors originally designed as a thesis project by Dominic Rath. The openocd daemon provides both a simple command line interface over telnet, and a GDB interface for more sophisticated debugging.

Further details about OpenOCD can be obtained from these sources:


 * OpenOCD Wiki
 * OpenOCD Quick Reference Sheet

Tested Environment
The following instructions were carried out on an 8-year old IBM ThinkPad 570 running Ubuntu Linux 7.10 and using an Olimex ARM-JTAG parallel port wiggler. For the most part, these instructions should be valid for other combinations of operating system and JTAG cables with few or no modifications. Windows users can find a pre-built OpenOCD installer, complete with the most common JTAG cable drivers, on the YAGARTO web site.

The gumstix used was a connex 400xm, with a custom built JTAG PCB based on the designs in.

OpenOCD Installation
On *nix platforms, the easiest way to install OpenOCD is to get the latest source code from the Subversion repository (revision 285 as of February 9, 2008):

$ svn co svn://svn.berlios.de/openocd/trunk OpenOCD

NOTE: OpenOCD revisions prior to ~272 may not work with verdex motherboards.

Building OpenOCD requires a C compiler (typically gcc), the GNU Autotools (autoconf and automake), and texinfo. The options passed to the configure script determine which cables are supported. In this example, only the configure options for a parallel port wiggler are used. For the full list of available options, run ./configure --help after ./bootstrap. To build OpenOCD, run the following from the OpenOCD directory created above:

$ ./bootstrap $ ./configure --enable-parport --enable-parport_ppdev $ make

Finally, to install OpenOCD:

$ sudo make install

or

$ su
 * 1) make install

Windows users should follow the instructions with the installer from YAGARTO.

Reflashing Procedure
The following steps describe how to reflash a gumstix using OpenOCD. Please read through them completely before starting, as some (in particular, step 10) are time sensitive.

1. Download the appropriate configuration (.cfg) and script (.script) files for your gumstix:

If you are not using a parallel port wiggler, you will need to change this section of the .cfg file to reflect your JTAG cable (configurations for many cables can be found in the OpenOCD info pages, and on the OpenOCD wiki):

interface parport parport_port 0 parport_cable wiggler jtag_speed 0 jtag_nsrst_delay 200 jtag_ntrst_delay 200 reset_config trst_and_srst
 * 1) CHANGE THIS TO MATCH YOUR CABLE ###
 * 1) use combined on interfaces or targets that can't set TRST/SRST separately

2. Attach the gumstix to the JTAG board and connect all cables except power (i.e. JTAG and serial).

3. In a terminal window (or a dedicated program such as HyperTerminal), open a serial connection to the gumstix's console. The wiki describes several ways of doing so here.

4. Connect the power supply.

5. In a second terminal window, change to the directory containing the downloaded configuration files and scripts, and run

$ openocd --file basix-connex-xm.cfg

Replace basix-connex-xm.cfg with the appropriate file name for your gumstix.

6. In a third terminal window, run

$ telnet localhost 4444

This connects to the OpenOCD console.

NOTE: If you're using a verdex, then for steps 7, 8, and 9, use address 0x5C000000 rather than 0xA3F00000.

7. At the OpenOCD console prompt run > load_image  0xA3F00000 bin

Wait while the bootloader is downloaded into the board's RAM. On the machine used for testing this procedure, this takes ~20 seconds.

8. [OPTIONAL] Run

> verify_image  0xA3F00000 bin

This ensures that the download was successful.

9. Start U-Boot by running

> resume 0xA3F00000

10. Quickly switch to the open serial terminal and press any key to prevent U-Boot from trying to load Linux (it may stop on its own, complaining about a bad magic number if you are using the older flash partitioning system - this is OK). If Linux does start to boot, switch back to the OpenOCD prompt and type

> reset init

After the initialization completes go back and repeat steps 7-10.

11. Follow the usual instructions on this wiki for reflashing U-Boot and the filesystem over serial.

12. After you have powered off the gumstix, switch to the OpenOCD prompt and shut down the OpenOCD server by running

> shutdown

13. Disconnect the JTAG cable.

If all went well you should now have a completely reflashed gumstix.

Origin of this HOWTO
This HOWTO was originally written by Andrew MacIsaac for Cetacea Networks Corporation. It was released to the public on December 20, 2007.