Debug Adapters/Interfaces/Dongles are normally configured through commands in an interface configuration file which is sourced by your opened .cfg file, or through a command line -f interface/....cfg option. These commands tell Open OCD what type of JTAG adapter you have, and how to talk to it.
The adapter driver builds-in similar knowledge; use this only when external configuration (such as jumping) changes what the hardware can support. The USB bus topology can be queried with the command sub -t or DRESG.
Each of the interface drivers listed here must be explicitly enabled when Open OCD is configured, in order to be made available at run time. Interface Driver: amt_jtagaccel Monte Chameleon in its JTAG Accelerator configuration, connected to a PC’s EPP mode parallel port.
Interface Driver: arm-jtag-ew Oliver ARM-JTAG-EW USB adapter This has one driver-specific command: Command: armjtagew_info Interface Driver: at91rm9200 Supports bit banged JTAG from the local system, presuming that system is an Armed AT91rm9200 and a specific set of GPIS is used.
Interface Driver: ep93xx Cirrus Logic EP93xx based single-board computer bit-banging (in development) The driver is using libusb-1.0 in asynchronous mode to talk to the TDI device, bypassing intermediate libraries like lift or D2XX.
Support for new TDI based adapters can be added completely through configuration files, without the need to patch and rebuild Open OCD. The driver uses a signal abstraction to enable TCL configuration files to define outputs for one or several TDI GPO.
Special signal names are reserved for first, first and LED (for blink) so that they, if defined, will be used for their customary purpose. When set, the adapter should route the SDIO 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 SDIO pin or keep the SDIO pin Hi-Z, respectively. Depending on the type of buffer attached to the TDI GPO, the outputs have to be controlled differently.
The USB bus topology can be queried with the command sub -t. Each value is a 16-bit number corresponding to the concatenation of the high and low TDI GPO 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.
The masks are TDI GPO register bit masks to tell the driver the connection and type of the output buffer driving the respective signal. Data_mask is the bit mask for the pin(s) connected to the data input of the output buffer.
The Joe (or Noe) option tells where the output-enable (or not-output-enable) input to the output buffer is connected. The options -input and input specify the bit mask for pins to be read with the method ftdi_get_signal.
Then the TDI pin is considered being connected straight to the target without any buffer. The TDI 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 TDI. Command: ftdi_set_signal name 0 | 1 | z Set a previously defined signal to the specified level.
Due to signal propagation delays, sampling TO on rising TCK can become quite peculiar at high JTAG clock speeds. However, TDI chips offer a possibility to sample TO on falling edge of TCK.
For example adapter definitions, see the configuration files shipped in the interface/TDI directory. Interface Driver: ft232r This driver is implementing synchronous bit bang mode of an TDI FT232R, FT230X, FT231X and similar USB PART bridge ICS by reusing RS232 signals as GPO.
These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain: Config Command: ft232r_serial_desc serial Specifies the serial of the adapter to use, in case the vendor provides unique IDs and more than one adapter is connected to the host.
Config Command: ft232r_jtag_nums tcktmstditdo Set four JTAG GPO numbers at once. If not specified, default 0 3 1 2 or TED CTS RED RTS is used.
Config Command: ft232r_restore_serial word Restore serial port after JTAG. Lower byte should set GPO direction register to a “sane” state: 0×15 for TED RTS DR as outputs (1), others as inputs (0).
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.
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 bit bang 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. Interface Driver: USB_blaster USB JTAG/USB-Blaster compatibles over one of the user space libraries for TDI chips.
These pins can be used as SST and/or TEST provided the appropriate connections are made on the target board. Command: usb_blaster_lowlevel_driver (TDI | ublast2) Chooses the low level access method for the adapter.
If not specified, TDI is selected unless it wasn’t enabled during the configure stage. Config Command: parport_port Display either the address of the I/O port (default: 0×378 for LPT1) or the number of the /dev/purport device.
Interface Driver: link SEEGER J-Link family of USB adapters. Open OCD was extensively tested and intended to run on all of them, but some combinations were reported as incompatible.
Command: link status Display various hardware related information, for example target voltage and pin states. Command: link freemen Display free device internal memory.
Command: link config target power Set the target power state on JTAG-pin 19. This will also change the USB Product ID (PID) of the device.
If you are using this adapter with a PSO or a Pro, you may need to add kitprog_init_acquire_psoc or Fitzroy acquire_psoc to your configuration script. Note that this driver is for the proprietary Fitzroy protocol, not the CMSIS-DAP mode introduced in firmware 2.14.
Earlier firmware versions only implement “SD line reset”. This is because, assuming debug is not disabled on the PSO, the PSO 5LP needs its JTAG interface switched to SD mode before communication can begin, but prior to firmware 2.14, “JTAG to SD” could only be sent with an acquisition sequence.
Config Command: kitprog_init_acquire_psoc Indicate that a PSO acquisition sequence needs to be run during adapter unit. Command: Fitzroy acquire_psoc Run a PSO acquisition sequence immediately.
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.
Config Command: parport_port Display either the address of the I/O port (default: 0×378 for LPT1) or the number of the /dev/purport device. Command: parport_toggling_time Displays how many nanoseconds the hardware needs to toggle TCK; the purport 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.
Tip: To measure the toggling time with a logic analyzer or a digital storage oscilloscope, follow the procedure below: Now, measure the time between the two closest spaced TCK transitions.
Config Command: presto_serial serial_string Configures the USB serial number of the Presto device to use. Note: This defines quite a few driver-specific commands, which are not currently documented here.
This type of adapter does not expose some lower level API’s that Open OCD would normally use to access the target. Currently, supported adapters include the Microelectronics ST-LINK, TI ACDI and Notion Nu-Link.
An error is returned for any AP number above the maximum allowed value. Interface Driver: opens opendous-jtag is a freely programmable USB adapter.
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.
Command: xds110 info Displays information about the connected XDS110 debug probe (e.g. firmware version). It is commonly found in Filing based PCI Express designs.
It allows debugging fabric based JTAG/SD devices such as Cortex-M1/M3 microcontrollers. Access to this is exposed via extended capability registers in the PCI Express configuration space.
Interface Driver: bcm2835gpio This SoC is present in Raspberry Pi which is a cheap single-board computer exposing some GPIS on its expansion header. The driver accesses memory-mapped GPO peripheral registers directly for maximum performance, but the only possible race condition is for the pins’ modes/mixing (which is highly unlikely), so it should be able to coexist nicely with both sylphs bit banging and various peripherals’ kernel drivers.
Interface Driver: imx_gpio i.MX SoC is present in many community boards. The driver emulates either JTAG and SD transport through bit banging.
The driver acts as a client for the SystemVerilog DPI server interface. 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. 8.3.2 SD Transport SD (Serial Wire Debug) is an ARM-specific transport which exposes one Debug Access Point (DAY, which must be explicitly declared.
Parameters are currently the same as “JTAG new tap” but this is expected to change. 8.3.4 SWIM Transport The Single Wire Interface Module (SWIM) is a low-pin-count debug protocol used by the Microelectronics MCU family STM8 and documented in the User Manual UM470.
SWIM does not support boundary scan testing nor multiple cores. The concept of Taps does not fit in the protocol since SWIM does not implement a scan chain.
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.
In both cases it’s safest to also set the initial JTAG clock rate to that same slow speed, so that Open OCD never starts up using a clock speed that’s faster than the scan chain can support. If your system supports adaptive clocking (ROCK), configuring JTAG to use that is probably the most robust approach.
However, it introduces delays synchronizing clocks; so it may not be the fastest solution. JTAG interfaces usually support a limited number of speeds.
Chip data sheets generally include a top JTAG clock rate. For example, most ARM cores accept at most one sixth of the CPU clock.
If your system uses ROCK, you won’t need to change the JTAG clocking after setup. If the interface device can not support it, an error is returned when you try to use ROCK.
Function: jtag_rclk fallback_speed_kHz This TCL pro (defined in startup.TCL) attempts to enable ROCK/RCK. If that fails (maybe the interface, board, or target doesn’t support it), falls back to the specified frequency.