Vivado Design Suite Tcl
Command Reference
Guide
UG835 (v2016.2) June 8, 2016
Revision History
Commands Deprecated as of 2016.1
•
•
•
get_gtbanks: Use ’get_iobanks -filter {BANK_TYPE == BT_MGT}’ instead.
open_netlist_design: Use ’link_design’ or ’open_run’ instead.
read_vcd:
Commands Added in 2016.1
check_syntax, copy_run, create_hw_device, create_hw_probe, create_hw_target, decrypt_bitstream,
delete_hw_probe, delete_hw_target, execute_hw_svf, list_hw_samples, report_bus_skew,
report_hw_targets, report_methodology, report_phys_opt, set_bus_skew, update_clock_routing,
update_module_reference, validate_dsa, write_hw_svf
Commands Modified in 2016.1
config_webtalk
06/08/2016: Released with Vivado Design Suite 2016.2 without changes from the previous version.
Vivado Design Suite Tcl Guide
UG835 (v2016.1) April 6, 2016
UG835 (v2016.2) June 8, 2016
www.xilinx.com
2
Send Feedback
Chapter 1
Introduction
Overview of Tcl Capabilities in Vivado
The Tool Command Language (Tcl) is the scripting language integrated in the Vivado™
tool environment. Tcl is a standard language in the semiconductor industry for application
programming interfaces, and is used by Synopsys® Design Constraints (SDC).
SDC is the mechanism for communicating timing constraints for FPGA synthesis tools from
Synopsys Synplify as well as other vendors, and is a timing constraint industry standard;
consequently, the Tcl infrastructure is a “Best Practice” for scripting language.
Tcl lets you perform interactive queries to design tools in addition to executing automated
scripts. Tcl offers the ability to “ask” questions interactively of design databases, particularly
around tool and design settings and state. Examples are: querying specific timing analysis
reporting commands live, applying incremental constraints, and performing queries immediately
after to verify expected behavior without re-running any tool steps.
The following sections describe some of the basic capabilities of Tcl with Vivado.
NOTE: This manual is not a comprehensive reference for the Tcl language. It is a reference
to the specific capabilities of the Vivado Design Suite Tcl shell, and provides reference to
additional Tcl programming resources.
Launching the Vivado Design Suite
You can launch the Vivado Design Suite and run the tools using different methods depending
on your preference. For example, you can choose a Tcl script-based compilation style method
in which you manage sources and the design process yourself, also known as Non-Project
Mode. Alternatively, you can use a project-based method to automatically manage your design
process and design data using projects and project states, also known as Project Mode. Either
of these methods can be run using a Tcl scripted batch mode or run interactively in the Vivado
IDE. For more information on the different design flow modes, see the Vivado Design Suite
User Guide: Design Flows Overview (UG892).
Tcl Shell Mode
If you prefer to work directly with Tcl commands, you can interact with your design using Tcl
commands with one of the following methods:
•
•
•
•
Enter individual Tcl commands in the Vivado Design Suite Tcl shell outside of the Vivado IDE.
Enter individual Tcl commands in the Tcl Console at the bottom of the Vivado IDE.
Run Tcl scripts from the Vivado Design Suite Tcl shell.
Run Tcl scripts from the Vivado IDE.
Vivado Design Suite Tcl Guide
UG835 (v2016.1) April 6, 2016
UG835 (v2016.2) June 8, 2016
www.xilinx.com
3
Send Feedback
Chapter 1:
Introduction
Use the following command to invoke the Vivado Design Suite Tcl shell either at the Linux
command prompt or within a Windows Command Prompt window:
vivado -mode tcl
TIP: On Windows, you can also select Start > All Programs > Xilinx Design Tools > Vivado
yyyy.x > Vivado yyyy.x Tcl Shell, where “yyyy.x” is the installed version of Vivado.
For more information about using Tcl and Tcl scripting, see the Vivado Design Suite User Guide:
Using the Tcl Scripting Capabilities (UG894). For a step-by-step tutorial that shows how to use
Tcl in the Vivado tool, see the Vivado Design Suite Tutorial: Design Flows Overview (UG888).
Tcl Batch Mode
You can use the Vivado tools in batch mode by supplying a Tcl script when invoking the
tool. Use the following command either at the Linux command prompt or within a Windows
Command Prompt window:
vivado -mode batch -source
The Vivado Design Suite Tcl shell will open, run the specified Tcl script, and exit when the script
completes. In batch mode, you can queue up a series of Tcl scripts to process a number of
designs overnight through synthesis, simulation, and implementation, and review the results
on the following morning.
Vivado IDE Mode
If you prefer to work in a GUI, you can launch the Vivado IDE from Windows or Linux. For
more information on the Vivado IDE, see the Vivado Design Suite User Guide: Using the
Vivado IDE (UG893).
Launch the Vivado IDE from your working directory. By default the Vivado journal and log
files, and any generated report files, are written to the directory from which the Vivado tool
is launched. This makes it easier to locate the project file, log files, and journal files, which
are written to the launch directory.
In the Windows OS, select Start > All Programs > Xilinx Design Tools > Vivado 2014.x >
Vivado 2014.x.
TIP: You can also double-click the Vivado IDE shortcut icon on your Windows desktop.
In the Linux OS, enter the following command at the command prompt:
vivado -or- vivado -mode gui
If you need help, with the Vivado tool command line executable, type:
vivado -help
If you are running the Vivado tool from the Vivado Design Suite Tcl shell, you can open the
Vivado IDE directly from the Tcl shell by using the start_gui command.
From the Vivado IDE, you can close the Vivado IDE and return to a Vivado Tcl shell by using
the stop_gui command.
Vivado Design Suite Tcl Guide
UG835 (v2016.1) April 6, 2016
UG835 (v2016.2) June 8, 2016
www.xilinx.com
4
Send Feedback
Chapter 1:
Introduction
Tcl Journal Files
When you invoke the Vivado tool, it writes the vivado.log file to record the various
commands and operations performed during the design session. The Vivado tool also writes a
file called vivado.jou which is a journal of just the Tcl commands run during the session. The
journal file can be used as a source to create new Tcl scripts.
NOTE: Backup versions of the journal file, named vivado_.backup.jou, are written
to save the details of prior runs whenever the Vivado tool is launched. The is a unique
identifier that allow the tool to create and store multiple backup versions of the log and journal
files.
Tcl Help
The Tcl help command provides information related to the supported Tcl commands.
•
help – Returns a list of Tcl command categories.
help
Command categories are groups of commands performing a specific function, like File
I/O for instance.
help -category category – Returns a list of commands found in the specified
category.
help -category object
This example returns the list of Tcl commands for handling objects.
help pattern – Returns a list of commands that match the specified search pattern. This
form can be used to quickly locate a specific command from a group of commands.
help get_*
This example returns the list of Tcl commands beginning with get_.
help command – Provides detailed information related to the specified command.
help get_cells
This example returns specific information of the get_cells command.
help -args command – Provides an abbreviated help text for the specified command,
including the command syntax and a brief description of each argument.
help -args get_cells
help -syntax command – Reports the command syntax for the specified command.
help -syntax get_cells
•
•
•
•
•
Scripting in Tcl
Vivado Design Suite Tcl Guide
UG835 (v2016.1) April 6, 2016
UG835 (v2016.2) June 8, 2016
www.xilinx.com
5
Send Feedback
Tcl Initialization Scripts
Chapter 1:
Introduction
TIP: The following describes where you can place init.tcl scripts if you would like to
customize Vivado on startup. No init.tcl scripts are provided in the Vivado release by default.
When you start the Vivado tool, it looks for a Tcl initialization script in two different locations:
1.
2.
In the software installation: installdir/Vivado/version/scripts/init.tcl
In the local user directory:
•
•
For Windows 7: %APPDATA%/Xilinx/Vivado/init.tcl
For Linux: $HOME/.Xilinx/Vivado/init.tcl
Where:
installdir is the installation directory where the Vivado Design Suite is installed.
If init.tcl exists, in one or both of those locations, the Vivado tool sources this file; first
from the installation directory and second from your home directory.
•
The init.tcl file in the installation directory allows a company or design group to
support a common initialization script for all users. Anyone starting the Vivado tool from
that installation location sources the enterprise init.tcl script.
The init.tcl file in the home directory allows each user to specify additional commands,
or to override commands from the software installation to meet their specific design
requirements.
• No init.tcl file is provided with the Vivado Design Suite installation. You must create
the init.tcl file and place it in either the installation directory, or your home directory,
as discussd to meet your specific needs.
•
The init.tcl file is a standard Tcl command file that can contain any valid Tcl command
supported by the Vivado tool. You can also source another Tcl script file from within init.tcl
by adding the following statement:
source path_to_file/file_name.tcl
NOTE: You can also specify the -init option when launching the Vivado Design Suite from
the command line. Type vivado -help for more information.
Sourcing a Tcl Script
A Tcl script can be sourced from either one of the command-line options or from the GUI.
Within the Vivado Integrated Design Environment (IDE) you can source a Tcl script from Tools
> Run Tcl Script.
You can source a Tcl script from a Tcl command-line option:
source file_name
When you invoke a Tcl script from the Vivado IDE, a progress bar is displayed and all operations
in the IDE are blocked until the scripts completes.
There is no way to interrupt script execution during run time; consequently, standard OS
methods of killing a process must be used to force interruption of the tool. If the process is
killed, you lose any work done since your last save.
Typing help source in the Tcl console will provide additional information regarding the
source command.
Vivado Design Suite Tcl Guide
UG835 (v2016.1) April 6, 2016
UG835 (v2016.2) June 8, 2016
www.xilinx.com
6
Send Feedback
Chapter 1:
Introduction
Using Tcl.pre and Tcl.post Hook Scripts
Tcl Hook scripts allow you to run custom Tcl scripts prior to (tcl.pre) and after (tcl.post)
synthesis and implementation design runs, or any of the implementation steps. Whenever
you launch a run, the Vivado tool uses a predefined Tcl script which executes a design flow
based on the selected strategy. Tcl Hook scripts let you customize the standard flow, with
pre-processors or post-processors, such as for generating custom reports. The Tcl Hook script
must be a standard Tcl script.
Every step in the design flow has a pre- and post-hook capability. Common examples are:
•
•
• Over-constraining timing constraints for portions of the flow.
• Multiple iterations of stages (e.g. multiple calls to phys_opt_design).
• Modifications to netlist, constraint, or device programming.
Custom reports: timing, power, utilization, or any user-defined tcl report.
Temporary parameters for workarounds.
IMPORTANT: Relative paths within the tcl.pre and tcl.post scripts are relative to the appropriate
run directory of the project they are applied to:
//. You can
use the DIRECTORY property of the current project or current run to define the relative paths in
your Tcl hook scripts:
get_property DIRECTORY [current_project] get_property DIRECTORY [current_run]
For more information on defining Tcl Hook scripts, refer to the Vivado Design Suite User Guide:
Using Tcl Scripting (UG894).
General Tcl Syntax Guidelines
Tcl uses the Linux file separator (/) convention regardless of which Operating System you
are running.
The following subsections describe the general syntax guidelines for using Tcl in the Vivado
Design Suite.
Using Tcl Eval
When executing Tcl commands, you can use variable substitution to replace some of the
command line arguments accepted or required by the Tcl command. However, you must use the
Tcl eval command to evaluate the command line with the Tcl variable as part of the command.
For instance, the help command can take the -category argument, with one of a number of
command categories as options:
help -category ipflow
You can define a variable to hold the command category:
set cat "ipflow"
Vivado Design Suite Tcl Guide
UG835 (v2016.1) April 6, 2016
UG835 (v2016.2) June 8, 2016
www.xilinx.com
7
Send FeedbackChapter 1:
Introduction
set is the Tcl keyword that defines the variable.
cat is the name of the variable being defined.
"ipflow" is the value assigned to the variable.
Where:
•
•
•
You can then evaluate the variable in the context of the Tcl command:
eval help -category $cat
or,
set cat "category ipflow" eval help $cat
You can also use braces {} in place of quotation marks “” to achieve the same result:
set runblocksOptDesignOpts { -sweep -retarget -propconst -remap } eval opt_design $runblocksOptDesignOpts
Typing help eval in the Tcl console will provide additional information regarding the eval
command.
Using Special Characters
Some commands take arguments that contain characters that have special meaning to Tcl.
Those arguments must be surrounded with curly braces {} to avoid unintended processing by
Tcl. The most common cases are as follows.
Bus Indexes - Because square brackets [] have special meaning to Tcl, an indexed (bit- or
part-selected) bus using the square bracket notation must be surrounded with curly braces.
For example, when adding index 4 of a bus to the Vivado Common Waveform Viewer window
using the square bracket notation, you must write the command as:
add_wave {bus[4]}
Parentheses can also be used for indexing a bus, and because parentheses have no special
meaning to Tcl, the command can be written without curly braces. For example:
add_wave bus(4)
Verilog Escaped Identifiers - Verilog identifiers containing characters or keywords that
are reserved by Verilog need to be “escaped” both in the Verilog source code and on the
simulator command line by prefixing the identifier with a backslash "\" and appending a space.
Additionally, on the Tcl command line the escaped identifier must be surrounded with curly
braces.
NOTE:
identifier with curly braces does not work, because Tcl interprets curly braces as reserved
characters even nested within curly braces.
Instead, you must use the technique described
below, in VHDL Extended Identifiers.
For example, to add a wire named "my wire" to the Vivado Common Waveform Viewer
window, you must write the command as:
add_wave {\my wire }
NOTE: Be sure to append a space after the final character, and before the closing brace.
Verilog allows any identifier to be escaped. However, on the Tcl command line do not escape
identifiers that are not required to be escaped. For example, to add a wire named "w" to the
Vivado Common Waveform Viewer window, the Vivado simulator would not accept:
add_wave {\w }
If an identifier already includes a curly brace, then the technique of surrounding the
Vivado Design Suite Tcl Guide
UG835 (v2016.1) April 6, 2016
UG835 (v2016.2) June 8, 2016
www.xilinx.com
8
Send Feedback