Next: , Previous: Daemon Configuration, Up: Top


8 Interface - Dongle Configuration

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

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

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

     # jlink interface
     interface jlink

Most adapters need a bit more configuration than that.

8.1 Interface Configuration

The interface command tells OpenOCD what type of JTAG dongle you are using. Depending on the type of dongle, you may need to have one or more additional commands.

— Config Command: interface name

Use the interface driver name to connect to the target.

— Command: interface_list

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

— Command: jtag interface

Returns the name of the interface driver being used.

8.2 Interface Drivers

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

— Interface Driver: amt_jtagaccel

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

— Config Command: parport_port number

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

— Config Command: rtck [enable|disable]

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

— Interface Driver: arm-jtag-ew

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

— Command: armjtagew_info

Logs some status

— Interface Driver: at91rm9200

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

— Interface Driver: dummy

A dummy software-only driver for debugging.

— Interface Driver: ep93xx

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

— Interface Driver: ft2232

FTDI FT2232 (USB) based devices over one of the userspace libraries. These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain:

— Config Command: ft2232_device_desc description

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

— Config Command: ft2232_serial serial-number

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

— Config Command: ft2232_layout name

Each vendor's FT2232 device can use different GPIO signals to control output-enables, reset signals, and LEDs. Currently valid layout name values include:

  • axm0432_jtag Axiom AXM-0432
  • comstick Hitex STR9 comstick
  • cortino Hitex Cortino JTAG interface
  • evb_lm3s811 Luminary Micro EVB_LM3S811 as a JTAG interface, either for the local Cortex-M3 (SRST only) or in a passthrough mode (neither SRST nor TRST)
  • luminary_icdi Luminary In-Circuit Debug Interface (ICDI) Board
  • flyswatter Tin Can Tools Flyswatter
  • icebear ICEbear JTAG adapter from Section 5
  • jtagkey Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
  • jtagkey2 Amontec JTAGkey2 (and compatibles)
  • m5960 American Microsystems M5960
  • olimex-jtag Olimex ARM-USB-OCD and ARM-USB-Tiny
  • oocdlink OOCDLink
  • sheevaplug Marvell Sheevaplug development kit
  • signalyzer Xverve Signalyzer
  • stm32stick Hitex STM32 Performance Stick
  • turtelizer2 egnite Software turtelizer2
  • usbjtag "USBJTAG-1" layout described in the OpenOCD diploma thesis

— Config Command: ft2232_vid_pid [vid pid]+

The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI default values are used. Currently, up to eight [vid, pid] pairs may be given, e.g.

               ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
— Config Command: ft2232_latency ms

On some systems using FT2232 based JTAG interfaces the FT_Read function call in ft2232_read() fails to return the expected number of bytes. This can be caused by USB communication delays and has proved hard to reproduce and debug. Setting the FT2232 latency timer to a larger value increases delays for short USB packets but it also reduces the risk of timeouts before receiving the expected number of bytes. The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.

For example, the interface config file for a Turtelizer JTAG Adapter looks something like this:

          interface ft2232
          ft2232_device_desc "Turtelizer JTAG/RS232 Adapter"
          ft2232_layout turtelizer2
          ft2232_vid_pid 0x0403 0xbdc8
— Interface Driver: gw16012

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

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

— Interface Driver: jlink

Segger jlink USB adapter

— 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

The layout of the parallel port cable used to connect to the target. 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 number

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

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_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 might look something like this:

          interface parport
          parport_port 0xc8b8
          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: ZY1000

This is the Zylin ZY1000 JTAG debugger.

Note: This defines some driver-specific commands, which are not currently documented here.
— Command: power [on|off]

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

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

— Command: jtag_khz max_speed_kHz

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

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

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

— Function: jtag_rclk fallback_speed_kHz

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

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