OpenOCD Config File Paths
Config File Basics
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 the hitex STR9_comStic 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/hitex_str9-comstick.cfg -f target/str912.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.
When you compile OpenOCD, the make install command copies the config files in three additional locations.
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 for the hitex STR9_comStic board. From openocd/src, you run OpenOCD as follows:
openocd -s ../tcl -f interface/hitex_str9-comstick.cfg -f target/str912.cfg
When OpenOCD searches for a config file, it looks in the following locations, in order:
- The current directory
- Any additional directories you supply with the -s switch
- Any additional directories added with OpenOCD's add_script_search_dir command
- Linux/Cygwin Only: The hidden directory .openocd in your home directory
- 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 you 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 for tcl/target/samsung_s3c2410.cfg and finds the file.