remotelaboratory/fpga/xilinx/programmer/dependencies/libxsvf/xsvftool-xpcu.src

xsvftool-xpcu - An (X)SVF player for the Xilinx Platform Cable USB
==================================================================

This program can be used to play SVF and XSVF files on the "Xilinx
Platform Cable USB" family of JTAG probes.

It is based on the libxsvf library:
http://www.clifford.at/libxsvf/

This tool replaces the original CPLD firmware from Xilinx when run
on one of the probes. See the notes below on how to restore the Xilinx
firmware on the CPLD.

The file 'firmware.c' also contains a brief description of the pin mappings
between the the Cypress CY7C68013A-100AIX and the Xilinx XC2C256-7VQ100
on the probe as used by this software, as well as a brief description of
the USB protocol this software is using.

With this software it is possible to use JTAG clock speeds up to 24 MHz.
But with the high frequencies there are "gaps" in the transmission resulting
in an effective transfer rate of approx 6 MBit/s.

This tool contains firmware for the CY7C68013A-100AIX (firmware.c) and for the
XC2C256-7VQ100 (hardware.v) on the probe. Some more exotic tools are needed to
build these. So pre-compiled versions of this firmware images are distributed
along with the xsvftool-xpcu source code. You need to set the USE_PREP_* config
options in the Makefile to '0' if you prefer building the firmware yourself.


xsvftool-xpcu vs. Xilinx USB cable driver
-----------------------------------------

When installed, the Xilinx "USB cable driver" tries to load its own FX2 firmware
to the probes as soon as the probe is connected to the system. Once the Xilinx
firmware is loaded into the probe the probe can't be accessed using xsvftool-xpcu.

So in order to use xsvftool-xpcu with a probe you need to uninstall or disable
the Xilinx driver. This can usually be done by commenting out the udev rules in
the /etc/udev/rules.d/xusbdfwu.rules file.

A probe that shows up as 03fd:0008 in the lsusb output is running the Xilinx
firmware. You won't be able to access this probe with xsvftool-xpcu unless you
deactivate the Xilinx driver as explained above, disconnect the probe from the
PC and reconnect it.

You can always load the Xilinx FX2 firmware in the probe manually without using
the udev rules (see "fxload" examples below).


Supported and unsupported hardware
----------------------------------

This software has been tested using the following probes:

	- A Xilinx Platform Cable USB
	- The on-board probe of a Spartan-6 development board
	- A self-built clone of the Xilinx Platform Cable USB

Per default the software recognizes the following USB vendor IDs and device IDs
(VID:PID) as a supported probe:

	03fd:0009	Xilinx Platform Cable USB
	03fd:000d	Xilinx Platform Cable USB (embedded)
	03fd:000f	Xilinx Platform Cable USB (low power)
	04b4:8613	Cypress FX2 without configuration PROM

Currently there is no support for the "Xilinx Platform Cable USB II" in this
software.


Notes on device permissions
---------------------------

To run xsvftool-xpcu as unprivileged user you need to set the permissions on
the USB device accordingly. E.g.:

	$ lsusb -d 04b4:8613
	Bus 002 Device 021: ID 04b4:8613 Cypress Semiconductor Corp.  CY7C68013 EZ-USB FX2 USB 2.0 Development Kit

	$ sudo chmod 0666 /dev/bus/usb/002/021

	$ ./xsvftool-xpcu -Pc
	Scanning JTAG chain..
	idcode=0x16d4a093, revision=0x1, part=0x6d4a, manufactor=0x049
	Total number of JTAG clock cycles performed: 79
	READY.

Instead of doing this manually each time the device is connected one might
prefer to create a udev rule that does set the permissions automatically:

	$ sudo vi /etc/udev/rules.d/xsvftool-xpcu.rules
	# Allow everyone access to the Xilinx Platform Cable USB (see 'man 7 udev' for details)
	ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="03fd", ATTR{idProduct}=="0008", MODE:="0666"
	ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="03fd", ATTR{idProduct}=="0009", MODE:="0666"
	ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="03fd", ATTR{idProduct}=="000d", MODE:="0666"
	ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="03fd", ATTR{idProduct}=="000f", MODE:="0666"
	ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="04b4", ATTR{idProduct}=="8613", MODE:="0666"

NOTE: The line for 03fd:0008 is for the re-enumerated device when the original
Xilinx firmware is used on the probe. It is not used nor needed when using
xsvftool-xpcu exclusively, but isn't harmful either.


Restore Xilinx CPLD Firmware with "xsvftool-xpcu"
-------------------------------------------------

The Xilinx ISE comes with XSVF files for programming the CPLD with the Xilinx
firmware. You can simply use "xsvftool-xpcu" to program the CPLD to the original
firmware:

	$ ./xsvftool-xpcu -P -x /opt/Xilinx/13.1/ISE_DS/ISE/data/xusb_emb.fmwr

After that you need to disconnect and reconnect the probe before you can load
the Xilinx FX2 firmware and use the probe with impact:

	$ lsusb -d 04b4:8613
	Bus 001 Device 106: ID 04b4:8613 Cypress Semiconductor Corp. CY7C68013 EZ-USB FX2 USB 2.0 Development Kit

	$ fxload -t fx2 -D /dev/bus/usb/001/106 -I /opt/Xilinx/13.1/ISE_DS/ISE/bin/lin/xusb_emb.hex

	### usually you need to wait a few seconds here for the device to re-enumerate and settle ###
	$ lsusb -d 03fd:0008
	Bus 001 Device 108: ID 03fd:0008 Xilinx, Inc. 

	### just scan the JTAG chain to test the probe ###
	$ /opt/Xilinx/13.1/ISE_DS/ISE/bin/lin/impact -batch /dev/null
	> setMode -bs
	> setCable -port usb21
	> identify
	> quit

NOTE: Use the *.hex file from the "ISE/bin/lin/" directory! It is different
from the one in the "ISE/data/" directory and only this one seams to work.


Restore Xilinx CPLD Firmware with "impact"
------------------------------------------

Up to ISE 11 the Xilinx "impact" program did automatically reprogram the CPLD on
the probe whenever needed. Since ISE 12 this does only work when there is already
an (older) Xilinx firmware on the probe. So in order to reprogram the CPLD on
the probe with "impact" you need ISE 11 installed. Then it is possible to
reprogram the CPLD just by loading the fx2 firmware and running impact on the
probe:

	$ lsusb -d 04b4:8613
	Bus 002 Device 021: ID 04b4:8613 Cypress Semiconductor Corp.  CY7C68013 EZ-USB FX2 USB 2.0 Development Kit

	$ fxload -t fx2 -D /dev/bus/usb/002/021 -I /opt/Xilinx/11.3/ISE/bin/lin/xusb_emb.hex

	### usually you need to wait a few seconds here for the device to re-enumerate and settle ###
	$ lsusb -d 03fd:0008
	Bus 002 Device 022: ID 03fd:0008 Xilinx, Inc. 

	$ vi impatch_batch.cmd
	setMode -bs
	setCable -port usb21
	quit

	### this automatically reprograms the CPLD without doing anything else with the probe ###
	$ /opt/Xilinx/11.3/ISE/bin/lin/impact -batch impatch_batch.cmd

The "reset-probe.sh" shell script in this directory (libxsvf/xsvftool-xpcu.src/)
does this automatically:

	$ bash reset-probe-impact.sh

WARNING: For some reason this procedure fails when the probe has been used with
xsvftool-xpcu between being connected to USB and loading xusb_emb.hex into the
FX2. So disconnect and reconnect the probe before running the reset-probe.sh
script!