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
adapter driver jlink

Most adapters need a bit more configuration than that.

8.1 Adapter Configuration

The adapter driver 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: adapter driver name

Use the adapter driver name to connect to the target.

Command: adapter list

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

Config Command: adapter 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.

Config Command: adapter gpio [ tdo | tdi | tms | tck | trst | swdio | swdio_dir | swclk | srst | led [ gpio_number | -chip chip_number | -active-high | -active-low | -push-pull | -open-drain | -open-source | -pull-none | -pull-up | -pull-down | -init-inactive | -init-active | -init-input ] ]

Define the GPIO mapping that the adapter will use. The following signals can be defined:

Some adapters require that the GPIO chip number is set in addition to the GPIO number. The configuration options enable signals to be defined as active-high or active-low. The output drive mode can be set to push-pull, open-drain or open-source. Most adapters will have to emulate open-drain or open-source drive modes by switching between an input and output. Input and output signals can be instructed to use a pull-up or pull-down resistor, assuming it is supported by the adaptor driver and hardware. The initial state of outputs may also be set, "active" state means 1 for active-high outputs and 0 for active-low outputs. Bidirectional signals may also be initialized as an input. If the swdio signal is buffered the buffer direction can be controlled with the swdio_dir signal; the active state means that the buffer should be set as an output with respect to the adapter. The command options are cumulative with later commands able to override settings defined by earlier ones. The two commands gpio led 7 -active-high and gpio led -chip 1 -active-low sent sequentially are equivalent to issuing the single command gpio led 7 -chip 1 -active-low. It is not permissible to set the drive mode or initial state for signals which are inputs. The drive mode for the srst and trst signals must be set with the adapter reset_config command. It is not permissible to set the initial state of swdio_dir as it is derived from the initial state of swdio. The command adapter gpio prints the current configuration for all GPIOs while the command adapter gpio gpio_name prints the current configuration for gpio_name. Not all adapters support this generic GPIO mapping, some require their own commands to define the GPIOs used. Adapters that support the generic mapping may not support all of the listed options.

Command: adapter name

Returns the name of the debug adapter driver being used.

Config Command: adapter usb location [<bus>-<port>[.<port>]...]

Displays or 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 or dmesg.

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

Config Command: adapter serial serial_string

Specifies the serial_string of the adapter to use. If this command is not specified, serial strings are not checked. Only the following adapter drivers use the serial string from this command: arm-jtag-ew, cmsis_dap, esp_usb_jtag, ft232r, ftdi, hla (stlink, ti-icdi), jlink, kitprog, opendus, openjtag, osbdm, presto, rlink, st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.

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

This is the NanoXplore’s ANGIE USB-JTAG Adapter.

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 v1 (USB HID based) or v2 (USB bulk).

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 backend [auto|usb_bulk|hid]

Specifies how to communicate with the adapter:

  • - hid Use HID generic reports - CMSIS-DAP v1
  • - usb_bulk Use USB bulk - CMSIS-DAP v2
  • - auto First try USB bulk CMSIS-DAP v2, if not found try HID CMSIS-DAP v1. This is the default if cmsis-dap backend is not specified.
Config Command: cmsis-dap usb interface [number]

Specifies the number of the USB interface to use in v2 mode (USB bulk). In most cases need not to be specified and interfaces are searched by interface string or for user class interface.

Command: cmsis-dap quirk [enable|disable]

Enables or disables the following workarounds of known CMSIS-DAP adapter quirks:

  • - disconnect and re-connect before sending a switch sequence
  • - packets pipelining is suppressed, only one packet at a time is submitted to the adapter

The quirk workarounds are disabled by default. The command without a parameter displays current setting.

Command: cmsis-dap info

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

Command: cmsis-dap cmd number number ...

Execute an arbitrary CMSIS-DAP command. Use for adapter testing or for handling of an adapter vendor specific command from a Tcl script.

Take given numbers as bytes, assemble a CMSIS-DAP protocol command packet from them and send it to the adapter. The first 4 bytes of the adapter response are logged. See https://arm-software.github.io/CMSIS_5/DAP/html/group__DAP__Commands__gr.html

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.

Support for new FTDI based adapters can be added completely 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 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.

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 possibility 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: ft232r

This driver is implementing synchronous bitbang mode of an FTDI FT232R, FT230X, FT231X and similar USB UART bridge ICs by reusing RS232 signals as GPIO. It currently doesn’t support using CBUS pins as GPIO.

List of connections (default physical pin numbers for FT232R in 28-pin SSOP package):

User can change default pinout by supplying configuration commands with GPIO numbers or RS232 signal names. GPIO numbers correspond to bit numbers in FTDI GPIO register. They differ from physical pin numbers. For details see actual FTDI chip datasheets. Every JTAG line must be configured to unique GPIO number different than any other JTAG line, even those lines that are sometimes not used like TRST or SRST.

FT232R

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

Config Command: ft232r vid_pid vid pid

The vendor ID and product ID of the adapter. If not specified, default 0x0403:0x6001 is used.

Config Command: ft232r jtag_nums tck tms tdi tdo

Set four JTAG GPIO numbers at once. If not specified, default 0 3 1 2 or TXD CTS RXD RTS is used.

Config Command: ft232r tck_num tck

Set TCK GPIO number. If not specified, default 0 or TXD is used.

Config Command: ft232r tms_num tms

Set TMS GPIO number. If not specified, default 3 or CTS is used.

Config Command: ft232r tdi_num tdi

Set TDI GPIO number. If not specified, default 1 or RXD is used.

Config Command: ft232r tdo_num tdo

Set TDO GPIO number. If not specified, default 2 or RTS is used.

Config Command: ft232r trst_num trst

Set TRST GPIO number. If not specified, default 4 or DTR is used.

Config Command: ft232r srst_num srst

Set SRST GPIO number. If not specified, default 6 or DCD is used.

Config Command: ft232r restore_serial word

Restore serial port after JTAG. This USB bitmode control word (16-bit) will be sent before quit. Lower byte should set GPIO direction register to a "sane" state: 0x15 for TXD RTS DTR as outputs (1), others as inputs (0). Higher byte is usually 0 to disable bitbang mode. When kernel driver reattaches, serial port should continue to work. Value 0xFFFF disables sending control word and serial port, then kernel driver will not reattach. If not specified, default 0xFFFF is used.

Interface Driver: remote_bitbang

Drive JTAG and SWD 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 and SWD.

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.

Config Command: remote_bitbang use_remote_sleep (on|off)

If this option is enabled, delays will not be executed locally but instead forwarded to the remote host. This is useful if the remote host performs its own request queuing rather than executing requests immediately.

This is disabled by default. This option must only be enabled if the given remote_bitbang host supports receiving the delay information.

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

adapter driver remote_bitbang
remote_bitbang port 3335
remote_bitbang host foobar

And if you also wished to enable remote sleeping:

adapter driver remote_bitbang
remote_bitbang port 3335
remote_bitbang host foobar
remote_bitbang use_remote_sleep on

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

adapter driver 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 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
Config 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.

Config 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.

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

Compatibility Note: SEGGER released many firmware versions for the many hardware 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.

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

Display free device internal memory.

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

Display the device configuration.

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

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

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.

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.

Reset the current configuration.

Write the current configuration to the internal persistent storage.

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

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
77a90000

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 not always unambiguous. It is recommended to use the serial number instead, if possible.

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

Interface Driver: kitprog

This driver is for Cypress Semiconductor’s KitProg adapters. The KitProg is an SWD-only adapter that is designed to be used with Cypress’s PSoC and PRoC device families, but it is possible to use it with some other devices. If you are using this adapter with a PSoC or a PRoC, you may need to add kitprog init_acquire_psoc or kitprog acquire_psoc to your configuration script.

Note that this driver is for the proprietary KitProg protocol, not the CMSIS-DAP mode introduced in firmware 2.14. If the KitProg is in CMSIS-DAP mode, it cannot be used with this driver, and must either be used with the cmsis-dap driver or switched back to KitProg mode. See the Cypress KitProg User Guide for instructions on how to switch KitProg modes.

Known limitations:

Config Command: kitprog init_acquire_psoc

Indicate that a PSoC acquisition sequence needs to be run during adapter init. Please be aware that the acquisition sequence hard-resets the target.

Command: kitprog acquire_psoc

Run a PSoC acquisition sequence immediately. Typically, this should not be used outside of the target-specific configuration scripts since it hard-resets the target as a side-effect. This is necessary for "reset halt" on some PSoC 4 series devices.

Command: kitprog info

Display various adapter information, such as the hardware version, firmware version, and target voltage.

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 http://www.lartmaker.nl/projects/jtag/).
  • - 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.

Config 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 speed 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 speed 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 speed command 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 with the rate you specified in the adapter speed command; 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:

adapter driver parport
parport port 0x278
parport cable wiggler
Interface Driver: presto

ASIX PRESTO USB JTAG programmer.

Raisonance RLink USB adapter

Interface Driver: usbprog

usbprog is a freely programmable USB adapter.

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 STMicroelectronics ST-LINK, TI ICDI and Nuvoton Nu-Link. ST-LINK 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 ST-LINK firmware even if current version reported is V2.J21.S4.

Config Command: hla_device_desc description

Currently Not Supported.

Config Command: hla_layout (stlink|icdi|nulink)

Specifies the adapter layout to use.

Config Command: hla_vid_pid [vid pid]+

Pairs of vendor IDs and product IDs of the device.

ST-Link only: Choose between ’exclusive’ USB communication (the default backend) or ’shared’ mode using ST-Link TCP server (the default port is 7184).

Note: ST-Link TCP server is a binary application provided by ST available from ST-LINK server software module.

Command: hla_command command

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

This is a driver that supports STMicroelectronics adapters ST-LINK/V2 (from firmware V2J24), STLINK-V3 and STLINK-V3PWR, thanks to a new API that provides directly access the arm ADIv5 DAP.

The new API provide access to multiple AP on the same DAP, but the maximum number of the AP port is limited by the specific firmware version (e.g. firmware V2J29 has 3 as maximum AP number, while V2J32 has 8). An error is returned for any AP number above the maximum allowed value.

Note: Either these same adapters and their older versions are also supported by the hla interface driver.

Choose between ’exclusive’ USB communication (the default backend) or ’shared’ mode using ST-Link TCP server (the default port is 7184).

Note: ST-Link TCP server is a binary application provided by ST available from ST-LINK server software module.

Note: ST-Link TCP server does not support the SWIM transport.

Pairs of vendor IDs and product IDs of the device.

Sends an arbitrary command composed by the sequence of bytes tx_byte and receives rx_n bytes.

For example, the command to read the target’s supply voltage is one byte 0xf7 followed by 15 bytes zero. It returns 8 bytes, where the first 4 bytes represent the ADC sampling of the reference voltage 1.2V and the last 4 bytes represent the ADC sampling of half the target’s supply voltage.

> st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0xf1 0x05 0x00 0x00 0x0b 0x08 0x00 0x00

The result can be converted to Volts (ignoring the most significant bytes, always zero)

> set a [st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
> set n [expr {[lindex $a 4] + 256 * [lindex $a 5]}]
> set d [expr {[lindex $a 0] + 256 * [lindex $a 1]}]
> echo [expr {2 * 1.2 * $n / $d}]
3.24891518738
Interface Driver: opendous

opendous-jtag is a freely programmable USB adapter.

This is the Keil ULINK v1 JTAG debugger.

Interface Driver: xds110

The XDS110 is included as the embedded debug probe on many Texas Instruments LaunchPad evaluation boards. The XDS110 is also available as a stand-alone USB debug probe with the added capability to supply power to the target board. The following commands are supported by the XDS110 driver:

Config Command: xds110 supply voltage_in_millivolts

Available only on the XDS110 stand-alone probe. Sets the voltage level of the XDS110 power supply. A value of 0 leaves the supply off. Otherwise, the supply can be set to any value in the range 1800 to 3600 millivolts.

Command: xds110 info

Displays information about the connected XDS110 debug probe (e.g. firmware version).

Interface Driver: xlnx_pcie_xvc

This driver supports the Xilinx Virtual Cable (XVC) over PCI Express. It is commonly found in Xilinx based PCI Express designs. It allows debugging fabric based JTAG/SWD devices such as Cortex-M1/M3 microcontrollers. Access to this is exposed via extended capability registers in the PCI Express configuration space.

For more information see Xilinx PG245 (Section on From_PCIE_to_JTAG mode).

Config Command: xlnx_pcie_xvc config device

Specifies the PCI Express device via parameter device to use.

The correct value for device can be obtained by looking at the output of lscpi -D (first column) for the corresponding device.

The string will be of the format "DDDD:BB:SS.F" such as "0000:65:00.1".

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.

GPIO numbers >= 32 can’t be used for performance reasons. GPIO configuration is handled by the generic command adapter gpio.

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

Config Command: bcm2835gpio speed_coeffs speed_coeff speed_offset

Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified, speed_coeff defaults to 113714, and speed_offset defaults to 28.

Config Command: bcm2835gpio peripheral_mem_dev device

Set the device path for access to the memory mapped GPIO control registers. Uses /dev/gpiomem by default, this is also the preferred option with respect to system security. If overridden to /dev/mem:

  • - OpenOCD needs cap_sys_rawio or run as root to open /dev/mem. Please be aware of security issues imposed by running OpenOCD with elevated user rights and by /dev/mem itself.
  • - correct peripheral_base must be configured.
  • - GPIO 0-27 pads are set to the limited slew rate and drive strength is reduced to 4 mA (2 mA on RPi 4).
Config Command: bcm2835gpio peripheral_base base

Set the peripheral base register address to access GPIOs. Ignored if /dev/gpiomem is used. For the RPi1, use 0x20000000. For RPi2 and RPi3, use 0x3F000000. For RPi4, use 0xFE000000. A full list can be found in the official guide.

Interface Driver: imx_gpio

i.MX SoC is present in many community boards. Wandboard is an example of the one which is most popular.

This driver is mostly the same as bcm2835gpio.

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

Interface Driver: am335xgpio The AM335x SoC is present in BeagleBone

Black and BeagleBone Green single-board computers which expose some of the GPIOs on the two expansion headers.

For maximum performance the driver accesses memory-mapped GPIO peripheral registers directly. The memory mapping requires read and write permission to kernel memory; if /dev/gpiomem exists it will be used, otherwise /dev/mem will be used. The driver restores the GPIO state on exit.

All four GPIO ports are available. GPIO configuration is handled by the generic command adapter gpio.

Config Command: am335xgpio speed_coeffs speed_coeff speed_offset

Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified speed_coeff defaults to 600000 and speed_offset defaults to 575.

See interface/beaglebone-swd-native.cfg for a sample configuration file.

Interface Driver: linuxgpiod

Linux provides userspace access to GPIO through libgpiod since Linux kernel version v4.6. The driver emulates either JTAG or SWD transport through bitbanging. There are no driver-specific commands, all GPIO configuration is handled by the generic command adapter gpio. This driver supports the resistor pull options provided by the adapter gpio command but the underlying hardware may not be able to support them.

See interface/dln-2-gpiod.cfg for a sample configuration file.

Interface Driver: sysfsgpio

Linux legacy userspace access to GPIO through sysfs is deprecated from Linux kernel version v5.3. Prefer using linuxgpiod, instead.

See interface/sysfsgpio-raspberrypi.cfg for a sample config.

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 http://www.openjtag.org/). 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.

Config Command: openjtag vid_pid vid pid

The USB vendor ID and product ID of the adapter. If not specified, default 0x0403:0x6001 is used. This value is only used with the standard variant.

openjtag vid_pid 0x403 0x6014
Interface Driver: vdebug

Cadence Virtual Debug Interface driver.

Config Command: vdebug server host:port

Specifies the host and TCP port number where the vdebug server runs.

Config Command: vdebug batching value

Specifies the batching method for the vdebug request. Possible values are 0 for no batching 1 or wr to batch write transactions together (default) 2 or rw to batch both read and write transactions

Config Command: vdebug polling min max

Takes two values, representing the polling interval in ms. Lower values mean faster debugger responsiveness, but lower emulation performance. The minimum should be around 10, maximum should not exceed 1000, which is the default gdb and keepalive timeout value.

Config Command: vdebug bfm_path path clk_period

Specifies the hierarchical path and input clk period of the vdebug BFM in the design. The hierarchical path uses Verilog notation top.inst.inst The clock period must include the unit, for instance 40ns.

Config Command: vdebug mem_path path base size

Specifies the hierarchical path to the design memory instance for backdoor access. Up to 4 memories can be specified. The hierarchical path uses Verilog notation. The base specifies start address in the design address space, size its size in bytes. Both values can use hexadecimal notation with prefix 0x.

Interface Driver: jtag_dpi

SystemVerilog Direct Programming Interface (DPI) compatible driver for JTAG devices in emulation. The driver acts as a client for the SystemVerilog DPI server interface.

Config Command: jtag_dpi set_port port

Specifies the TCP/IP port number of the SystemVerilog DPI server interface.

Config Command: jtag_dpi set_address address

Specifies the TCP/IP address of the SystemVerilog DPI server interface.

Interface Driver: buspirate

This driver is for the Bus Pirate (see http://dangerousprototypes.com/docs/Bus_Pirate) and compatible devices. It uses a simple data protocol over a serial port connection.

Most hardware development boards have a UART, a real serial port, or a virtual USB serial device, so this driver allows you to start building your own JTAG adapter without the complexity of a custom USB connection.

Config Command: buspirate port serial_port

Specify the serial port’s filename. For example:

buspirate port /dev/ttyUSB0
Config Command: buspirate speed (normal|fast)

Set the communication speed to 115k (normal) or 1M (fast). For example:

buspirate speed normal
Config Command: buspirate mode (normal|open-drain)

Set the Bus Pirate output mode.

  • - In normal mode (push/pull), do not enable the pull-ups, and do not connect I/O header pin VPU to JTAG VREF.
  • - In open drain mode, you will then need to enable the pull-ups.

For example:

buspirate mode normal
Config Command: buspirate pullup (0|1)

Whether to connect (1) or not (0) the I/O header pin VPU (JTAG VREF) to the pull-up/pull-down resistors on MOSI (JTAG TDI), CLK (JTAG TCK), MISO (JTAG TDO) and CS (JTAG TMS). For example:

buspirate pullup 0
Config Command: buspirate vreg (0|1)

Whether to enable (1) or disable (0) the built-in voltage regulator, which can be used to supply power to a test circuit through I/O header pins +3V3 and +5V. For example:

buspirate vreg 0
Command: buspirate led (0|1)

Turns the Bus Pirate’s LED on (1) or off (0). For example:

buspirate led 1
Interface Driver: esp_usb_jtag

Espressif JTAG driver to communicate with ESP32-C3, ESP32-S3 chips and ESP USB Bridge board using OpenOCD. These chips have built-in JTAG circuitry and can be debugged without any additional hardware. Only an USB cable connected to the D+/D- pins is necessary.

Command: espusbjtag tdo

Returns the current state of the TDO line

Command: espusbjtag setio setio

Manually set the status of the output lines with the order of (tdi tms tck trst srst)

espusbjtag setio 0 1 0 1 0
Config Command: espusbjtag vid_pid vid_pid

Set vendor ID and product ID for the ESP usb jtag driver

espusbjtag vid_pid 0x303a 0x1001
Config Command: espusbjtag caps_descriptor caps_descriptor

Set the jtag descriptor to read capabilities of ESP usb jtag driver

espusbjtag caps_descriptor 0x2000
Config Command: espusbjtag chip_id chip_id

Set chip id to transfer to the ESP USB bridge board

espusbjtag chip_id 1
Interface Driver: dmem Direct Memory access debug interface

The Texas Instruments K3 SoC family provides memory access to DAP and coresight control registers. This allows control over the microcontrollers directly from one of the processors on the SOC itself.

For maximum performance, the driver accesses the debug registers directly over the SoC memory map. The memory mapping requires read and write permission to kernel memory via "/dev/mem" and assumes that the system firewall configurations permit direct access to the debug memory space.

+-----------+
|  OpenOCD  |   SoC mem map (/dev/mem)
|    on     +--------------+
| Cortex-A53|              |
+-----------+              |
                           |
+-----------+        +-----v-----+
|Cortex-M4F <--------+           |
+-----------+        |           |
                     |  DebugSS  |
+-----------+        |           |
|Cortex-M4F <--------+           |
+-----------+        +-----------+

NOTE: Firewalls are configurable in K3 SoC and depending on various types of device configuration, this function may be blocked out. Typical behavior observed in such cases is a firewall exception report on the security controller and armv8 processor reporting a system error.

See tcl/interface/ti_k3_am625-swd-native.cfg for a sample configuration file.

Command: dmem info

Print the DAPBUS dmem configuration.

Config Command: dmem device device_path

Set the DAPBUS memory access device (default: /dev/mem).

Config Command: dmem base_address base_address

Set the DAPBUS base address which is used to access CoreSight compliant Access Ports (APs) directly.

Config Command: dmem ap_address_offset offset_address

Set the address offset between Access Ports (APs).

Config Command: dmem max_aps n

Set the maximum number of valid access ports on the SoC.

Config Command: dmem emu_ap_list n

Set the list of Access Ports (APs) that need to be emulated. This emulation mode supports software translation of an AP request into an address mapped transaction that does not rely on physical AP hardware. This maybe needed if the AP is either denied access via memory map or protected using other SoC mechanisms.

Config Command: dmem emu_base_address_range base_address address_window_size

Set the emulated address and address window size. Both of these parameters must be aligned to page size.

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 either the hla interface driver (in which case the command is transport select hla_jtag) or the st-link interface driver (in which case the command is transport select dapdirect_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 either the hla interface driver (in which case the command is transport select hla_swd) or the st-link interface driver (in which case the command is transport select dapdirect_swd).

Config 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.

The newer SWD devices (SW-DP v2 or SWJ-DP v2) support the multi-drop extension of SWD protocol: two or more devices can be connected to one SWD adapter. SWD transport works in multi-drop mode if DAP is configured with both -dp-id and -instance-id parameters regardless how many DAPs are created.

Not all adapters and adapter drivers support SWD multi-drop. Only the following adapter drivers are SWD multi-drop capable: cmsis_dap (use an adapter with CMSIS-DAP version 2.0), ftdi, all bitbang based.

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.3.4 SWIM Transport

The Single Wire Interface Module (SWIM) is a low-pin-count debug protocol used by the STMicroelectronics MCU family STM8 and documented in the User Manual UM470.

SWIM does not support boundary scan testing nor multiple cores.

The SWIM transport is selected with the command transport select swim.

The concept of TAPs does not fit in the protocol since SWIM does not implement a scan chain. Nevertheless, the current SW model of OpenOCD requires defining a virtual SWIM TAP through the command swim newtap basename tap_type. The TAP definition must precede the target definition command target create target_name stm8 -chain-position basename.tap_type.

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 speed, but only for (ARM) cores and boards which support adaptive clocking.

Command: adapter speed 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]