OpenOCD Config File Paths

Config File Basics
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 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 TinCanTools Flyswatter2 and Hammer board. 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

If you do not supply any config files with the -f switch, OpenOCD attempts to load a config file called openocd.cfg. This file is not supplied by default; you must write or supply it yourself. If OpenOCD cannot find this file, it prints an error and exits.

Default Locations for Config Files
The OpenOCD source comes with config files in three different locations.


 * openocd/tcl/target
 * openocd/tcl/interface
 * openocd/tcl/board

When you compile OpenOCD, the make install command copies the config files in three additional locations.


 * /usr/local/share/openocd/scripts/target
 * /usr/local/share/openocd/scripts/interface
 * /usr/local/share/openocd/scripts/board

If you compile OpenOCD for Windows using Cygwin, these paths are within Cygwin. The full Windows paths would be C:\cygwin\usr\local\share\openocd\scripts\target and so on.

Searching Additional Directories: The -s Switch
You can tell OpenOCD to look for config files in a directory using the -s command line switch, like this:

openocd -s path/to/dir_with_cfg_files -f cfg_file.cfg

The search path can be absolute, or relative to the current directory. For example, suppose you have just finished compiling OpenOCD. The openocd executable is located in openocd/src and the config files are in openocd/tcl. You want to run OpenOCD with the Flyswatter and Hammer board. From openocd/src, you run OpenOCD as follows:

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

File Locations
When OpenOCD searches for a config file, it looks in the following locations, in order:


 * 1) The current directory
 * 2) Any additional directories you supply with the -s switch
 * 3) Any additional directories added with OpenOCD's add_script_search_dir command
 * 4) Linux/Cygwin Only: The hidden directory .openocd in your home directory
 * 5) Linux/Cygwin Only: The directory /usr/local/share/openocd/scripts (created in /usr/local/share when you compile OpenOCD)

If the config file exists in more than one location, OpenOCD uses the first one found. This is especially important if you have more than one copy of the same config file on your computer. If you need to change a config file, make sure your place it where OpenOCD will use it in preference to other versions of the file.

On Windows the last two locations will only be available if you run OpenOCD from within Cygwin.

Loading Config Files from Other Config Files
Some config files load other config files. For example, the config file for the Hammer, hammer.cfg, contains this line:

source [find target/samsung_s3c2410.cfg]

When OpenOCD loads hammer.cfg, it also tries to load target/samsung_s3c2410.cfg and gives an error if it cannot find this file. You need to ensure that OpenOCD can find this file from one of its search directories. If you have your config files in the default openocd/tcl directory, the executable in openocd/src, and you run OpenOCD like this:

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

...then OpenOCD won't find target/samsung_s3c2410.cfg. It searches for /tcl/board/target and /tcl/interface/target but doesn't find either. However, if you run OpenOCD like this:

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

...then it looks looks for tcl/target/samsung_s3c2410.cfg and finds the file.