Lib(X)SVF - A library for implementing SVF and XSVF JTAG players

Please check the subversion repository for updates: http://svn.clifford.at/libxsvf/trunk/

You also might want to have a look at the project homepage: http://www.clifford.at/libxsvf/

In papers and reports, please refer to Lib(X)SVF as follows: "Clifford Wolf, Lib(X)SVF: A library for implementing SVF and XSVF JTAG players. http://www.clifford.at/libxsvf/", e.g. using the following BibTeX code:

@MISC{LibXSVF, author = {Clifford Wolf}, title = {Lib(X)SVF: A library for implementing SVF and XSVF JTAG players}, howpublished = "\url{http://www.clifford.at/libxsvf/}" }

Please send bug reports and fixes to clifford@clifford.at.

Copyright and Disclaimer

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Introduction

JTAG (IEEE 1149.1, aka "Boundary Scan", [1], [2]) is a standard IC testing, debugging and programming port.

SVF (Serial Vector Format, [3], [4]) is a file format for storing the patterns that should be sent to the JTAG interface, as well as the expected response. It is used as an exchange format between programms that generate the JTAG input/output patterns and devices that can physically talk to a JTAG interface.

XSVF (Xilinx Serial Vector Format, [5]) is a binary variant of the SVF file format, optimized but not limited to programming Xilinx FPGA and CPLD devices.

Often one wants to use an embedded host processor or microcontroller to access the JTAG interface on an embedded device instead of using an external JTAG probe. This library can be used to implement such a solution. In addition to playing SVF and XSVF files this library is also capable of scanning the devices in the JTAG chain.

Lib(X)SVF is free software licensed under the ISC license (a licence that is functionally equivalent to the 2-clause BSD license).

[1] http://en.wikipedia.org/wiki/JTAG [2] http://www.fpga4fun.com/JTAG.html [3] http://en.wikipedia.org/wiki/Serial_Vector_Format [4] http://www.asset-intertech.com/support/svf.pdf [5] http://www.xilinx.com/bvdocs/appnotes/xapp503.pdf

Limitations and non-standard extensions

The SVF commands 'PIO' and 'PIOMAP' are unsupported. Any use of this commands in an SVF input file is reported as error.

The SVF 'RUNTEST' command is implemented in a limited manner: The 'MAXIMUM' time parameter is ignored. Combining 'SCK' with a time parameter results in first executing the specified number of clock pulses followed by a delay of the specified timespan, instead of performing the clock cycles and the delay in parallel.

The SVF commands 'HDR', 'HIR', 'SDR', 'SIR', 'TDR' and 'TIR' support an additional non-standard 'RMASK' parameter. This is a mask for the TDO bits, simmilar to the standard 'MASK' parameter. All TDO bits marked using a '1' in 'RMASK' are reported back to the host application using the the ret_tdo() callback function. This can be used to read data (such as device serial numbers) using JTAG by providing SVF templates.

Using and Porting

The library itself is written in plain C and does not depend on any library calls or headers, not even from the standard C library. So it can be ported easily even to restricted environment, such as embedded systems.

So far the libary has only been tested on 32 bit hosts. Using it on 16 bit processors might not be possible without performing some minor fixes in the code.

The program 'xsvftool-gpio' (see xsvftool-gpio.c) is a good example of how to use the library. Please have a look at this program first.

Note: See 'Host accessor macros' below for an alternative way of integrating libxsvf into your host environment.

The host application must provide an libxsvf_host struct as defined in libxsvf.h. This struct contains some function pointers that must be set to implementations of the following functions:

int setup(struct libxsvf_host *h);

This function is called by libxsvf to setup/initialize the
jtag interface. It is executed before any other libxsvf_host
callback function is called.

This function should return 0 when setting up the jtag
interface went fine and -1 on an error.

int shutdown(struct libxsvf_host *h);

This function is called by libxsvf to shutdown the jtag
interface. No other libxsvf_host callback function will
be called after this function has been executed.

This function should return 0 when shutting down the jtag
interface went fine and -1 on an error.

void udelay(struct libxsvf_host *h, long usecs, int tms, long num_tck)

A function that delays execution for at least the specified
number of microseconds.

When the 'num_tck' argument is not 0 also the specified number tck
clock cycles (i.e. 1-0-1 transitions) must be generated with TMS set
to the value specified in the 'tms' argument.

A simple implementation may perform the delay and the clock cycles
after another instead of parallel. This only has an impact on the
runtime of the player, not on its functionality.

int getbyte(struct libxsvf_host *h);

A function that returns the next byte from the input file
or -1 on end of file.

int sync(struct libxsvf_host *h);

This function is only needed when writing bindings for an asynchronous
hardware interface (see 'Using libxsvf with asynchronous interfaces' below).

This function is optional and the function pointer may be set to a NULL
pointer on implementations using the simple synchronous interface.

void pulse_tck(struct libxsvf_host *h, int tms, int tdi, int tdo, int rmask, int sync)

This is the main JTAG I/O callback function.
It must perform the following tasks:

* Set the tms line to the value specified in the 'tms' argument.

* Set the tdi line to the value specified in the 'tdi' argument.
  This argument may be '-1' to indicate that the value of the tdi
  line is not important. In this case the tdi line may be set to
  any value or may be left unchanged.

* Create a negative pulse (1-0-1) on the JTAG TCK line.

* Check the tdo line against the should-be value specified in
  the 'tdo' argument. This argument may be '-1' to indicate that
  the value of the tdo line doesn't need to be checked.

* Store the current tdo value if the 'rmask' value is set to '1'.
  This step may be ignored if the RMASK feature (see "Limitations
  and non-standard extensions" above) is not used.

The function must return the current value of the tdo line, or -1 on
a TDO-mismatch-error.

A simple implementation of this function would look like this:

--snip--
int my_pulse_tck(struct libxsvf_host *h, int tms, int tdi, int tdo, int rmask, int sync) {
	int line_tdo;
	setPort(TMS, tms);
	if (tdi >= 0)
		setPort(TDI, tdi);
	setPort(TCK, 0);
	setPort(TCK, 1);
	line_tdo = getPort(TDO);
	return tdo < 0 || line_tdo == tdo ? line_tdo : -1;
}
--snap--

The 'sync' argument can safely be ignored unless you are writing
bindings for an asynchronous hardware interface (see 'Using libxsvf
with asynchronous interfaces' below).

void pulse_sck(struct libxsvf_host *h);

A function to create a pulse on the JTAG SCK line.

This function is optional and the function pointer may
be set to a NULL pointer on implementations without an
SCK line. In this cases an SVF 'RUNTEST n SCK' command
has no effect.

void set_trst(struct libxsvf_host *h, int v);

A function to set the JTAG TRST line to the specified
    value:
	 1 ... drive the line high
	 0 ... drive the line low
	-1 ... do not drive the line (high impedance)
	-2 ... got SVF 'TRST ABSENT' command

This function is optional and the function pointer may
be set to a NULL pointer on implementations without an
TRST line. In this cases an SVF 'TRST' command has no
effect.

int set_frequency(struct libxsvf_host *h, int v);

A function to set the JTAG CLK frequency to the specified
value in Hz. This function should return 0 when setting
the frequency was successful and -1 on error. 

This function pointer is optional (may be set to NULL).
In this case an SVF FREQUENCY command always results in
an error.

void report_tapstate(struct libxsvf_host *h);

This function is called whenever the state of the TAP
state machine has changed. The TAP state can be read
using the h->tap_state enum.

This function pointer is optional (may be set to NULL)
and is for debugging purposes only.

void report_device(struct libxsvf_host *h, unsigned long idcode);

This function is called in scan mode for each device found
in the JTAG chain.

This function pointer is optional (may be set to NULL)
and is only called in the SCAN mode.

void report_status(struct libxsvf_host *h, const char *message);

This function is called each time before an SVF or XSVF
command is executed.

This function pointer is optional (may be set to NULL)
and is for debugging purposes only.

void report_error(struct libxsvf_host *h, const char *file, int line, const char *message);

This function is called whenever an error is detected
in libxsvf. It is not optional and should provide a
way to notify a user about the error.

void *realloc(struct libxsvf_host *h, void

Libxsvf

Install / Use

README

Copyright and Disclaimer

Introduction

Limitations and non-standard extensions

Using and Porting