## 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 to 3
                 | -d<n>    set debug level to <level>
    --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. a directory in the `OPENOCD_SCRIPTS` environment variable (if set),
5. `%APPDATA%/OpenOCD` (only on Windows),
6. `$HOME/Library/Preferences/org.openocd` (only on Darwin),
7. `$XDG_CONFIG_HOME/openocd` (`$XDG_CONFIG_HOME` defaults to `$HOME/.config`),
8. `$HOME/.openocd`,
9. the site wide script library `$pkgdatadir/site` and
10. 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.org/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 server. 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 server.

Once OpenOCD starts running as a server, it waits for connections from clients (Telnet, GDB, RPC) 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 server 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.