Xilinx ISE Webpack 11

The Xilinx ISE is an integrated development environment for Xilinx FPGAs and CPLDs. the Webpack is the no-cost version of ISE, which has some restrictions. Notably, the Webpack is only delivered for 32-bit systems. Furthermore, while it is provided for Linux, Xilinx specifies that it is intended to run only on RHEL and SUSE. There is a large user community of developers that run the ISE on other Linux environments, however. Installation has become progressively easier from version to version, but each version has different challenges. For versions before ISE 11, please see Xilinx ISE WebPACK (10 and Earlier).

The ISE is a GUI that invokes ISE tools to perform various design steps. Most of the tools are simple POSIX-compliant batch applications that will run in essentially any Linux environment. The GUI has more extensive demands on the system. A few of the tools interact with the target hardware via a "programming cable" (usually just called a "cable.") The interface to the cable is via a "cable driver" that must be integrated with the system.

There are three main areas of difficulty when running a "non-standard" setup:
 * 32-bit versus 64-bit problems
 * Library incompatibilities affecting the GUI
 * Cable drivers

For ISE 11, The problems are fairly minor.

Summary
There are three approaches to the 32-bit installation, two approaches (at least) to the Library problem, and four approaches to the Cable driver problem. I chose to directly install on my main 64-bit partition, to use my libraries "as-is", and to use the usb_driver "shim" for the cables. This paper describes this specific approach in detail. the alternatives are mentioned briefly as some were needed in the past and others may be needed again in the future.

Prerequisites
You need to be logged in as root to do many of these steps.

The webpack needs some packages to be installed prior to installation. This will be true for any ISE installation on any Linux platform. Therefore: emerge acroread emerge mozilla-firefox emerge libusb emerge fxload

32-bit installation on a 64-bit system
The Webpack binaries are 32-bit binaries and will require 32-bit libraries. Therefore, you must have already built your Gentoo system with multilib support. Once you have done this, there is no special requirement for ISE 11 on an up-to-date Gentoo circa 2009-09-09. However, the Xilinx install script does not know this, so it objects. After you download the WebPack from Xilinx, follow all the instructions, but instead of typing ./xsetup, we pretend we are 32-bit by typeing: linux32 ./xsetup Webpack will then install correctly.

We also need a simple way to invoke the Xilinx programs. Create a script named /usr/local/bin/xilinx. Place the following in the script: source /opt/Xilinx/11.1/settings32.sh DISPLAY=:0 exec ise
 * 1) !/bin/sh

and make it executable: chmod +x /usr/local/bin/xilinx

32-bit Alternatives
If you are starting from scratch, you may choose to simply use a 32-bit Gentoo system.

You can choose to install in a 32-bit "sandbox" on your 64-bit system. follow the directions for the 32-bit chrroot.

You can choose to implement a 32-bit virtual machine inside your 64-bit Gentoo. Follow the directions for KVM. (or another VM of your choice.)

Library Incompatibilities
I did not find any incompatibilities other than the one that affects the cable drver.

Library Alternatives
In the past, most library problems occurred when the ISE depended on a library version that differs from what Gentoo has installed. minor problems can sometimes be fixed by creating a link from the needed library name to Gentoo's installed library version. larger but isolated problems can be fixed by compiling the needed version of the library and placing it in Xilinx's Library directory. In the worst case, the problem affects a large set of libraries and cannot be fixed piecemeal. In this case, you must use a chroot or a virtual machine.

Historically, most of the library issues have affected the ISE GUI, so another alternative is to avoid the use of the ISE GUI and run the individual ISE programs as command-line programs. This has always been possible, but there is a new comprehensive edition of the Xilinx documentation that removes much of the mystery. The command-line tools are useful in any event, since they permit automation of the design flow when the ISE is used in conjunction with other tools.

Cable Driver Problems
ISE 11.1 does not properly access a USB cable when installed as described above. To correct this, we use the (mis-named) libusb-driver. First, acquire the source tarball for the driver and compile it. Then, move the library into the Xilinx library directory. Now comes the tricky part: we force the relevant ISE command-line tools to use the driver even though they think they are using a Xilinx-supplied kernel driver. We do this by "preloading" our new library when we load those command-line tools. In older versions of the ISE, we did this in the general invocation script, but this won't work for ISE 11.1, because the tools are now invoked from scripts within the ISE. Therefore, we follow the advice of Ken Ryan and for each tool that uses a cable, we move the tool's binary file and add a tiny script that preloads the driver and then calls the binary. For WebPack, the only tool is impact, but other Xilinx tools in the full ISE can be handled the same way.

for impact, first find the binary whose name is _impact and move it to _impact.bin in the same directory. For ISE 11.1 WebPack, the tool is at /opt/Xilinx/11.1/ISE/bin/lin so cd /opt/Xilinx/11.1/ISE/bin/lin mv _impact _impact.bin

now, create a file named _impact and make it executable touch _impact chmod +x _impact edit _impact to look like this: LD_PRELOAD=libusb-driver.so $0.bin $*
 * 1) !/bin/sh
 * 2) Preload driver binary

Cable Alternatives
In ISE 10.1, Xilinx implemented a way to use libusb directly, without the use of libusb-driver. This is good, because (among other things) the ISE installation now adjusts the udev entries properly to grant user permissions. Unfortunately, This altetnative fails in 11.1, (at least for WebPack on a 64-bit Gentoo) and I cannot find a fix.

I also had problems with a 32-bit Gentoo. There were actually two issues. The iMPACT driver will double check that the installed firmware is the one distributed with the Xilinx installation. So make sure you have  or   available even if you installed the firmware in a different directory or tell udev to use the firmware directly from the installation directory. Note that executing iMPACT as root will work (without having '/usr/share/xusbdfwu.hex') but the USB installer will be executed in the background, which will the USB firmware somewhere in your system.

Secondly, iMPACT tries to load  via dlopen. This fails on newer Gentoo installations because  is only a linker script and not a symlink to the actual libusb.so. I fixed this by putting a symlink to the correct libusb.so in the Xilinx library directory.

The "standard" approach is to install specialized cable drivers in the kernel. This approach is fragile, because the drivers must be recompiled for each new kernel and because these drivers sometimes fall out of sync. This approach is no longer preferred even by Xilinx.

A third alternative is not use the Xilinx cables tools at all, but to use xc3sprog.

Possible Webpack 11.1 + libusb on AMD64 fix
A possible fix that worked for this author is to self-compile a special libusb install. Simply emerging libusb will build libusb against the system libraries, which aren't necessarily the same as the xilinx versions. Steps that worked for me were : source /opt/Xilinx/11.1/settings64.sh; cd libusb-sources; ./configure --prefix=/opt/libusb --exec-prefix=/opt/libusb --without-pkgconfig --disable-build-docs; make; make install; export LD_LIBRARY_PATH=/opt/libusb/lib:$LD_LIBRARY_PATH; impact

Simply mod settings64.sh to change the LD_LIBRARY_PATH to include that, and you're good from then on. For reference, I was using it with a Platform Cable USB II. Ensure that you do the "source" command first. This exposes the right libraries to the linker when building libusb.

Manual Installation
When using the lib-usb solution, one problem is the actual installation of the 'Cable Drivers' onto the system. In the following section, the installation procedure from the Xilinx 11.4 software is described (as reverse engineered from a SuSE system).

First, make sure 'fxload' is installed, this is needed to load the firmware for the JTAG programmer.

emerge -av fxload

Next, create a file in '/etc/udev/rules.d/' called 'xusbdfwu.rules', this is the magic that loads the firmware into the programmer upon connecting: SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0008", MODE="666" BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0007", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusbdfwu.hex -D $TEMPNODE" BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0009", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_xup.hex -D $TEMPNODE" BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="000d", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_emb.hex -D $TEMPNODE" BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="000f", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_xlp.hex -D $TEMPNODE" BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0013", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_xp2.hex -D $TEMPNODE" BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0015", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_xse.hex -D $TEMPNODE"
 * 1) version 0003

In case the default version does not work (it does not on udev 151), use the updated version below: ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="0008", MODE="666" SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="0007", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusbdfwu.hex -D $tempnode" SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="0009", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_xup.hex -D $tempnode" SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="000d", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_emb.hex -D $tempnode" SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="000f", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_xlp.hex -D $tempnode" SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="0013", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_xp2.hex -D $tempnode" SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="0015", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusb_xse.hex -D $tempnode"
 * 1) version 0003

The rules above assume the firmware is actually present in '/usr/share'. To prevent the Xilinx software from installing all kinds of files in your Gentoo system, it might be wise to replace the paths above with files from the Xilinx directory. Use something like this to track down the firmware: find /opt/Xilinx -name "*.hex"

For some reason the firmware seems to be present in multiple locations (albeit in 32-bit and 64-bit versions). I used the firmware from the installer directory: '/opt/Xilinx/11/ISE/bin/lin64/install_script/install_drivers/linux_drivers/pcusb' - note that the path might differ on your system! Also, these are the 64-bit versions which seems to differ from the 32-bit version, make sure to select the correct version.

If you encounter the following error message it might help to create the following symlink: ln -s /lib/libusb-0.1.so.4.4.4 /lib/libusb.so