kramble / jtagger Goto Github PK

Jtagger is a utility to program a Terasic DE0-Nano board from a linux host computer
and communicate via virtual jtag. It does NOT need the installation of Altera/Intel
Quartus software or drivers (this was the reason the utility was written).

The project came about because I installed (dual boot) LinuxMint onto on old Windows Vista
laptop, but did not have the free disk space for a linux installation of Quartus. I could
run the pre-existing windows version via wine, but needed to boot into Vista to program the
DE0-Nano. Also tcl is a right pain for communicating with the device, and I wanted something
I could call from C instead.

I came across OpenOCD which is nice, but rather complex (it takes a full 10 minutes to build),
and still relies on that [REDACTED] tcl interpreter. OpenFPGALoader is simpler and works very
well as a programmer, so with both tools I was able to both program and communicate with a
test FPGA design (see fpga/vjtag) which was based on https://github.com/tomverbeure/jtag_gpios
As an aside, congratulations to Tom for a very informative blog https://tomverbeure.github.io

Anyway, after a bit of hacking with the OpenOCD source, I came up with jtagger which is much
simpler and suits my purposes better. In fact I liked it so much that I'm sharing it here. Voila!
That said, the code is VERY amateurish, so please just use it for inspiration, not as a finshed
professional application.

Licensing
---------
I have copied code fragments from OpenOCD https://openocd.org/ https://github.com/openocd-org/openocd
and a couple of entire source files, so see LICENSING for the relevant terms. I've also included
copyright notices on files containing code fragments (hopefully I didn't miss any). I also used
OpenFPGALoader for inspiration (and some reverse engineering) but I don't think that warrants explict
licensing (there are jtag data strings in program.c generated by logging OpenFPGALoader FTDI calls).

The demo fpga/vjtag verilog code and bitstream is based on https://github.com/tomverbeure/jtag_gpios
from the blog post https://tomverbeure.github.io/jtag/2018/05/04/JTAG-for-FPGAs-1-JTAG-GPIO.html
Code was released under an Unlicense license https://unlicense.org/, except for jtag_tap_defines.v 
which was released under LGPL (see file).

Buiding
-------
You'll need the usual gcc and build tools (make). The only other dependancies are libusb-dev and
libftdi-dev (sudo apt-install libusb-dev libftdi-dev), then just "cd src" and "make".
CAVEAT: I haven't tried a build on a "clean" system, so YMMV. I may have missed something.
See src/README_Win32.txt for Windows, currently only 32 bit but that should run OK on 64 bit.

Testing
-------
A prebuilt bitstream is supplied in fpga/vjtag so after building src you can just do
cd ../fpga/vjtag
../../src/jtagger -r system.rbf
../../src/jtagger			(basic test)

A more comprehensive demo is txrxmem which communicates with on-chip block ram (can easily be
integrated with a softcore CPU using a simple DMA interface)
cd ../txrxmem
../../src/jtagger -r system.rbf
../../src/jtagger			(basic test)
../../src/jtagger -u st		(upload speed and stress test)

Also a fun demo (DE0-Nano plays music) see fpga/audio/README for details

$ ./jtagger --help 
------------------
Usage: jtagger --help -v -y -p filename.svf -r filename.rbf

A standalone jtag driver for the DE0-Nano (Quartus is not required).
Without options, jtagger prints the chip id and checks for a virtual jtag hub.
If a hub is found, the first instance is listed and some I/O is attempted.
See the vjtag verilog project for details (this is just an example, the jtagger
source should be modified to support your own system requirements).

OPTIONS
-v sets verbose mode.
-s communicates with a separate jtag server (DEPRECIATED).
-p will program a .svf file (default system.svf), likely BUGGY (use -r instead)
-r will program a .rbf file (default system.rbf), must not be compressed.
-y autoconfirm programming
-u pass string to usercode (additional parameters)

NB only Altera/Intel Quartus .svf programming files are supported as the svf
parsing is very crude, tested on Quartus 10.1 (other versions may not work).
Use raw binary files (-r) instead. The -p option is likely to be removed in future
as writing a full svf parser does not appeal to me as a good use of my time (it
only exists because that is how the project began, rbf was added later).

Jtagger was originally designed as a client/server but this is now depreciated
as the standalone functionality is much faster and less "quirky". The jtagserver
executable is not longer built by default (edit the Makefile to reenable).

Employs code from OpenOCD and OpenFPGALoader under the GPL license.
You may find those projects more useful than jtagger which was written as a
personal project to drive a vitual jtag hub without needing Quartus installed.
Nevertheless, you may be pleasantly surprised at just how FAST it programs,
and certainly how fast it can bulk transfer data, compared with Quartus TCL.