18 JTAG Commands

Most general purpose JTAG commands have been presented earlier. (See JTAG Speed, Reset Configuration, and TAP Declaration.) Lower level JTAG commands, as presented here, may be needed to work with targets which require special attention during operations such as reset or initialization.

To use these commands you will need to understand some of the basics of JTAG, including:

• A JTAG scan chain consists of a sequence of individual TAP devices such as a CPUs.
• Control operations involve moving each TAP through the same standard state machine (in parallel) using their shared TMS and clock signals.
• Data transfer involves shifting data through the chain of instruction or data registers of each TAP, writing new register values while the reading previous ones.
• Data register sizes are a function of the instruction active in a given TAP, while instruction register sizes are fixed for each TAP. All TAPs support a BYPASS instruction with a single bit data register.
• The way OpenOCD differentiates between TAP devices is by shifting different instructions into (and out of) their instruction registers.

18.1 Low Level JTAG Commands

These commands are used by developers who need to access JTAG instruction or data registers, possibly controlling the order of TAP state transitions. If you’re not debugging OpenOCD internals, or bringing up a new JTAG adapter or a new type of TAP device (like a CPU or JTAG router), you probably won’t need to use these commands. In a debug session that doesn’t use JTAG for its transport protocol, these commands are not available.

Command: drscan tap [numbits value]+ [-endstate tap_state]

Loads the data register of tap with a series of bit fields that specify the entire register. Each field is numbits bits long with a numeric value (hexadecimal encouraged). The return value holds the original value of each of those fields.

For example, a 38 bit number might be specified as one field of 32 bits then one of 6 bits. For portability, never pass fields which are more than 32 bits long. Many OpenOCD implementations do not support 64-bit (or larger) integer values.

All TAPs other than tap must be in BYPASS mode. The single bit in their data registers does not matter.

When tap_state is specified, the JTAG state machine is left in that state. For example DRPAUSE might be specified, so that more instructions can be issued before re-entering the RUN/IDLE state. If the end state is not specified, the RUN/IDLE state is entered.

Warning: OpenOCD does not record information about data register lengths, so it is important that you get the bit field lengths right. Remember that different JTAG instructions refer to different data registers, which may have different lengths. Moreover, those lengths may not be fixed; the SCAN_N instruction can change the length of the register accessed by the INTEST instruction (by connecting a different scan chain).

Command: flush_count

Returns the number of times the JTAG queue has been flushed. This may be used for performance tuning.

For example, flushing a queue over USB involves a minimum latency, often several milliseconds, which does not change with the amount of data which is written. You may be able to identify performance problems by finding tasks which waste bandwidth by flushing small transfers too often, instead of batching them into larger operations.

Command: irscan [tap instruction]+ [-endstate tap_state]

For each tap listed, loads the instruction register with its associated numeric instruction. (The number of bits in that instruction may be displayed using the scan_chain command.) For other TAPs, a BYPASS instruction is loaded.

When tap_state is specified, the JTAG state machine is left in that state. For example IRPAUSE might be specified, so the data register can be loaded before re-entering the RUN/IDLE state. If the end state is not specified, the RUN/IDLE state is entered.

Note: OpenOCD currently supports only a single field for instruction register values, unlike data register values. For TAPs where the instruction register length is more than 32 bits, portable scripts currently must issue only BYPASS instructions.

Command: jtag_reset trst srst

Set values of reset signals. The trst and srst parameter values may be 0, indicating that reset is inactive (pulled or driven high), or 1, indicating it is active (pulled or driven low). The reset_config command should already have been used to configure how the board and JTAG adapter treat these two signals, and to say if either signal is even present. See Reset Configuration.

Note that TRST is specially handled. It actually signifies JTAG’s RESET state. So if the board doesn’t support the optional TRST signal, or it doesn’t support it along with the specified SRST value, JTAG reset is triggered with TMS and TCK signals instead of the TRST signal. And no matter how that JTAG reset is triggered, once the scan chain enters RESET with TRST inactive, TAP post-reset events are delivered to all TAPs with handlers for that event.

Command: pathmove start_state [next_state ...]

Start by moving to start_state, which must be one of the stable states. Unless it is the only state given, this will often be the current state, so that no TCK transitions are needed. Then, in a series of single state transitions (conforming to the JTAG state machine) shift to each next_state in sequence, one per TCK cycle. The final state must also be stable.

Command: runtest num_cycles

Move to the RUN/IDLE state, and execute at least num_cycles of the JTAG clock (TCK). Instructions often need some time to execute before they take effect.

Command: verify_ircapture (enable|disable)

Verify values captured during IRCAPTURE and returned during IR scans. Default is enabled, but this can be overridden by verify_jtag. This flag is ignored when validating JTAG chain configuration.

Command: verify_jtag (enable|disable)

Enables verification of DR and IR scans, to help detect programming errors. For IR scans, verify_ircapture must also be enabled. Default is enabled.

18.2 TAP state names

The tap_state names used by OpenOCD in the drscan, irscan, and pathmove commands are the same as those used in SVF boundary scan documents, except that SVF uses IDLE instead of RUN/IDLE.

• RESET ... stable (with TMS high); acts as if TRST were pulsed
• RUN/IDLE ... stable; don’t assume this always means IDLE
• DRSELECT
• DRCAPTURE
• DRSHIFT ... stable; TDI/TDO shifting through the data register
• DREXIT1
• DRPAUSE ... stable; data register ready for update or more shifting
• DREXIT2
• DRUPDATE
• IRSELECT
• IRCAPTURE
• IRSHIFT ... stable; TDI/TDO shifting through the instruction register
• IREXIT1
• IRPAUSE ... stable; instruction register ready for update or more shifting
• IREXIT2
• IRUPDATE

Note that only six of those states are fully “stable” in the face of TMS fixed (low except for RESET) and a free-running JTAG clock. For all the others, the next TCK transition changes to a new state.

• From DRSHIFT and IRSHIFT, clock transitions will produce side effects by changing register contents. The values to be latched in upcoming DRUPDATE or IRUPDATE states may not be as expected.
• RUN/IDLE, DRPAUSE, and IRPAUSE are reasonable choices after drscan or irscan commands, since they are free of JTAG side effects.
• RUN/IDLE may have side effects that appear at non-JTAG levels, such as advancing the ARM9E-S instruction pipeline. Consult the documentation for the TAP(s) you are working with.