mirror of
https://github.com/wfjm/w11.git
synced 2026-01-20 02:14:25 +00:00
247 lines
9.5 KiB
Markdown
247 lines
9.5 KiB
Markdown
## Guide to the Build System (Xilinx ISE Version)
|
|
|
|
### Table of content
|
|
|
|
- [Concept](#user-content-concept)
|
|
- [Setup system environment](#user-content-sysenv)
|
|
- [Setup environment variables](#user-content-envvar)
|
|
- [Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl](#user-content-ghdllibs)
|
|
- [Building test benches](#user-content-buildtb)
|
|
- [With ghdl](#user-content-buildtb-ghdl)
|
|
- [With ISE ISim](#user-content-buildtb-isim)
|
|
- [Building FPGA bit files](#user-content-buildfpga)
|
|
- [Configuring FPGAs (via make flow)](#user-content-config-make)
|
|
- [Configuring FPGAs (directly via config_wrapper)](#user-content-config-wrap)
|
|
- [Note on Artix-7 based designs](#user-content-artix)
|
|
|
|
### <a id="concept">Concept</a>
|
|
|
|
This projects uses GNU make to
|
|
- generate bit files (synthesis with xst and place&route with par)
|
|
- generate test benches (with ghdl or Xilinx ISim)
|
|
- configure the FPGA (with Xilinx Impact or Linux jtag)
|
|
|
|
The Makefile's in general contain only a few definitions, all the make logic
|
|
is concentrated in a few master makefiles which are included.
|
|
|
|
Simulation and synthesis tools usually need a list of the VHDL source
|
|
files, often in proper compilation order (libraries before components).
|
|
The different tools have different formats of these 'project files'.
|
|
|
|
The build system employed in this project is based on manifest files called
|
|
|
|
'vbom' or "VHDL bill of material" files
|
|
|
|
which list for each vhdl source file the libraries and sources for the
|
|
instantiated components, the later via their vbom, and last but not least
|
|
the name of the vhdl source file.
|
|
|
|
All file name are relative to the current directory. A recursive traversal
|
|
through all vbom's gives for each vhld module all sources needed to compile
|
|
it. The vbomconv script in tools/bin does this, and generates depending on
|
|
options
|
|
- make dependency files
|
|
- ISE xst project files (synthesis)
|
|
- ISE ISim project files (simulation)
|
|
- ghdl commands for analysis, inspection and make step
|
|
|
|
The master make files contain pattern rules like
|
|
|
|
%.ngc : %.vbom -- synthesize with xst
|
|
% : %.vbom -- build functional model test bench
|
|
|
|
which encapsulate all the vbomconv magic
|
|
|
|
A full w11a system is build from about 100 source files, test benches
|
|
from even more. Using the vbom's a large number of designs can be easily
|
|
maintained.
|
|
|
|
For more details on vbomconv consult the man page.
|
|
|
|
### <a id="sysenv">Setup system environment</a>
|
|
|
|
#### <a id="envvar">Setup environment variables</a>
|
|
|
|
The build flows require the environment variables:
|
|
- `RETROBASE`: must refer to the installation root directory
|
|
- `XTWI_PATH`: install path of the ISE version, without `/ISE_DS/` !
|
|
- `RETRO_FX2_VID` and `RETRO_FX2_PID`: default USB VID/PID for Cypress FX2
|
|
|
|
For general instructions on environment see [INSTALL.md](INSTALL.md) .
|
|
For details on `RETRO_FX2_VID` and `RETRO_FX2_PID` see
|
|
[INSTALL_fx2_support.md](INSTALL_fx2_support.md).
|
|
|
|
Notes:
|
|
- The build system uses a small wrapper script called `xtwi` to encapsulate
|
|
the Xilinx environment. It uses `XTWI_PATH` to setup the ISE environment on
|
|
the fly. For details consult 'man xtwi'.
|
|
- don't run the ISE setup scripts ..../settings(32|64).sh in your working
|
|
shell. Setup only `XTWI_PATH` !
|
|
|
|
#### <a id="ghdllibs">Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl</a>
|
|
|
|
A few entities use `UNISIM` or `UNIMACRO` primitives, and models derived after
|
|
the par step require also `SIMPRIM` primitives. In these cases ghdl has to
|
|
link against a compiled `UNISIM`, `UNIMACRO` or `SIMPRIM` libraries.
|
|
|
|
To make handling of the parallel installation of several ISE versions
|
|
easy the compiled libraries are stored in sub-directories under `$XILINX`:
|
|
|
|
$XILINX/ghdl/unisim
|
|
$XILINX/ghdl/unimacro
|
|
$XILINX/ghdl/simprim
|
|
|
|
Two helper scripts will create these libraries:
|
|
|
|
cd $RETROBASE
|
|
xise_ghdl_unisim # does UNISIM and UNIMACRO
|
|
xise_ghdl_simprim # does SIMPRIM
|
|
|
|
Run these scripts for each ISE version which is installed.
|
|
|
|
### <a id="buildtb">Building test benches</a>
|
|
|
|
The build flows support two simulators
|
|
- ghdl -> open source, with VHPI support, doesn't accept sdf files
|
|
- ISE ISim -> limited to 50k lines in WebPack, no VHPI support
|
|
|
|
#### <a id="buildtb-ghdl">With ghdl</a>
|
|
|
|
To compile a ghdl based test bench named `<tbench>` all is needed is
|
|
|
|
make <tbench>
|
|
|
|
The make file will use `<tbench>.vbom`, create all make dependency files,
|
|
and generate the needed ghdl commands.
|
|
|
|
In many cases the test benches can also be compiled against the gate
|
|
level models derived after the `xst`, `map` or `par` step. To compile them
|
|
|
|
make <tbench>_ssim # for post-xst (using UNISIM)
|
|
make <tbench>_fsim # for post-map (using SIMPRIM)
|
|
make <tbench>_tsim # for post-par (using SIMPRIM)
|
|
|
|
Individual working directories are used for the different models
|
|
|
|
ghdl.bsim for bahavioral model
|
|
ghdl.ssim for post-xst
|
|
ghdl.fsim for post-map
|
|
ghdl.tsim for post-par
|
|
|
|
and can co-exist. The `make ghdl_tmp_clean` can be used to flush the ghdl
|
|
work areas, but in general this is not needed (since V0.73).
|
|
|
|
Notes:
|
|
- the post-xst simulation (_ssim targets) proved to be a valuable tool.
|
|
- ghdl fails to read sdf files generated by Xilinx tools, and thus does
|
|
not support a post-par simulation with full timing.
|
|
- post-par simulations without timing annotation often fail, most likely
|
|
due to clocking and delta cycle issues due to inserted clock buffers.
|
|
|
|
#### <a id="buildtb-isim">With ISE ISim</a>
|
|
|
|
To compile a ISE ISim based test bench named `<tbench>` all is needed is
|
|
|
|
make <tbench>_ISim
|
|
|
|
The make file will use `<tbench>.vbom`, create all make dependency files,
|
|
and generate the needed ISE ISim project files and commands.
|
|
|
|
In many cases the test benches can also be compiled against the gate
|
|
level models derived after the xst, map or par step. To compile them
|
|
|
|
make ise_tmp_clean
|
|
make <tbench>_ISim_ssim # for post-xst
|
|
make <tbench>_ISim_fsim # for post-map
|
|
make <tbench>_ISim_tsim # for post-par
|
|
|
|
Notes:
|
|
- ISim in ISE WebPack is limited to about 50k lines source code. That is
|
|
enough for many functional simulations, a w11a system has about 27k lines,
|
|
the test bench adds another 3k lines. But the limit gets quickly exceeded
|
|
with post-xst and especially post-par models. If the limit is exceeded, the
|
|
simulation engine throttles to snails speed.
|
|
- ISim does not support VHPI (interfacing of external C routines to VHDL).
|
|
Since VHPI is used in the rlink simulation all system test benches with
|
|
an rlink interface, thus most, will only run with ghdl and not with ISim.
|
|
|
|
### <a id="buildfpga">Building FPGA bit files</a>
|
|
|
|
To generate a bit file for a system named `<sys>` all is needed is
|
|
|
|
make <sys>.bit
|
|
|
|
The make file will use `<sys>.vbom`, create all make dependency files, build
|
|
the ucf file with cpp, and run the synthesis flow (`xst`, `ngdbuild`, `par`,
|
|
`trce`). The log files will be conveniently renamed
|
|
|
|
<sys>_xst.log # xst log file
|
|
<sys>_tra.log # translate (ngdbuild) log file (renamed %.bld)
|
|
<sys>_map.log # map log file (renamed %_map.mrp)
|
|
<sys>_par.log # par log file (renamed %.par)
|
|
<sys>_pad.log # pad file (renamed %_pad.txt)
|
|
<sys>_twr.log # trce log file (renamed %.twr)
|
|
<sys>_tsi.log # trce tsi file (renamed %.tsi)
|
|
<sys>_bgn.log # bitgen log file (renamed %.bgn)
|
|
|
|
If only the xst or par output is wanted just use
|
|
|
|
make <sys>.ngc
|
|
make <sys>.ncd
|
|
|
|
Some tools require a `.svf` rather than a `.bit` file. It can be created with
|
|
|
|
make <sys>.svf
|
|
|
|
A simple 'message filter' system is also integrated into the make build flow.
|
|
For many (though not all) systems a `.mfset` file has been provided which
|
|
defines the `xst`, `par` and `bitgen` messages which are considered ok. To see
|
|
only the remaining message extracted from the various `.log` files simply
|
|
use the make target
|
|
|
|
make <sys>.mfsum
|
|
|
|
after a re-build.
|
|
|
|
### <a id="config-make">Configuring FPGAs (via make flow)</a>
|
|
|
|
The make flow supports also loading the bitstream into FPGAs, either
|
|
via Xilinx Impact, or via the Cypress FX2 USB controller is available.
|
|
|
|
For Xilinx Impact a Xilinx USB Cable II has to be properly setup, than
|
|
simply use
|
|
|
|
make <sys>.iconfig
|
|
|
|
For using the Cypress FX2 USB controller on Digilent Nexys2, Nexys3 and
|
|
Atlys boards just connect the USB cable and
|
|
|
|
make <sys>.jconfig
|
|
|
|
This will automatically check and optionally re-load the FX2 firmware
|
|
to a version matching the FPGA design, generate a .svf file from the
|
|
.bit file, and configure the FPGA. In case the bit file is out-of-date
|
|
the whole design will be re-implemented before.
|
|
|
|
### <a id="config-wrap">Configuring FPGAs (directly via `config_wrapper`)</a>
|
|
|
|
The make flow described above uses two scripts
|
|
|
|
config_wrapper # must be used with xtwi !
|
|
fx2load_wrapper
|
|
|
|
which can be used directly for loading available bit or svf files into
|
|
the FPGA. For detailed documentation see the respective man pages.
|
|
|
|
### <a id="artix">Note on Artix-7 based designs</a>
|
|
|
|
The development for Nexys4 started with ISE, but has now fully moved to
|
|
Vivado. The make files for the ISE build flows have been kept for comparison
|
|
are have the name `Makefile.ise`. So for some Nexys4 designs and associated
|
|
one can still start with a
|
|
|
|
make -f Makefile.ise <target>
|
|
|
|
an ISE based build. To be used for tool comparisons, the ISE generated bit
|
|
files were never tested in an FPGA.
|