Next: , Previous: , Up: Top   [Contents][Index]

8 Debug Adapter Configuration

Correctly installing OpenOCD includes making your operating system give OpenOCD access to debug adapters. Once that has been done, Tcl commands are used to select which one is used, and to configure how it is used.

Note: Because OpenOCD started out with a focus purely on JTAG, you may find places where it wrongly presumes JTAG is the only transport protocol in use. Be aware that recent versions of OpenOCD are removing that limitation. JTAG remains more functional than most other transports. Other transports do not support boundary scan operations, or may be specific to a given chip vendor. Some might be usable only for programming flash memory, instead of also for debugging.

Debug Adapters/Interfaces/Dongles are normally configured through commands in an interface configuration file which is sourced by your openocd.cfg file, or through a command line -f interface/....cfg option.

source [find interface/olimex-jtag-tiny.cfg]

These commands tell OpenOCD what type of JTAG adapter you have, and how to talk to it. A few cases are so simple that you only need to say what driver to use:

# jlink interface
interface jlink

Most adapters need a bit more configuration than that.

8.1 Interface Configuration

The interface command tells OpenOCD what type of debug adapter you are using. Depending on the type of adapter, you may need to use one or more additional commands to further identify or configure the adapter.

Config Command: interface name

Use the interface driver name to connect to the target.

Command: interface_list

List the debug adapter drivers that have been built into the running copy of OpenOCD.

Command: interface transports transport_name+

Specifies the transports supported by this debug adapter. The adapter driver builds-in similar knowledge; use this only when external configuration (such as jumpering) changes what the hardware can support.

Command: adapter_name

Returns the name of the debug adapter driver being used.

8.2 Interface Drivers

Each of the interface drivers listed here must be explicitly enabled when OpenOCD is configured, in order to be made available at run time.

Interface Driver: amt_jtagaccel

Amontec Chameleon in its JTAG Accelerator configuration, connected to a PC’s EPP mode parallel port. This defines some driver-specific commands:

Config Command: parport_port number

Specifies either the address of the I/O port (default: 0x378 for LPT1) or the number of the /dev/parport device.

Config Command: rtck [enable|disable]

Displays status of RTCK option. Optionally sets that option first.

Interface Driver: arm-jtag-ew

Olimex ARM-JTAG-EW USB adapter This has one driver-specific command:

Command: armjtagew_info

Logs some status

Interface Driver: at91rm9200

Supports bitbanged JTAG from the local system, presuming that system is an Atmel AT91rm9200 and a specific set of GPIOs is used.

Interface Driver: cmsis-dap

ARM CMSIS-DAP compliant based adapter.

Config Command: cmsis_dap_vid_pid [vid pid]+

The vendor ID and product ID of the CMSIS-DAP device. If not specified the driver will attempt to auto detect the CMSIS-DAP device. Currently, up to eight [vid, pid] pairs may be given, e.g.

cmsis_dap_vid_pid 0xc251 0xf001 0x0d28 0x0204
Config Command: cmsis_dap_serial [serial]

Specifies the serial of the CMSIS-DAP device to use. If not specified, serial numbers are not considered.

Command: cmsis-dap info

Display various device information, like hardware version, firmware version, current bus status.

Interface Driver: dummy

A dummy software-only driver for debugging.

Interface Driver: ep93xx

Cirrus Logic EP93xx based single-board computer bit-banging (in development)

Interface Driver: ftdi

This driver is for adapters using the MPSSE (Multi-Protocol Synchronous Serial Engine) mode built into many FTDI chips, such as the FT2232, FT4232 and FT232H.

The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device, bypassing intermediate libraries like libftdi or D2XX.

Support for new FTDI based adapters can be added competely through configuration files, without the need to patch and rebuild OpenOCD.

The driver uses a signal abstraction to enable Tcl configuration files to define outputs for one or several FTDI GPIO. These outputs can then be controlled using the ftdi_set_signal command. Special signal names are reserved for nTRST, nSRST and LED (for blink) so that they, if defined, will be used for their customary purpose. Inputs can be read using the ftdi_get_signal command.

To support SWD, a signal named SWD_EN must be defined. It is set to 1 when the SWD protocol is selected. When set, the adapter should route the SWDIO pin to the data input. An SWDIO_OE signal, if defined, will be set to 1 or 0 as required by the protocol, to tell the adapter to drive the data output onto the SWDIO pin or keep the SWDIO pin Hi-Z, respectively.

Depending on the type of buffer attached to the FTDI GPIO, the outputs have to be controlled differently. In order to support tristateable signals such as nSRST, both a data GPIO and an output-enable GPIO can be specified for each signal. The following output buffer configurations are supported:

These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain:

Config Command: ftdi_vid_pid [vid pid]+

The vendor ID and product ID of the adapter. Up to eight [vid, pid] pairs may be given, e.g.

ftdi_vid_pid 0x0403 0xcff8 0x15ba 0x0003
Config Command: ftdi_device_desc description

Provides the USB device description (the iProduct string) of the adapter. If not specified, the device description is ignored during device selection.

Config Command: ftdi_serial serial-number

Specifies the serial-number of the adapter to use, in case the vendor provides unique IDs and more than one adapter is connected to the host. If not specified, serial numbers are not considered. (Note that USB serial numbers can be arbitrary Unicode strings, and are not restricted to containing only decimal digits.)

Config Command: ftdi_location <bus>:<port>[,<port>]...

Specifies the physical USB port of the adapter to use. The path roots at bus and walks down the physical ports, with each port option specifying a deeper level in the bus topology, the last port denoting where the target adapter is actually plugged. The USB bus topology can be queried with the command lsusb -t.

This command is only available if your libusb1 is at least version 1.0.16.

Config Command: ftdi_channel channel

Selects the channel of the FTDI device to use for MPSSE operations. Most adapters use the default, channel 0, but there are exceptions.

Config Command: ftdi_layout_init data direction

Specifies the initial values of the FTDI GPIO data and direction registers. Each value is a 16-bit number corresponding to the concatenation of the high and low FTDI GPIO registers. The values should be selected based on the schematics of the adapter, such that all signals are set to safe levels with minimal impact on the target system. Avoid floating inputs, conflicting outputs and initially asserted reset signals.

Config Command: ftdi_layout_signal name [-data|-ndata data_mask] [-input|-ninput input_mask] [-oe|-noe oe_mask] [-alias|-nalias name]

Creates a signal with the specified name, controlled by one or more FTDI GPIO pins via a range of possible buffer connections. The masks are FTDI GPIO register bitmasks to tell the driver the connection and type of the output buffer driving the respective signal. data_mask is the bitmask for the pin(s) connected to the data input of the output buffer. -ndata is used with inverting data inputs and -data with non-inverting inputs. The -oe (or -noe) option tells where the output-enable (or not-output-enable) input to the output buffer is connected. The options -input and -ninput specify the bitmask for pins to be read with the method ftdi_get_signal.

Both data_mask and oe_mask need not be specified. For example, a simple open-collector transistor driver would be specified with -oe only. In that case the signal can only be set to drive low or to Hi-Z and the driver will complain if the signal is set to drive high. Which means that if it’s a reset signal, reset_config must be specified as srst_open_drain, not srst_push_pull.

A special case is provided when -data and -oe is set to the same bitmask. Then the FTDI pin is considered being connected straight to the target without any buffer. The FTDI pin is then switched between output and input as necessary to provide the full set of low, high and Hi-Z characteristics. In all other cases, the pins specified in a signal definition are always driven by the FTDI.

If -alias or -nalias is used, the signal is created identical (or with data inverted) to an already specified signal name.

Command: ftdi_set_signal name 0|1|z

Set a previously defined signal to the specified level.

  • - 0, drive low
  • - 1, drive high
  • - z, set to high-impedance
Command: ftdi_get_signal name

Get the value of a previously defined signal.

Command: ftdi_tdo_sample_edge rising|falling

Configure TCK edge at which the adapter samples the value of the TDO signal

Due to signal propagation delays, sampling TDO on rising TCK can become quite peculiar at high JTAG clock speeds. However, FTDI chips offer a possiblity to sample TDO on falling edge of TCK. With some board/adapter configurations, this may increase stability at higher JTAG clocks.

  • - rising, sample TDO on rising edge of TCK - this is the default
  • - falling, sample TDO on falling edge of TCK

For example adapter definitions, see the configuration files shipped in the interface/ftdi directory.

Interface Driver: remote_bitbang

Drive JTAG from a remote process. This sets up a UNIX or TCP socket connection with a remote process and sends ASCII encoded bitbang requests to that process instead of directly driving JTAG.

The remote_bitbang driver is useful for debugging software running on processors which are being simulated.

Config Command: remote_bitbang_port number

Specifies the TCP port of the remote process to connect to or 0 to use UNIX sockets instead of TCP.

Config Command: remote_bitbang_host hostname

Specifies the hostname of the remote process to connect to using TCP, or the name of the UNIX socket to use if remote_bitbang_port is 0.

For example, to connect remotely via TCP to the host foobar you might have something like:

interface remote_bitbang
remote_bitbang_port 3335
remote_bitbang_host foobar

To connect to another process running locally via UNIX sockets with socket named mysocket:

interface remote_bitbang
remote_bitbang_port 0
remote_bitbang_host mysocket
Interface Driver: usb_blaster

USB JTAG/USB-Blaster compatibles over one of the userspace libraries for FTDI chips. These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain:

Config Command: usb_blaster_device_desc description

Provides the USB device description (the iProduct string) of the FTDI FT245 device. If not specified, the FTDI default value is used. This setting is only valid if compiled with FTD2XX support.

Config Command: usb_blaster_vid_pid vid pid

The vendor ID and product ID of the FTDI FT245 device. If not specified, default values are used. Currently, only one vid, pid pair may be given, e.g. for Altera USB-Blaster (default):

usb_blaster_vid_pid 0x09FB 0x6001

The following VID/PID is for Kolja Waschk’s USB JTAG:

usb_blaster_vid_pid 0x16C0 0x06AD
Command: usb_blaster_pin (pin6|pin8) (0|1|s|t)

Sets the state or function of the unused GPIO pins on USB-Blasters (pins 6 and 8 on the female JTAG header). These pins can be used as SRST and/or TRST provided the appropriate connections are made on the target board.

For example, to use pin 6 as SRST:

usb_blaster_pin pin6 s
reset_config srst_only
Command: usb_blaster_lowlevel_driver (ftdi|ublast2)

Chooses the low level access method for the adapter. If not specified, ftdi is selected unless it wasn’t enabled during the configure stage. USB-Blaster II needs ublast2.

Command: usb_blaster_firmware path

This command specifies path to access USB-Blaster II firmware image. To be used with USB-Blaster II only.

Interface Driver: gw16012

Gateworks GW16012 JTAG programmer. This has one driver-specific command:

Config Command: parport_port [port_number]

Display either the address of the I/O port (default: 0x378 for LPT1) or the number of the /dev/parport device. If a parameter is provided, first switch to use that port. This is a write-once setting.

Interface Driver: jlink

SEGGER J-Link family of USB adapters. It currently supports JTAG and SWD transports.

Compatibility Note: SEGGER released many firmware versions for the many harware versions they produced. OpenOCD was extensively tested and intended to run on all of them, but some combinations were reported as incompatible. As a general recommendation, it is advisable to use the latest firmware version available for each hardware version. However the current V8 is a moving target, and SEGGER firmware versions released after the OpenOCD was released may not be compatible. In such cases it is recommended to revert to the last known functional version. For 0.5.0, this is from "Feb 8 2012 14:30:39", packed with 4.42c. For 0.6.0, the last known version is from "May 3 2012 18:36:22", packed with 4.46f.

Command: jlink hwstatus

Display various hardware related information, for example target voltage and pin states.

Command: jlink freemem

Display free device internal memory.

Command: jlink jtag [2|3]

Set the JTAG command version to be used. Without argument, show the actual JTAG command version.

Command: jlink config

Display the device configuration.

Command: jlink config targetpower [on|off]

Set the target power state on JTAG-pin 19. Without argument, show the target power state.

Command: jlink config mac [ff:ff:ff:ff:ff:ff]

Set the MAC address of the device. Without argument, show the MAC address.

Command: jlink config ip [A.B.C.D(/E|F.G.H.I)]

Set the IP configuration of the device, where A.B.C.D is the IP address, E the bit of the subnet mask and F.G.H.I the subnet mask. Without arguments, show the IP configuration.

Command: jlink config usb [0 to 3]

Set the USB address of the device. This will also change the USB Product ID (PID) of the device. Without argument, show the USB address.

Command: jlink config reset

Reset the current configuration.

Command: jlink config write

Write the current configuration to the internal persistent storage.

Command: jlink emucom write <channel> <data>

Write data to an EMUCOM channel. The data needs to be encoded as hexadecimal pairs.

The following example shows how to write the three bytes 0xaa, 0x0b and 0x23 to the EMUCOM channel 0x10:

> jlink emucom write 0x10 aa0b23
Command: jlink emucom read <channel> <length>

Read data from an EMUCOM channel. The read data is encoded as hexadecimal pairs.

The following example shows how to read 4 bytes from the EMUCOM channel 0x0:

> jlink emucom read 0x0 4
Config: jlink usb <0 to 3>

Set the USB address of the interface, in case more than one adapter is connected to the host. If not specified, USB addresses are not considered. Device selection via USB address is deprecated and the serial number should be used instead.

As a configuration command, it can be used only before ’init’.

Config: jlink serial <serial number>

Set the serial number of the interface, in case more than one adapter is connected to the host. If not specified, serial numbers are not considered.

As a configuration command, it can be used only before ’init’.

Interface Driver: parport

Supports PC parallel port bit-banging cables: Wigglers, PLD download cable, and more. These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain:

Config Command: parport_cable name

Set the layout of the parallel port cable used to connect to the target. This is a write-once setting. Currently valid cable name values include:

  • - altium Altium Universal JTAG cable.
  • - arm-jtag Same as original wiggler except SRST and TRST connections reversed and TRST is also inverted.
  • - chameleon The Amontec Chameleon’s CPLD when operated in configuration mode. This is only used to program the Chameleon itself, not a connected target.
  • - dlc5 The Xilinx Parallel cable III.
  • - flashlink The ST Parallel cable.
  • - lattice Lattice ispDOWNLOAD Cable
  • - old_amt_wiggler The Wiggler configuration that comes with some versions of Amontec’s Chameleon Programmer. The new version available from the website uses the original Wiggler layout (’wiggler’)
  • - triton The parallel port adapter found on the “Karo Triton 1 Development Board”. This is also the layout used by the HollyGates design (see
  • - wiggler The original Wiggler layout, also supported by several clones, such as the Olimex ARM-JTAG
  • - wiggler2 Same as original wiggler except an led is fitted on D5.
  • - wiggler_ntrst_inverted Same as original wiggler except TRST is inverted.
Config Command: parport_port [port_number]

Display either the address of the I/O port (default: 0x378 for LPT1) or the number of the /dev/parport device. If a parameter is provided, first switch to use that port. This is a write-once setting.

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.

Command: parport_toggling_time [nanoseconds]

Displays how many nanoseconds the hardware needs to toggle TCK; the parport driver uses this value to obey the adapter_khz configuration. When the optional nanoseconds parameter is given, that setting is changed before displaying the current value.

The default setting should work reasonably well on commodity PC hardware. However, you may want to calibrate for your specific hardware.

Tip: To measure the toggling time with a logic analyzer or a digital storage oscilloscope, follow the procedure below:

> parport_toggling_time 1000
> adapter_khz 500

This sets the maximum JTAG clock speed of the hardware, but the actual speed probably deviates from the requested 500 kHz. Now, measure the time between the two closest spaced TCK transitions. You can use runtest 1000 or something similar to generate a large set of samples. Update the setting to match your measurement:

> parport_toggling_time <measured nanoseconds>

Now the clock speed will be a better match for adapter_khz rate commands given in OpenOCD scripts and event handlers.

You can do something similar with many digital multimeters, but note that you’ll probably need to run the clock continuously for several seconds before it decides what clock rate to show. Adjust the toggling time up or down until the measured clock rate is a good match for the adapter_khz rate you specified; be conservative.

Config Command: parport_write_on_exit (on|off)

This will configure the parallel driver to write a known cable-specific value to the parallel interface on exiting OpenOCD.

For example, the interface configuration file for a classic “Wiggler” cable on LPT2 might look something like this:

interface parport
parport_port 0x278
parport_cable wiggler
Interface Driver: presto


Config Command: presto_serial serial_string

Configures the USB serial number of the Presto device to use.

Interface Driver: rlink

Raisonance RLink USB adapter

Interface Driver: usbprog

usbprog is a freely programmable USB adapter.

Interface Driver: vsllink

vsllink is part of Versaloon which is a versatile USB programmer.

Note: This defines quite a few driver-specific commands, which are not currently documented here.

Interface Driver: hla

This is a driver that supports multiple High Level Adapters. This type of adapter does not expose some of the lower level api’s that OpenOCD would normally use to access the target.

Currently supported adapters include the ST STLINK and TI ICDI. STLINK firmware version >= V2.J21.S4 recommended due to issues with earlier versions of firmware where serial number is reset after first use. Suggest using ST firmware update utility to upgrade STLINK firmware even if current version reported is V2.J21.S4.

Config Command: hla_device_desc description

Currently Not Supported.

Config Command: hla_serial serial

Specifies the serial number of the adapter.

Config Command: hla_layout (stlink|icdi)

Specifies the adapter layout to use.

Config Command: hla_vid_pid vid pid

The vendor ID and product ID of the device.

Command: hla_command command

Execute a custom adapter-specific command. The command string is passed as is to the underlying adapter layout handler.

Interface Driver: opendous

opendous-jtag is a freely programmable USB adapter.

Interface Driver: ulink

This is the Keil ULINK v1 JTAG debugger.

Interface Driver: ZY1000

This is the Zylin ZY1000 JTAG debugger.

Note: This defines some driver-specific commands, which are not currently documented here.

Command: power [on|off]

Turn power switch to target on/off. No arguments: print status.

Interface Driver: bcm2835gpio

This SoC is present in Raspberry Pi which is a cheap single-board computer exposing some GPIOs on its expansion header.

The driver accesses memory-mapped GPIO peripheral registers directly for maximum performance, but the only possible race condition is for the pins’ modes/muxing (which is highly unlikely), so it should be able to coexist nicely with both sysfs bitbanging and various peripherals’ kernel drivers. The driver restores the previous configuration on exit.

See interface/raspberrypi-native.cfg for a sample config and pinout.

Interface Driver: openjtag

OpenJTAG compatible USB adapter. This defines some driver-specific commands:

Config Command: openjtag_variant variant

Specifies the variant of the OpenJTAG adapter (see Currently valid variant values include:

Config Command: openjtag_device_desc string

The USB device description string of the adapter. This value is only used with the standard variant.

8.3 Transport Configuration

As noted earlier, depending on the version of OpenOCD you use, and the debug adapter you are using, several transports may be available to communicate with debug targets (or perhaps to program flash memory).

Command: transport list

displays the names of the transports supported by this version of OpenOCD.

Command: transport select transport_name

Select which of the supported transports to use in this OpenOCD session.

When invoked with transport_name, attempts to select the named transport. The transport must be supported by the debug adapter hardware and by the version of OpenOCD you are using (including the adapter’s driver).

If no transport has been selected and no transport_name is provided, transport select auto-selects the first transport supported by the debug adapter.

transport select always returns the name of the session’s selected transport, if any.

8.3.1 JTAG Transport

JTAG is the original transport supported by OpenOCD, and most of the OpenOCD commands support it. JTAG transports expose a chain of one or more Test Access Points (TAPs), each of which must be explicitly declared. JTAG supports both debugging and boundary scan testing. Flash programming support is built on top of debug support.

JTAG transport is selected with the command transport select jtag. Unless your adapter uses the hla interface driver, in which case the command is transport select hla_jtag.

8.3.2 SWD Transport

SWD (Serial Wire Debug) is an ARM-specific transport which exposes one Debug Access Point (DAP, which must be explicitly declared. (SWD uses fewer signal wires than JTAG.) SWD is debug-oriented, and does not support boundary scan testing. Flash programming support is built on top of debug support. (Some processors support both JTAG and SWD.)

SWD transport is selected with the command transport select swd. Unless your adapter uses the hla interface driver, in which case the command is transport select hla_swd.

Command: swd newdap ...

Declares a single DAP which uses SWD transport. Parameters are currently the same as "jtag newtap" but this is expected to change.

Command: swd wcr trn prescale

Updates TRN (turnaraound delay) and prescaling.fields of the Wire Control Register (WCR). No parameters: displays current settings.

8.3.3 SPI Transport

The Serial Peripheral Interface (SPI) is a general purpose transport which uses four wire signaling. Some processors use it as part of a solution for flash programming.

8.4 JTAG Speed

JTAG clock setup is part of system setup. It does not belong with interface setup since any interface only knows a few of the constraints for the JTAG clock speed. Sometimes the JTAG speed is changed during the target initialization process: (1) slow at reset, (2) program the CPU clocks, (3) run fast. Both the "slow" and "fast" clock rates are functions of the oscillators used, the chip, the board design, and sometimes power management software that may be active.

The speed used during reset, and the scan chain verification which follows reset, can be adjusted using a reset-start target event handler. It can then be reconfigured to a faster speed by a reset-init target event handler after it reprograms those CPU clocks, or manually (if something else, such as a boot loader, sets up those clocks). See Target Events. When the initial low JTAG speed is a chip characteristic, perhaps because of a required oscillator speed, provide such a handler in the target config file. When that speed is a function of a board-specific characteristic such as which speed oscillator is used, it belongs in the board config file instead. In both cases it’s safest to also set the initial JTAG clock rate to that same slow speed, so that OpenOCD never starts up using a clock speed that’s faster than the scan chain can support.

jtag_rclk 3000
$_TARGET.cpu configure -event reset-start { jtag_rclk 3000 }

If your system supports adaptive clocking (RTCK), configuring JTAG to use that is probably the most robust approach. However, it introduces delays to synchronize clocks; so it may not be the fastest solution.

NOTE: Script writers should consider using jtag_rclk instead of adapter_khz, but only for (ARM) cores and boards which support adaptive clocking.

Command: adapter_khz max_speed_kHz

A non-zero speed is in KHZ. Hence: 3000 is 3mhz. JTAG interfaces usually support a limited number of speeds. The speed actually used won’t be faster than the speed specified.

Chip data sheets generally include a top JTAG clock rate. The actual rate is often a function of a CPU core clock, and is normally less than that peak rate. For example, most ARM cores accept at most one sixth of the CPU clock.

Speed 0 (khz) selects RTCK method. See FAQ RTCK. If your system uses RTCK, you won’t need to change the JTAG clocking after setup. Not all interfaces, boards, or targets support “rtck”. If the interface device can not support it, an error is returned when you try to use RTCK.

Function: jtag_rclk fallback_speed_kHz

This Tcl proc (defined in startup.tcl) attempts to enable RTCK/RCLK. If that fails (maybe the interface, board, or target doesn’t support it), falls back to the specified frequency.

# Fall back to 3mhz if RTCK is not supported
jtag_rclk 3000

Next: , Previous: , Up: Top   [Contents][Index]