1 |
36 |
wfjm |
# $Id: README_buildsystem_ISE.txt 779 2016-06-26 15:37:16Z mueller $
|
2 |
29 |
wfjm |
|
3 |
|
|
Guide to the Build System (Xilinx ISE Version)
|
4 |
|
|
|
5 |
|
|
Table of content:
|
6 |
|
|
|
7 |
|
|
1. Concept
|
8 |
|
|
2. Setup system environment
|
9 |
|
|
a. Setup environment variables
|
10 |
|
|
b. Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl
|
11 |
|
|
3. Building test benches
|
12 |
|
|
a. With ghdl
|
13 |
|
|
b. With ISE ISim
|
14 |
|
|
4. Building systems
|
15 |
|
|
5. Configuring FPGAs (via make flow)
|
16 |
|
|
6. Configuring FPGAs (directly via config_wrapper)
|
17 |
|
|
7. Note on Artix-7 based designs
|
18 |
|
|
|
19 |
|
|
1. Concept ----------------------------------------------------------------
|
20 |
|
|
|
21 |
|
|
This projects uses GNU make to
|
22 |
|
|
- generate bit files (synthesis with xst and place&route with par)
|
23 |
|
|
- generate test benches (with ghdl or Xilinx ISim)
|
24 |
|
|
- configure the FPGA (with Xilinx Impact or Linux jtag)
|
25 |
|
|
|
26 |
|
|
The Makefile's in general contain only a few definitions, all the make logic
|
27 |
|
|
is concentrated in a few master makefiles which are included.
|
28 |
|
|
|
29 |
|
|
Simulation and synthesis tools usually need a list of the VHDL source
|
30 |
|
|
files, often in proper compilation order (libraries before components).
|
31 |
|
|
The different tools have different formats of these 'project files'.
|
32 |
|
|
|
33 |
|
|
The build system employed in this project is based on manifest files called
|
34 |
|
|
'vbom' or "VHDL bill of material" files
|
35 |
|
|
which list for each vhdl source file the libraries and sources for the
|
36 |
|
|
instantiated components, the later via their vbom, and last but not least
|
37 |
|
|
the name of the vhdl source file.
|
38 |
|
|
All file name are relative to the current directory. A recursive traversal
|
39 |
|
|
through all vbom's gives for each vhld module all sources needed to compile
|
40 |
|
|
it. The vbomconv script in tools/bin does this, and generates depending on
|
41 |
|
|
options
|
42 |
|
|
- make dependency files
|
43 |
|
|
- ISE xst project files (synthesis)
|
44 |
|
|
- ISE ISim project files (simulation)
|
45 |
|
|
- ghdl commands for analysis, inspection and make step
|
46 |
|
|
|
47 |
|
|
The master make files contain pattern rules like
|
48 |
|
|
%.ngc : %.vbom -- synthesize with xst
|
49 |
|
|
% : %.vbom -- build functional model test bench
|
50 |
|
|
which encapsulate all the vbomconv magic
|
51 |
|
|
|
52 |
|
|
A full w11a system is build from about 100 source files, test benches
|
53 |
|
|
from even more. Using the vbom's a large number of designs can be easily
|
54 |
|
|
maintained.
|
55 |
|
|
|
56 |
|
|
For more details on vbomconv consult the man page.
|
57 |
|
|
|
58 |
|
|
2. Setup system environment -----------------------------------------------
|
59 |
|
|
|
60 |
|
|
2a. Setup environment variables --------------------------------------
|
61 |
|
|
|
62 |
|
|
The build flows require the environment variables:
|
63 |
|
|
|
64 |
|
|
- RETROBASE: must refer to the installation root directory
|
65 |
|
|
- XTWI_PATH: install path of the ISE version, without /ISE_DS/ !
|
66 |
|
|
- RETRO_FX2_VID and RETRO_FX2_PID: default USB VID/PID for Cypress FX2
|
67 |
|
|
|
68 |
|
|
For general instructions on environment see INSTALL.txt .
|
69 |
|
|
For details on RETRO_FX2_VID and RETRO_FX2_PID see INSTALL_fx2.txt.
|
70 |
|
|
|
71 |
|
|
Notes:
|
72 |
|
|
- The build system uses a small wrapper script called xtwi to encapsulate
|
73 |
|
|
the Xilinx environment. It uses XTWI_PATH to setup the ISE environment on
|
74 |
|
|
the fly. For details consult 'man xtwi'.
|
75 |
|
|
- don't run the ISE setup scripts ..../settings(32|64).sh in your working
|
76 |
|
|
shell. Setup only XTWI_PATH !
|
77 |
|
|
|
78 |
|
|
2b. Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl ---------------
|
79 |
|
|
|
80 |
|
|
A few entities use UNISIM or UNIMACRO primitives, and models derived after
|
81 |
|
|
the par step require also SIMPRIM primitives. In these cases ghdl has to
|
82 |
|
|
link against a compiled UNISIM, UNIMACRO or SIMPRIM libraries.
|
83 |
|
|
|
84 |
|
|
To make handling of the parallel installation of several ISE versions
|
85 |
|
|
easy the compiled libraries are stored in sub-directories under $XILINX:
|
86 |
|
|
|
87 |
|
|
$XILINX/ghdl/unisim
|
88 |
|
|
$XILINX/ghdl/unimacro
|
89 |
|
|
$XILINX/ghdl/simprim
|
90 |
|
|
|
91 |
|
|
Two helper scripts will create these libraries:
|
92 |
|
|
|
93 |
|
|
cd $RETROBASE
|
94 |
|
|
xise_ghdl_unisim # does UNISIM and UNIMACRO
|
95 |
|
|
xise_ghdl_simprim # does SIMPRIM
|
96 |
|
|
|
97 |
|
|
Run these scripts for each ISE version which is installed.
|
98 |
|
|
|
99 |
|
|
3. Building test benches --------------------------------------------------
|
100 |
|
|
|
101 |
|
|
The build flows support two simulators
|
102 |
|
|
- ghdl -> open source, with VHPI support, doesn't accept sdf files
|
103 |
|
|
- ISE ISim -> limited to 50k lines in WebPack, no VHPI support
|
104 |
|
|
|
105 |
|
|
3a. With ghdl --------------------------------------------------------
|
106 |
|
|
|
107 |
|
|
To compile a ghdl based test bench named all is needed is
|
108 |
|
|
|
109 |
|
|
make
|
110 |
|
|
|
111 |
|
|
The make file will use .vbom, create all make dependency files,
|
112 |
|
|
and generate the needed ghdl commands.
|
113 |
|
|
|
114 |
|
|
In many cases the test benches can also be compiled against the gate
|
115 |
|
|
level models derived after the xst, map or par step. To compile them
|
116 |
|
|
|
117 |
36 |
wfjm |
make _ssim # for post-xst (using UNISIM)
|
118 |
|
|
make _fsim # for post-map (using SIMPRIM)
|
119 |
|
|
make _tsim # for post-par (using SIMPRIM)
|
120 |
29 |
wfjm |
|
121 |
36 |
wfjm |
Individual working directories are used for the different models
|
122 |
|
|
ghdl.bsim for bahavioral model
|
123 |
|
|
ghdl.ssim for post-xst
|
124 |
|
|
ghdl.fsim for post-map
|
125 |
|
|
ghdl.tsim for post-par
|
126 |
|
|
and can co-exist. The 'make ghdl_tmp_clean' can be used to flush the ghdl
|
127 |
|
|
work areas, but in general this is not needed (since V0.73).
|
128 |
29 |
wfjm |
|
129 |
|
|
Notes:
|
130 |
|
|
- the post-xst simulation (_ssim targets) proved to be a valuable tool.
|
131 |
|
|
- ghdl fails to read sdf files generated by Xilinx tools, and thus does
|
132 |
|
|
not support a post-par simulation with full timing.
|
133 |
|
|
- post-par simulations without timing annotation often fail, most likely
|
134 |
|
|
due to clocking and delta cycle issues due to inserted clock buffers.
|
135 |
|
|
|
136 |
|
|
3b. With ISE ISim ----------------------------------------------------
|
137 |
|
|
|
138 |
|
|
To compile a ISE ISim based test bench named all is needed is
|
139 |
|
|
|
140 |
|
|
make _ISim
|
141 |
|
|
|
142 |
|
|
The make file will use .vbom, create all make dependency files,
|
143 |
|
|
and generate the needed ISE ISim project files and commands.
|
144 |
|
|
|
145 |
|
|
In many cases the test benches can also be compiled against the gate
|
146 |
|
|
level models derived after the xst, map or par step. To compile them
|
147 |
|
|
|
148 |
|
|
make ise_tmp_clean
|
149 |
|
|
make _ISim_ssim # for post-xst
|
150 |
|
|
make _ISim_fsim # for post-map
|
151 |
|
|
make _ISim_tsim # for post-par
|
152 |
|
|
|
153 |
|
|
Notes:
|
154 |
|
|
- ISim in ISE WebPack is limited to about 50k lines source code. That is
|
155 |
|
|
enough for many functional simulations, a w11a system has about 27k lines,
|
156 |
|
|
the test bench adds another 3k lines. But the limit gets quickly exceeded
|
157 |
|
|
with post-xst and especially post-par models. If the limit is exceeded, the
|
158 |
|
|
simulation engine throttles to snails speed.
|
159 |
|
|
- ISim does not support VHPI (interfacing of external C routines to VHDL).
|
160 |
|
|
Since VHPI is used in the rlink simulation all system test benches with
|
161 |
|
|
an rlink interface, thus most, will only run with ghdl and not with ISim.
|
162 |
|
|
|
163 |
|
|
4. Building systems -------------------------------------------------------
|
164 |
|
|
|
165 |
|
|
To generate a bit file for a system named all is needed is
|
166 |
|
|
|
167 |
|
|
make .bit
|
168 |
|
|
|
169 |
|
|
The make file will use .vbom, create all make dependency files, build
|
170 |
|
|
the ucf file with cpp, and run the synthesis flow (xst, ngdbuild, par, trce).
|
171 |
|
|
The log files will be conveniently renamed
|
172 |
|
|
|
173 |
|
|
_xst.log # xst log file
|
174 |
|
|
_tra.log # translate (ngdbuild) log file (renamed %.bld)
|
175 |
|
|
_map.log # map log file (renamed %_map.mrp)
|
176 |
|
|
_par.log # par log file (renamed %.par)
|
177 |
|
|
_pad.log # pad file (renamed %_pad.txt)
|
178 |
|
|
_twr.log # trce log file (renamed %.twr)
|
179 |
|
|
_tsi.log # trce tsi file (renamed %.tsi)
|
180 |
|
|
_bgn.log # bitgen log file (renamed %.bgn)
|
181 |
|
|
|
182 |
|
|
If only the xst or par output is wanted just use
|
183 |
|
|
|
184 |
|
|
make .ngc
|
185 |
|
|
make .ncd
|
186 |
|
|
|
187 |
|
|
Some tools require a .svf rather than a .bit file. It can be created with
|
188 |
|
|
|
189 |
|
|
make .svf
|
190 |
|
|
|
191 |
|
|
A simple 'message filter' system is also integrated into the make build flow.
|
192 |
|
|
For many (though not all) systems a .mfset file has been provided which
|
193 |
|
|
defines the xst,par and bitgen messages which are considered ok. To see
|
194 |
|
|
only the remaining message extracted from the various .log files simply
|
195 |
|
|
use the make target
|
196 |
|
|
|
197 |
|
|
make .mfsum
|
198 |
|
|
|
199 |
|
|
after a re-build.
|
200 |
|
|
|
201 |
|
|
5. Configuring FPGAs (via make flow) --------------------------------------
|
202 |
|
|
|
203 |
|
|
The make flow supports also loading the bitstream into FPGAs, either
|
204 |
|
|
via Xilinx Impact, or via the Cypress FX2 USB controller is available.
|
205 |
|
|
|
206 |
|
|
For Xilinx Impact a Xilinx USB Cable II has to be properly setup, than
|
207 |
|
|
simply use
|
208 |
|
|
|
209 |
|
|
make .iconfig
|
210 |
|
|
|
211 |
|
|
For using the Cypress FX2 USB controller on Digilent Nexys2, Nexys3 and
|
212 |
|
|
Atlys boards just connect the USB cable and
|
213 |
|
|
|
214 |
|
|
make .jconfig
|
215 |
|
|
|
216 |
|
|
This will automatically check and optionally re-load the FX2 firmware
|
217 |
|
|
to a version matching the FPGA design, generate a .svf file from the
|
218 |
|
|
.bit file, and configure the FPGA. In case the bit file is out-of-date
|
219 |
|
|
the whole design will be re-implemented before.
|
220 |
|
|
|
221 |
|
|
6. Configuring FPGAs (directly via config_wrapper) -------------------------
|
222 |
|
|
|
223 |
|
|
The make flow described above uses two scripts
|
224 |
|
|
config_wrapper # must be used with xtwi !
|
225 |
|
|
fx2load_wrapper
|
226 |
|
|
which can be used directly for loading available bit or svf files into
|
227 |
|
|
the FPGA. For detailed documentation see the respective man pages.
|
228 |
|
|
|
229 |
|
|
7. Note on Artix-7 based designs ------------------------------------------
|
230 |
|
|
|
231 |
|
|
The development for Nexys4 started with ISE, but has now fully moved to
|
232 |
|
|
Vivado. The make files for the ISE build flows have been kept for comparison
|
233 |
|
|
are have the name Makefile.ise. So for some Nexys4 designs and associated
|
234 |
|
|
one can still start with a
|
235 |
|
|
|
236 |
|
|
make -f Makefile.ise
|
237 |
|
|
|
238 |
|
|
an ISE based build. To be used for tool comparisons, the ISE generated bit
|
239 |
|
|
files were never tested in an FPGA.
|