Next: Reset Configuration, Previous: Server Configuration, Up: Top [Contents][Index]
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.
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.
Use the adapter driver name to connect to the target.
List the debug adapter drivers that have been built into the running copy of OpenOCD.
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.
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.
Returns the name of the debug adapter driver being used.
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.
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 (ti-icdi), jlink, kitprog, opendus, openjtag, osbdm, presto, rlink, st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.
Each of the interface drivers listed here must be explicitly enabled when OpenOCD is configured, in order to be made available at run time.
Amontec Chameleon in its JTAG Accelerator configuration, connected to a PC’s EPP mode parallel port. This defines some driver-specific commands:
Specifies either the address of the I/O port (default: 0x378 for LPT1) or the number of the /dev/parport device.
Displays status of RTCK option. Optionally sets that option first.
This is the NanoXplore’s ANGIE USB-JTAG Adapter.
Olimex ARM-JTAG-EW USB adapter This has one driver-specific command:
Logs some status
Supports bitbanged JTAG from the local system, presuming that system is an Atmel AT91rm9200 and a specific set of GPIOs is used.
ARM CMSIS-DAP compliant based adapter v1 (USB HID based) or v2 (USB bulk).
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
Specifies how to communicate with the adapter:
cmsis-dap backend is not specified.
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.
Enables or disables the following workarounds of known CMSIS-DAP adapter quirks:
The quirk workarounds are disabled by default. The command without a parameter displays current setting.
Display various device information, like hardware version, firmware version, current bus status.
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
A dummy software-only driver for debugging.
Cirrus Logic EP93xx based single-board computer bit-banging (in development)
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:
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
Provides the USB device description (the iProduct string) of the adapter. If not specified, the device description is ignored during device selection.
Selects the channel of the FTDI device to use for MPSSE operations. Most adapters use the default, channel 0, but there are exceptions.
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.
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.
Set a previously defined signal to the specified level.
Get the value of a previously defined signal.
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.
For example adapter definitions, see the configuration files shipped in the interface/ftdi directory.
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:
The vendor ID and product ID of the adapter. If not specified, default 0x0403:0x6001 is used.
Set four JTAG GPIO numbers at once. If not specified, default 0 3 1 2 or TXD CTS RXD RTS is used.
Set TCK GPIO number. If not specified, default 0 or TXD is used.
Set TMS GPIO number. If not specified, default 3 or CTS is used.
Set TDI GPIO number. If not specified, default 1 or RXD is used.
Set TDO GPIO number. If not specified, default 2 or RTS is used.
Set TRST GPIO number. If not specified, default 4 or DTR is used.
Set SRST GPIO number. If not specified, default 6 or DCD is used.
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.
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.
Specifies the TCP port of the remote process to connect to or 0 to use UNIX sockets instead of TCP.
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.
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
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:
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
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
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.
This command specifies path to access USB-Blaster II firmware image. To be used with USB-Blaster II only.
Gateworks GW16012 JTAG programmer. This has one driver-specific command:
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.
Switch the 5 V target power supply on or off. Without argument, show the state of the target power supply. The target power supply is usually connected to pin 19 of the 20-pin connector.
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’.
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:
kitprog init_acquire_psoc in order to
communicate with PSoC 5LP devices. This is because, assuming debug is not
disabled on the PSoC, the PSoC 5LP needs its JTAG interface switched to SWD
mode before communication can begin, but prior to firmware 2.14, "JTAG to SWD"
could only be sent with an acquisition sequence.
Indicate that a PSoC acquisition sequence needs to be run during adapter init. Please be aware that the acquisition sequence hard-resets the target.
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.
Display various adapter information, such as the hardware version, firmware version, and target voltage.
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:
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:
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.
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 500This 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 1000or 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 speedcommand 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 speedcommand; be conservative.
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
ASIX PRESTO USB JTAG programmer.
Raisonance RLink USB adapter
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.
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.
Currently Not Supported.
Specifies the adapter layout to use.
Pairs of vendor IDs and product IDs of the device.
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 2015 firmware V2J24), STLINK-V3 and STLINK-V3PWR, thanks to a new API that provides directly access the arm ADIv5 DAP.
The older API that requires HLA transport is deprecated and will be dropped from OpenOCD. In mean time it’s still available by using interface/stlink-hla.cfg.
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
opendous-jtag is a freely programmable USB adapter.
This is the Keil ULINK v1 JTAG debugger.
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:
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.
Displays information about the connected XDS110 debug probe (e.g. firmware version).
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).
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".
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.
Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified, speed_coeff defaults to 113714, and speed_offset defaults to 28.
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:
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.
peripheral_base must be configured.
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.
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.
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.
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.
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.
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.
OpenJTAG compatible USB adapter. This defines some driver-specific commands:
Specifies the variant of the OpenJTAG adapter (see http://www.openjtag.org/). Currently valid variant values include:
The USB device description string of the adapter. This value is only used with the standard variant.
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
Cadence Virtual Debug Interface driver.
Specifies the host and TCP port number where the vdebug server runs.
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
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.
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.
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.
SystemVerilog Direct Programming Interface (DPI) compatible driver for JTAG devices in emulation. The driver acts as a client for the SystemVerilog DPI server interface.
Specifies the TCP/IP port number of the SystemVerilog DPI server interface.
Specifies the TCP/IP address of the SystemVerilog DPI server interface.
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.
Specify the serial port’s filename. For example:
buspirate port /dev/ttyUSB0
Set the communication speed to 115k (normal) or 1M (fast). For example:
buspirate speed normal
Set the Bus Pirate output mode.
For example:
buspirate mode normal
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
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
Turns the Bus Pirate’s LED on (1) or off (0). For example:
buspirate led 1
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.
Returns the current state of the TDO line
Manually set the status of the output lines with the order of (tdi tms tck trst srst)
espusbjtag setio 0 1 0 1 0
Set vendor ID and product ID for the ESP usb jtag driver
espusbjtag vid_pid 0x303a 0x1001
Set the jtag descriptor to read capabilities of ESP usb jtag driver
espusbjtag caps_descriptor 0x2000
Set chip id to transfer to the ESP USB bridge board
espusbjtag chip_id 1
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.
Print the DAPBUS dmem configuration.
Set the DAPBUS memory access device (default: /dev/mem).
Set the DAPBUS base address which is used to access CoreSight compliant Access Ports (APs) directly.
Set the address offset between Access Ports (APs).
Set the maximum number of valid access ports on the SoC.
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.
Set the emulated address and address window size. Both of these parameters must be aligned to page size.
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).
displays the names of the transports supported by this version of OpenOCD.
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). When invoked with no transport name:
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).
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).
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.
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.
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.
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.
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.
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: Reset Configuration, Previous: Server Configuration, Up: Top [Contents][Index]