JTAG OpenOCD Toolchain under Ubuntu 10.04

We have choosen to write this for Ubuntu because it seems to be the choice for people starting with Linux today (and we use it) and we have chosen to use 10.04 because it is a long term support (LTS) version. The steps should be able to be used on most systems with the package management steps changed appropriately.

  1. Setup your JTAG hardware
  2. Download and install Latest Codesourcery G++ lite EABI
  3. Download and install StellarisWare Packages
  4. Install OpenOCD and other utilities
  5. Download examples, modify the makefile and compile
  6. Use OpenOCD by hand, and perl script
  7. Download, install and configure editor/IDE

We would like to acknowledge that we learned how to setup this kind of toolchain from: http://fun-tech.se/stm32/index.php though this guide is significantly modified for our tastes and Stellaris parts.

This guide is used across our development boards any place you see <boardName> please replace it with the name of your board. IE Eridani, Cygni, Procyon, etc.

Setup your JTAG hardware

Hardware under Linux is one of those things, it tends to either work automatically or be very hard to make work. There is no way a guide could cover all possible hardware so here we just try to explain for the JTAGs we have used.

First thing is to plug in the JTAG, which presumably is USB based.

lsusb will give a listing of the usb devices attached to your computer. The first part of the ID string is the vendor ID the second part is the product ID.

Most inexpensive JTAGs are FT2232 based, for this I am assuming yours is (Ti's ICDI, Dangerous Prototypes Bus Blaster and Olimex's ARM-USB-TINY are; these are the JTAGs we have tested with). The FTDI driver is in the Linux kernel. The some kernels in the 2.6.32 series have had bugs in the FTDI driver. It is suggested that you use the latest kernel but if you have any issue kernel 2.6.32-26 is known to work with the JTAGs mentioned.

On Ubuntu these FTDI based serial devices can only be accessed with sudo unless you create special rules for them.

Open a terminal and goto:

cd /etc/udev/rules.d/

open your favorite text editor and make a new file:

sudo gedit 82-ftdiusb.rules

the file contents should be something like this:

BUS!="usb", ACTION!="add", SUBSYSTEM!=="usb_device", GOTO="kcontrol_rules_end"

# Just an extra serial port (Sparkfun FT232R)
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="664", GROUP="plugdev"

ATTRS{idVendor}=="15ba", ATTRS{idProduct}=="0004", MODE="664", GROUP="plugdev"

# Bus Blaster 2
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="664", GROUP="plugdev"

# TI/Luminary Stellaris Evaluation Board (several)
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="bcd9", MODE="664", GROUP="plugdev"

# TI/Luminary Stellaris In-Circuit Debug Interface (ICDI) Board
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="bcda", MODE="664", GROUP="plugdev"


You basically just need to add:

ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="664", GROUP="plugdev"

for each FTDI device you want to use in user space (without sudo). This code lets members of plugdev use the device. The default Ubuntu account should be a member of this group. If the device isn't there nothing bad will happen.

Use lsusb to find XXXX and YYYY for your JTAG.

These rules aren't in effect yet, the easiest way to have them active is just to reboot (I don't know a special command).

Download and install Latest Codesourcery G++ lite EABI

You may download the latest version of G++ EABI from here. The version at the time of writing was 2010.09-51.

G++ EABI is a cross compiler for ARM programs running without an OS.

To install successfully you need to change a few things:

sudo dpkg-reconfigure -plow dash -- > Answer **NO**

This changes the shell to bash.

Check that it is the default shell:

ls -lh /bin/sh

This should result in something like:

lrwxrwxrwx 1 root root 4 2011-01-23 11:09 /bin/sh -> bash

Now we can run the installer:

/bin/sh arm-YOURVERSIONNUMBER-arm-none-eabi.bin 

For this guide we accepted all of the defaults on install. It should be the default but be sure in the path step that the path is added for the user you wish to complete your development with.

The path is added to .profile for which is executed on startup, you can either rerun that whole script or add the path for this boot by hand:

PATH="/home/YOUR USER NAME/CodeSourcery/Sourcery_G++_Lite/bin:${PATH}"
export PATH

Check that everything is setup correctly:


It should say:

arm-none-eabi-gcc: no input files

Download and install StellarisWare Packages

Go to Ti's site and get the complete StellarisWare here.

The most recent version we have used is SW-LM3S-8264, but newer versions should be fine as well. If the complete package is too large you can get most of functionality with StellarisWare Driver Library standalone package.

Create a folder called “Development” in your home directory.

Although this file is an .exe it actually contains a ZIP of all the examples and codes, just double click on it and the archiver will open. Extract the files to:


Create a directory called <boardName> in your Development directory when you are done installing the StellarisWare software.

Install OpenOCD and other utilities

We are going to make OpenOCD from scratch. There is a binary of OpenOCD in 10.04 but it is not the most recent version. At the time of writing 0.4.0 was the latest stable version. Lots of features and fixes (and bugs) are always being added to OpenOCD, we have mostly been working with development snapshots of OpenOCD if you run into problems with OpenOCD try the latest development version and see if they go away.

We are going to also install perl-telnet and gtkterm here.

OpenOCD is accessed via telnet, and perl-telnet lets us include a script in our makefile to make and flash the board all at once. If you don't want this functionality you don't have to install perl-telnet.

gtkterm is a serial port terminal program which we presume most people will want to have to do some serial port text I/O.

Let's install everything we need at once:

sudo apt-get install make libftdi-dev libftdi1 libtool subversion git-core automake texinfo libnet-telnet-perl gtkterm

That is a number 1 at the end of libftdi if you are retyping.

Now let's get the source and put it in our development directory:

cd ~/Development
git clone git://openocd.git.sourceforge.net/gitroot/openocd/openocd OpenOCD
cd OpenOCD

At this time we recommend you use OpenOCD 0.5.0 (a version after 8/2/2011 is needed for Cygni).

To do this use the following command:

git reset --hard v0.5.0

If you want to use the latest development release just leave this line out.

Now run the install scripts, and install:

./configure --enable-maintainer-mode --enable-ft2232_libftdi
sudo make
sudo make install

If you get any errors stop and figure out why before the next step. Sometimes “no rule to make jimtcl” would appear but adding make before make install seems to have fixed that error.

At the terminal try:


If everything is fine you will get:

Open On-Chip Debugger <version> (current time)

Download examples, modify the makefile and flash the board

All of the really important stuff is now installed. You should be able to proceed now with any text editor and a terminal.

First you need to download and unzip the examples for your board. For this guide we will assume they are in Development/<boardNameExamples>.

In the example zip there are files to support this toolchain as well as other toolchains.

Open the “makefilesettings” in the root of the example directory in your favorite text editor.

This file is included (added to) all the other make files, this lets us update one file to change the build settings across all our example programs. The MAKEFILE tells a program called make how to create our program. It specifies all sorts of information. If you would like to know more about the MAKEFILE you can read about it here. For now we just need to change a few lines in makefilesettings.

DIR_STELLARISWARE = the directory you installed StellarisWare to

Open a terminal and change to the blinky directory.



If everything is setup right now you will get no errors.

If you get an error you have made a mistake in the guide. Please review it again.

Use OpenOCD by hand, and perl script

Now we already installed OpenOCD but we really didn't use it, that is because it is hard to show how to use it without files contained in the example archive.

The critical file is openocd.cfg, while you can run openocd without this file it contains the information about what JTAG to use and what target to expect. The config file is setup for the Olimex ARM-TINY-USB interface but it is easy to change this to something else is needed, the following is Eridani's openocd.cfg:

# Change this line for your interface of choice
source [find interface/olimex-jtag-tiny.cfg]

set CHIPNAME lm3s3651
source [find target/stellaris.cfg]

This file calls two much longer files to setup everything. Basically the only line you might need to change or replace with a few lines of code is:

source [find interface/olimex-jtag-tiny.cfg]

You will find other interfaces in:


Open openocd.cfg in the root of the examples directory and make any needed changes for your JTAG.

Next run ./updateOpenOCDcfg.sh

This will update all of the copies of openocd.cfg in your example directory with the changes you have made.

Power the board in some way as per the the board documentation. The power light will be on.

We already made the blinky exmaple. Attach your JTAG to the board and open a terminal in the blinky directory:


You should get something like:

Open On-Chip Debugger <version> (current time)
Licensed under GNU GPL v2
For bug reports, read
500 kHz
500 kHz
jtag_nsrst_delay: 100
srst_only separate srst_gates_jtag srst_open_drain
Info : clock speed 500 kHz
Info : JTAG tap: lm3s3651.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3)
Info : lm3s3651.cpu: hardware has 6 breakpoints, 4 watchpoints

This last line is the power of the JTAG really, you can pause the execution of the code with breakpoints! We aren't going to cover that at length here but that is one of the reasons you'd want to use a JTAG over simple bootloader in-circuit programming.

Now openocd is attached and running. If you weren't able to get the JTAG to work you might have a problem with your udev rules. You can try running under sudo. If that doesn't work the JTAG isn't configured correctly in the script (or not supported), or the board isn't powered.

Let's flash the board by hand!

Open another terminal

telnet localhost 4444

You will get:

Trying ::1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger

It doesn't matter what directory you run telnet from. The directory you run openocd from does matter (path wise).

To see this example work attach a jumper to the pin used in blinky.c

The pin used for blinking the LED in blinky.c is:

Board Pin
Eridani D0
Cygni B0
Procyon B5

To flash the board we need 3 commands:

reset halt

This stops the code from running. You don't want it trying to read the flash you are writing (and it won't let you). It will say target state halted if it works and some pointers.

flash write_image erase blinky.bin

This command erases the flash and writes the .bin file you compiled. It should write 1024 bytes.

reset run

This command restart the microcontroller and runs the code. Your board will be blinking now.

If all you want to do is flash the board, there is a nice little make command in the makefile:

make flash

This runs the commands above after making the binary. It still requires openocd to be running in the directory the .bin file will be created in but it is a convenient way to flash for iterative changes in simple programs that do not need breakpoint debugging.

To start using breakpoints and debuggers you simply halt the microcontroller in openocd:

reset halt

Then attach the debugger of choice. The port is 3333 for debugging with OpenOCD.

If you want more details on how to get started with this (it isn't chip specific), a good page is here: http://fun-tech.se/stm32/OpenOCD/gdb.php

Download, install and configure editor/IDE

There are many editors which you could use. In Linux the field is wide open. For something simple gedit will due. It is really up to your taste.

If you want to do hardware GDB debugging you may wish to read our Eclipse based guide.

Goodluck and enjoy!

toolchain/jtaglin.txt · Last modified: 2014/08/01 20:14 (external edit)
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki