Guide to install and build w11a systems, test benches and support software
Table of content
- System requirements
- Setup environment variables
- Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl
- Compile and install the support software
- The build system
- Available designs
- Available bitkits with bit and log files
- Configure FPGA
- Generate Doxygen based source code view
All instructions below assume that the project files reside in a
working directory with the name represented as
to download the repository
git clone https://github.com/wfjm/w11
use the latest snapshop under
cd <install-dir> git checkout master
to use tagged verions list available tags
cd <install-dir> git tag -l
and select one of them
cd <install-dir> git checkout tags/<tag>
The GitHub repository contains the full version history since 2010. Prior to October 2016 the project was maintained on OpenCores, access to the legacy svn repository is described in INSTALL_from_opencores.md.
This project contains not only VHDL code but also support software. Therefore quite a few software packages are expected to be installed. The following list gives the Ubuntu/Debian package names, but mapping this to other distributions should be straight forward.
building the FPGA bit files requires the Xilinx design tools
- Vivado WebPACK (for Series-7 based designs)
- ISE WebPACK (for Spartan-3 and Spartan-6 based designs)
building and using the rlink backend software requires:
- full C/C++ development chain (gcc,g++,cpp,make)
- Boost C++ library (>= 1.40), with date-time, thread, and regex
- libusb 1.0 (>= 1.0.6)
- Perl (>= 5.10) (usually included in base installations)
- Tcl (>= 8.6), with tclreadline support
- full C/C++ development chain (gcc,g++,cpp,make)
for VHDL simulations one needs
-> see INSTALL_ghdl.md for the unfortunately gory details
additional requirements for using Cypress FX (on Nexys2/3) see INSTALL_fx2_support.md.
for doxygen documentation an up-to-date installation of doxygen is required, version 184.108.40.206 or later
The make flows for building test benches (ghdl, Vivado xsim or ISE ISim based) and FPGA bit files (with Vivado or ISE) as well as the support software (mainly the rlink backend server) requires the definition of the environment variables:
||must refer to the installation root directory|
||the tools binary directory
|current working directory
||the tools library directory
||the tools man page directory
||pathname for includes of Tcl runtime library|
||name of Tcl runtime library|
||default USB VID, see below|
||default USB PID, see below|
||pathname for libraries of Tcl (optional)|
||pathname for includes of boost library (optional)|
||pathname for libraries of boost library (optional,
For bash and alike use
export RETROBASE=<install-dir> export PATH=$PATH:$RETROBASE/tools/bin:. export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$RETROBASE/tools/lib export MANPATH=$MANPATH:$RETROBASE/tools/man
In most cases the boost library version coming with the distribution will work, similar for Tcl, in those cases simply use
export TCLINC=/usr/include/tcl8.6 export TCLLIBNAME=tcl8.6
and don't setup
After that building functional model based test benches will work. If you want to also build post-synthesis or post-place&route test benches read next section.
For Cypress FX2 (on Nexys2/3) related setup see INSTALL_fx2_support.md.
The build system for test benches also supports test benches run against the
gate level models derived after synthesis or place&route. In this case ghdl
has to link against a compiled a
The details are described in
c++11 features are used in the code
|Feature||Description||in gcc since|
|N2343||decltype (used by boost bind)||gcc 4.3|
|N2930||range based for||gcc 4.6|
|N1984||auto-types variables||gcc 4.4|
Required tools and libraries:
g++ >= 4.6 (see c++11 usage above) boost >= 1.35 (boost::thread api changed, new one is used) linusb >= 1.0.5 (timerfd support)
Build was tested under:
ubuntu xenial (16.04 LTS): gcc 5.4.0 boost 1.58 libusb 1.0.20 ubuntu trusty (14.04 LTS): gcc 4.8.2 boost 1.54 libusb 1.0.17 debian wheezy (7.0.8): gcc 4.7.2 boost 1.49 libusb 1.0.11
To build all sharable libraries
cd $RETROBASE/tools/src make -j 4
Default is to compile with
-O2 and without
-g. These options can be
overwritten with the
CXXOPTFLAGS enviromnent variable (or make opion).
To build with
-O3 optimize use
make -j 4 CXXOPTFLAGS=-O3
To build a debug version with full symbol table use
make -j 4 CXXOPTFLAGS=-g
To cleanup, e.g. before a re-build
cd $RETROBASE/tools/src rm_dep make realclean
The Tcl files are organized in several packages. To create the Tcl
package files (
cd $RETROBASE/tools/tcl setup_packages
To use these packages it is convenient to make them available via the
'auto_path' mechanism. To do that add in your
lappend auto_path [file join $env(RETROBASE) tools tcl] lappend auto_path [file join $env(RETROBASE) tools lib]
The w11 project contains two ready to use
- include the auto_path statements above
tclreadline(and thus in
tclshrcan event loop)
To use them simply copy them into your home directory (or soft link them)
cd $HOME ln -s $RETROBASE/tools/tcl/.tclshrc . ln -s $RETROBASE/tools/tcl/.wishrc .
The generation of FPGA firmware and test benches is based on make flows.
All details on
- building test benches
- building FPGA bit files
- configuring FPGAs
can be found under
- README_buildsystem_Vivado.md for Artix-7 based designs
- README_buildsystem_ISE.md for Spartan-3 and Spartan-6 based designs
Ready to build designs are organized in the directories
$RETROBASE/rtl/sys_gen/<design>/<board> with <design> w11a w11a system tst_rlink rlink over serial link tester tst_rlink_cuff rlink over FX2 interface tester and <board> cmoda7 c7: Digilent Cmod A7 board arty arty: Digilent Arty A7-35 board basys3 b3: Digilent Basys3 board nexys4d n4d: Digilent Nexys4 board (DDR RAM version) nexys4 n4: Digilent Nexys4 board (cellular RAM version) nexys3 n3: Digilent Nexys3 board nexys2 n2: Digilent Nexys2 board (-1200 FPGA version) s3board s3: Digilent S3board (-1000 FPGA version) for w11a designs which only use BRAM as memory are provided arty_bram br_arty: Digilent Arty A7-35 board nexys4d_bram br_n4d: Digilent Nexys4 board (DDR RAM version)
To build the designs locally use
cd $RETROBASE/rtl/sys_gen/<design>/<board> make sys_<dtype>_<btype>.bit
with in most cases
<btype>= abbreviation for the board, e.g. n4 for nexys4.
Tarballs with ready to use bit files and all logfiles from the tool chain can be downloaded from http://www.retro11.de/data/oc_w11/bitkits/ .
This area is organized in folders for different releases. The tarball file names contain information about release, Xlinix tool, and design:
Vivado based designs: These designs can be loaded with the Vivado hardware server into the FPGA.
ISE based designs: These designs can be loaded with
config_wrapperinto the FPGA. The procedures for the supported boards are given below.
RETROBASEenvironment variables must be defined.
config_wrapper bit2svfis only needed once to create the svf files.
fx2load_wrapperis needed once after each board power on.
for Digilent Nexys3 board (using Cypress FX2 USB controller)
xtwi config_wrapper --board=nexys3 bit2svf <design>.bit fx2load_wrapper --board=nexys3 xtwi config_wrapper --board=nexys3 jconfig <design>.svf
for Digilent Nexys2 board (using Cypress FX2 USB controller)
xtwi config_wrapper --board=nexys2 bit2svf <design>.bit fx2load_wrapper --board=nexys2 xtwi config_wrapper --board=nexys2 jconfig <design>.svf
for Digilent S3board (using ISE Impact)
xtwi config_wrapper --board=s3board iconfig <design>.bit
Currently there is not much real documentation included in the source files. The doxygen generated html output is nevertheless very useful to browse the code. C++, Tcl and Vhdl source are covered by setup files contained in the project files.
To generate the html files
cd $RETROBASE/tools/dox export RETRODOXY <desired root of html documentation> ./make_doxy
RETRODOXY is not defined
/tmp is used. To view the docs use
firefox $RETRODOXY/w11/cpp/html/index.html & firefox $RETRODOXY/w11/tcl/html/index.html & firefox $RETRODOXY/w11/vhd/html/index.html &