UHD: Updating README in tools/ directory.

3 files changed, 170 insertions, 31 deletions

diff --git a/tools/README b/tools/README
deleted file mode 100644
index 7c23a1fff..000000000
--- a/tools/README
+++ /dev/null
@@ -1,31 +0,0 @@
-#
-# Copyright 2014 Ettus Research LLC
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-#
-
-
-UHD Tools
-=========
-
-This folder contains tools which might be useful when debugging or
-working on USRPs. None of these tools actually require UHD to be installed!
-
-
-List of tools:
--------------
-
-impact_jtag_programmer.sh    - Program the X3x0 FPGA via JTAG. Requires Xilinx iMPACT.
-
-
diff --git a/tools/README.md b/tools/README.md
new file mode 100644
index 000000000..d58577589
--- /dev/null
+++ b/tools/README.md
@@ -0,0 +1,22 @@
+USRP™ Tools
+============================
+
+This folder contains tools that are useful for working with and/or debugging
+your USRP™ device. Tools in this directory do **not** link against UHD. They are
+either stand-alone programs or software to be used in third-party applications.
+
+For UHD™ software tools, look in `uhd/host/utils`.
+
+
+## List of Tools
+
+__usrp_x3xx_fpga_jtag_programmer.sh__
+
+This tool is to be used with the USRP™ X300 and X310 devices. It allows you to
+program the X3x0 FPGA via JTAG. Note that loading the FPGA image via JTAG does
+**not** store the FPGA in the on-device flash storage. Thus, as soon as you
+cycle power, the image will be lost. To permanently burn an FPGA image, please
+refer to `uhd/host/utils/usrp_x3xx_fpga_burner`.
+
+This tool requires that Xilinx iMPACT has been installed on your system.
+
diff --git a/tools/usrp_x3xx_fpga_jtag_programmer.sh b/tools/usrp_x3xx_fpga_jtag_programmer.sh
new file mode 100755
index 000000000..df563da14
--- /dev/null
+++ b/tools/usrp_x3xx_fpga_jtag_programmer.sh
@@ -0,0 +1,148 @@
+#!/bin/bash
+#
+
+### Helper functions ##########################################
+function help {
+	cat <<EOHELP
+
+Usage: impact_jtag_programmer.sh [--help|-h] [--impact-path=<PATH>] --fpga-path=<FPGA Image File>
+
+-h             - Shows this.
+--impact-path  - Path to the iMPACT binary (if not already in PATH).
+                 Often something like /opt/Xilinx/14.4/ISE_DS/ISE/bin/lin64/impact
+--fpga-path    - Path to the FPGA image.
+--nipcie       - When this option is set, this script will fail if it was unable
+                 to stop the NI RIO USRP PCIe driver.
+
+This script uses Xilinx iMPACT to reprogram the FPGA through the USB JTAG connector.
+You can use this to unbrick USRP X3x0 devices.
+
+EOHELP
+}
+
+### Go, go, go! ###############################################
+echo "======================================="
+echo " Copyright 2014 Ettus Research LLC"
+echo ""
+echo " JTAG Programming Tool"
+echo "======================================="
+echo ""
+
+IMPACTPATH="impact" # This'll work if impact is in $PATH
+FPGAIMG=""
+FORCENIPCIECHECK=0
+
+# Go through cmd line options
+for i in "$@"
+do
+case $i in
+    -h|--help)
+        help
+        exit
+        ;;
+    --impact-path=*)
+    IMPACTPATH="${i#*=}"
+    ;;
+    --fpga-path=*)
+    FPGAIMG="${i#*=}"
+    ;;
+    --nipcie)
+        FORCENIPCIECHECK=1
+        ;;
+    *)
+        echo Unrecognized option: $i
+        echo
+        help
+        exit
+        break
+        ;;
+esac
+done
+
+# Test impact binary is available
+IMPACTEXECUTABLE=`which $IMPACTPATH`
+if [ ! $? -eq 0 ]; then
+    echo "ERROR: Cannot find 'impact' executable. Make sure you have iMPACT installed"
+    echo "and that it is in your PATH, or use the --impact-path option to provide the"
+    echo "location of the 'impact' executable."
+    exit 1
+fi
+
+# Test the FPGA image file is readable
+if [ -z $FPGAIMG ]; then
+    echo "ERROR: No FPGA image file provided."
+    exit 1
+fi
+if [ ! -r $FPGAIMG ]; then
+    echo "ERROR: Can't read the FPGA image file ($FPGAIMG)."
+    exit 1
+fi
+
+# Test if we need to stop PCIe
+NIUSRPRIOPCIE=`which niusrprio_pcie`
+HASNIUSRPRIOPCIE=$?
+if [ ! $HASNIUSRPRIOPCIE -eq 0 -a $FORCENIPCIECHECK -eq 1 ]; then
+    echo "ERROR: Cannot find the niusrprio_pcie executable. Make sure it is in your PATH."
+    exit 1
+fi
+
+NIUSRPRIOWASLOADED=0
+# If we do, check if we can run niusrprio_pcie
+if [ $HASNIUSRPRIOPCIE -eq 0 ]; then
+    NIUSRPRIOSTATUSOUTPUT=`niusrprio_pcie status`
+    NIUSRPRIORETVAL=$?
+    if [ ! $NIUSRPRIORETVAL -eq 0 ]; then
+        echo "ERROR: Can't run 'niusrprio_pcie status'. Maybe you forgot to use sudo?"
+        exit $NIUSRPRIORETVAL
+    fi
+    NIUSRPRIOSTATUSOUTPUTGREP=`niusrprio_pcie status | grep usrp`
+    if [ ! -z "$NIUSRPRIOSTATUSOUTPUTGREP" ]; then
+        NIUSRPRIOWASLOADED=1
+    fi
+fi
+if [ $NIUSRPRIOWASLOADED -eq 1 ]; then
+    echo "==== Stopping nisurprio drivers... "
+    niusrprio_pcie stop
+    NIUSRPRIORETVAL=$?
+    if [ ! $NIUSRPRIORETVAL -eq 0 ]; then
+        echo "ERROR: Can't run 'niusrprio_pcie stop'. Maybe you forgot to use sudo?"
+        exit $NIUSRPRIORETVAL
+    else
+        echo "Done."
+    fi
+fi
+
+# Create batch file
+CMD_PATH=`mktemp XXXXXXXX.impact.cmd`
+echo "==== Generating impact batch file ${CMD_PATH}..."
+echo "setmode -bscan" > ${CMD_PATH}
+echo "setcable -p auto" >> ${CMD_PATH}
+echo "addDevice -p 1 -file ${FPGAIMG}" >> ${CMD_PATH}
+echo "program -p 1" >> ${CMD_PATH}
+echo "quit" >> ${CMD_PATH}
+
+# Run impact
+echo "==== Running impact -- loading ${FPGAIMG} into the FPGA..."
+${IMPACTEXECUTABLE} -batch ${CMD_PATH}
+RETVAL=$?
+if [ ! $RETVAL -eq 0 ]; then
+    echo "ERROR: Programming failed. Check output above for hints. Maybe you forgot to use sudo?"
+else
+    echo "==== Programming complete! =============="
+fi
+
+# Remove batch file
+rm $CMD_PATH
+if [ $NIUSRPRIOWASLOADED -eq 1 ]; then
+    echo "==== Re-starting nisurprio drivers... "
+    niusrprio_pcie start
+    NIUSRPRIORETVAL=$?
+    if [ ! $NIUSRPRIORETVAL -eq 0 ]; then
+        echo "WARNING: nisusrprio drivers were running before, but could not be reloaded after flashing."
+        echo "This is usually not a problem with the FPGA image burning."
+    fi
+fi
+
+exit $RETVAL
+
+# C'est tout