Libusb Device Filter

If you encounter problems with using a USB device with libusb on Windows, you may need to install a libusb device filter. This guide assumes that you already have libusb-win32 installed on Windows, and that you have the libusb-win32 binary version 1.2.2.0 in a folder called libusb-win32-bin-1.2.2.0. If not, see Compiling Openocd for information on installing libusb.

 

Installing a Device Filter

Plug in your USB device, and ensure that the libusb drivers are already installed.

Installing a Device Filter for the Flyswatter

In Windows Explorer, navigate to \libusb-win32-bin-1.2.2.0\bin, and open the folder \x86, \amd64, or \ia64, depending on your processor. Find and run install-filter-win.exe. (If you are unsure whether you have a 32- or 64-bit processor and choose the wrong installer, it will display an error message and terminate.)

In the installer, select your device and click “Install.”

OpenOCD Troubleshooting

The pages below describe common errors encountered with OpenOCD and TinCanTools hardware. If you are new to OpenOCD or to command-line interface in general, start with Running OpenOCD on Windows or Running OpenOCD on Linux.

OpenOCD Troubleshooting: Adapter Speed Not Selected

You run OpenOCD, and you see this error:
Error: An adapter speed is not selected in the init script. Insert a call to adapter_khz or jtag_rclk to proceed.

Adapter speed error in Windows XP

You will most likely see this error with the original TinCanTools Flyswatter an OpenOCD build that supports the Flyswatter2. OpenOCD now expects the flyswatter.cfg file to specify an adapter speed, and throws an error when it doesn’t. This guide will demonstrate how to fix the problem.

 

Step 1: Find Your Interface Config File

Find the config file for your interface device. For the Flyswatter this file is called flyswatter.cfg located in your interface folder. Open this file in a text editor.

 

Step 2: Look for a Line Reading jtag_khz

Search the file for a line reading jtag_khz followed by a number. The jtag_khz call has been replaced by adapter_khz in the latest version is no longer supported by OpenOCD. Replace the word jtag_khz with the word adapter_khz, leaving the number unchanged.

If the file does not contain a jtag_khz call, proceed to Step 3. (You may skip Step 2 with the Flyswatter. The flyswatter.cfg file distributed with OpenOCD does not contain a jtag_khz line.)

 

Step 3: Specify an Adapter Speed

Adding adapter_khz to flyswatter.cfg

If you found a jtag_khz line in Step 2, skip this step. If you did not find a jtag_khz line, add a line at the bottom of the file specifying an adapter speed (in kHz). For the flyswatter, use 6000 kHz. The line should read like this:

adapter_khz 6000

See the image to the right. For other hardware, contact the manufacturer to obtain the correct clock speed.

OpenOCD should now be able to communicate with your hardware correctly.

OpenOCD Troubleshooting: Can’t Find File.cfg

You attempt to run OpenOCD and it exits immediately with a warning:
Can't find [file].cfg

OpenOCD has failed to find one or more config files. This guide will help you diagnose and correct the problem.

 

Can’t Find openocd.cfg

If you see this message, you have likely run OpenOCD with no command line arguments. OpenOCD requires at least one config file to tell it how to communicate with your hardware. If you don’t specify any, it searches for openocd.cfg. However, OpenOCD doesn’t provide openocd.cfg by default. Even if it did, it wouldn’t do any good because it wouldn’t be tailored to any particular hardware.

Find the config files with your hardware. If you have compiled OpenOCD from source, they are most likely located in your OpenOCD directory, at tcl/interface, tcl/board, or tcl/target. Run OpenOCD again, using the -f switch to specify the path to each config file. For example:

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

If you know how to write your own config files you can also write your own openocd.cfg and place it in the same directory as the OpenOCD binary, but this is not necessary. See the links at the bottom of this page for more information on config files.

 

Can’t Find a File Specified with -f

You run OpenOCD with the -f switch and OpenOCD can’t find the file. For example, suppose you ran OpenOCD as above and saw the following error:

Can't find board/hammer.cfg

Make sure the config file exists and the path you specified is correct. If the file is present on your computer, make sure OpenOCD can find it from one of its default search paths. See OpenOCD Config File Paths for information on how OpenOCD finds config files.

 

Can’t Find Another Config File

OpenOCD prints a runtime error stating that it can’t open a config file you didn’t specify with -f. For example, suppose you ran OpenOCD as follows:

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

…and saw this error:

Runtime Error: embedded:startup.tcl:58: Can't find target/samsung_s3c2410.cfg

So why was OpenOCD looking for samsung_s3c2410.cfg? The hammer.cfg file contains the line:

source [find target/samsung_s3c2410.cfg]

…to load the config file for the Hammer’s CPU. When OpenOCD parses hammer.cfg it also searches for target/samsung_s3c2410.cfg, just as if you had specified it with the -f switch.

If OpenOCD fails to find a file specified in another config file, make sure the file path is valid for OpenOCD‘s search paths. You may need to specify an additional search path with the -s switch. See OpenOCD Config File Paths for more information on search paths and the -s switch.

 

More Information

Running OpenOCD on Windows

Running OpenOCD on Linux

OpenOCD Config File Paths

OpenOCD Troubleshooting: Device Not Found (Linux)

On startup you see an error message indicating that OpenOCD cannot find the device. If your build of OpenOCD uses the libftdi driver library, the error message reads:
Error: unable to open ftdi device: device not found

Device Not Found error with libftdi

Follow these instructions to diagnose the problem.

 

Step 1: Make Sure the Device is Connected

Unplug your device, plug it back in, and check the all connections to make sure they are secure. Many devices also have LEDs to indicate that they are receiving power. The Flyswatter2 and Hammer all have red LEDs to indicate that they are powered. If you do not see a red light come on when you plug in the device, it isn’t receiving power.

The Flyswatter and Flyswatter2 also have green LEDs to indicate active USB connections. If you do not see a green light on your Flyswatter, then the device does not have an active USB connection.

 

Step 2: Check your Driver Messages

Open a terminal window (Applications menu > Accessories > Terminal) and type:

dmesg

You will see a list of messages describing driver activity on your system. Look for a message indicating that Ubuntu has detected your device. If you have installed the D2XX drivers you should see something like the image to the right. (Even if you intend to run an OpenOCD build compiled with libftdi, seeing the D2XX drivers does not indicate that OpenOCD will fail.)

dmesg Shows a Connected FTDI Device

If do not see a message indicating that Ubuntu has detected a USB device with an FT2232 interface, or if the message is followed by another message indicating that the device has been disconnected, then Ubuntu does not currently recognize that the device is plugged in.

dmesg Shows a Disconnected FTDI Device

The dmesg command prints lots and lots of messages, often more than you can search through by hand. You can filter the output for messages related to your USB drivers by piping it to grep, like this:

dmesg | grep -i usb

Step 3: List USB Devices

Use lsusb to get information about your hardware. A guide to using lsusb is provided here. Follow the steps shown on the Lsusb page. If you encounter any problems, your hardware may be faulty or there may be a problem with your drivers.

OpenOCD Troubleshooting: Device Not Opened (Linux)

On startup you see an error message indicating that OpenOCD cannot find the device. If your build of OpenOCD uses the libftdi driver library, the error message reads:
Error: unable to open ftdi device: device not opened

Device Not Opened error with libftd2xx

With OpenOCD 0.4.0 this error appears as:

Error: unable to open ftdi device: 3

Try the following to correct the issue.

 

Manually Unload the FTDI_SIO Driver

OpenOCD should unload the ftdi_sio kernel module automatically on startup. If it fails, you will see the “device not opened” error. You can correct this by manually unloading the module with this command:

sudo rmmod ftdi_sio

You should see no text output, and the command prompt should appear again immediately. You should now be able to start OpenOCD successfully.

OpenOCD Troubleshooting: Invalid Command Name JTAG

You attempt to run OpenOCD with a target board and a JTAG interface device, such as the TinCanTools Flyswatter. OpenOCD exits with a config file error like this:

Runtime Error: invalid command name “jtag”

Runtime Error: target/samsung_s3c2410.cfg:26: invalid command name "jtag"

This particular config file target/samsung_s3c2410.cfg is called by hammer.cfg, the config file for the TinCanTools Hammer. You would see this error if you ran OpenOCD from the command line like this:

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

 

Solution: Reverse the Order of the Config Files

Instead of running OpenOCD as above, pass OpenOCD flyswatter.cfg before hammer.cfg, like this:

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

OpenOCD should now run successfully.

OpenOCD Troubleshooting: JTAG Sticky Error

JTAG-DP_STICKY_ERROR on startup

You may see one or more JTAG-DP_STICKY_ERROR immediately on startup. This is caused by a bug in OpenOCD 0.4.0, but don’t worry. OpenOCD will still be able to talk to the board. The errors look like this.

Beagle startup err.png

There is a bug in OpenoCD 0.4.0 causing the first debug session, after OpenOCD has been started, to fail if the target is running when OpenoCD tries to connect. This bug has been fixed in recent git and can be worked around in OpenOCD 0.4.0 by adding -c init -c ‘reset init’ to the command line when starting OpenOCD.

If you see this error, then the next time you try to start OpenOCD it will give an error the next time it tries to communicate with the Beagleboard. When you exit OpenOCD you will need to disconnect and reconnect the power cable to the Beagleboard before OpenOCD will be able to communicate with the Beagleboard again.

OpenOCD Troubleshooting: JTAG Tap Unexpected

Contents

You run OpenOCD with a board with a JTAG interface and see an error like this:

Info : JTAG tap: s3c2410.cpu tap/device found: 0x0032409d (mfg: 0x04e, part: 0x0324, ver: 0x0)Warn : JTAG tap: s3c2410.cpu UNEXPECTED: 0x0032409d (mfg: 0x04e, part: 0x0324, ver: 0x0)Error: JTAG tap: s3c2410.cpu expected 1 of 1: 0xffffffff (mfg: 0x7ff, part: 0xffff, ver: 0xf)Error: Trying to use configured scan chain anyway...Warn : Bypassing JTAG setup events due to errors

When OpenOCD tries to initialize JTAG, it tries to detect the test access port (TAP) ID of each device in the JTAG chain. The tap ID is set by the manufacturer. OpenOCD’s config files contain expected tap values for each board. You may encounter this error either because OpenOCD has failed to read the tap ID correctly, or because the expected value in a config file is incorrect or outdated.

Look at the “tap/device found” and “UNEXPECTED” values in OpenOCD’s output. If you see a value of 0x00000000 or 0x000000ff, OpenOCD has failed to read the tap ID. If you see any other value, some other error has occurred, and the error is most likely an incorrect value in a config file.

 

Info : JTAG tap: omap3530.jrc tap/device found: 0x000000ff (mfg: 0x07f, part: 0x0000, ver: 0x0)Warn : JTAG tap: omap3530.jrc UNEXPECTED: 0x000000ff (mfg: 0x07f, part: 0x0000, ver: 0x0)Error: JTAG tap: omap3530.jrc expected 1 of 1: 0x0b7ae02f (mfg: 0x017, part: 0xb7ae, ver: 0x0)Error: Trying to use configured scan chain anyway...Error: couldn't read enough bytes from FT2232 device (0 < 2)

In this example, OpenOCD has found an ID of 0x000000ff, an invalid tap ID. For this output you would refer to the Failed to Read Tap ID section below. For the example at the top of the page, OpenOCD has detected an ID of 0x0032409d, and you would start with the Incorrect Value in Config File section.

 

Failed to Read Tap ID

If you see a tap ID found with a value of 0x00000000 or 0x000000ff, OpenOCD has failed to read the tap ID.

 

Step 1: Check JTAG Connection

In particular, make sure the JTAG ribbon cable is secured, and is not connected backwards. A loose or misaligned connection will cause the tap ID to read incorrectly. WARNING: a misaligned connection may damage the pins on the JTAG header! If you are unsure whether the cable is connected backwards, consult the manual before testing.

 

Step 2: Check for Updated Config Files

The config files distributed with your version of OpenOCD may not reflect recent revisions made by the manufacturer. TinCanTools maintains a page with updated config files for use with guides on this wiki. Check for config files on the OpenOCD Config Files page.

If you are using an older version of OpenOCD (0.4.0 or earlier), check for updated config files in version 0.5.0. Direct link to OpenOCD 0.5.0: http://prdownload.berlios.de/openocd/openocd-0.5.0.zip

 

Note for Beagleboard/Beagleboard XM Users

The Beagleboard and Beagleboard XM have an issue that may prevent the JTAG chain from initializing correctly. You may be able to correct this issue by running the init and reset init commands on OpenOCD startup.

With the Flyswatter2 and the Beagleboard XM, run OpenOCD as follows:

openocd -f interface/flyswatter2.cfg -f board/ti_beagleboard_xm.cfg -c init -c "reset init"

With the Beagleboard:

openocd -f interface/flyswatter2.cfg -f board/ti_beagleboard.cfg -c init -c "reset init"

The Beagleboard sometimes has additional issues. For more information, see Beagleboard Troubleshooting: JTAG Tap Unexpected 0x000000ff.

 

Incorrect Value in Config File

If OpenOCD finds an unexpected tap ID other than 0 (0x00000000) or 0x000000ff the issue is most likely an incorrect expected value in a config file. The example at the beginning of this article occurs when running OpenOCD with the Hammer and the hammer.cfg file provided with OpenOCD 0.4.0:

Info : JTAG tap: s3c2410.cpu tap/device found: 0x0032409d (mfg: 0x04e, part: 0x0324, ver: 0x0)Warn : JTAG tap: s3c2410.cpu UNEXPECTED: 0x0032409d (mfg: 0x04e, part: 0x0324, ver: 0x0)Error: JTAG tap: s3c2410.cpu expected 1 of 1: 0xffffffff (mfg: 0x7ff, part: 0xffff, ver: 0xf)

OpenOCD has found a valid tap ID – 0x0032409d – but it doesn’t match the expected value – 0xffffffff. For OpenOCD to initialize JTAG correctly you will need to change the expected ID in the config file to match the actual ID.

 

Step 1: Check for Updated Config Files

The config files distributed with your version of OpenOCD may not reflect recent revisions made by the manufacturer. TinCanTools maintains a page with updated config files for use with guides on this wiki. Check for config files on the OpenOCD Config Files page.

If you are using an older version of OpenOCD (0.4.0 or earlier), check for updated config files in version 0.5.0. Direct link to OpenOCD 0.5.0: http://prdownload.berlios.de/openocd/openocd-0.5.0.zip

If the no new config file is available or the new file fails to correct the issue, proceed to Step 2.

 

Step 2: Note the Unexpected Value

The first two lines above list the tap ID detected by OpenOCD. Take note of the 32-bit hexadecimal value (the one with 0x followed by 8 digits) in the first two lines, and the expected value in the third line.

Info : JTAG tap: s3c2410.cpu tap/device found: 0x0032409d (mfg: 0x04e, part: 0x0324, ver: 0x0)Warn : JTAG tap: s3c2410.cpu UNEXPECTED: 0x0032409d (mfg: 0x04e, part: 0x0324, ver: 0x0)Error: JTAG tap: s3c2410.cpu expected 1 of 1: 0xffffffff (mfg: 0x7ff, part: 0xffff, ver: 0xf)

The found tap ID is 0x0032409d and the expected tap ID is 0xffffffff. You will need these values in step 3.

 

Step 3: Find the Config File for your Board

Find the config file for your board. This file usually has the same name as your board and is located in a folder called board/. For example, if you were using OpenOCD with the Flyswatter and the Hammer, and you started OpenOCD like this:

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

The config file for your board is hammer.cfg, and you can find it in /home/myusername/openocd/tcl/board. If you aren’t setting OpenOCD’s search directory with the -s flag you may have to look in multiple places to find the board config file OpenOCD actually uses. See OpenOCD Config File Paths.

 

Setting CPUTAPID for the Hammer in WordPad

Step 4: Edit the Config File

Open the config file in a text editor. Find a line that calls the config file for your processor. It should look like this:

source [find target/name_of_the_target.cfg]

For the Hammer, the target file is samsung_s3c2410.cfg, so this line reads:

source [find target/samsung_s3c2410.cfg]

Immediately above this line, add a new line that reads:

set CPUTAPID 0x[TapID]

…where 0x[TapID is value found in Step 1. (Don’t actually type “0xTapID.” Type the hexadecimal value you found above.) For the Hammer, the file should now read like this:

# Target Configuration for the TinCanTools S3C2410 Based Hammer Module# http://www.tincantools.comset CPUTAPID 0x0032409dsource [find target/samsung_s3c2410.cfg]$_TARGETNAME configure -event reset-init { ....

Save the file and close it.

 

Step 5: Verify that OpenOCD finds the Tap Correctly

Run OpenOCD again. It should print a line indicating that it has found the tap correctly:

Info : JTAG tap: s3c2410.cpu tap/device found: 0x0032409d (mfg: 0x04e, part: 0x0324, ver: 0x0)

OpenOCD Troubleshooting: Unable to Fetch Product Description

You run OpenOCD on Ubuntu and it cannot communicate with your FTDI drivers. If you use an OpenOCD build compiled with the libftdi driver library, it exits on startup after printing this error:
Error: unable to open ftdi device: unable to fetch product description

OpenOCD requires superuser privileges to communicate with your drivers. For information on running OpenOCD as root on Ubuntu, see OpenOCD and Permissions. If you have access to your system’s root password and wish to allow other users to run OpenOCD without sudo, see Accessing Devices without Sudo.