Notes on Xilinx ISE/WebPack

Installation on Windows

If the GUI installer never starts without any error message, then just run …\bin\nt\xsetup.exe or …\bin\nt64\xsetup.exe directly. The toplevel installer seems to try to detect what system it is running on and gets confused if it encounters certain configurations (I suspect it is the XP Media Center Edition, a mixed breed between XP Home and XP Professional, that makes it bail in my case).

ISE13.2 and later actually come with a newer version of the Digilent plugin than is available from Digilent itself, after installation of ISE you find the installer in …/ISE_DS/common/bin/<OS>/digilent/. The Adept framework however is an older version that will not work with the JTAG HS-1, so you still need to get that one from the Digilent website. You should install the Digilent software in its default location. While it allows you to change the installation path, any later update will use the default installation path with no option to change it.

Impact in ISE13.3 (and apparently earlier) crashes when loading the IPF project and/or opening the program cable if any Digilent cable has been set to operate at 30MHz. To clear this, start from an empty project — there must be only a single Digilent cable connected, otherwise the UI gets confused — open the cable, set a different speed. Program a device with the new settings. Close the cable, open it again in auto mode and check that the speed has been correctly remembered. You should now be able to use the other Impact projects again (unless you've manually set one of them to use 30MHz).

Installation on Linux

With ISE14.1 and openSUSE 12.1/Tumbleweed the GUI installer finally works, but if you try to use any file choser window, it will hang there, so just enter the path name to the installation by hand.
Older versions: If the GUI installer never starts, segfaults or otherwise misbehaves, try the batch installer — this was the ticket for me to finally get the install done on openSuSE 11.3. I've since updated to openSuSE 11.4 and ISE13.x with the same installer problems and using the same solution. ISE seems to be compiled using older libraries than required by some applications and the LD_LIBRARY_PATH settings don't seem to be correct or some libs are compiled in statically that shouldn't be. I really wish someone would educate them about using the dynamic linker correctly, especially how rpath specification and $ORIGIN work…

Do not try to install the cable drivers unless you really have a Xilinx cable and also have the kernel sources installed since it will fail if they aren't. You don't need those drivers at all if you have a Digilent (or compatible) board or JTAG programmer and you can use libusb-driver if you need to use a parallel port cable or the popup-windows annoy you too much.

To run any applications, just open a new shell and source …/ISE_DS/settings32.csh or …/ISE_DS/settings32.sh as appropriate. Start all Xilinx (and only those) applications from this shell. Alternatively you can start a subshell together with the application. That is more cumbersome to do on the command line, but easier to set up with an alias or wrapper script.

The shell script above sets LD_LIBRARY_PATH in a way that prevents most if not all KDE4.6 applications from running. This means that ISE can't fire up a browser to show certain parts of the help, otherwise I've not run across problems so far. I've tried to prepend the system libraries to the LD_LIBRARY_PATH which allows to run KDE applications from the command line, but the problem with starting from within ISE remains (with a strange complaint from the dynamic linker). I've not extensively tested if that produces further problems, but it seems likely.
I've solved the problem for Firefox (which is started via its own wrapper script) by ignoring the imported LD_LIBRARY_PATH in that wrapper. So now the external webpages and some internal documentation will be correctly sent off to Firefox. The only problem is that on each update of Firefox I'll have to re-edit the wrapper.

ISE14.1 comes again with a newer version of the Digilent plugin (version 2.2.10 vs. 2.1.7 from Digilent), but the Adept runtime is current. The FTDI drivers have not been updated, so there is no need to reinstall those.
Older versions: ISE13.2 actually comes with a newer version of the Digilent plugin than is available from Digilent itself (it's version 2.1.5 vs. 2.0.5), after installation of ISE you find the installer in …/ISE_DS/common/bin/<OS>/digilent/. The Adept framework however is an older version that will not work with the JTAG HS-1, so you still need to get that one from the Digilent website. ISE13.3 comes with the exact same versions of the plugins, so the same setup as for ISE13.2 can be used.

Use libusb-driver on Linux

Head over to Xilinx JTAG tools or better yet, clone the Git repository git clone git://git.zerfleddert.de/usb-driver and apply this patch (which sets up to only use libusb-driver by default). Install the resulting library into /usr/local/lib/libusb-driver.so, rename the Impact binary to impact.orig and install a shell wrapper in its place:

#!/usr/bin/sh
LD_PRELOAD=/usr/local/lib/libusb-driver.so exec ${0}.orig "$@"

Batch Installation on Linux

When the GUI install for some reason doesn't work, cd to bin/lin, start ./batchxsetup --samplebatchtemplate batch.tmpl to create a batch install template, once you've edited it to your liking, start the batch install using that template ./batchxsetup --batch batch.tmpl. The batch install template should look like this (note that the installer adds the »14.1« by itself now and it shouldn't be included in the destination directory):

 destination_dir=/opt/Xilinx
 copy_preferences=Y
 use_multiple_cores=Y

 application=Acquire or Manage a License Key::0
 application=Install Cable Drivers::0

 application=Sourcery CodeBench for Xilinx Cortex-A9 EABI::1
 application=Sourcery CodeBench for Xilinx Cortex-A9 GNU/Linux::1
 application=Setup PlanAhead Install Environment::1
 application=Install Linux System Generator Info XML::1
 application=Ensure Linux System Generator Symlinks::1

The ISE13.2 template (with a different path to the installation of course) can be used for ISE13.3. There is a new option to take advantage of multiple processor cores during installation that you might want to add and customize appropriately.

The batch install template for ISE13.2 should look like this:

 destination_dir=/opt/Xilinx/13.2
 copy_preferences=Y
 application=Acquire or Manage a License Key::0
 package=ISE WebPACK::1
 application=Configure WebTalk::1
 application=Install Linux System Generator Info XML::0
 application=Ensure Linux System Generator Symlinks::0
 application=Install Cable Drivers::0
 application=setupEnv.sh::1

The batch install template for ISE13.1 should look like this:

 destination_dir=/opt/Xilinx/13.1

 copy_preferences=Y

 application=Acquire or Manage a License Key::0
 application=Install Cable Drivers::0

 package=ISE WebPACK::1
 environment_variable=PATH::1
 environment_variable=LD_LIBRARY_PATH::1
 environment_variable=XILINX::1
 environment_variable=XILINX_DSP::1
 environment_variable=PATH::1
 environment_variable=LD_LIBRARY_PATH::1
 application=Configure WebTalk::1
 application=Install Linux System Generator Info XML::0
 application=Ensure Linux System Generator Symlinks::0
 environment_variable=XILINX_PLANAHEAD::1
 environment_variable=PATH::1
 application=setupEnv.sh::0
 environment_variable=XILINX_EDK::1
 environment_variable=PATH::1
 environment_variable=LD_LIBRARY_PATH::1

Version Control with Git

ISE litters its files all over the project directory by default, making proper version control a bit difficult. Specifying a separate working directory in the project settings takes care of that. Coregen when started from ISE, however always uses the source directory for re-generating the cores, no matter what the project settings in ISE are. This can be improved by opening the ISE-generated project file coregen.cpg in Coregen and setting the temporary directory to some separate place in the ISE working directory and then cleaning up the mess that the first run has already created. If you already have a Coregen project file someplace else, it is easy to modify it so that it can be used directly in the new project, saving you the cleanup. The remaining plumbing required is to make sure that git doesn't pick up the files that ISE generates, so that only the sources make it into the repository:

# put into .gitignore or .git/info/exclude
# 
iseconfig
isework
cgwork
.lso
*.log
cores/*
!cores/*.xco

The directory structure implied by this is:

ProjectName/
- cgwork/
- cores/
- iseconfig/ (auto-generated)
- isework/
- ProjectName.xise

I prefer to put any sources (Verilog, VHDL) into a separate directory. Note that ISE doesn't require that the sources come from within the project hierarchy, but even if you use sources from someplace else they should probably be added to the project directory as a git submodule or subtree.

ISE tools on Windows seem not to care about CRLF or LF line endings at all. They do however place CRLF line endings on any lines you modify (and only those!) in the GUI. You now have mixed line endings in source files, which should never propagate into the repository. Configure Git appropriately to normalize line endings into the repository before checking in files.