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

  - `tdo`, `tdi`, `tms`, `tck`, `trst`: JTAG transport signals
  - `swdio`, `swclk`: SWD transport signals
  - `swdio_dir`: optional swdio buffer control signal
  - `srst`: system reset signal
  - `led`: optional activity led

  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: aice (aice_usb), arm-jtag-ew, cmsis_dap, 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: 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 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:

  - Push-pull with one FTDI output as (non-)inverted data line
  - Open drain with one FTDI output as (non-)inverted output-enable
  - Tristate with one FTDI output as (non-)inverted data line and another FTDI output as (non-)inverted output-enable
  - Unbuffered, using the FTDI GPIO as a tristate output directly by switching data and direction as necessary

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

  - RXD(5) - TDI
  - TXD(1) - TCK
  - RTS(3) - TDO
  - CTS(11) - TMS
  - DTR(2) - TRST
  - DCD(10) - SRST

  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

  - bit 7 - RI
  - bit 6 - DCD
  - bit 5 - DSR
  - bit 4 - DTR
  - bit 3 - CTS
  - bit 2 - RTS
  - bit 1 - RXD
  - bit 0 - TXD

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

      adapter driver remote_bitbang
      remote_bitbang port 3335
      remote_bitbang host foobar

  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.

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

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

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

  - The frequency of SWCLK cannot be configured, and varies between 1.6 MHz and 2.7 MHz.
  - For firmware versions below 2.14, "JTAG to SWD" sequences are replaced by "SWD line reset" in the driver. This is for two reasons. First, the KitProg does not support sending arbitrary SWD sequences, and only firmware 2.14 and later implement both "JTAG to SWD" and "SWD line reset" in firmware. Earlier firmware versions only implement "SWD line reset". Second, due to a firmware quirk, an SWD sequence must be sent after every target reset in order to re-establish communications with the target.
  - Due in part to the limitation above, KitProg devices with firmware below version 2.14 will need to use `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.
  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.

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

  Config Command: hla_stlink_backend (usb | tcp [port]) ¶

    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.

Interface Driver: st-link ¶

  This is a driver that supports STMicroelectronics adapters ST-LINK/V2 (from firmware V2J24) and STLINK-V3, 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.

  Config Command: st-link backend (usb | tcp [port]) ¶

    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.

  Config Command: st-link vid_pid [vid pid]+ ¶

    Pairs of vendor IDs and product IDs of the device.

  Command: st-link cmd rx_n (tx_byte)+ ¶

    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.

Interface Driver: ulink ¶

  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 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_base base ¶

    Set the peripheral base register address to access GPIOs. 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:

    - standard Standard variant (default).
    - cy7c65215 Cypress CY7C65215 Dual Channel USB-Serial Bridge Controller (see http://www.cypress.com/?rID=82870).
  Config Command: openjtag device_desc string ¶

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

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

### 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