Next: , Previous: About Jim-Tcl, Up: Top


4 Running

Properly installing OpenOCD sets up your operating system to grant it access to the debug adapters. On Linux, this usually involves installing a file in /etc/udev/rules.d, so OpenOCD has permissions. An example rules file that works for many common adapters is shipped with OpenOCD in the contrib directory. MS-Windows needs complex and confusing driver configuration for every peripheral. Such issues are unique to each operating system, and are not detailed in this User's Guide.

Then later you will invoke the OpenOCD server, with various options to tell it how each debug session should work. The --help option shows:

bash$ openocd --help

--help       | -h       display this help
--version    | -v       display OpenOCD version
--file       | -f       use configuration file <name>
--search     | -s       dir to search for config files and scripts
--debug      | -d       set debug level <0-3>
--log_output | -l       redirect log output to file <name>
--command    | -c       run <command>

If you don't give any -f or -c options, OpenOCD tries to read the configuration file openocd.cfg. To specify one or more different configuration files, use -f options. For example:

     openocd -f config1.cfg -f config2.cfg -f config3.cfg

Configuration files and scripts are searched for in

  1. the current directory,
  2. any search dir specified on the command line using the -s option,
  3. any search dir specified using the add_script_search_dir command,
  4. $HOME/.openocd (not on Windows),
  5. the site wide script library $pkgdatadir/site and
  6. the OpenOCD-supplied script library $pkgdatadir/scripts.
The first found file with a matching file name will be used.
Note: Don't try to use configuration script names or paths which include the "#" character. That character begins Tcl comments.

4.1 Simple setup, no customization

In the best case, you can use two scripts from one of the script libraries, hook up your JTAG adapter, and start the server ... and your JTAG setup will just work "out of the box". Always try to start by reusing those scripts, but assume you'll need more customization even if this works. See OpenOCD Project Setup.

If you find a script for your JTAG adapter, and for your board or target, you may be able to hook up your JTAG adapter then start the server with some variation of one of the following:

     openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
     openocd -f interface/ftdi/ADAPTER.cfg -f board/MYBOARD.cfg

You might also need to configure which reset signals are present, using -c 'reset_config trst_and_srst' or something similar. If all goes well you'll see output something like

     Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
     For bug reports, read
             http://openocd.sourceforge.net/doc/doxygen/bugs.html
     Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
            (mfg: 0x23b, part: 0xba00, ver: 0x3)

Seeing that "tap/device found" message, and no warnings, means the JTAG communication is working. That's a key milestone, but you'll probably need more project-specific setup.

4.2 What OpenOCD does as it starts

OpenOCD starts by processing the configuration commands provided on the command line or, if there were no -c command or -f file.cfg options given, in openocd.cfg. See Configuration Stage. At the end of the configuration stage it verifies the JTAG scan chain defined using those commands; your configuration should ensure that this always succeeds. Normally, OpenOCD then starts running as a daemon. Alternatively, commands may be used to terminate the configuration stage early, perform work (such as updating some flash memory), and then shut down without acting as a daemon.

Once OpenOCD starts running as a daemon, it waits for connections from clients (Telnet, GDB, Other) and processes the commands issued through those channels.

If you are having problems, you can enable internal debug messages via the -d option.

Also it is possible to interleave Jim-Tcl commands w/config scripts using the -c command line switch.

To enable debug output (when reporting problems or working on OpenOCD itself), use the -d command line switch. This sets the debug_level to "3", outputting the most information, including debug messages. The default setting is "2", outputting only informational messages, warnings and errors. You can also change this setting from within a telnet or gdb session using debug_level<n> (see debug_level).

You can redirect all output from the daemon to a file using the -l <logfile> switch.

Note! OpenOCD will launch the GDB & telnet server even if it can not establish a connection with the target. In general, it is possible for the JTAG controller to be unresponsive until the target is set up correctly via e.g. GDB monitor commands in a GDB init script.