Running OpenOCD on Linux with the Beagleboard xM

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 Ubuntu command line interface, the terminal window. 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.

This guide was written for the Ubuntu 10.04 LTS release. You may encounter differences on other Linux distributions. The instructions on this page use the Beagleboard as an example embedded chip target. The instructions are otherwise identical to those at Running OpenOCD on Linux, which provides examples for the TinCanTools Hammer.

Opening the Command Prompt
Open the Applications menu from the menu bar on your desktop, and choose Accessories > Terminal. Ubuntu should open black window with white text and a prompt.

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 /home cd /usr/local/lib

...or relative...

cd src/openocd cd TinCanTools/openocd

Absolute paths are from your root directory, and begin with a slash. Relative paths are from the current directory and do not begin with a slash. File paths are case sensitive.

If you need to navigate to your home directory, type cd by itself like this...

cd

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.

To reach your root directory, you can type:

cd /

If you need to include your home directory in a path (home/USERNAME, replacing USERNAME with the name of your account), you can type it out as normal, or you can use the tilde key (~) as shorthand. For example:

cd /home/USERNAME/TinCanTools cd ~/TinCanTools

...both take you to the same place.

Running OpenOCD
Navigate to the directory containing your openocd executable. If you have just compiled OpenOCD according to the instructions on this wiki, the executable is located in openocd/src or openocd-0.4.0/src. In that directory, simply type...

openocd

To run the program. It won't do anything though, because you need the appropriate permissions and config files. To exit openocd, press CTRL + C.

OpenOCD and Permissions
OpenOCD needs administrator privileges to interact with your USB drivers. Even Linux users with administrator privileges do not typically log on with those privileges active. However, Linux provides commands to run another command as the root user. On Ubuntu, this command is sudo. To run a program as root, type sudo, then a space, then the name of the program. For example...

openocd

...runs OpenOCD with your user permissions, and likely prevents OpenOCD from interacting with libUSB. However...

sudo openocd

...runs OpenOCD as root, with full permission to access your USB drivers.

When you use the sudo command, Linux will prompt you for your password, not the root user's password. If you cannot use sudo, contact your system administrator. You can also configure Linux to allow OpenOCD to access specific hardware devices without sudo. See Accessing Devices without Sudo.

OpenOCD Config Files
Each time you use OpenOCD you will need to configure it by passing it paths to configuration files. In the OpenOCD 0.4.0 release, these files are found in openocd-0.4.0/tcl and its subdirectories. From the tcl directory, the configuration file for the Flyswatter is at interface/flyswatter.cfg. The file for the Beagleboard is at board/ti_beagleboard.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:

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

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

sudo openocd -f interface/flyswatter.cfg -f board/ti_beagleboard_xm.cfg

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

source [find target/amdm37x.cfg]

When you run OpenOCD with the ti_beagleboard_xm.cfg file, OpenOCD searches from the current directory for target/amdm37x.cfg. If the current directory does not contain OpenOCD's target directory, it may not find the amdm37x.cfg file, or it may find a different amdm37x.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 the openocd binary from your openocd-0.4.0/src directory to your openocd-0.4.0/tcl directory. To run OpenOCD, navigate to openocd-0.4.0/tcl in the command terminal and run OpenOCD as above. You can also create a new directory anywhere on your system, and copy the openocd binary and the contents of openocd-0.4.0/tcl to the new directory.

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.

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

telnet localhost 4444

You may need to run telnet as root:

sudo 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.