github.com/wfjm.w11
1
0
Fork 0
mirror of https://github.com/wfjm/w11.git synced 2026-01-13 15:37:43 +00:00
Code Issues Releases Wiki Activity
wfjm.w11/doc/INSTALL.md
wfjm 279a5e0fd2 cleanup setup spelling [skip ci]
2022-08-20 08:37:33 +02:00

296 lines
11 KiB
Markdown
Raw Blame History

# Guide to install and build w11a systems, test benches and support software
### Table of content
- [Download](#user-content-download)
- [System requirements](#user-content-sysreq)
- [Set up environment variables](#user-content-envvar)
- [Compile UNISIM/UNIMACRO/SIMPRIM libraries for GHDL](#user-content-ghdl-lib)
- [Compile and install the support software](#user-content-build-tools)
- [Compile sharable libraries](#user-content-build-cpp)
- [Set up Tcl packages](#user-content-build-tcl)
- [The build system](#user-content-build-system)
- [Available designs](#user-content-build-fpga)
- [Available bitkits with bit and log files](#user-content-bitkits)
- [Configure FPGA](#user-content-fpgaconf)
- [Generate doxygen based source code view](#user-content-build-doxy)
### <a id="download">Download</a>
All instructions below assume that the project files reside in a
working directory with the name represented as `<install-dir>`
- to download the repository
git clone https://github.com/wfjm/w11
- use the latest snapshop under `master`
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](http://opencores.org) as project
[w11](http://opencores.org/project,w11). In October 2016 the repository was
[moved from OpenCores to GitHub](https://wfjm.github.io/blogs/w11/2016-12-11-w11-moved-to-github.html) including all revision history.
### <a id="sysreq">System requirements</a>
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 straightforward.
- 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)
-> package: `build-essential`
- libusb 1.0 (>= 1.0.6)
-> package: `libusb-1.0-0-dev`
- Perl (>= 5.10) (usually included in base installations)
- Tcl (>= 8.6), with tclreadline support
-> package: `tcl` `tcl-dev` `tcllib` `tclreadline`
- for VHDL simulations one needs
- GHDL
-> see [INSTALL_ghdl.md](INSTALL_ghdl.md) for the unfortunately gory details
- GTKWave
-> package: `gtkwave`
- for cross-verification the SimH simulator is used.
See [INSTALL_simh.md](INSTALL_simh.md) for the unfortunately gory details.
- additional requirements for using Cypress FX (on Nexys2/3) see
[INSTALL_fx2_support.md](INSTALL_fx2_support.md).
- for doxygen documentation an up-to-date installation of doxygen is
required, version 1.8.3.1 or later.
### <a id="envvar">Set up environment variables</a>
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:
| Variable | Comment |
| :------- | :------ |
| `RETROBASE` | must refer to the installation root directory |
| `PATH` | the tools binary directory `$RETROBASE/tools/bin` must be in the path |
| | current working directory `.` must be in the path (expected e.g. by `TBW`) |
| `LD_LIBRARY_PATH` | the tools library directory `$RETROBASE/tools/lib` must be in the library path |
| `MANPATH` | the tools man page directory `$RETROBASE/tools/man` should be in the man path |
| `TCLINC` | pathname for includes of Tcl runtime library |
| `TCLLIBNAME` | name of Tcl runtime library |
| `RETRO_FX2_VID` | default USB VID, see below |
| `RETRO_FX2_PID` | default USB PID, see below |
| `TCLLIB` | pathname for libraries of Tcl _(optional)_ |
| `BOOSTINC` | pathname for includes of boost library _(optional)_ |
| `BOOSTLIB` | pathname for libraries of boost library _(optional, `BOOSTINC` and `BOOSTLIB` must be either both defined or both undefined)_ |
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
Boost was essential in the pre-c++11 times but has been completely replaced
by `std::` classes provided by c++11. In most cases the Tcl version coming with
the distribution will work, in those cases simply use
export TCLINC=/usr/include/tcl8.6
export TCLLIBNAME=tcl8.6
and don't set up `BOOSTINC` and `BOOSTLIB`.
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 the next section.
For Cypress FX2 (on Nexys2/3) related setup see
[INSTALL_fx2_support.md](INSTALL_fx2_support.md).
### <a id="ghdl-lib">Compile UNISIM/UNIMACRO/SIMPRIM libraries for GHDL</a>
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 `UNISIM`, `UNIMACRO` or `SIMPRIM` library.
The details are described in
- [README_buildsystem_Vivado.md](README_buildsystem_Vivado.md#user-content-ghdllibs)
- [README_buildsystem_ISE.md](README_buildsystem_ISE.md#user-content-ghdllibs)
### <a id="build-tools">Compile and install the support software</a>
#### <a id="build-cpp">Compile sharable libraries</a>
The backend codebase uses many `c++11` language features, e.g.
`nullptr`, `auto`, lambda functions, list initialization, range-based `for`,
to name the most prominent. Recently some `c++17` language features are
used as well.
A C++ compiler with full `c++17` support is therefore needed, so either
`gcc 7.3` or `clang 7`. Current experience is:
- gcc 9.3.0 and clang 10, as in Ubuntu 20.04 LTS, _will work !!_
- gcc 8.3.0 and clang 7, as in Debian 10, _should work !!_
Required tools and libraries:
g++ >= 7.3 (see c++17 usage above)
libusb >= 1.0.5 (timerfd support)
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` environment variable (or make option).
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
#### <a id="build-tcl">Set up Tcl environment</a>
The Tcl files are organized in several packages. To create the Tcl
package files (`pkgIndex.tcl`)
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 `.tclshrc` or `.wishrc`
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 `.tclshrc` or `.wishrc`
files which
- include the auto_path statements above
- activate `tclreadline` (and thus in `tclshrc` an 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 .
### <a id="build-system">The build system</a>
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](README_buildsystem_Vivado.md)
for Artix-7 based designs
- [README_buildsystem_ISE.md](README_buildsystem_ISE.md)
for Spartan-3 and Spartan-6 based designs
### <a id="build-fpga">Available designs</a>
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
- `<dtype>` = `<design>`
- `<btype>` = abbreviation for the board, e.g. n4 for nexys4.
### <a id="bitkits">Available bitkits with bit and log files</a>
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:
<release>_<tool>_<design>.tgz
### <a id="fpgaconf">Configure FPGA</a>
- 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_wrapper` into the FPGA. The
procedures for the supported boards are given below.
Notes:
1. `XTWI_PATH` and `RETROBASE` environment variables must be defined.
2. `config_wrapper bit2svf` is only needed once to create the svf files.
3. `fx2load_wrapper` is 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
### <a id="build-doxy">Generate Doxygen based source code view</a>
Currently there is not much real documentation included in the source
files. The doxygen generated html output is nevertheless very useful
to browse and navigate the source code. For details see
[README.md](../tools/dox/README.md) in directory `tools/dox`.
Reference in New Issue View Git Blame Copy Permalink