Programming Digilent Nexys 2 from Linux

I recently bought a Digilent Nexys 2 board, and after a few days of
research got to the point where I can successfully program it over USB
from a Linux host without the use of a separate (and expensive!) JTAG
interface.  Google told me even before I purchased the board that this
is a very common requirement; it seems that I'm not the only one
interested in linux-hosted FPGA development.  The pieces to make this
work were all there, happily (see the README in the download below for
details -- the chain of responsibility here is long); it just took
work to assemble them correctly.

For those interested, I wrote a quick perl script to automate the
process, available at: [url]http://plausible.org/andy/nexys2prog.tar.gz
[/url]

This wraps the multi-step mess (device detection/configuration, SVF
generation, and JTAG download) as fully as possible, most importantly
by doing the USB bus enumeration and dynamically reprogramming the
Nexys 2 with a patched usb_jtag firmware blob in the script itself.
The user just specifies the Xilinx bitstream file as the sole
argument.

Installation is as simple as I could make it, requiring only Xilinx
ISE, two binary packages (fxload and libftdi -- both available via apt-
get on Ubuntu Intrepid) and one source install (UrJTAG -- just a
simple "./configure;make;make install" will do).

Hopefully this will help other newbies with the learning curve.  Let
me know if something doesn't work, or if there are questions.

On Mar 30, 4:46=A0pm, Andy Ross <andy.ross...@gmail.com> wrote:
> I recently bought a Digilent Nexys 2 board, and after a few days of
> research got to the point where I can successfully program it over USB
> from a Linux host without the use of a separate (and expensive!) JTAG
> interface. =A0Google told me even before I purchased the board that this
> is a very common requirement; it seems that I'm not the only one
> interested in linux-hosted FPGA development. =A0The pieces to make this
> work were all there, happily (see the README in the download below for
> details -- the chain of responsibility here is long); it just took
> work to assemble them correctly.
>
> For those interested, I wrote a quick perl script to automate the
> process, available at: [url]http://plausible.org/andy/nexys2prog.tar.gz
> [/url]
>
> This wraps the multi-step mess (device detection/configuration, SVF
> generation, and JTAG download) as fully as possible, most importantly
> by doing the USB bus enumeration and dynamically reprogramming the
> Nexys 2 with a patched usb_jtag firmware blob in the script itself.
> The user just specifies the Xilinx bitstream file as the sole
> argument.
>
> Installation is as simple as I could make it, requiring only Xilinx
> ISE, two binary packages (fxload and libftdi -- both available via apt-
> get on Ubuntu Intrepid) and one source install (UrJTAG -- just a
> simple "./configure;make;make install" will do).
>
> Hopefully this will help other newbies with the learning curve. =A0Let
> me know if something doesn't work, or if there are questions.

Thanks for putting that together! I've been googling unsuccessfully
for all that info since buying my Nexsys 2 a few months ago. derp derp
derp.

Eric

On 30 mar, 20:46, Andy Ross <andy.ross...@gmail.com> wrote:
> I recently bought a Digilent Nexys 2 board, and after a few days of
> research got to the point where I can successfully program it over USB
> from a Linux host without the use of a separate (and expensive!) JTAG
> interface. =A0Google told me even before I purchased the board that this
> is a very common requirement; it seems that I'm not the only one
> interested in linux-hosted FPGA development. =A0The pieces to make this
> work were all there, happily (see the README in the download below for
> details -- the chain of responsibility here is long); it just took
> work to assemble them correctly.
>
> For those interested, I wrote a quick perl script to automate the
> process, available at: [url]http://plausible.org/andy/nexys2prog.tar.gz
> [/url]
>
> This wraps the multi-step mess (device detection/configuration, SVF
> generation, and JTAG download) as fully as possible, most importantly
> by doing the USB bus enumeration and dynamically reprogramming the
> Nexys 2 with a patched usb_jtag firmware blob in the script itself.
> The user just specifies the Xilinx bitstream file as the sole
> argument.
>
> Installation is as simple as I could make it, requiring only Xilinx
> ISE, two binary packages (fxload and libftdi -- both available via apt-
> get on Ubuntu Intrepid) and one source install (UrJTAG -- just a
> simple "./configure;make;make install" will do).
>
> Hopefully this will help other newbies with the learning curve. =A0Let
> me know if something doesn't work, or if there are questions.

That's great! Any idea if that works for a Nexys (not version 2)? I'm
trying to get it working but so far I wasn't able to. The program
detects if the cable is present or not, and appears to change the
board's firmware somehow, since until the board is powered down, its
lsusb output changes from:
Bus 007 Device 033: ID 1443:0005
to:
Bus 007 Device 034: ID 16c0:06ad VOTI
but the program doesn't show anything else.

Do you have any idea of what's happening, since it appears both the
nexys 1 and 2 have the same programming interface?

On Apr 1, 2:23=A0pm, Ronan Paix=E3o <ronanpai...@yahoo.com.br> wrote:
> Do you have any idea of what's happening, since it appears both the
> nexys 1 and 2 have the same programming interface?

The script was written specifically for the Nexys 2, as obviously
that's all I have available to test with and I'm still new enough at
this stuff (FPGA work, not software development, that is) that I'm
more likely to hurt things than help by guessing at inappropriate
abstractions.  But looking really briefly at the schematics, it seems
like it should work in principle.  The JTAG pinout on the FX2 chip
looks identical, and obviously you're seeing the firmware reload work
successfully.

First off, run the script with a "-v" to enable verbose mode and see
what the underlying error is.

The one thing I see that will need to be changed is the path to the
BDSL files on line 236; the Nexys has (I think) a Spartan 3, not a 3E,
and Xilinx spreads these files out all over their tree.  Try this:

--- nexys2prog
+++ nexys2prog
@@ -233,7 +233,7 @@
 sub play_svf {
     open JTAG, ">$TMPID.jtag" or die "cannot write to $TMPID.jtag";
     # Just the BSDL directories needed for the 2 chips on the
Nexys2...
-    print JTAG "bsdl path $XILINX/spartan3e/data;$XILINX/xcf/data\n";
+    print JTAG "bsdl path $XILINX/spartan3e/data;$XILINX/spartan3/
data;$XILINX/xcf/data\n";
     print JTAG "cable usbblaster\n";
     print JTAG "detect\n";
     print JTAG "part 1\n";

Another potential gotcha is that the iMPACT script generator is
specifying an XCF04S and not the 02 part that seems to be on the
Nexys.  But as this is just being fed a bypass command, I can't see
why it would matter.  And now that I'm understanding JTAG better, I'm
not sure why this chip needs to be specified at all just to generate
SVF, when the real bypass command is actually done by UrJTAG at
runtime...

Let me know how things work out.  Now that I have a better handle on
things and am getting out of the "blind stitchwork" phase, I'm
starting to think about nicer interfaces.  One thing to note is that a
Xilinx bitstream file embeds its part identifier, so there's really no
need to know anything about the board design a priori -- we could just
scan the JTAG bus for a matching part number, regardless of where it
lives on the chain, and program that.  Likewise extending the FX2
interface to handle other known FX2 parts (the KNJN Saxo boards, which
I almost bought, or the Digilent cable), or even arbitrary JTAG
interfaces that can be detected, is possible.

Then again, the whole point here is to allow me to play with FPGAs and
learn something, not do tool integration that won't teach me anything
new. :)

Andy,

Sure hope this works. I'm tried of having to reboot into windows to burn
code into my boards.

Does this reprogram the 8051? Does that mean if I use it I cannot go 
back and use the digilent adept software?

John Eaton



Andy Ross wrote:
> I recently bought a Digilent Nexys 2 board, and after a few days of
> research got to the point where I can successfully program it over USB
> from a Linux host without the use of a separate (and expensive!) JTAG
> interface.  Google told me even before I purchased the board that this
> is a very common requirement; it seems that I'm not the only one
> interested in linux-hosted FPGA development.  The pieces to make this
> work were all there, happily (see the README in the download below for
> details -- the chain of responsibility here is long); it just took
> work to assemble them correctly.
> 
> For those interested, I wrote a quick perl script to automate the
> process, available at: [url]http://plausible.org/andy/nexys2prog.tar.gz
> [/url]
> 
> This wraps the multi-step mess (device detection/configuration, SVF
> generation, and JTAG download) as fully as possible, most importantly
> by doing the USB bus enumeration and dynamically reprogramming the
> Nexys 2 with a patched usb_jtag firmware blob in the script itself.
> The user just specifies the Xilinx bitstream file as the sole
> argument.
> 
> Installation is as simple as I could make it, requiring only Xilinx
> ISE, two binary packages (fxload and libftdi -- both available via apt-
> get on Ubuntu Intrepid) and one source install (UrJTAG -- just a
> simple "./configure;make;make install" will do).
> 
> Hopefully this will help other newbies with the learning curve.  Let
> me know if something doesn't work, or if there are questions.

I'm pretty sure that the Digilent 8051 code is loaded from flash at
power-up and this process reloads new open-source code from USB which
is lost at the next power down or reset. You should be OK using this
with Adept as long as you cycle power.

Eric

On Apr 1, 9:40=A0pm, John Eaton <nos...@spam.com> wrote:
> Andy,
>
> Sure hope this works. I'm tried of having to reboot into windows to burn
> code into my boards.
>
> Does this reprogram the 8051? Does that mean if I use it I cannot go
> back and use the digilent adept software?
>
> John Eaton
>
> Andy Ross wrote:
> > I recently bought a Digilent Nexys 2 board, and after a few days of
> > research got to the point where I can successfully program it over USB
> > from a Linux host without the use of a separate (and expensive!) JTAG
> > interface. =A0Google told me even before I purchased the board that thi=
s
> > is a very common requirement; it seems that I'm not the only one
> > interested in linux-hosted FPGA development. =A0The pieces to make this
> > work were all there, happily (see the README in the download below for
> > details -- the chain of responsibility here is long); it just took
> > work to assemble them correctly.
>
> > For those interested, I wrote a quick perl script to automate the
> > process, available at: [url]http://plausible.org/andy/nexys2prog.tar.gz
> > [/url]
>
> > This wraps the multi-step mess (device detection/configuration, SVF
> > generation, and JTAG download) as fully as possible, most importantly
> > by doing the USB bus enumeration and dynamically reprogramming the
> > Nexys 2 with a patched usb_jtag firmware blob in the script itself.
> > The user just specifies the Xilinx bitstream file as the sole
> > argument.
>
> > Installation is as simple as I could make it, requiring only Xilinx
> > ISE, two binary packages (fxload and libftdi -- both available via apt-
> > get on Ubuntu Intrepid) and one source install (UrJTAG -- just a
> > simple "./configure;make;make install" will do).
>
> > Hopefully this will help other newbies with the learning curve. =A0Let
> > me know if something doesn't work, or if there are questions.

emeb wrote:
> I'm pretty sure that the Digilent 8051 code is loaded from flash at
> power-up and this process reloads new open-source code from USB
> which is lost at the next power down or reset. You should be OK
> using this with Adept as long as you cycle power.

Yes, that's exactly right.  The FX2 chip has a built-in loader that
works irrespective of what the boot configuration was.  Once the
device reboots (you have to unplug it from the USB bus, it's not
controlled by the FPGA power switch) it restreams its firmware from
the I2C EEPROM and acts like a Digilent device again.

It should be noted that I've only done the integration work here.
There were *lots* of people involved in making this work.  Here's the
relevant section of the README in the package.  (One credit that I've
since realized I missed is that the usb_jtag firmware is itself based
on similar 8051 code from the GNU Radio folks).

  Xilinx, of course, provides a Linux version of their free (as-in-
beer)
  ISE WebPack product [1].  But Digilent uses a proprietary protocol
for
  their USB interface, and they neither document it nor provide tools
  other than a (decidedly clunky) Windows GUI [2] to use it.

  Nonetheless the USB hardware on the device is open.  The Cypress FX2
  USB chip on the board, which itself is a 8051 microcontroller, is
  fully programmable from across the USB bus [3] and that interface is
  supported from linux thanks to the work of the linux-hotplug project
  [4].  The sdcc project provides a free C compiler [5] for the 8051,
  which Kolja Waschk used to write a firmware suite named
"usb_jtag" [6]
  for a FX2-based USB/JTAG cable that allows it to be used as a
  compatible replacement for an Altera USB Blaster -- a cable based on
a
  different USB interface part from FTDI, which is supported under
linux
  by the libftdi project [7].  The UrJTAG project [8], which is a
  currently-maintained fork of the mostly-abandonware openwince-jtag
  project, provides a high level JTAG interface (using libftdi as one
of
  many drivers) that can be used to program the FPGA using SVF files
  from the Xilinx iMPACT tool.  The Nexys 2 board enters the picture
at
  last when Sune Mai, in posts on fpga4fun.com [9] and on the UrJTAG
  mailing list [10], ported Waschk's usb_jtag firmware to the Nexys 2
by
  simply changing the 8051 port assignments of the JTAG pins (the FX2
on
  the Digilent board is wired differently than the usb_jtag cable, but
  is otherwise compatible) and by fixing a integer overflow bug the
  upstream code had with handling large bitstream files.  Neither
change
  has been merged into Kolja's code, unfortunately.

  Finally, Morgan Delahaye-Prat collected the above into a single
  walkthrough on his (French) blog [11], providing detailed
instructions
  and downloadable files and patches.  The language barrier for
  non-French-speakers can be surmounted without too much difficulty
via
  google's language tools.  The Rube Goldberg-like complexity of the
  process, however, took much longer to puzzle out and left me with a
  tree full of tiny scripts, notes, and patched software trees.

  [1] http://www.xilinx.com/ise/logic_design_prod/webpack.htm
  [2] http://digilentinc.com/Products/Detail.cfm?Prod=ADEPT
  [3] http://download.cypress.com.edgesuite.net/design_resources/datasheets/contents/cy7c68013a_8.pdf
  [4] http://linux-hotplug.sourceforge.net
  [5] http://sdcc.sourceforge.net
  [6] http://www.ixo.de/info/usb_jtag/
  [7] http://www.intra2net.com/en/developer/libftdi
  [8] http://urjtag.org
  [9] http://www.fpga4fun.com/forum/viewtopic.php?p=4779
  [10] http://sourceforge.net/forum/forum.php?thread_id=2312452&forum_id=682993
  [11] http://www.m-del.net/info.html

Andy Ross <andy.ross.or@gmail.com> wrote:
> emeb wrote:
> > I'm pretty sure that the Digilent 8051 code is loaded from flash at
> > power-up and this process reloads new open-source code from USB
> > which is lost at the next power down or reset. You should be OK
> > using this with Adept as long as you cycle power.

> Yes, that's exactly right.  The FX2 chip has a built-in loader that
> works irrespective of what the boot configuration was.  Once the
> device reboots (you have to unplug it from the USB bus, it's not
> controlled by the FPGA power switch) it restreams its firmware from
> the I2C EEPROM and acts like a Digilent device again.

I have a modified version of the USRP FX2 firmware and a modified version of
xc3sprog(Linux) to directly programm Spartan3/XCF and XC95XL via a
Bit/Jedecfile. Probably the firmware needs some adapations, as the JTAG Pins
will differ. However I don't have a Digilent adapter available, to someone
interested must do this changes by himself.

Some nearly recent verison is uploaded to the patches section of 
xc3sprog at sourceforge.

-- 
Uwe Bonnes                bon@elektron.ikp.physik.tu-darmstadt.de

Institut fuer Kernphysik  Schlossgartenstrasse 9  64289 Darmstadt
--------- Tel. 06151 162516 -------- Fax. 06151 164321 ----------

On Apr 2, 9:06=A0am, Uwe Bonnes <b...@elektron.ikp.physik.tu-
darmstadt.de> wrote:
> I have a modified version of the USRP FX2 firmware and a modified version=
 of
> xc3sprog(Linux) to directly programm Spartan3/XCF and XC95XL via a
> Bit/Jedecfile. Probably the firmware needs some adapations, as the JTAG P=
ins
> will differ. However I don't have a Digilent adapter available, to someon=
e
> interested must do this changes by himself.

Yeah.  With all due respect, though, the "someone needs to make it
work" part is a huge hurdle.  There are all sorts of half-solutions
like that floating around the internet in various stages of decay.
Your own xc3sprog patches, for example, are still patches because the
project itself is abandoned.  And of course, xc3sprog itself is a fork
of someone else's abandoned work...

I did see your stuff, by the way, but ultimately decided on the UrJTAG-
based solution instead.  UrJTAG is actively maintained, works well,
and is more generically useful for anyone working with their FPGA
board than a Spartan-specific C program will be.

Likewise, Kolja Waschk's FX2 firmware seemed cleaner to me.  It
emulates an existing protocol (spoken by the FTDI-based Altera
USBBlaster cable) and thus works out-of-the-box with UrJTAG without
modification.  And the patches required for it consist only of a few
modified pin assignments and a fix for an integer overflow bug, so
it's easier for me to maintain as part of the script.

Obviously the Right Thing here would be for someone to write a generic
firmware suite for the FX2 (abstracting the JTAG pin assignments
somehow), pair it with dynamic USB device detection and configuration
for all known FX2-based JTAG controllers, and mate it to UrJTAG such
that any bitstream file can be thrown at any JTAG chain with the
expected results.

But I didn't have time (or the device library, or the domain
knowledge) to do that.  So instead I wanted to get to a solution that
works well for just one device and requires as little from the user as
possible.  That's what this script does.

Andy Ross <andy.ross.or@gmail.com> wrote:
...
> like that floating around the internet in various stages of decay.
> Your own xc3sprog patches, for example, are still patches because the
> project itself is abandoned.  And of course, xc3sprog itself is a fork
> of someone else's abandoned work...

That's the history of most open source projects.

> I did see your stuff, by the way, but ultimately decided on the UrJTAG-
> based solution instead.  UrJTAG is actively maintained, works well,
> and is more generically useful for anyone working with their FPGA
> board than a Spartan-specific C program will be.

The stuff is in SVN locally.

> Likewise, Kolja Waschk's FX2 firmware seemed cleaner to me.  It
> emulates an existing protocol (spoken by the FTDI-based Altera
> USBBlaster cable) and thus works out-of-the-box with UrJTAG without
> modification.  And the patches required for it consist only of a few
> modified pin assignments and a fix for an integer overflow bug, so
> it's easier for me to maintain as part of the script.

This will have a hugh inpact on transfer speed

> Obviously the Right Thing here would be for someone to write a generic
> firmware suite for the FX2 (abstracting the JTAG pin assignments
> somehow), pair it with dynamic USB device detection and configuration
> for all known FX2-based JTAG controllers, and mate it to UrJTAG such
> that any bitstream file can be thrown at any JTAG chain with the
> expected results.

Thats a "eierlegende Wollmichsau", doing everything right, but probably
never in time.

> ...

-- 
Uwe Bonnes                bon@elektron.ikp.physik.tu-darmstadt.de

Institut fuer Kernphysik  Schlossgartenstrasse 9  64289 Darmstadt
--------- Tel. 06151 162516 -------- Fax. 06151 164321 ----------