Table of Contents
JTAG OpenOCD Toolchain under Windows
This guide is tested under Windows 7 but should work on other versions as well.
- Install Drivers for your JTAG
- Download and install Latest Codesourcery G++ lite EABI
- Install and setup Cygwin, OpenOCD, and other utilities
- Download and install StellarisWare Packages
- Download examples, modify the makefile and compile
- Use OpenOCD by hand, and perl script
- 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 and for the modifications for Cygwin we referenced: http://forum.sparkfun.com/viewtopic.php?f=18&t=11221
You may wish to install a terminal like teraterm or putty as well for telnet and serial port access. Although we will install a command line telnet inside of cygwin.
This toolchain is designed to be compatible with the serial windows chain as much as possible.
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.
Install Drivers for your JTAG
When you plug-in your JTAG in Windows you will be prompted to install drivers. Make sure everything is nice and happy with your hardware before continuing. When we compile OpenOCD later you may need to change an option or two to support your JTAG device. We presume it is a USB FT2232 device for this tutorial and the steps here should work in that case.
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.
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.
Check that everything is setup correctly by opening a command prompt and running:
If the path is set up correctly it should say:
arm-none-eabi-gcc: no input files
Install and setup Cygwin, OpenOCD, and other utilities
OpenOCD could be made to work under MinGW, but Cygwin is a more full environment and lets the two JTAG guides have more similarity in how they are installed. These instructions are for the native FTDI drivers and not libftdi. Your mileage may vary with what you build against and what JTAG you are using. We tested this build against ARM-USB-TINY. A good resource builds of OpenOCD in windows is here.
Cygwin is sort of like WINE is for Windows under Linux it is a layer that lets you use standard *nix tools under Windows.
Download setup.exe for Cygwin and run it.
You should probably install with the defaults, (C:\cygwin, etc just to keep everything normal). You don't need to change anything until we get to the “select packages” step.
Here we need a bunch of stuff that isn't default.
Under “Development” add the following:
Under “Net” add inetutils
Under “Perl” add perl
Under “Web” add wget
Click next and you will see there are a ton of dependencies that also need to be installed. This is as it should be I tired to minimize the clicking. The checkbox to install all these extra packages should be checked and you can just click next.
Cygwin will then download everything and install itself.
When it is done Windows will likely complain that it might not have installed correctly. It did.
Right click the cygwin shortcut and goto options, there: check the quick edit box. This will allow you to paste by right clicking the mouse in a cygwin terminal.
Next we want to setup a new system variable in Windows called HOME. This is under Control Panel→ System and Security → System→ Advanced Settings
Click on Environmental Variable and then New
Create an entry:
Variable name: HOME Variable value: C:\Users\yourUserName
Now we need to run some commands to get the stuff we need and setup our environment:
mkdir ~/Development cd ~/Development mkdir ftdi
Goto: http://www.ftdichip.com/Drivers/D2XX.htm and get the latest driver for FTDI (for this guide I used: 2.08.08.) and extract the contents to the ftdi directory you just made (C:\Users\USERNAME\Development\ftdi).
The ftdi directory should now contain: amd64, i386, static, ftd2xx.h…
Finally it is time to start building OpenOCD!
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:
./bootstrap ./configure --enable-maintainer-mode --disable-werror --disable-shared --enable-ft2232_ftd2xx --with-ftd2xx-win32-zipdir=/cygdrive/c/Users/USERNAME/Development/ftdi make make install
Be sure to change USERNAME above. It might take a while to completely compile. 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 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 user directory (the parent folder of My Documents).
You should install this to the Development (eg: C:\Users\your_user_name\Development\StellarisWare) directory you created and not to C:\ which is the default. Under Windows 7 and Vista C:\ access can require admin elevation which gets old fast.
Create a directory called <boardName> in your Development directory when you are done installing the StellarisWare software. I also created a shortcut to Development for my desktop.
At the end of the install I was warned that the program may not have installed correctly. This is because the installer is not aware of Windows 7. These packages can be opened as a Zip file as well under Linux/OS X.
Download examples, modify the makefile and compile
All of the really important stuff is now installed. You should be able to proceed now with any text editor and the command prompt. In the last step we will make it a bit more convenient than that, but now we should try to use all the nice tools we installed.
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.
SERIALPROG = 0 WINDOWS = 1 DIR_STELLARISWARE = the directory you installed StellarisWare to
Open a command prompt 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 cygwin 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 http://openocd.berlios.de/doc/doxygen/bugs.html 500 kHz 500 kHz jtag_nsrst_delay: 100 srst_only separate srst_gates_jtag srst_open_drain Info : device: 4 "2232C" Info : deviceID: 364511236 Info : SerialNumber: FTS9P7YEA Info : Description: Olimex OpenOCD JTAG TINY A Info : clock speed 500 kHz Info : JTAG tap: lm3s3651.cpu tap/device found: 0x3ba00477 (mfg ba00, 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 that doesn't work the JTAG isn't configured correctly in the script (or not supported), the board isn't powered, or OpenOCD was not built correctly for the JTAG.
Let's flash the board by hand!
Open another cygwin terminal
telnet localhost 4444
You will get:
Trying ::1... Trying 127.0.0.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). If you prefer you can use putty or similar as a telnet client.
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:
To flash the board we need 3 commands:
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.
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:
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:
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. For the purposes of this guide we will configure Programmer's Notepad because it is small, simple to use and because of its wide spread use with the WinAVR package.
To finish our toolchain let's add shortcuts to the 3 most common tasks make: all, clean and flash.
Note: to use make flash with this toolchain you will need OpenOCD running in the correct directory before executing the command.
Download and install Programmer's Notepad. You may install it anywhere.
Run Programmer's Notepad when done.
Click on tools, in the left hand bar
Change the scheme to C/C++, and click Add
Fill in the following:
Name: cs-make all
Save: Current File (this is up to you, it will save the file before running the command if you select this).
Add two more commands the same way changing parameters and name to “flash” and “clean” in place of “all”.
Open the blinky.c file that you already fixed the makefile for in the previous step.
Change the delay for the blink if you wish and have the device ready to program. Then run the “cs-make flash” command.
The output will appear and you can dock it by dragging it to the bottom of the program window if it isn't already. With the skeleton code in “basic” example you should be ready start writing your own code. The library documentation is useful reading.