3.2. JTAG 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.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.

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

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

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

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.