OpenOCD configuration

OpenFacts, the Open Source Knowledge Database

The Open On-Chip Debugger (OpenOCD) runs as a daemon, and reads it current configuration by default from the file openocd.cfg in the current directory. A different configuration file can be specified with the -f <conf.file> given at the openocd command line.

The configuration file is used to specify on which ports the daemon listens for new connections, the JTAG interface used to connect to the target, the layout of the JTAG chain, the targets that should be debugged, and connected flashes.

This page is supposed to document the current state of the OpenOCD - i.e. the latest version available from SVN.

Daemon configuration

telnet_port <number>: Port on which to listen for incoming telnet connections
gdb_port <number>: First port on which to listen for incoming GDB connections. The GDB port for the first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.

daemon_startup <'attach'|'reset'>: Tells the OpenOCD whether it should reset the target when the daemon is launched, or if it should just attach to the target.

JTAG interface configuration

interface <name>: Use the interface driver <name> to connect to the target. Currently supported interfaces are

parport: PC parallel port bit-banging (Wigglers, PLD download cable, ...)
amt_jtagaccel: Amontec Chameleon in its JTAG Accelerator configuration connected to a PC's EPP mode parallel port
ft2232: FTDI FT2232 based devices using either the open-source libftdi or the binary only FTD2XX driver. The FTD2XX is superior in performance, but not available on every platform. The libftdi uses libusb, and should be portable to all systems that provide libusb.
ep93xx: Cirrus Logic EP93xx based single-board computer bit-banging (in development)

jtag_speed <number>: Limit the maximum speed of the JTAG interface. Usually, a value of zero means maximum speed. The actual effect of this option depends on the JTAG interface used.

reset_config <signals> [combination] [trst_type] [srst_type]: The configuration of the reset signals available on the JTAG interface AND the target. If the JTAG interface provides SRST, but the target doesn't connect that signal properly, the OpenOCD can't use it. <signals> can be 'none', 'trst_only', 'srst_only' or 'trst_and_srst'. [combination] is an optional value specifying broken reset signal implementations. 'srst_pulls_trst' states that the testlogic is reset together with the reset of the system (e.g. Philips LPC2000, "broken" board layout), 'trst_pulls_srst' says that the system is reset together with the test logic (only hypothetical, I haven't seen hardware with such a bug, and can be worked around).
-: The [trst_type] and [srst_type] parameters allow the driver type of the reset lines to be specified. Possible values are 'trst_push_pull' (default) and 'trst_open_drain' for the test reset signal, and 'srst_open_drain' (default) and 'srst_push_pull' for the system reset. These values only affect JTAG interfaces with support for different drivers, like the Amontec JTAGkey and JTAGAccelerator.

jtag_device <IR length> <IR capture> <IR mask> <IDCODE instruction>: Describes the devices that form the JTAG daisy chain, with the first device being the one closest to TDO. The parameters are the length of the instruction register (4 for all ARM7/9s), the value captured during Capture-IR (0x1 for ARM7/9), and a mask of bits that should be validated when doing IR scans (all four bits (0xf) for ARM7/9). The IDCODE instruction will in future be used to query devices for their JTAG identification code. This line is the same for all ARM7 and ARM9 devices. Other devices, like CPLDs, require different parameters. An example configuration line for a Xilinx XC9500 CPLD would look like this:

jtag_device 8 0x01 0x0e3 0xfe The instruction register (IR) is 8 bits long, during Capture-IR 0x01 is loaded into the IR, but only bits 0-1 and 5-7 should be checked, the others (2-4) might vary. The IDCODE instruction is 0xfe.

jtag_nsrst_delay <ms>: How long (in miliseconds) the OpenOCD should wait after deasserting nSRST before starting new JTAG operations.
jtag_ntrst_delay <ms>: How long (in miliseconds) the OpenOCD should wait after deasserting nTRST before starting new JTAG operations.

The jtag_n[st]rst_delay options are useful if reset circuitry (like a reset supervisor, or on-chip features) keep a reset line asserted for some time after the external reset got deasserted.

parport options

parport_port <number>: Either the address of the I/O port (default: 0x378 for LPT1) or the number of the /dev/parport device

When using PPDEV to access the parallel port, use the number of the parallel port: 'parport_port 0' (the default). If 'parport_port 0x378' is specified you may encounter a problem.

parport_cable <name>: The layout of the parallel port cable used to connect to the target. Currently supported cables are

wiggler: Original Wiggler layout, also supported by several clones, such as the Olimex ARM-JTAG
old_amt_wiggler: The Wiggler configuration that comes with Amontec's Chameleon Programmer. The new version available from the website uses the original Wiggler layout ('wiggler')
chameleon: Describes the connection of the Amontec Chameleon's CPLD when operated in configuration mode. This is only used to program the Chameleon itself, not a connected target.
dlc5: Xilinx Parallel cable III.
triton: The parallel port adapter found on the Karo Triton 1 Development Board. This is also the layout used by the Holly-Gates design (see http://www.lartmaker.nl/projects/jtag/).
flashlink: ST Parallel cable.

amt_jtagaccel options

parport_port <number>: Either the address of the I/O port (default: 0x378 for LPT1) or the number of the /dev/parport device

ft2232 options

ft2232_device_desc <description>: The USB device description of the FTDI FT2232 device. If not specified, the FTDI default value is used. This setting is only valid if compiled with FTD2XX support.
ft2232_layout <name>: The layout of the FT2232 GPIO signals used to control output-enables and reset signals. Valid layouts are

usbjtag: The "USBJTAG-1" layout described in the original OpenOCD diploma thesis
jtagkey: Amontec JTAGkey and JTAGkey-tiny
signalyzer: Signalyzer
olimex-jtag: Olimex ARM-USB-OCD
m5960: American Microsystems M5960
evb_lm3s811: Luminary Micro EVB_LM3S811 as a JTAG interface (not onboard processor), no TRST or SRST signals on external connector
comstick: Hitex STR9 comstick

ft2232_vid_pid <vid> <pid>: The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI default values are used. This command is not available on Windows.
ft2232_latency <ms>: On some systems using ft2232 based JTAG interfaces the FT_Read function call in ft2232_read() fails to return the expected number of bytes. This can be caused by USB communication delays and has proved hard to reproduce and debug. Setting the FT2232 latency timer to a larger value increases delays for short USB packages but it also reduces the risk of timeouts before receiving the expected number of bytes. The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.

ep93xx options

Currently, there are no options available for the ep93xx interface.

Target configuration

target <type> <endianess> <reset_mode> <JTAG pos> <variant>: Defines a target that should be debugged. Currently supported types are:

arm7tdmi
arm720t
arm9tdmi
arm920t
arm922t
arm926ejs
arm966e
cortex_m3
xscale

If you want to use a target board that is not on this list, see Adding a new target board

Endianess may be 'little' or 'big'.

The reset_mode specifies what should happen to the target when a reset occurs:

reset_halt: Immediately request a target halt after reset. This allows targets to be debugged from the very first instruction. This is only possible with targets and JTAG interfaces that correctly implement the reset signals.
reset_init: Similar to 'reset_halt', but executes the script file defined to handle the 'reset' event for the target. Like 'reset_halt' this only works with correct reset implementations.
reset_run: Simply let the target run after a reset.
run_and_halt: Let the target run for some time (default: 1s), and then request halt.
run_and_init: A combination of 'reset_init' and 'run_and_halt'. The target is allowed to run for some time, then halted, and the 'reset' event script is executed.

On JTAG interfaces / targets where system reset and test-logic reset can't be driven completely independent (like the LPC2000 series), or where the JTAG interface is unavailable for some time during startup (like the STR7 series), you can't use 'reset_halt' or 'reset_init'.

target_script <target#> <event> <script_file>: Event is either 'reset' or 'post_halt' or 'pre_resume'. TODO: describe exact semantic of events
run_and_halt_time <target#> <time_in_ms>: The amount of time the debugger should wait after releasing reset before it asserts a debug request. This is used by the 'run_and_halt' and 'run_and_init' reset modes.
working_area <target#> <address> <size> <'backup'|'nobackup'>: Specifies a working area for the debugger to use. This may be used to speed-up downloads to target memory and flash operations, or to perform otherwise unavailable operations (some coprocessor operations on ARM7/9 systems, for example). The last parameter decides whether the memory should be preserved (backup). If possible, use a working_area that doesn't need to be backed up, as that slows down operation.

arm7tdmi options

target arm7tdmi <endianess> <reset_mode> <jtag#>: The arm7tdmi target definition requires at least one additional argument, specifying the position of the target in the JTAG daisy-chain. The first JTAG device is number 0. The optional [variant] parameter has been removed in recent versions. The correct feature set is determined at runtime.

arm720t options

ARM720t options are similar to ARM7TDMI options.

arm9tdmi options

ARM9TDMI options are similar to ARM7TDMI options. Supported variants are 'arm920t', 'arm922t' and 'arm940t'. This enables the hardware single-stepping support found on these cores.

arm920t options

ARM920t options are similar to ARM9TDMI options.

arm966e options

ARM966e options are similar to ARM9TDMI options.

xscale options

Supported variants are 'ixp42x', 'ixp45x', 'ixp46x', 'pxa250', 'pxa255', 'pxa26x'.

Flash configuration

flash bank <driver> <base> <size> <chip_width> <bus_width> [driver_options ...]: Configures a flash bank at <base> of <size> bytes and <chip_width> and <bus_width> bytes using the selected flash <driver>.

lpc2000 options

flash bank lpc2000 <base> <size> 0 0 <variant> <target#> <clock> ['calc_checksum']: LPC flashes don't require the chip and bus width to be specified. Additional parameters are the <variant>, which may be 'lpc2000_v1' (older LPC21xx and LPC22xx) or 'lpc2000_v2' (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx), the number of the target this flash belongs to (first is 0), the frequency at which the core is currently running (in kHz - must be an integral number), and the optional keyword 'calc_checksum', telling the driver to calculate a valid checksum for the exception vector table.

'AS OF R189, the order of arguments will be switched to: flash bank lpc2000 <base> <size> 0 0 <target#> <variant>'

cfi options

flash bank cfi <base> <size> <chip_width> <bus_width> <target#>: CFI flashes require the number of the target they're connected to as an additional argument. The CFI driver makes use of a working area (specified for the target) to significantly speed up operation.

at91sam7 options

flash bank at91sam7 0 0 0 0 <target#>: AT91SAM7 flashes only require the target#, all other values are looked up after reading the chip-id and type.

str7 options

flash bank str7x <base> <size> 0 0 <variant> <target#>: variant can be either STR71x, STR73x or STR75x.

'AS OF R189, the order of arguments will be switched to: flash bank str7x <base> <size> 0 0 <target#> <variant>'

str9 options

flash bank str9x <base> <size> 0 0 <target#>: The str9 needs the flash controller to be configured prior to Flash programming, eg.
str9x flash_config 4 2 0 0x80000
This will setup the BBSR, NBBSR, BBADR and NBBADR registers respectively.

str9 options (str9xpec driver)

flash bank str9xpec <base> <size> 0 0 <target#>: Before using the flash commands the turbo mode will need enabling using str9xpec enable_turbo <num>.

Only use this driver for locking/unlocking the device or configuring the option bytes. Use the standard str9 driver for programming.

stellaris (LM3Sxxx) options

flash bank stellaris <base> <size> 0 0 <target#>: stellaris flash plugin only require the target#.

stm32x options

flash bank stm32x <base> <size> 0 0 <target#>: stm32x flash plugin only require the target#.

configurations for the LPC2000

please see config LPC2000

This page has been written as part of the Open On-Chip Debugger project.