Added files to recover firmware using OpenOCD with a JTAG adapter

README.md

@@ -11,6 +11,7 @@ The following directories are included:
 * `python` -- Python test programs
 * `tests` -- example programs (qladisp, qlatest, etc.)
 * `util` -- low-level Firewire utility programs (do not depend on `lib`)
+* `jtag-rescue` -- script to rescue a hosed FPGA V1 or V2 using a jtag adapter and openocd
 
 Documentation for the software is on the [wiki](http://github.com/jhu-cisst/mechatronics-software/wiki).
 

jtag-rescue/.gitattributes

@@ -0,0 +1,2 @@
+FPGA1394EthQLA.bit filter=lfs diff=lfs merge=lfs -text
+FPGA1394QLA.bit filter=lfs diff=lfs merge=lfs -text

jtag-rescue/52-digilent-usb.rules

@@ -0,0 +1,54 @@
+###########################################################################
+#                                                                         #
+#  52-digilent-usb.rules -- UDEV rules for Digilent USB Devices           #
+#                                                                         #
+###########################################################################
+#  Author: MTA                                                            #
+#  Copyright 2010 Digilent Inc.                                           #
+###########################################################################
+#  File Description:                                                      #
+#                                                                         #
+#  This file contains the rules used by UDEV when creating entries for    #
+#  Digilent USB devices. In order for Digilent's shared libraries and     #
+#  applications to access these devices without root privalages it is     #
+#  necessary for UDEV to create entries for which all users have read     #
+#  and write permission.                                                  #
+#                                                                         #
+#  Usage:                                                                 #
+#                                                                         #
+#  Copy this file to "/etc/udev/rules.d/" and execute                     #
+#  "/sbin/udevcontrol reload_rules" as root. This only needs to be done   #
+#  immediately after installation. Each time you reboot your system the   #
+#  rules are automatically loaded by UDEV.                                #
+#                                                                         #
+###########################################################################
+#  Revision History:                                                      #
+#                                                                         #
+#  04/15/2010(MTA): created                                               #
+#  02/28/2011(MTA): modified to support FTDI based devices                #
+#  07/10/2012(MTA): modified to work with UDEV versions 098 or newer      #
+#  04/19/2013(MTA): modified mode assignment to use ":=" insetead of "="  #
+#       so that our permission settings can't be overwritten by other     #
+#       rules files                                                       #
+#  07/28/2014(MTA): changed default application path                      #
+#                                                                         #
+###########################################################################
+
+# Create "/dev" entries for Digilent device's with read and write
+# permission granted to all users.
+ATTR{idVendor}=="1443", MODE:="666"
+ACTION=="add", ATTR{idVendor}=="0403", ATTR{manufacturer}=="Digilent", MODE:="666", RUN+="/usr/sbin/dftdrvdtch %s{busnum} %s{devnum}"
+
+# The following rules (if present) cause UDEV to ignore all UEVENTS for
+# which the subsystem is "usb_endpoint" and the action is "add" or
+# "remove". These rules are necessary to work around what appears to be a
+# bug in the Kernel used by Red Hat Enterprise Linux 5/CentOS 5. The Kernel
+# sends UEVENTS to remove and then add entries for the endpoints of a USB
+# device in "/dev" each time a process releases an interface. This occurs
+# each time a data transaction occurs. When an FPGA is configured or flash
+# device is written a large number of transactions take place. If the
+# following lines are commented out then UDEV will be overloaded for a long
+# period of time while it tries to process the massive number of UEVENTS it
+# receives from the kernel. Please note that this work around only applies
+# to systems running RHEL5 or CentOS 5 and as a result the rules will only
+# be present on those systems.

jtag-rescue/openocd.cfg

@@ -0,0 +1,24 @@
+source [find interface/ftdi/digilent_jtag_hs3.cfg]
+
+source [find cpld/xilinx-xc6s.cfg]
+source [find cpld/jtagspi.cfg]
+adapter_khz 10000
+telnet_port 4444
+
+proc program_fpga {} {
+    global _CHIPNAME
+    xc6s_program $_CHIPNAME.tap
+    pld load 0 FPGA1394EthQLA.bit
+}
+
+proc program_fpga_filename {filename} {
+    global _CHIPNAME
+    xc6s_program $_CHIPNAME.tap
+    pld load 0 $filename
+}
+
+proc program_prom {} {
+    jtagspi_init 0 bscan_spi_xc6slx45.bit
+    jtagspi_program FPGA1394Eth-QLA.bin 0x0
+    program_fpga
+}

jtag-rescue/program_fpga.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+if [ $1 ]; then
+openocd -f openocd.cfg -c "init;program_fpga_filename $1;exit"
+else
+openocd -f openocd.cfg -c "init;program_fpga;exit"
+fi
+

jtag-rescue/readme.md

@@ -0,0 +1,48 @@
+# OpenOCD configuration for flashing the FPGA and PROM
+
+## Prerequisites
+### JTAG adapter
+OpenOCD supports most FTDI-based adapters. We recommend Digilent HS2/HS3. OpenOCD does not support the Xilinx Platform Cable DLC9G.
+
+### Software
+Install [OpenOCD](http://openocd.org/). Binary is available for Linux, Mac OS, and Windows.
+
+For Ubuntu, install from apt repository.
+
+```
+sudo apt install openocd
+```
+
+Create a udev rule for the JTAG (if you are using the Digilent JTAG). Create a file at `/etc/udev/rules.d/52-digilent-usb.rules` with the following content.
+
+```
+ATTR{idVendor}=="1443", MODE:="666"
+ACTION=="add", ATTR{idVendor}=="0403", ATTR{manufacturer}=="Digilent", MODE:="666"
+```
+
+Reload the udev rules.
+
+```
+udevadm control --reload-rules
+```
+
+Now unplug and plug in your JTAG adapter.
+
+
+## Usage
+
+`cd` into the `openocd` directory. Use the `program_fpga.sh`. The working directory must be `openocd`. Depending on your FPGA hardware (no-ethernet vs ethernet)
+
+```
+./program_fpga.sh FPGA1394QLA.bit
+
+```
+
+or
+
+```
+./program_fpga.sh FPGA1394EthQLA.bit
+```
+
+This temporarily programs the FPGA with v7 firmware. Now, without powering off the FPGA, reprogram the PROM using firewire.
+