18 Boundary Scan Commands

One of the original purposes of JTAG was to support boundary scan based hardware testing. Although its primary focus is to support On-Chip Debugging, OpenOCD also includes some boundary scan commands.

18.1 SVF: Serial Vector Format

The Serial Vector Format, better known as SVF, is a way to represent JTAG test patterns in text files. In a debug session using JTAG for its transport protocol, OpenOCD supports running such test files.

Command: svf filename [-tap tapname] [[-]quiet] [[-]nil] [[-]progress] [[-]ignore_error]

This issues a JTAG reset (Test-Logic-Reset) and then runs the SVF script from filename.

Arguments can be specified in any order; the optional dash doesn’t affect their semantics.

Command options:

• - -tap tapname ignore IR and DR headers and footers specified by the SVF file with HIR, TIR, HDR and TDR commands; instead, calculate them automatically according to the current JTAG chain configuration, targeting tapname;
• - [-]quiet do not log every command before execution;
• - [-]nil “dry run”, i.e., do not perform any operations on the real interface;
• - [-]progress enable progress indication;
• - [-]ignore_error continue execution despite TDO check errors.

18.2 XSVF: Xilinx Serial Vector Format

The Xilinx Serial Vector Format, better known as XSVF, is a binary representation of SVF which is optimized for use with Xilinx devices. In a debug session using JTAG for its transport protocol, OpenOCD supports running such test files.

Important: Not all XSVF commands are supported.

Command: xsvf (tapname|plain) filename [virt2] [quiet]

This issues a JTAG reset (Test-Logic-Reset) and then runs the XSVF script from filename. When a tapname is specified, the commands are directed at that TAP. When virt2 is specified, the XRUNTEST command counts are interpreted as TCK cycles instead of microseconds. Unless the quiet option is specified, messages are logged for comments and some retries.

The OpenOCD sources also include two utility scripts for working with XSVF; they are not currently installed after building the software. You may find them useful:

• svf2xsvf ... converts SVF files into the extended XSVF syntax understood by the xsvf command; see notes below.
• xsvfdump ... converts XSVF files into a text output format; understands the OpenOCD extensions.

The input format accepts a handful of non-standard extensions. These include three opcodes corresponding to SVF extensions from Lattice Semiconductor (LCOUNT, LDELAY, LDSR), and two opcodes supporting a more accurate translation of SVF (XTRST, XWAITSTATE). If xsvfdump shows a file is using those opcodes, it probably will not be usable with other XSVF tools.

18.3 IPDBG: JTAG-Host server

IPDBG is a set of tools to debug IP-Cores. It comprises, among others, a logic analyzer and an arbitrary waveform generator. These are synthesize-able hardware descriptions of logic circuits in addition to software for control, visualization and further analysis. In a session using JTAG for its transport protocol, OpenOCD supports the function of a JTAG-Host. The JTAG-Host is needed to connect the circuit over JTAG to the control-software. For more details see http://ipdbg.org.

Command: ipdbg [-start|-stop] -tap tapname -hub ir_value [dr_length] [-port number] [-tool number] [-vir [vir_value [length [instr_code]]]]

Starts or stops a IPDBG JTAG-Host server. Arguments can be specified in any order.

Command options:

• -start|-stop starts or stops a IPDBG JTAG-Host server (default: start).
• -tap tapname targeting the TAP tapname.
• -hub ir_value states that the JTAG hub is reachable with dr-scans while the JTAG instruction register has the value ir_value.
• -port number tcp port number where the JTAG-Host is listening.
• -tool number number of the tool/feature. These corresponds to the ports "data_(up/down)_(0..6)" at the JtagHub.
• -vir [vir_value [length [instr_code]]] On some devices, the user data-register is only reachable if there is a specific value in a second dr. This second dr is called vir (virtual ir). With this parameter given, the IPDBG satisfies this condition prior an access to the IPDBG-Hub. The value shifted into the vir is given by the first parameter vir_value (default: 0x11). The second parameter length is the length of the vir data register (default: 5). With the instr_code (default: 0x00e) parameter the ir value to shift data through vir can be configured.

Examples:

ipdbg -start -tap xc6s.tap -hub 0x02 -port 4242 -tool 4

Starts a server listening on tcp-port 4242 which connects to tool 4. The connection is through the TAP of a Xilinx Spartan 6 on USER1 instruction (tested with a papillion pro board).

ipdbg -start -tap 10m50.tap -hub 0x00C -vir -port 60000 -tool 1

Starts a server listening on tcp-port 60000 which connects to tool 1 (data_up_1/data_down_1). The connection is through the TAP of a Intel MAX10 virtual jtag component (sld_instance_index is 0; sld_ir_width is smaller than 5).