3.2. JTAG commands

3.2.1. Overview

Following is a list of commands currently supported by jtag and some example usage.

bit

define new BSR bit

bus

change active bus

bsdl

manage BSDL files

cable

select JTAG cable

detect

detect parts on the JTAG chain

detectflash

detect parameters of flash chips attached to a part

discovery

discovery of unknown parts in the JTAG chain

dr

display or set active data register for a part

endian

set/print endianess for reading/writing binary files

eraseflash

erase flash memory by number of blocks

flashmem

burn flash memory with data from a file

frequency

setup JTAG frequency

get

get external signal value

help

display this help

include

include command sequence from external file

initbus

initialize bus driver for active part

instruction

change active instruction for a part or declare new instruction

part

change active part for current JTAG chain

peek

read a single word

poke

write a single word

print

display JTAG chain list/status

quit

exit and terminate this session

readmem

read content of the memory and write it to file

register

define new data register for a part

scan

detect changes on input pins of current part

set

set external signal value

shift

shift data/instruction registers through JTAG chain

signal

define new signal for a part

svf

execute SVF commands from file

writemem

write content from file to memory

Some tools derived from the same openwince JTAG Tools code base as UrJTAG know additional commands, which are not supported in UrJTAG. See the section about "Unsupported commands", below, about workarounds.

3.2.2. Basic commands

3.2.2.1. quit

This command closes the jtag console.

3.2.2.2. help

Without additional parameter it gives an overview of the available commands. With a parameter you can get more information about any of the commands. Example:

jtag> help cable

Most cable drivers require some more details about the cable to start properly. To learn about the details, use the "cable" command with the name of the cable followed by the word "help". Example:

jtag> cable wiggler help

3.2.2.3. include

Run commands from a named script file installed with UrJTAG or applies a BSDL file to the active part. The directory prefix is added automatically (e.g. /usr/share/urjtag/, depending on your installation), unless the file name starts with a dot or slash.

For example, the following startup sequence configures the cable, chain, and loads definitions and bus driver for a Samsung S3C4510B CPU to peek its memory at 0x0:

jtag> cable wiggler ppdev /dev/parport0
jtag> detect
jtag> include samsung/s3c4510b/s3c4510b
jtag> peek 0x0000

If the file contains valid BSDL syntax, it will be converted to native commands on the fly.

Optionally, a number X may be specified following the file name, to cause an X times repetition of the command sequence from the file.

3.2.3. Chain management

3.2.3.1. cable

Sets and initializes the cable driver. This is usually the first command that you are executing in a session. Example:

jtag> cable EA253 parallel 0x378
Initializing ETC EA253 JTAG Cable on parallel port at 0x378

For a parallel cable using the ppdev driver you would use this:

jtag> cable DLC5 ppdev /dev/parport0

If you get an error, it may be that the parallel port kernel driver was compiled as a module in your Linux kernel and wasn't loaded automatically. Then you should try to load the ppdev driver manually (with root rights outside the jtag shell):

modprobe ppdev
modprobe parport
modprobe parport_pc

UrJTAG now also supports some USB cables. Unfortunately, there is no standard for "JTAG over USB", so this support is limited to a few selected cables only. For cables based on the FT2232 chip from FTDI, the cable command has to be given cable name and optionally the driver name, USB Vendor, and Product ID of the cable:

jtag> cable ARM-USB-OCD vid=15ba pid=0003 driver=ftdi-mpsse

For all known cables, UrJTAG knows the VID and PID so you can just say

jtag> cable ARM-USB-OCD

If your cable isn't detected automatically though it's listed as a known and supported cable, feel free to report its VID and PID. It might be a different revision and should be added to the known & tested list of cables.

As stated above, the driver name is not mandatory for the cable command. UrJTAG will select the driver automatically based on UrJTAG's configuration. In case your system provides just one of libftdi or FTD2XX the respective driver is selected. If both libraries are available, then FTD2XX is selected. That's simply because FTD2XX showed some performance advantages over libftdi in the past. You can still force libftdi with the respective parameter.

Warning

There's one quirk to consider when using FTDI's FTD2XX driver. It connects to any known FTDI chip, randomly. I.e. if there's more than one FTDI device connected to the host, chances are that the driver connects to the wrong USB device. This might be an OEM USB-serial converter and you'll be banging your head why there's no proper reading from the JTAG chain. Therefore it's strongly recommended to specify the desc=xxx parameter for the cable command if the ftd2xx driver is to be used. Set xxx to the product or serial number descriptor string that are exhibited by the USB device.

3.2.3.2. detect

Detects devices on the chain. Example:

jtag> detect
IR length: 5
Chain length: 1
Device Id: 01011001001001100100000000010011
  Manufacturer: Intel
  Part:         PXA250
  Stepping:     C0
  Filename:     /usr/local/share/jtag/intel/pxa250/pxa250c0

During "detect", UrJTAG searches through the files in its database (usually in /usr/share/urjtag) and optionally in the search path for BSDL files (see bsdl command) to find a match for the manufacturer, revision and part number for the IDCODE read from the part. However, not all parts identify themselves in a way that is useful for "detect". For example, many chips with an ARM processor core inside present an IDCODE that may be specific to the the particular core inside the chip (e.g. ARM7TDMI), but doesn't tell about the actual manufacturer of the chip. In such case, the data for the part has to be included manually. See also the documentation for the "include" command.

3.2.3.3. print

Print a list of parts in the chain and the currently active instruction per part. Further details of bus, signals and instructions can be obtained with dedicated command options, see "help print".

3.2.3.4. initbus

Selects and initializes a bus of the currently selected part, e.g. the external memory bus of a CPU. This is required in order to access chips that aren't connected in the JTAG chain, but indirectly accessible through other chips (e.g. CPU or programmable logic).

Type "help initbus" to get a list of supported bus types. If you do not find a bus driver for your specific hardware, you might be lucky enough to have EJTAG in your target (most MIPS-based CPUs do) and should try the "ejtag" bus driver. In contrast to the method "via BSR", it uploads some instructions to the CPU and triggers their execution to access the bus, and should work with almost any EJTAG-capable chip (Note: JTAG isn't EJTAG):

jtag> initbus ejtag

There's another option to support new chips "via BSR", the "prototype" bus driver, which can be adapted to support your part with command parameters. The only prerequisite for using this driver is knowledge of the names of the signals that represent address bus, data bus, and enable signals, and that address and data lines are numbered in order.

For example, assume the signals are named in the BSDL description as follows:

  • Data bus: D0, D1, … D31

  • Address bus: ADDR0, ADDR1, … ADDR22

  • Output Enable: nOE

  • Write Enable: nWE

  • Chip Select: nRCS0

The enable signals seem to be active low (indicated by the leading "n" in their names). Further we assume the interesting connected part, some flash chip, is only 16 bits wide even though the data bus width is 32 bits. With this information, you could use the following command (all on a single line!) to access the bus:

initbus prototype amsb=ADDR22 alsb=ADDR0 dmsb=D15 dlsb=D0
          ncs=nRCS0 nwe=nWE noe=nOE amode=x16

The "prototype" bus driver cannot deal with systems where address and data bus are multiplexed on the same pins. If signals aren't numbered in the right order or with gaps, you may get along by defining proper names as aliases for the actual signals, with commands like "salias ADDR12 BSCGX44".

Most drivers work "via BSR", i.e. they directly access the pins of the device. Because it isn't possible to efficiently address only particular pins but only all at once, and data for all pins has to be transferred through JTAG for every single change, this method isn't the fastest, but usually easiest to implement and, well, sometimes it counts whether it works at all.

The "fjmem" (FPGA JTAG memory) bus driver attempts to address this issue by moving control and observation away from BSR to a device-internal register. For sure this is only possible on FPGAs where the designer can hook additional logic to the JTAG chain. A core design plus examples for different FPGA families is available in the extra/fjmem directory. Refer to the README located there.

Some chips don't allow direct access to their pins via BSR at all. For these, writing a new bus driver that utilizes a debug module to upload specific code to access the bus is inevitable.

3.2.3.5. bus

It's possible to initialize more than one bus for part(s) within a chain. The "bus" command allows to select the active bus for readmem, flashmem, etc. operation.

3.2.4. Part definition commands

The following commands are also used in the data files to define a device (IC) on the JTAG chain. It is not recommended to use these commands in an interactive session. Instead you should produce a device definition file out of a .bsd file using one of the supplied tools (or use the new BSDL subsystem, see below).

bit

define new BSR bit

instruction

change active instruction for a part or declare new instruction

register

define new data register for a part

signal

define new signal for a part

3.2.5. TAP control

The following commands can be used to directly manipulate and display the state of the TAP controller(s) and registers in the chain:

dr

display or set active data register for a part

instruction

change active instruction for a part or declare new instruction

get

get external signal value

pod

low level direct access to POD signals like TRST; use with care

scan

detect changes on input pins of current part

set

set external signal value

shift

shift data/instruction registers through JTAG chain

3.2.6. RAM/Flash access

These commands can be used if a part in the chain has memory connected to it (or integrated). Before they can be used, a bus driver has to be selected and initialized (see initbus command).

detectflash

detect parameters of flash chips attached to a part

endian

set/print endianess for reading/writing binary files

eraseflash

erase flash memory by number of blocks

flashmem

burn flash memory with data from a file

peek

read a single word

poke

write a single word

readmem

read content of the memory and write it to file

writemem

write content from file to memory

3.2.7. Highlevel commands

3.2.7.1. svf

The SVF player operates on a single part in the scan chain. Therefore, you have to bring up the JTAG software, specify a cable and detect the scan chain beforehand.

The player will establish a new instruction called "SIR" and a new register called "SDR". They are used internally by the respective SVF commands and are reassigned with new values as the player advances through the file. It is not recommended to use them outside of the SVF player as their content is dynamic.

An example session:

jtag> cable ppdev /dev/parport0 DLC5
Initializing Xilinx DLC5 JTAG Parallel Cable III on ppdev port /dev/parport0
jtag> detect
IR length: 5
Chain length: 1
Device Id: 10010000101000100000000010010011
  Manufacturer: Xilinx
  Part:         XC2S300E-PQ208
  Stepping:     9
  Filename:     /usr/local/share/jtag/xilinx/xc2s300e-pq208/xc2s300e-pq208
jtag> part <desired part of the scan chain>
jtag> svf <SVF file for selected part>
jtag> instruction BYPASS
jtag> shift ir
jtag> part <next part>
jtag> svf <SVF file for selected part>
jtag> instruction BYPASS
jtag> shift ir

It is recommended to set the part's instruction register to BYPASS although most SVF files do this at the end. By setting the instruction explicitely to BYPASS the output of the print command will always show meaningful information.

The SVF player will issue messages when situations arise that cannot be handled. These messages are classified as warnings or errors depending on whether the player can continue operation (warning) or not (error). In case the TDO parameter of an SDR command leads to a mismatch the player issues a warning and continues. If the player should abort in this case then specify stop at the svf command.

The absence of error or warning messages indicate that the SVF file was executed without problems. To get a progress reporting while the player advances through the SVF file, specify progress at the svf command.

3.2.7.2. bsdl

The bsdl command is used to set up and test the underlying BSDL subsystem of UrJTAG.

Whenever detect encounters a new part, a configuration process is started. This involves matching the retrieved IDCODE against the part descriptions in /usr/share/urjtag as described above. However, before this database is searched for a suitable description, the BSDL subsystem is started and searches for a BSDL file that matches this device. If it finds a matching file, traversal of the /usr/share/urjtag database is skipped. If not, then this standard process follows.

To tell the BSDL subsytem where to look for BSDL files, the bsdl path pathlist command has to be issued prior to detect. The contents of pathlist must be a semicolon-separated list of directories where BSDL files are located. This list is stored by bsdl path and is used later on when detect calls the BSDL subsystem.

Important

The BSDL subsystem applies the first BSDL file that parses without errors and that contains the correct IDCODE. Scanning the specified directories happens in exactly the given order. Inside a directory however, the order depends largely on your filesystem's behavior.

Further details of the bsdl command:

  • bsdl path <path1>[;<path2>[;<pathN>]] set paths for locating BSDL files

  • bsdl debug on|off switches debug messages on or off

  • bsdl test [file] reads file (if specified) or all files found via bsdl path and prints a short status, an active part is not required

  • bsdl dump [file] reads file (if specified) or all files found via bsdl path and prints all configuration commands, an active part is not required

Tip

The bsdl dump file command implements the same functionality as bsdl2jtag.

3.2.8. Unsupported commands

3.2.8.1. script

Although it's still there, its functionality has been merged into the include command. Please use "include" instead.

3.2.8.2. setdevice

This command was only there to support the SHARC 21065L processor, which has no IDCODE and therefore can't be initialized correctly by just running "detect". However, the proper initialization can be done after "detect" by loading the proper declarations and bus driver manually:

jtag> include analog/sharc21065l/sharc21065l

3.2.8.3. spiflashmem

The commands "spidetectflash", "spiflashmem", "spireadflash" and "spieraseflash" only exist in a version of the JTAG tools copyrighted by Intratrade Ltd., we just know about them from a posting on the net.