How-To: Digilent Nexys(2) on Linux

Copyright © 2010 Hauke Dämpfling (Last Update: $Date: 2010-05-27 17:37:18 +0000 (Thu, 27 May 2010) $)
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 (alternate hyperlink) or any later version published by the Free Software Foundation.
Any comments, suggestions, etc. greatly appreciated! I can only provide very limited support. See the SourceForge project page.

A	Preparation	Tested on Ubuntu 9.10, but should work on any Debian-based system and can be adapted to most Linux distros. The firmware was tested with a Digilent Nexys2 board, and should work the same with a Nexys(1). The following instructions are very similar to, but currently more complete than, the nexys2prog instructions, see here and here.
1	Install Xilinx ISE
2	`sudo apt-get install fxload libftdi1`	These packages should also be available for other distros, such as SuSE.
3	`sudo apt-get remove openwince-jtag`	This package conflicts with the UrJTAG tools that we will install in the next step, and development has been discontinued in favor of UrJTAG anyway.
4	Download UrJTAG (`.tar.gz`) `tar xzf urjtag-VERSION.tar.gz` `cd urjtag-VERSION` `./configure` `make` `sudo make install`	Tested with UrJTAG 0.10. There is also a "`urjtag`" package in the Ubuntu repositories, but as far as I can tell it's not current. Do a "`sudo apt-get remove urjtag`" to make sure you don't have it installed. If you don't have a full build environment: "`sudo apt-get install build-essential automake autoconf libtool`" and take a look at the "Compilation and Installation" section of the UrJTAG Documentation. UrJTAG installs to `/usr/local` by default.
5	You may need write access to the files in `/dev/bus/usb`	Method 1: Run the `nexys2prog` script with `sudo`. Method 2: Add "`, GROUP="plugdev"`" to the line "`SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", MODE="0664"`" in the file `/etc/udev/rules.d/40-basic-permissions.rules` (note the comma before `GROUP`. You may need to create the file if it doesn't exist, or add the entire line if it doesn't exist. If you happen have VirtualBox installed, the group `vboxusers` will actually already have this permission via `/etc/udev/rules.d/10-vboxdrv.rules`. The same might be true for other software packages, so you should probably check the files in `/etc/udev/rules.d/` first.
6	`svn co https://ixo-jtag.svn.sourceforge.net\ /svnroot/ixo-jtag/nexys2prog/trunk nexys2prog` `cd nexys2prog`	This will get the latest version of nexys2prog. If you want to stay up-to-date, run "`svn up`" in the `nexys2prog` directory to check for new versions. If you don't have the `svn` command (Subversion) installed, do "`sudo apt-get install subversion`". The nexys2prog distribution includes a pre-built version of the Cypress FX2 firmware as the file `usb_jtag.hex`. If you would like to customize the firmware and/or re-build it from source, see the section on this below. Note: To save space I've wrapped the URL on the left over two lines, you should still be able to copy & paste this into a shell as-is. If you have any problems, join the two lines and make sure to remove the backslash (`\`) from the end of the first line. Or, use your browser to copy the hyperlink on the left.
B	Programming the Board
7	Generate a Xilinx `.bit` file	Method 1: Use the Xilinx ISE IDE. Method 2: Take a look at the provided `build.sh` script as an example of how to use the command line.
8	Connect & power up your Nexys(2) board.
9	`./nexys2prog FILENAME.bit`	This will program the custom firmware on the Cypress FX2 chip if necessary, and then program the FPGA with the bitstream. Note that both processes are not permanent, both the FPGA and the FX2 chip will load their original, unaltered firmware if you cycle the power (remember that you'll have to unplug the USB cable to cycle the FX2's power).

Xilinx ISE (free WebPack)

	Installation	Tested with Xilinx ISE 11.1 on Ubuntu 9.10, but it should work on any Linux distro that's supported by Xilinx.
1	`sudo apt-get install libstdc++5 libmotif3 libxp6 libcurl3`	These are the requirements as documented in the Xilinx installation instructions.
2	Download the free "WebPack", single-file version	A quick and fairly painless registration with Xilinx is required. This is a huge download, a few GB if I remember correctly! Make sure you've got some time... There is also a "Web Install Client", but that was much slower for me, and if you use it, the following procedure will be different.
3	`tar xf FILENAME.tar` `cd NEWDIRECTORY` `sudo ./xsetup`	Here, "`NEWDIRECTORY`" is there directory that was created by unpacking the `tar` file. The `sudo` is required to be able to install to the default location of `/opt/Xilinx/VERSION`, if you want to install somewhere else, such as your home directory, the `sudo` may not be required (I'm not sure).
4	Run the installer - see notes	The installer should be pretty self-explanatory, but please note the following: If the installer asks whether you want to update, I suggest not running the update program and instead downloading and installing the updates manually, as this goes faster for me - this is described in the next step. The installer may complain about about there being no space left on the disk (0 bytes), you can safely ignore this (assuming of course you do have enough space left on your disk). If you ran `xsetup` with `sudo`, and the installer launches a browser, this can cause some files (the browser's settings files) in your home directory to change ownership to `root`, this can cause problems the next time you use your browser. If this happens, you'll need to change these permissions back ("`chown -Rc USER:GROUP PATHs`").
5	Download any updates, per Update do: `tar xf FILENAME.tar` `cd NEWDIRECTORY` `sudo ./xsetup`	The installation of updates is very similar to the installation of the WebPack, see above.
6	Set up the environment - see notes	Depending on your platform, you'll need to run either `settings32.sh`, `settings32.csh`, `settings64.sh`, or `settings64.csh` to set up environment variables (for details, see the installation documentation, there is a link to it from the WebPack download page). Or, the following bash script starts Xilinx ISE, just set `XILINX_DIR` to the appropriate path and change the `settings32.sh` script name to the one appropriate to your platform: `#!/bin/bash XILINX_DIR=/opt/Xilinx/11.1 source $XILINX_DIR/settings32.sh $XILINX_DIR/ISE/bin/lin/ise`

Building the Cypress FX2 Firmware

A	Preparation	Tested on Ubuntu 9.10, but should work with any Linux distribution that supports SDCC.
1	`sudo apt-get install sdcc`	If you happen to be using a version of Ubuntu before 9.10, you'll need to install `sdcc-nf` instead of `sdcc`.
2	`svn co https://ixo-jtag.svn.sourceforge.net\ /svnroot/ixo-jtag/usb_jtag/trunk usb_jtag` `cd usb_jtag/device/c51/`	This will get the latest version of the firmware. If you want to stay up-to-date, run "`svn up`" in the `usb_jtag` directory to check for new versions. If you don't have the `svn` command (Subversion) installed, do "`sudo apt-get install subversion`". Note: To save space I've wrapped the URL on the left over two lines, you should still be able to copy & paste this into a shell as-is. If you have any problems, join the two lines and make sure to remove the backslash (`\`) from the end of the first line. Or, use your browser to copy the hyperlink on the left.
3	Edit `Makefile` and change "`HARDWARE=hw_basic`" to "`HARDWARE=hw_nexys`"	See the `README.txt` for more information.
B	Compilation
4	`make`	This will build the firmware as `std.hex`. If you want to use `nexys2prog`, replace the `usb_jtag.hex` file with the one you just built. To clean up the build directory to its original state, run "`make clean`" (note that this deletes the `.hex` file as well).

Back