View source for OpenOCD Config File Paths

__NOTOC__
==Config File Basics==

Each time you use [[EmSys:OpenOCD |OpenOCD]] you will need to configure it by passing it paths to configuration files. In the [[EmSys:OpenOCD |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 CEDT-USB-JTAG is at '''interface/cedt-arm-jtag.cfg'''.
-->

When you start [[EmSys:OpenOCD |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 [[EmSys:OpenOCD |OpenOCD]] for the the hitex STR9_comStic Board, the current directory contains the [[EmSys:OpenOCD |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, [[EmSys:OpenOCD |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 [[EmSys:OpenOCD |OpenOCD]] cannot find this file, it prints an error and exits.

==Default Locations for Config Files==

The [[EmSys:OpenOCD |OpenOCD]] source comes with config files in three different locations.  

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

When you compile [[EmSys:OpenOCD |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 [[EmSys:OpenOCD |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 [[EmSys:OpenOCD |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 [[EmSys:OpenOCD |OpenOCD]]. The '''openocd''' executable is located in '''openocd/src''' and the config files are in '''openocd/tcl'''. You want to run [[EmSys:OpenOCD |OpenOCD]] for the hitex STR9_comStic board. From '''openocd/src''', you run [[EmSys:OpenOCD |OpenOCD]] as follows:

 openocd -s ../tcl -f interface/hitex_str9-comstick.cfg -f target/str912.cfg

==File Locations==

When [[EmSys:OpenOCD |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, [[EmSys:OpenOCD |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 [[EmSys:OpenOCD |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 [[EmSys:OpenOCD |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 [[EmSys:OpenOCD |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 [[EmSys:OpenOCD |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.