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] [-noreset] [-addcycles cyclecount]

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.
• - -noreset omit JTAG reset (Test-Logic-Reset) before executing content of the SVF file;
• - -addcycles cyclecount inject cyclecount number of additional TCLK cycles after each SDR scan instruction;

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. The JTAG-Hub is the circuit which transfers the data from JTAG to the different tools connected to the Hub. Hub implementations for most major FPGA vendors/families are provided. For more details see http://ipdbg.org.

Command: ipdbg create-hub hub_name -tap tapname -ir ir_value [dr_length] [-vir [vir_value [length [instr_code]]]]

Command: ipdbg create-hub hub_name -pld pld_name [user] [-vir [vir_value [length [instr_code]]]]

Creates a IPDBG JTAG Hub. The created hub is later used to start, stop and configure IPDBG JTAG Host servers. The first argument hub_name is the name of the created hub. It can be used later as a reference.

The pld drivers are able to provide the tap and ir_value for the IPDBG JTAG-Host server. This will be used with the second variant with option -pld.

Command options:

• hub_name the name of the IPDBG hub. This name is also used to create the object’s command, referred to here as $hub_name, and in other places where the Hub needs to be identified.
• -tap tapname targeting the TAP tapname.
• -ir ir_value states that the JTAG hub is reachable with dr-scans while the JTAG instruction register has the value ir_value. Also known as USERx instructions. The optional dr_length is the length of the dr. Current JTAG-Hub implementation only supports dr_length=13, which is also the default value.
• -vir [vir_value [length [instr_code]]] To support more Hubs than USER registers in a single FPGA it is possible to use a mechanism known as virtual-ir where the user data-register is 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.
• -pld pld_name [user] The defined driver for the pld pld_name is used to get the tap and user instruction. The pld devices names can be shown by the command pld devices. With [user] one can select a different USERx-Instruction. If the IPDBG JTAG-Hub is used without modification the default value of 1 which selects the first USERx instruction is adequate. The USERx instructions are vendor specific and don’t change between families of the same vendor. So if there’s a pld driver for your vendor it should work with your FPGA even when the driver is not compatible with your device for the remaining features. If your device/vendor is not supported you have to use the first variant.

Command: $hub_name ipdbg start -tool number -port number

Starts a IPDBG JTAG-Host server. The remaining arguments can be specified in any order.

Command options:

• -port number tcp port number where the JTAG-Host will listen. The default is 4242 which is used when the option is not given.
• -tool number number of the tool/feature. These corresponds to the ports "data_(up/down)_(0..6)" at the JtagHub. The default is 1 which is used when the option is not given.

Command: $hub_name ipdbg stop -tool number

Stops a IPDBG JTAG-Host server. Command options:

• -tool number number of the tool/feature. These corresponds to the ports "data_(up/down)_(0..6)" at the JtagHub. The default is 1 which is used when the option is not given.

Examples:

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

Creates a IPDBG Hub and 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 create-hub max10m50.ipdbghub -tap max10m50.tap -hub 0x00C -vir
max10m50.ipdbghub ipdbg start -tool 1 -port 60000

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

ipdbg create-hub xc7.ipdbghub -pld xc7.pld
xc7.ipdbghub ipdbg start -port 5555 -tool 0

Starts a server listening on tcp-port 5555 which connects to tool 0 (data_up_0/data_down_0). The TAP and ir value used to reach the JTAG Hub is given by the pld driver.

Command: $hub_name queuing -size size

Configure the queuing between IPDBG JTAG-Host and Hub. The maximum possible queue size is 1024 which is also the default.

• -size size max number of transfers in the queue.

bitbang.ibdbghub queuing -size 32

Send a maximum of 32 transfers to the queue before executing them.