Xilinx ISE - Vivado and Tcl

Xilinx ISE and the new Vivado are one of the many EDA tools that can (and should, for advanced users) be controlled using Tcl.

Why should you use Tcl to control your design flow?



  • You can write scripts to replay established portions of your design flow to standardize the process. There is a constant danger if repeatability depends on remembering to click on the correct boxes and menus in the user interface. If you create a script that you can run many times, you will guarantee that you are issuing the same commands to the tool each time you invoke it.
  • In a project you typically perform the same actions thousands of times. At the same time you might want to explore different combination of options for your synthesis and simulation steps. Sometimes you just simply change the main directory of your project or you want to start a new projects with the same setting of an old one. That could be cumbersome if done with a GUI, time consuming and error prone. Automating all those steps with a script is really invaluable for real designers. 

There are two ways of running a script:



  • Within the GUI there is a Tcl console, in which you can source (i.e. call/run) a script. If you can't find the console on ISE go to View-> Panels -> Tcl Console
  • You can source the script in a DOS or Linux shell typing "xtclsh scriptname" and avoid the overhead of a graphical interface completely.

With all this in mind, we want to explore the ways in which we can command ISE or Vivado from a Tcl script. We will synthesise a simple design using XSTand implement it in a Kintex7 device.

Tcl scripting (and .do files which are nothing more than Tcl plus bultin commands) are invaluable also to automate simulation processes, we cover this topic in another section of our free technical resources section.
 

Input files
 

The first thing which should be done is to tell the tool which source files will be used. We want to do this in a maintainable way, and to this end all filenames are given at the top of the script.
We set a Tcl list to contain the source filenames we require:

 

# set output directory
set compile_directory output_dir
# set the top-level of our HDL sources:
set top_name counter
# input source files list:
set hdl_files [ list \
  ../counter.vhd \
  ../campera_util_pkg.vhd \
  ...Other files... \
]
# set constraints with pin placements. Note the relative path
set constraints_file ../constraints/counter.ucf

 

A # denotes a comment; a comment in Tcl is terminated by a newline and is ignored by the parser. Please note that as other Tcl behaviour means a hash character will not always be interpreted as the beginning of a comment. As a rule try to use the # character as the first character, each comment line appears on a separate line where # is the first character on that line.
Don't include mismatched round or square brackets and don't use curly brackets at all in comment lines.

The set command is used to apply a value to a variable:
 

set variable_name value
 

In the setting of the variable "hdl_files" we used the list command to create a Tcl list from the text strings that follow it. As a simpler alternative, we could have used braces to enclose a set of strings:
 

set hdl_files {
  ../counter.vhd
  ../
campera_util_pkg.vhd
  ...Other files...
}

 

This approach has some drawbacks, especially when the list items have spaces or special characters. It's generally best to construct the list using the list command. This also allows you to use lappend and lindex commands to manipulate the list.

Setting a Compilation Directory

We now need to set the output directory where our processed files will be saved. We can use the file command and its sub-command mkdir to create a directory:
 

if {![file isdirectory $compile_directory]} {
  file mkdir $compile_directory
}

 

This code checks if the directory exists; if not, it is created with the command mkdir. The $ character in front of a variable name gives you the content of that variable.
 

Project Creation and Settings
 

Assuming no ISE project exists in this directory we can make our own. Xilinx provides the project command (for ISE), which includes sub-commands for the project settings and other related tasks. 
 

project new $counter_proj.ise
project set family Kintex7
project set device XC7K70T
project set package FBG484
project set speed -3

 

Within Tcl it is easy to add new commands by writing your own procedures. This is outside of the scope of this brief discussion but is fully covered  in our Tcl courses.

Now we need to add our source files to the project we just created. Xilinx provide a Tcl command for this, the xfile command. It is used to add or remove files and to get information on any source files in the current ISE project.

We need to add some files, and we already have a list of source files (which is useful for maintenance also). THis can be easily obtained with the foreach Tcl statement on the source files list.
 

foreach filename $hdl_files {
  xfile add $filename
  puts "Adding file $filename to the project."
}

 

The puts command is a simple way to write to STDOUT (which is usually the console/shell).

Note: don't forget to add the constraints file; NGDBuild does not automatically detect .ucf files when run from Tcl. Use xfile add in the same way.



xfile add $constraints_file
 

Running Processes
 

Before we run any processes, we can set other process options using project set as shown above; see the Xilinx Command Line Tools User Guide for exhaustive detail.
Now we can run some process, and just as with the ISE GUI, running any given process will run any required prior processes. We can generate the programming file with a single script line:

 

process run "Generate Programming File"
 

And the design will be synthesised and implemented before the bit stream is generated. Just as in the GIU, we can force a rerun writing:
 

process run "Implement Design" -force rerun_all

Copyright 2018 Campera Electronic Systems Srl | All rights reserved | P.IVA 01780710495