First fix-ups for Ubuntu 16.04

- document urjtag build (jtag in Ubuntu 16.04 is broken)
- add environment sanity wrappers for acroread,awk,firefox to ensure
  proper operation of vivado under Ubuntu 16.04

doc/INSTALL_fx2_support.md

@@ -19,8 +19,9 @@ USB Interface. Re-building them requires
 - Small Device C Compiler -> package: `sdcc` `sdcc-ucsim`
 - for FX2 firmware download and jtag programming over USB one needs
   - fxload -> package: `fxload`
-  - urjtag -> package: `urjtag`  for Ubuntu 12.04 and newer  
-    see [INSTALL_urjtag.md](INSTALL_urjtag.md) for other distributions !!
+  - urjtag -> package: `urjtag` for Ubuntu 12.04 or 14.04,
+      is **broken in Ubuntu 16.04**.
+      See [INSTALL_urjtag.md](INSTALL_urjtag.md) for installation from sources !!
 
 ### Setup environment variables  <a name="envvar"></a>
 

doc/INSTALL_urjtag.md

@@ -1,50 +1,42 @@
 # Installation of urjtag
 
-The w11 project uses the open source JTAG Access software from the
-SourceForge project
-[urjtag](https://sourceforge.net/projects/urjtag/) 
-for configuring FPGA over the Cypress FX2 USB Interface available on 
-Digilent Nexys2, Nexys3 and Atlys boards.
+`urjtag` is a available as Debian/Ubuntu package since long time.
+but with quite varying quality:
+  - Debian Squeeze and Ubuntu 11.10 (oneiric) or were **broken** due to a
+    string size limitation problem
+  - Ubuntu 12.04 **works**
+  - Ubuntu 14.04 **works**
+  - Ubuntu 16.04 is **corrupt**, crashes with a SEGFAULT in the `detect` command
 
-The most recent version works fine. This version is delivered with 
-Ubuntu 12.04 LTS and later Ubuntu versions. In this case simply install the 
-package `urjtag`. Try the command
+If you have installed the package `urjtag` and the command
 
     jtag
 
-it should print
+prints
 
     UrJTAG 0.10 #2007
 
-and show a version number of `#2007` or higher.
+with a version number of `#2007` or higher and
 
-Old versions unfortunately have a string size limitation problem with can
-lead to problems when used with Digilent S3BOARDS (or other cases with
-multiple devices in the jtag chain). Therefore for
+    cd $RETROBASE/rtl/sys_gen/tst_rlink_cuff/nexys3/ic
+    make sys_tst_rlink_cuff_ic_n3.jconfig
 
-    Debian Squeeze and older
-    Ubuntu 11.10 (oneiric) and older
+works fine with a connected `nexys3` board all is fine.
 
-or if the 'jtag' command prints something like
+Otherwise install from sources. I prefer in install in `$HOME/usr_local`
+to keep distribution packages and self-compiled things separate. Do do
 
-    UrJTAG 0.10 #1502
-    UrJTAG 0.9 #1476
+    cd <your source directory>
+    time git clone https://git.code.sf.net/p/urjtag/git urjtag
 
-it is advisible to install the urjtag software from sources.
+    cd urjtag/urjtag
+    ./autogen.sh --prefix=$HOME/usr_local 2>&1 | tee autogen.log
+    time make 2>&1 | tee make.log
+    time make install 2>&1 | tee install.log
 
-Simlest is to install an up-to-date version directly from the SourceForge
-svn repository, start at
-https://sourceforge.net/p/urjtag/svn/HEAD/tree/trunk/ , do a 
-`svn co` for revision `2007` or later, build and install.
+Tested with urjtag version (from `git log`)
 
-Alternatively start with the `V0.10 (rev #1502)` tarball available from
-https://sourceforge.net/projects/urjtag/files/
-and download
+    commit d938d4679692d94709f30fa9d20205e22436f39b
+    Author: Geert Stappers <stappers@debian.org>
+    Date:   Mon Mar 20 12:04:22 2017 +0100
 
-    urjtag-0.10.tar.gz            (dated 2009-04-17)
-
-Change in file `src/cmd/parse.c` the line
-
-    #define MAXINPUTLINE 100    /* Maximum input line length */
-
-and replace `100` with `512`, build and install.

doc/w11a_os_guide.md

@@ -106,7 +106,7 @@ All examples below use the same basic setup
 
      **Note**: the arty w11a has currently only 176 kB memory (all from BRAMS!)
      unix-v5 works fine. XXDP, RT11 and RSX-11M should work.
-     211bsd will not boot, either most RSX-11M+ systems.
+     211bsd will not boot, neither most RSX-11M+ systems.
 
   - for b3 over serial
 

tools/README.md

@@ -4,6 +4,7 @@ This directory tree contains **many tools** and is organized in
 | --------- | ------- |
 | [asm-11](asm-11) | environment for `asm-11` assembler |
 | [bin](bin)       | support scripts and tools |
+| [bin_xilinx_wrapper](bin_xilinx_wrapper) | wrappers for Xilinx environments |
 | [dox](dox)       | configuration files for Doxygen |
 | [fx2](fx2)       | firmware for Cypress FX2 USB interface |
 | [make](make)     | make includes |

tools/bin/xtwi

@@ -1,7 +1,7 @@
 #!/bin/bash
-# $Id: xtwi 830 2016-12-26 20:25:49Z mueller $
+# $Id: xtwi 862 2017-04-01 12:44:51Z mueller $
 #
-# Copyright 2013-2016 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
+# Copyright 2013-2017 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
 # License disclaimer see License.txt in $RETROBASE directory
 #
 # Xilinx Tool Wrapper script for ISE:
@@ -10,6 +10,7 @@
 #
 #  Revision History:
 # Date         Rev Version  Comment
+# 2017-04-01   862   1.2.1  add usr_local/bin and bin_xilinx_wrapper to PATH
 # 2016-08-28   804   1.2    BUGFIX: add ":." to PATH even under BARE_PATH
 # 2016-02-21   735   1.1    use BARE_PATH ect to provide clean environment
 # 2013-10-12   539   1.0    Initial version
@@ -34,11 +35,12 @@ then
   fi
 
   # provide clean environment when BARE_PATH ect defined
-  #   add only $RETROBASE/tools/bin and '.' to path
-  #   '.' is needed to start ISim tb's, which usually are in cwd
+  #   add prepend $HOME/usr_local/bin to path
+  #   add append $RETROBASE/tools/bin and '.' to path
+  #   '.' is needed to start tb's, which usually are in cwd
   if [ -n "$BARE_PATH" ]
   then
-    export PATH=$BARE_PATH:$RETROBASE/tools/bin:.
+    export PATH=$HOME/usr_local/bin:$BARE_PATH:$RETROBASE/tools/bin:.
     unset LD_LIBRARY_PATH
     if [ -n "$BARE_LD_LIBRARY_PATH" ]
     then
@@ -46,6 +48,9 @@ then
     fi 
   fi
 
+  # add bin_xilinx_wrapper to path (for firefox ect interceptors)
+  export PATH=$RETROBASE/tools/bin_xilinx_wrapper:$PATH
+
   # check whether 32 or 64 bit system (uname -m gives 'i686' or 'x86_64')
   if [ `uname -m` = "x86_64" ]
   then

tools/bin/xtwv

@@ -1,7 +1,7 @@
 #!/bin/bash
-# $Id: xtwv 830 2016-12-26 20:25:49Z mueller $
+# $Id: xtwv 862 2017-04-01 12:44:51Z mueller $
 #
-# Copyright 2013-2016 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
+# Copyright 2013-2017 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
 # License disclaimer see License.txt in $RETROBASE directory
 #
 # Xilinx Tool Wrapper script for Vivado
@@ -10,6 +10,7 @@
 #
 #  Revision History:
 # Date         Rev Version  Comment
+# 2017-04-01   862   1.1.1  add usr_local/bin and bin_xilinx_wrapper to PATH
 # 2016-02-21   735   1.1    use BARE_PATH ect to provide clean environment
 # 2014-04-18   554   1.0.1  fake XILINX_VIVADO, 2014.1 doesn't define it anymore
 # 2013-10-12   539   1.0    Initial version (cloned from xtwi)
@@ -33,10 +34,12 @@ then
   fi
 
   # provide clean environment when BARE_PATH ect defined
-  #   add only $RETROBASE/tools/bin to path
+  #   add prepend $HOME/usr_local/bin to path
+  #   add append $RETROBASE/tools/bin and '.' to path
+  #   '.' is needed to start tb's, which usually are in cwd
   if [ -n "$BARE_PATH" ]
   then
-    export PATH=$BARE_PATH:$RETROBASE/tools/bin
+    export PATH=$HOME/usr_local/bin:$BARE_PATH:$RETROBASE/tools/bin:.
     unset LD_LIBRARY_PATH
     if [ -n "$BARE_LD_LIBRARY_PATH" ]
     then
@@ -44,6 +47,9 @@ then
     fi 
   fi
 
+  # add bin_xilinx_wrapper to path (for firefox ect interceptors)
+  export PATH=$RETROBASE/tools/bin_xilinx_wrapper:$PATH
+  
   # check whether 32 or 64 bit system (uname -m gives 'i686' or 'x86_64')
   if [ `uname -m` = "x86_64" ]
   then

tools/bin_xilinx_wrapper/README.md

@@ -0,0 +1,13 @@
+This directory contains wrappers for general system tools called from within
+Xilinx IDE (ISE or Vivado). The wrappers reset the environment used inside the
+IDE to a very basic default environment with
+
+    unset LD_LIBRARY_PATH
+    export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+
+and finally execute the chosen tool via `exec` like
+
+    exec firefox "$@"
+
+This ensures that these tools work properly and don't fail due to conflicting
+library versions.

tools/bin_xilinx_wrapper/acroread

@@ -0,0 +1,9 @@
+#!/bin/bash
+#
+# wrapper for the acroread command used in Xilinx ISE/Vivado
+# it cleans up the environment, and redirects to ocular
+# following a suggestion of Clifford Wolf
+#
+unset LD_LIBRARY_PATH
+export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+exec okular "$@"

tools/bin_xilinx_wrapper/awk

@@ -0,0 +1,8 @@
+#!/bin/bash
+#
+# wrapper for the awk command used in Xilinx Vivado
+# it cleans up the environment
+#
+unset LD_LIBRARY_PATH
+export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+exec awk "$@"

tools/bin_xilinx_wrapper/firefox

@@ -0,0 +1,9 @@
+#!/bin/bash
+#
+# wrapper for the firefox command used in Xilinx ISE/Vivado
+# it cleans up the environment
+# following a suggestion of Clifford Wolf
+#
+unset LD_LIBRARY_PATH
+export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+exec firefox "$@"