Next: Reset Configuration, Previous: Daemon 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 interface jlink
Most adapters need a bit more configuration than that.
The interface 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 interface 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.
Returns the name of the debug adapter driver being used.
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.
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.
A dummy software-only driver for debugging.
Cirrus Logic EP93xx based single-board computer bit-banging (in development)
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:
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.
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.)
Each vendor’s FT2232 device can use different GPIO signals to control output-enables, reset signals, and LEDs. Currently valid layout name values include:
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
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
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:
Provides the USB device description (the iProduct string) of the FTDI FT245 device. If not specified, the FTDI default value is used. This setting is only valid if compiled with FTD2XX support.
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 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 (as with an AVR board):
$_TARGETNAME configure -event reset-assert \ "usb_blaster pin6 1; wait 1; usb_blaster pin6 0"
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 jlink USB adapter
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_khz
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_khz 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 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_khz rate
commands 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 for the adapter_khz rate you specified; 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:
interface parport parport_port 0x278 parport_cable wiggler
ASIX PRESTO USB JTAG programmer.
Configures the USB serial number of the Presto device to use.
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 the Zylin ZY1000 JTAG debugger.
Note: This defines some driver-specific commands, which are not currently documented here.
Turn power switch to target on/off. No arguments: print status.
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. The transport must be supported by the debug adapter hardware and by the version of OPenOCD you are using (including the adapter’s driver). No arguments: returns name of session’s selected 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.
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.)
Declares a single DAP which uses SWD transport. Parameters are currently the same as "jtag newtap" but this is expected to change.
Updates TRN (turnaraound delay) and prescaling.fields of the Wire Control Register (WCR). No parameters: displays current settings.
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.
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_khz
, 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: Daemon Configuration, Up: Top [Contents][Index]