Running OpenOCD on Windows

OpenOCD provides a command line interface for interacting with embedded devices. To use OpenOCD you will need to run it from the command line. This guide includes basic information about using the Windows command line. If you are already proficient with the command line, you can find information specific to OpenOCD under the OpenOCD Config Files and Telnet Connection headings.

Opening the Command Prompt
Open the Start Menu and click on Run... A small dialog box will appear. Type:

cmd

...and click OK. In Windows 7/Vista, the Run command does not appear in the Start Menu by default. To enable it, see Configuring Windows 7 for OpenOCD.

Command Prompt Basics - Paths and Navigation
The command prompt displays your current directory location. You will need to navigate to the OpenOCD directory to run it. To change directories, type 'cd followed by a file path. File paths can be absolute...

cd \Program Files\TinCanTools cd C:\windows\system32

...or relative...

cd Program Files cd TinCanTools/openocd

Absolute paths are from your root directory, and begin with a slash or the current drive letter. Relative paths are from the current directory and do not begin with a slash. Absolute paths use forward slashes (\) and relative paths use backslashes (/). File paths are not case sensitive.

If you need to move to a new drive, type the drive letter followed by a colon...

E:

If you need to go back to the parent of the current directory, you can type...

cd ..

You can even use this as part of a longer relative path. For example...

cd ../../TinCanTools

...would take you up two levels, and then into a folder called TinCanTools.

Running OpenOCD
Navigate to the directory containing your openocd executable. In the folder with the executable, make sure you also see three directories called interface/, board/, and target/. If you don't see these directories, create a new folder somewhere on your computer containing openocd, interface/, board/, and target/. (If you have just compiled OpenOCD yourself, you can find the executable in openocd/src or openocd-/src, and the three directories you need in openocd/tcl or openocd-/tcl.

In the directory containing the openocd executable, type...

openocd -f path_to/cfg_file [-f path_to/other_cfg_file]

Replace path_to/cfg_file and so on with the .cfg files for your hardware devices. For example, to run OpenOCD for the Flyswatter2 and the hammer, you would use:

openocd -f interface/flyswatter2.cfg -f board/hammer.cfg

For the original Flyswatter and the Beagleboard, you would use:

openocd -f interface/flyswatter.cfg -f board/ti_beagleboard.cfg

See below for more information on config files.

Telnet Connection
OpenOCD runs as a daemon. It accepts connections from other programs, but does not provide any means for you to give it commands directly. Once OpenOCD is running on your computer you will need to connect to it through another program, such as telnet.

Windows XP and Windows Server 2003 provide the telnet client by default. To use telnet in Windows 7/Vista you will need to enable it manually. The Configuring Windows 7 for OpenOCD page will show you how to enable the telnet client.

To run telnet and connect to OpenOCD, open a new command prompt. From any directory, type:

telnet localhost 4444

You should see a simple prompt (>). From this prompt you will be able to send commands to OpenOCD. To exit the telnet prompt, press CTRL + C.

OpenOCD and Permissions
OpenOCD needs administrator privileges to interact with your USB drivers. You will need to be logged onto an account with administrator privileges. If you do not have access to such an account, contact your system administrator.

Search Path
OpenOCD searches in its own directory first for config files. This guide assumes that the openocd binary is in a directory containing three folders, called interface/, board/, and target/. If you have just compiled OpenOCD yourself, you will need to move the openocd executable somewhere where it can find interface/, board/, and target, as described in the compilation guides on this page.

You can also tell OpenOCD where to look for interface/, board/, and target/ with the -s flag, like this:

openocd -s ../tcl -f interface/flyswatter.cfg -f board/hammer.cfg

This would tell OpenOCD to look for interface/ and board/ one level up in a folder called tcl/. For more information, see OpenOCD Config File Paths.

OpenOCD Config Files
Each time you use OpenOCD you will need to configure it by passing it paths to configuration files. In the OpenOCD release, these files are found in openocd-/tcl and its subdirectories. From the tcl directory, the configuration file for the Flyswatter is at interface/flyswatter.cfg. The file for the TinCanTools Hammer is at board/hammer.cfg. If your copy of OpenOCD includes support for the Flyswatter2, its config file is at interface/flyswatter2.cfg.

When you start OpenOCD, you tell it to use the config files for your hardware with the -f switch, like this:

openocd -f path_to/cfg_file [-f path_to/other_cfg_file]

For example, suppose you want to run OpenOCD for the Flyswatter2 and the Hammer. The current directory contains the OpenOCD executable and the board, interface, and target directories provided with the OpenOCD source. You would type:

openocd -f interface/flyswatter2.cfg -f board/hammer.cfg

Be aware that config files may contain paths to other config files. For example hammer.cfg, the config file for the TinCanTools Hammer, contains this line:

source [find target/samsung_s3c2410.cfg]

When you run OpenOCD with the hammer.cfg file, OpenOCD searches from the current directory for target/samsung_s3c2410.cfg. If the current directory does not contain OpenOCD's target folder, it may not find the samsung_s3c2410.cfg file, or it may find a different samsung_s3c2410.cfg file elsewhere on your system. For more information, see OpenOCD Config File Paths.

If you have compiled OpenOCD yourself, the easiest way to avoid these issues is to copy openocd.exe from your openocd-/src folder to your openocd-/tcl folder. To run OpenOCD, navigate to openocd-/tcl in the command console and run OpenOCD as above. You can also create a new folder anywhere on your system, and copy openocd.exe and the contents of openocd-/tcl to the new folder. You can find more information on creating a new folder for OpenOCD in the Windows guides on the Compiling OpenOCD page.

LibUSB Device Filters
When you run OpenOCD for the first time with new hardware, you may encounter this error:

Unable to open FTDI device: unable to claim USB device. Please make sure the default FTDI driver is not in use.

If you see this error, you will need to install a Libusb Device Filter.

Running Commands on Startup: the -c Flag
You can instruct OpenOCD to run a command on startup with the -c flag. For example:

sudo openocd -f interface/flyswatter.cfg -c "jtag_khz 6000" -f board/hammer.cfg

The jtag_khz command sets the Flyswatter's clock speed. Starting OpenOCD like this does the following, in order:


 * run commands in flyswatter.cfg
 * run the OpenOCD command to set the Flyswatter's clock speed
 * run commands in hammer.cfg (which loads samsung_s3c2410.cfg and runs commands found there)