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