Xilinx ISE WebPACK (10 and Earlier)

This HOWTO deals with installing Xilinx ISE WebPack on Gentoo Linux with a 2.6 kernel. ISE WebPack is the no-cost version of the Xilinx ISE toolset for programming and downloading Xilinx FPGAs and CPLDs. Much of this information may also be relevant to installing the full Xilinx ISE.

ISE WebPack is supplied in binary form only. It is provided for the x86 (i.e., 32-bit) version of RHEL, and Xilinx does not support it on other Linux distributions or architectures. This HOWTO is intended to bridge the support gap and permit you to run ISE WebPack under x86 or amd64 Gentoo Linux. The HOWTO was originally written for v8.1i of the WebPack and for Gentoo circa 2006.1, but it has been updated to reflect WebPack v9.2i and Gentoo as of 2007-12-28. Since the HOWTO is primarily for new installations, information about older releases is secondary, although it is still present.

ISE WebPack is a GUI application suite which can also control any of several proprietary peripherals of the type known as a "programming cable" or just "cable." A cable connects your Linux host system to a development board that has one or more Xilinx FPGAs, PROMs, or CPLDs. The problems associated with running WebPack on Gentoo naturally divide into two parts:
 * installing and running the application suite itself.
 * installing the cable drivers

The HOWTO is therefore divided into two main sections that address the two parts separately.

Installing the Xilinx Webpack Application Suite
There are two approaches to installing and running the Xilinx Webpack application suite. There are advantages and disadvantages to each approach. You may decide to try both of them. The traditional approach is to install and run the suite as it is supplied by Xilinx: as an integrated development environment with the applications run from the common GUI supplied by Xilinx. Almost all of the documentation available from Xilinx and available on the web assumes that you will run the ISE in this fashion. The advantages of this approach are that you can use Xilinx's well-thought-out GUI and its documentation. The disadvantages are that the interface from the main GUI to the actual application engines is somewhat fragile and tends to break in a non-standard Linux implementation. It is also more complex to replace individual Xilinx helper applications with Opensource equivalents. The alternative is to run the individual helper applications from the command line or from a separate IDE such as Eclipse. This approach is not yet well-documented, but it is in use by several developers. Until it is better documented, you should probably not try it unless the traditional approach fails for you. This HOWTO currently assumes that you will be using the Xilinx GUI.

Prerequisites
(Note for amd64 systems: Prerequisite applications can be amd64. However, since WebPack is a 32-bit application, the prerequisite libraries are the 32-bit versions -- can an amd64 person please expand this?)

TCL
WebPACK fails if it attempts to use a TCL newer than 8.4.15. To avoid this, force WebPACK to use tits own TCL library by exporting the LD_PRELOAD variable before ise start. Here is my startup script:

It works even if your system has a newer TCL.

Glibc
WebPack version 10.1 uses the newer glibc API and so these steps are not neccessary when using that version. Older versions of the WebPack use the old glibc-2.0 API, so your glibc must be compiled with backward compatibility. The easiest approach is:

This takes awhile. Failure to do this causes Webpack to fail to run certain critical subsidiary processes, causing secondary windows to fail to appear: these failures are usually silent: you will not see an error message, but the window will not appear. Unfortunately, the two relevant USE flags, glibc-compat20 and nptlonly, are present in glibc-2.5 and in glibc 2.7, but not ins glibc 2.6. Therefore, you may need to unmask glibc 2.7 or down-rev to glibc-2.5 to use this option. If you prefer not to do this, See this description for a cleaner but more complicated alternative.

Openmotif
You will need openmotif, and Webpack 9.2i or below insists that the version must be < 2.3.0. As of 2008-02, Webpack will run with the current version of openmotif if you assure it that it is actually the older version.

Since openmotif < 2.3.0 is now blocked, you have to install the current openmotif version and manually create the symlinks for the old lib

Other prerequisites
You will also need xorg-x11 and acroread. Without acroread, the help screens may not appear. About xorg-x11: The entire Gentoo community shifted to xorg-x11 over the course of 2007. If you are still using the older x11, Please upgrade.

For Webpack v8.1i, you additionally need portmap. Users report that without portmap, the install takes much longer to complete.

ISE uses IP to talk to its components, so if you are running a firewall, you need to configure it to allow traffic from localhost to localhost.

Installing

 * Download a full copy of the WebPack installer (839MB). Do not install it yet.
 * Run the following:

Error: Cannot run process - /opt/xilinx92i/.xinstall_driverscript insmod: error inserting '/lib/modules/misc/windrvr6.o': -1 Invalid module format
 * Now run the WebPack install, still as root. You will be prompted for an install directory. You should install in /opt unless you have reason to do otherwise. The installer will create a directory with a name of the form /opt/Xilinx92i, which will allow you to install a newer version in the future without destroying your current version.
 * After the install, there will be errors like the following as the installer tries and fails to install the RHEL cable driver kernel modules. You can safely ignore and click through:
 * Run the following:


 * (For versions<=8.1 Extract the latest firmware from ***ftp://ftp.xilinx.com/pub/utilities/fpga/xusbdfwu-1025.zip to /etc/hotplug/usb/xusbdfwu.fw/)

Running
You can (and should) run the WebPack ISE as a regular user, not as root. To start the ISE:

You should be able to now perform all ISE operations except for those that require the use of a download cable. It is a good idea to try out your installation at this point before proceeding to the cable driver portion of the installation.

Information on installing on other Linux Distributions

 * (Links to this information were lost during the database restoration. Please search the web and update this section.)

FPGA Downloader Installation Methods
The WebPack ISE creates binary image files for download to the target system. The ISE can then invoke its own internal downloader, IMPACT, to load the binary onto the target, or you may use a separate program. In addition, there are two ways to connect IMPACT to the actual hardware on your PC, so there are three approaches. There are advantages and disadvantages to each approach. They are listed here in their historical order of development. You should pick one approach. Installation for each method is described in its own section later in the document.

Method 1: kernel modules
The Xilinx-approved method for use on supported RHEL Linux is to install two Linux kernel drivers that they supply. The advantage of this method is that most existing documentation assumes this approach. The disadvantage is that the drivers tend to not work with non-RHEL Linuxes and to break from version to version. Since you are reading the Gentoo Xilinx HOWTO, you are already not going to be supported by Xilinx. Xilinx is considering providing open source kernel modules to replace the binary-only modules. Until these drivers are in the main kernel tree, you will probably need to recompile them and re-install them each time you update your kernel.

Method 2: Xup and XC3Sprog
You can use a separate GPLed application named XC3Sprog to download the FPGA images via a parallel port cable. For a USB cable (at least for the Spartan 3E starter kit) you can use Xup to reprogram the USB logic on the board and then use a custom version of XC3Sprog to download the FPGA images. The advantage is that this is completely separate from the WebPack installation, and for USB at least, there is a potential to later actually use the USB cable to communicate with your FPGA system. One disadvantage is that it takes awhile each time you switch back and forth between IMPACT and Xup, but this will not matter if you decide to stick with Xup. A minor disadvantage is that a download takes twice as long (4 seconds instead of 2 seconds) because Xup has not yet been optimized. The third disadvantage is that it is not integrated with the ISE.

Method 3: User-space cable driver library
You can use IMPACT without installing the kernel drivers, by installing a "wrapper library." this approach uses a library which provides the API that IMPACT expects to use, but then invokes the user-space IO libraries instead of the kernel modules. The advantages are that the ISE and IMPACT run exactly as expected and at full speed, and the system should work with any kernel including 64-bit kernels.

Installing Cable Driver Kernel Modules
This section deals with installing modules on a 32bits distribution. The Webpack and ISE 8.1 and 8.2 distributions do not include 64-bit cable drivers. However, 64-bit cable drivers are available from the Xilinx ftp site:

Base installation

 * Obtain the xpc4drvr parallel port programmer driver source code provided by Xilinx. Ignore the windrvr source code bundled in the tarball, as it is v7.00, and a newer version, v7.02 is available elsewhere:


 * ftp://ftp.xilinx.com/pub/utilities/M1_workstation/linuxdrivers.2.6.tar.gz


 * Untar this and cd into the xpc4drvr directory, run ./configure and type 'make' to compile the xpc4drvr driver module. Once it has compiled, copy the resulting xpc4drvr.ko driver into /lib/modules/misc or run 'make install'
 * Next, obtain the windrvr6 driver interface provided by Jungo (the source ver 8.11 produces windrvr6, instead of windrvr8, oddly enough)
 * http://www.jungo.com/st/download/WD811LN.tgz (works with 2.6.17.9)
 * http://www.jungo.com/st/download/WD910LN.tgz (works with 2.6.21-suspend2-r6) (bugfixed for Ubuntu 7.10)


 * http://www.jungo.com/st/download/WD811LNX86_64.tgz (for x86_64)
 * http://www.jungo.com/st/download/WD910LNX86_64.tgz (for Ubuntu 7.10 x86_64)

Note: Check for news of the latest version here: http://www.jungo.com/st/wdver.html, and tweak the filename to suit -- for example, WD1001 instead of WD910.


 * Untar this and cd into the 'WinDriver/redist' directrory and just type './configure' and 'make' to compile the windrvr6 driver module. (If this fails, see the discussion page). Once it has compiled, copy the resulting windrvr6.ko driver into /lib/modules/misc or run 'make install'.
 * The check for udev seems not to work properly; you may have to manually edit the redist/configure.wd script (line 888 in version 10.0.1) to USE_UDEV="yes".
 * When not using UDEV, add the following to /etc/conf.d/local.start - make sure this script is executed before startise is run the first time or parallel port programming will not work

insmod /lib/modules/misc/windrvr6.ko set -- $(grep windrvr6 /proc/devices) rm -f /dev/windrvr6 mknod -m 0666 /dev/windrvr6 c $1 0 insmod /lib/modules/misc/xpc4drvr.ko set -- $(grep xpc4drvr /proc/devices) for i in 0 1 2 3 do rm -f /dev/xpc4_$i mknod -m 0666 /dev/xpc4_$i c $1 $i done An alternative to setting permissions is adding a permission rule to UDEV: (FIXME please confirm)

Using udev
If you don't use hotplug you have to use udev. This is also useful if you don't want to use the rc.local script. ENV{UDEVD_EVENT}=="1", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0007", RUN+="/sbin/fxload -v -t fx2 -I /etc/hotplug/usb/xusbdfwu.fw/xusbdfwu.hex -D $env{DEVNAME}" ENV{UDEVD_EVENT}=="1", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0009", RUN+="/sbin/fxload -v -t fx2  -I /etc/hotplug/usb/xusbdfwu.fw/xusbdfwu.hex -D $env{DEVNAME}" ENV{UDEVD_EVENT}=="1", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="000b", RUN+="/sbin/fxload -v -t fx2  -I /etc/hotplug/usb/xusbdfwu.fw/xusbdfwu.hex -D $env{DEVNAME}" ENV{UDEVD_EVENT}=="1", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="000d", RUN+="/sbin/fxload -v -t fx2  -I /etc/hotplug/usb/xusbdfwu.fw/xusbdfwu.hex -D $env{DEVNAME}" ENV{UDEVD_EVENT}=="1", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="000f", RUN+="/sbin/fxload -v -t fx2  -I /etc/hotplug/usb/xusbdfwu.fw/xusbdfwu.hex -D $env{DEVNAME}" ENV{UDEVD_EVENT}=="1", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0013", RUN+="/sbin/fxload -v -t fx2  -I /etc/hotplug/usb/xusbdfwu.fw/usb_xp2.hex -D $env{DEVNAME}"
 * Find and comment (or remove) this line in (for instance) /etc/udev/rules.d/05-udev-early.rules
 * 1) SUBSYSTEM=="module",         OPTIONS="ignore_device"
 * Make the rules file: /etc/udev/rules.d/52-xilinxusb.rules containing:

ACTION=="add", DEVPATH=="/module/windrvr6", RUN+="/bin/rm -f /dev/windrvr6" ACTION=="add", DEVPATH=="/module/windrvr6", PROGRAM="/bin/grep windrvr6 /proc/devices" RUN+="/bin/mknod -m 0666 /dev/windrvr6 c %c{1} 0" ACTION=="remove", DEVPATH=="/module/windrvr6", RUN+="/bin/rm -f /dev/windrvr6"

ACTION=="add", DEVPATH=="/module/xpc4drvr", RUN+="/bin/rm -f /dev/xpc4_?" ACTION=="add", DEVPATH=="/module/xpc4drvr", PROGRAM="/bin/grep xpc4drvr /proc/devices" RUN+="/bin/mknod -m 0666 /dev/xpc4_0 c %c{1} 0" ACTION=="add", DEVPATH=="/module/xpc4drvr", PROGRAM="/bin/grep xpc4drvr /proc/devices" RUN+="/bin/mknod -m 0666 /dev/xpc4_1 c %c{1} 1" ACTION=="add", DEVPATH=="/module/xpc4drvr", PROGRAM="/bin/grep xpc4drvr /proc/devices" RUN+="/bin/mknod -m 0666 /dev/xpc4_2 c %c{1} 2" ACTION=="add", DEVPATH=="/module/xpc4drvr", PROGRAM="/bin/grep xpc4drvr /proc/devices" RUN+="/bin/mknod -m 0666 /dev/xpc4_3 c %c{1} 3" ACTION=="remove", DEVPATH=="/module/xpc4drvr", RUN+="/bin/rm -f /dev/xpc4_?"
 * run

Xup: GPL programmer for Spartan 3e Starter Kit
There is an GPL alternative to Xilinx's iMPACT called Xup. Xup can be used to program the Spartan 3e Starter kit. The primary documentation and download are at http://inisyn.org/src/xup/.

In its current form Xup can be immediately used to program the starter kit development board on 32bit Gentoo systems through the USB cable supplied with the Xilinx board. Note:AMD64 users need to replace all instances of "long int" to "u_int32_t" in the source files under Xup's provided XC3Sprog. Send any questions regarding this to mailto://brandon@cs.uri.edu.

The author of Xup mentions that his software might be usable for programming Virtex devices provided that modifications are made.

Xup works by re-programming the 8051 microprocessor in the Cypress USB slave chip on the Spartan3E board. This permits the 8051 to implement a message layer on the USB that can be understood by the customized XC3Sprog application that is provided with Xup. This protocol replaces the undocumented protocol used by the Xilinx drivers. The new 8051 source code is provided with Xup, so it may be possible to eventually create a USB data path from your PC to your FPGA application by reprogramming the 8051 and the CPLD.

Installing Xup on Gentoo generally follows this pattern:

In order to use it for non root user, you should create a special group (here xilinx) and add the authorized users to this group. Then create a simple udev script (as for instance /etc/udev/rules.d/z25-xilinx.rules): ACTION!="add", GOTO="xilinx_rules_end" SUBSYSTEM!="usb_device", GOTO="xilinx_rules_end" SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="000d", MODE="664", GROUP="xilinx" LABEL="xilinx_rules_end" The provided xc3sprog uses a file named devlist.txt which has JTAG IDCODES in it. Some starter kit boards have two devices with variant codes that are not in the file provided with Xup. Adde the following lines to devlist.txt: 41c22093 8 XC3S500E f5045093 8  XCF04S These differ in the first digit from exisiting codes for these devices. After this, the program should run.
 * 1) xilinx xup cable

User-Space Cable Driver library
This library is misnamed "usb-driver" because it was initially developed for USB cables. It now permits IMPACT and other Xilinx tools to drive most common USB and parallel cables, including some that IMPACT cannot drive using the normal kernel-driver approach. The main web site is here.

Installation on Gentoo generally follows this pattern:

add the following line immediately above the "exec ise" line:

Code| export LD_PRELOAD=/opt/usb-driver/libusb-driver.so }}

and save and exit the file.

Now, carefully follow the rest of the instructions for your cable type in the README. For USB, pay special attention to the fxload instructions. For parallel remember to build your kernel with


 * parport
 * parport_pc
 * ppdev

integrated or as modules (in that case load them before starting Xilinx)

This thread on comp.arch.fpga has the initial announcement, two good sets of step-by-step instructions, and many reports of success.

Cable is locked
IMPACT can crash under various conditions and leave the cable in a "locked" condition. For example, if an Impact profile uses an .mcs file, then changing .mcs prom file when Impact window is open causes Impact to crash. This can lock whichever cable the IMPACT was using when the crash occurred.

The solution to this problem is to run IMPACT in batch mode, to clear the lock. From any commandline window, run the following:


 * setmode -bs
 * cleancablelock
 * setcable -p auto
 * quit

ISE fails to launch some applications
Some examples:
 * When you try to run a behavioral simulation the result never appears in the window.
 * When you try to create the bit file, The process starts but never finishes.
 * When you try to launch IMPACT, the impact window never appears.
 * When you try to assign package pin constraints, the window never appears.

These are all symptoms that your system's installed tcl or glibc are too new or you're missing openmotif. You must follow the instruction in the "Prerequisites" section above.

QT and fonts related problems

 * When open impact, you might have this problem: "QSettings::sync: filename is null/empty". This is because the configuration file xilinxrc in $HOME/.qt/ has the permission 0600 or belongs to root only. You can solve this problem by chmod or chown.
 * When you install ISE, Chipscope or EDK, you might have this problem: "couldn't open fontconfigs chosen font with Xft!!!". First of all, you must have gsfonts installed, if you have it and the problem remains you can solve this error by run

The two problems above won't give you real problem when you run Xilinx, but this is nice to see a clear environment.

Troubleshooting the ds300 and XUP-V2P usb-interface
Not all of these steps are needed:
 * Run "bash /bin/lin/setup_pcusb" as root to install the USB drivers
 * Install fxload in /sbin see: http://prdownloads.sourceforge.net/linux-hotplug/
 * Put the absolute path to the firmware: /etc/hotplug/usb/xusbdfwu.fw/xusbdfwu.hex in /etc/hotplug/usb/xusbdfwu
 * edit /etc/udev/permissions.d/udev.permissions, set permissions of windrv6 to 0666 or chmod it.
 * Extract the latest fimware from ftp://ftp.xilinx.com/pub/utilities/fpga/xusbdfwu-1025.zip to /etc/hotplug/usb/xusbdfwu.fw/

Current work around for XUP boards if you are still experiencing problems:
 * 1) Turn on XUP board.
 * 2) Plug in to USB
 * 3) Wait 10 seconds
 * 4) Unplug and reconnect USB

TODO

 * Configure udev so /dev nodes are created automatically at boot, so above local.start script additions become unnecessary
 * Try loading the kernel modules by naming them in /etc/modules.autoload.d/kernel-2.6
 * How to get modprobe to locate these modules located in /lib/modules/misc without moving them into /lib/modules/ ?

EDK Simulation Libraries Compilation
EDK uses xilperl to compile simulation libraries. xilperl requires libdb-4.1.so, without it, you'll get this error: xilperl: error while loading shared libraries: libdb-4.1.so: cannot open shared object file: No such file or directory A quick fix is to create a symbolic link:

Note: If you are using amd64, you'll want to create the link in /usr/lib32