Charles Fulks
Abstract
Script les automate the use of FPGA simulation and synthesis tools. Knowledge of the
tool set-up is captured; saving time during the development and maintenance phases of a
project. This paper presents practical TCL scripting techniques and examples suitable for
immediate use on FPGA projects.
This code herein is oered as is without any warranty either expressed or
implied; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE! User assumes all risk. In no event shall the authors or any
contributor to this code be liable for any damages or losses, including, but not limited to,
incidental, consequential, or any other damages, resulting from the use or misuse of any
information contained here.
Legal Notice:
Table of Contents
1 Introduction
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 Directory Structure
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
4 Simulation Script
5 Synthesis Script
6 Concluding Thoughts
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
Denition of Acronyms
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
References .
List of Figures
2.1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Source Listings
3.1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2
3.3
4.1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2
4.3
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4
4.5
4.6
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7
4.8
10
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Page 2 of 13
1 Introduction
In short, there is more to the story than the source code. A process provides a disciplined
and documented way to capture critical design artifacts. Running simulation and synthesis
steps in a script captures additional critical design artifacts.
The goal in writing Tool Control Language (TCL) scripts is to automate as many steps as possible. The
scripts are critical design artifacts that must be in the revision control system. The following paragraphs
describe some of the benets.
A synthesis script can set the multitude of behind the scenes switches
and buttons in the synthesis tool to ensure a design will simulate or synthesize independent of the host
computer .
The script necessarily has all simulation or synthesis steps. The script captures
knowledge of the set-up. This ensures that the engineer, now or several years from now, does not spend
2 debugging a nonexistent problem due to a missing le type of problem. This can signicantly ease
time
maintenance in months (or years) when you don't remember how to put the project together.
A script can automatically insert the host computer date and time into
the FPGA source to provide a consistent version register. This avoids the annoying question Which bit
stream is in the FPGA?.
Speed:
Running a script is generally much faster than entering (or clicking) commands. This saves a few
2 Directory Structure
You will generate many les; the tools generate many more. Keeping them well organized
is one key to productivity you eliminate the time spent repeatedly searching for les.
Figure 2.1 shows a directory structure to segregate les by project while combining similar, non-project
specic les. This is intended as a starting point for developing a directory tree that works for your specic
circumstances.
Tools such as Altera Quartus, Mentor Graphics ModelSim, and Xilinx ISE create many les that should be
segregated to their own directories. It may be advisable to add some of these les to your revision control
system. References that are not project specic should go in a directory at the same level as
Library.
Page 3 of 13
Projects
Another Project
This Project
Documentation
Scripts
Source
Test_Bench
Library
Communication
UART
Documentation
Math
Source
Memory
References
Figure 2.1: Multiple Project Directory structure
version
of the design is resident in the FPGA. When an engineer making a change to the design forgets to update
the
version
register, the resulting confusion may lead to several hours debugging a non-existent problem.
time_stamp.tcl.
with a check that the preexisting VHSIC Hardware Description Language (VHDL) package, ostensibly
If
time_stamp_pkg.vhd
then gets the system date and time and opens both les.
Listing 3.1: Time stamp: Set-up
#
#
#
#
#
File:
time_stamp.tcl
Engineer:
Charles Fulks
Company:
Intuitive Research and Technology
Description: This script modifies the VHDL constant SYNTHESIS_TIME_STAMP
in an an existing VHDL package with the current host system date and time.
constant SYNTHESIS_TIME_STAMP,
time_stamp_pkg.vhd,
then writes it to the temporary le. If the check for the string is true,
it writes the string with the encoded system date and time.
Listing 3.2: Time stamp: Search and replace
Page 5 of 13
}
The last section of code from
time_stamp.tcl, Listing 3.3, closes both les, checks that the preceding search
was successful, deletes the original le, and renames the temporary le to the original le name. The last
few lines form the
else
}
} else {
puts "\ ntime_stamp: Epic fail !!!\ n"
error " File: $DIR / $TIME_STAMP_FILE not writable !!! "
}
4 Simulation Script
A more eective way to learn TCL is to atter someone; that is, copy their script and
modify it for your purposes. The scripts included here are for this, more noble purpose.
Simulation requires more time up front, but the return on investment is excellent. The primary benet is
that you know the FPGA functionality is correct prior to lab integration. The functional simulation proves
that the design, described by the Hardware Description Language (HDL), meets the requirements. Verifying
functionality in hardware in the lab is very labor intensive. Because of the limited visibility into the FPGA,
it is very dicult to debug. During a simulation you have nearly unlimited visibility into the design. Finding
a design or coding error is much faster during simulation than during lab integration.[2]
The overall ow of the simulation script is as follows.
Page 6 of 13
A healthy sprinkling of
informative messages to the simulator command window can provide much needed
insight into the processes. Including the simulation script name separates script messages from test bench
messages and tool messages.
Listing 4.1 shows the le header.
The
engineer can copy line 13 and paste it into the simulation program to start the simulation.
Listing 4.1: Simulation script: Header
#
#
#
#
#
#
#
#
#
#
#
#
#
Company:
Engineer:
File Name:
Target Devices:
Tool versions:
Dependencies:
Description:
Revision:
The next section, shown in Listing 4.2, sets user variables to control the simulation, sets up directory paths,
and then clears the simulator command window.
Listing 4.2: Simulation script: Preamble
# User switches
set COMPILE_DESIGN
set COMPILE_TEST_BENCH
set SIMULATE
set RUN_TIME
yes
yes
yes
" 18 ms "
set TEST_BENCH_NAME
" debounce_tb "
set SIM_SCRIPT_NAME
" debounce_sim.tcl "
set SIM_DEFAULT_WAVE_NAME " debounce_default_wave.tcl "
set MODELSIM_WINDOW_NAME
set WAVE_WINDOW_NAME
# Where will we find
set DIR_PROJECT
set DIR_SCRIPTS
set DIR_PACKAGES
set DIR_SOURCE
set DIR_TESTBENCH
set DIR_COMP_LIBRARY
The next section, Listing 4.3, creates lists of the les in the project . Separating these lists into subsets such
3 Note
Page 7 of 13
as
For
instance, you may be working on the design and not wish to compile the test bench.
Listing 4.3: Simulation script: File lists
version
register.
vmap work
$DIR_LIBRARY / $LIB_NAME
foreach loop (Listing 4.6) to compile each le in the DESIGN_FILE_LIST and TEST_BENCH_FILE_LIST.
foreach loops; one for the
DESIGN_FILE_LIST and one for the TEST_BENCH_FILE_LIST. The addition of user switches in the preamble
Next we write a
For designs with a large number of les it may be advantageous to write two
could disable compilation of either the design or the test bench.
Listing 4.6: Simulation script: Compilation
if { $COMPILE == yes } {
puts " Compiling files to the $LIB_NAME library... "
foreach design [ concat $DESIGN_FILE_LIST $TEST_BENCH_FILE_LIST ] {
if {[ file isfile ${ DIR_PACKAGES }/ $design ]} {
puts " vcom -93 -lint -work $LIB_NAME ${ DIR_PACKAGES }/ ${ design }"
vcom
-93 -lint -work $LIB_NAME ${ DIR_PACKAGES }/ ${ design }
} elseif {[ file isfile ${ DIR_COMP_LIBRARY }/ $design ]} {
puts " vcom -93 -lint -work $LIB_NAME ${ DIR_COMPONENT_LIBRARY }/ ${ design }"
vcom
-93 -lint -work $LIB_NAME ${ DIR_COMPONENT_LIBRARY }/ $ { design }
} elseif {[ file isfile ${ DIR_SOURCE }/ $design ]} {
puts " vcom -93 -lint -work $LIB_NAME ${ DIR_SOURCE }/ $ { design }"
vcom
-93 -lint -work $LIB_NAME ${ DIR_SOURCE }/ $ { design }
} elseif {[ file isfile ${ DIR_TESTBENCH }/ $design ]} {
puts " vcom -93 -lint -work $LIB_NAME ${ DIR_TESTBENCH }/ ${ design }"
vcom
-93 -lint -work $LIB_NAME ${ DIR_TESTBENCH }/ ${ design }
} else {
puts " ********************************************************* "
puts " WARNING: DUT File $design not found "
puts " ********************************************************* "
return
}
}
puts "\ nCompilation complete !"
} else {
puts " Compilation disabled by user "
}
Listing 4.7 starts the simulation, displays signals in the waveform window, runs the simulation, and sets the
wave window zoom. Note that the script checks for a local copy of
wave.do.
ModelSim wave window setup le. If a local copy is not available, the script calls the default. The default
should be in the revision control system. The local
Page 9 of 13
} else {
puts [ format "\n% s: No local wave.do, running %s" $SIM_SCRIPT_NAME
$SIM_DEFAULT_WAVE_NAME ]
do $SIM_DEFAULT_WAVE_NAME
}
puts [ format "\n% s: Running simulation for % s... " $SIM_SCRIPT_NAME $RUN_TIME ]
run $RUN_TIME
# Name the waveform window
view -title $WAVE_WINDOW_NAME wave
if { $ZOOM == yes } {
WaveRestoreZoom $ZOOM_BEGIN $ZOOM_END
} else {
wave zoomfull
}
puts [ format "\n% s: Simulation complete. " $SIM_SCRIPT_NAME ]
} else {
puts [ format "\n% s: Simulation disabled by user " $SIM_SCRIPT_NAME ]
}
# Let the engineer know we ' re done
puts [ format "\n% s: Script complete. \ n" $SIM_SCRIPT_NAME ]
The
debounce_default_wave.tcl
le, Listing 4.8, sets up the waveform window with the relevant signals.
This saves time, but more importantly, this shows the future engineer what was interesting when it was
designed. It makes getting up to speed much quicker.
Listing 4.8: Simulation script: Simulation
# File:
debounce_default_wave.tcl
# Engineer: Charles Fulks
configure wave -namecolwidth 300
configure wave -valuecolwidth 100
# add signals to the wave window
add wave -divider " DUT "
add wave reset
add wave clock
add wave debounce_input
add wave -radix hex / debounce_tb / count
add wave -noupdate -format Analog-Step -height
add wave debounce_ce
add wave -group -expand { debouncer }
add wave -group { debouncer } dut / sample (1)
add wave -group { debouncer } dut / sample (2)
add wave -group { debouncer } dut / sample (3)
add wave -group -expand { output register clock
add wave -group { output register clock enable }
add wave -group { output register clock enable }
add wave -group { output register clock enable }
add wave -divider " debounce output "
add wave -color yellow debounce_output
enable }
-color yellow spy_all_high
dut / all_high
dut / all_low
Page 10 of 13
5 Synthesis Script
Running synthesis tools from scripts helps ensure no missed steps or settings.
Keeping
the synthesis script in the version control system greatly assists future maintenance and
modication tasks.
There are many buttons and knobs that control the synthesis
When certain synthesis software property settings are required for successful synthesis, we can
develop the It only synthesizes on John's PC. category of problem. One way to avoid this is to generate a
synthesis script with all necessary settings and steps; including time stamp register updating.
Most FPGA tools can be run from the command line. Several tools will generate a TCL script that captures
all current settings. Consider the many settings in tools as complex as Altera Quartus II, Xilinx ISE, Lattice
Diamond, and Microsemi Libero. These settings may not be easily recoverable.
Generating a synthesis TCL script usually requires two steps. The rst is to have the tool auto-generate
the script. The second is to modify the script with time stamp calls, etc. An Internet search on xilinx
ise
generate tcl script produces many results. At http://www.xilinx.com/support/documentation/sw_
manuals/xilinx13_1/ise_p_generate_tcl_script.htm
Select
including explicit
only those process properties in your project that have been modied from their default
values.
The properties listed are only those you have modied from their default
values. This is useful to generate a script that can be used to easily set process properties
in other projects to values you desire.
6 Concluding Thoughts
The source code only partially describes an FPGA design.
synthesis steps from a script captures many additional critical design artifacts. Furthermore,
scripts ease future maintenance and modication eorts.
Page 11 of 13
This paper described some of the benets of TCL scripting FPGA simulation and synthesis steps.
We
provided examples to help design organizations develop their process and to help groups with establshed
processes improve.
The author activly solicts constructive comments and brief discussions at
fpga@irtc-hq.com.
Page 12 of 13
Denition of Acronyms
FPGA
HDL
TCL
VHDL
References
[1]
[2]
[3]
Doulos.
Automating_Tool_Flows_with_Tcl/quartus.php.
2012.
Best FPGA Development Practices. Design West 2012 Class ESC-405. 2012.
Xilinx. PlanAhead Tcl Command Reference Guide. Xilinx UG789. 2012.
Page 13 of 13