Wmat: Adding proper categories

2012-04-18T03:25:36Z

Adding proper categories

Wmat: Porting the TCT content.

2012-03-30T00:35:30Z

Porting the TCT content.

New page

''This guide contains general information on running OpenOCD, but all examples use the {{HAMMER_PRODUCTLINK}}. For examples using the {{BEAGLEBOARD_PRODUCTLINK}}, see [[Running OpenOCD on Linux with the Beagleboard]].''

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

==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 lib/mingw
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. 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-{{OPENOCD_VERNUM}}/src''', and the three directories you need in '''openocd/tcl''' or '''openocd-{{OPENOCD_VERNUM}}/tcl'''.

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

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

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

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

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

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

==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 -f interface/flyswatter.cfg -f board/hammer.cfg

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

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

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

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

==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:

sudo 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 directory 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]] {{OPENOCD_VERNUM}} release, these files are found in '''openocd-{{OPENOCD_VERNUM}}/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:

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

sudo 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''' directory, it may not find the '''samsung_s3c2410.cfg''' file, or it may find a different '''samsung_s3c2410.cfg''' file elsewhere on your system. You can avoid this by giving OpenOCD the path to your config files. 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-{{OPENOCD_VERNUM}}/src''' directory to your '''openocd-{{OPENOCD_VERNUM}}/tcl''' directory. To run [[OpenOCD]], navigate to '''openocd-{{OPENOCD_VERNUM}}/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-{{OPENOCD_VERNUM}}/tcl''' to the new directory.

==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)

← Older revision		Revision as of 03:25, 18 April 2012
Line 143:		Line 143:
	*run the OpenOCD command to set the Flyswatter's clock speed		*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)		*run commands in ''hammer.cfg'' (which loads ''samsung_s3c2410.cfg'' and runs commands found there)
		+
		+	[[Category:TinCanTools]]
		+	[[Category:OpenOCD]]

Running OpenOCD on Linux - Revision history

Wmat: Adding proper categories

Wmat: Porting the TCT content.