Next: OpenOCD Project Setup, 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. 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>
    --pipe       | -p       use pipes when talking to gdb

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

         openocd -f interface/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.berlios.de/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.

For details on the `-p` option. See Connecting to GDB.

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.