Introduction - 2023.1 English

Vivado Design Suite User Guide: Using Tcl Scripting (UG894)

Document ID
UG894
Release Date
2023-06-14
Version
2023.1 English

The Tool Command Language, or Tcl, is an interpreted programming language with variables, procedures (procs), and control structures, to interface to a variety of design tools and to the design data.

Tip: For more information, see the Vivado Design Suite Tcl Command Reference Guide (UG835), or type <command> -help. For information on launching and using the AMD Vivado™ Design Suite, see the Vivado Design Suite User Guide: Getting Started (UG910).

The language is easily extended with new function calls, and has been expanded to support new tools and technology since its inception and adoption in the early 1990s. It has been adopted as the standard application programming interface, or API, among most EDA vendors to control and extend their applications.

AMD has adopted Tcl as the native programming language for the Vivado Design Suite, as it is easily adopted and mastered by designers familiar with this industry standard language. The Tcl interpreter inside the Vivado Design Suite provides the full power and flexibility of Tcl to control the application, access design objects and their properties, and create custom reports. Using Tcl, you can adapt your design flow to meet specific design challenges.

Tcl provides built-in commands to read and write files to the local file system. This enables you to dynamically create directories, start FPGA design projects, add files to the projects, run synthesis and implementation. You can customize the reports generated from design projects, on device usage and quality of results, to share across the organization.

You can also use Tcl to implement new design approaches, or work around existing problems, inserting and deleting design objects, or modifying properties as needed. You can write scripts to replay established portions of your design flow to standardize the process.

Many of the Tcl commands discussed in the following text and script examples are specific to the Vivado Design Suite. You can find detailed information regarding Tcl commands specific to the Vivado Design Suite in the Vivado Design Suite Tcl Command Reference Guide (UG835), or in the Help system of the Vivado tools.

The AMD Vivado™ IDE uses Xilinx Design Constraints (XDC) to specify the design constraints. XDC is based on a subset of all the Tcl commands available in Vivado and is interpreted exactly like Tcl. The XDC commands are primarily timing constraints, physical constraints, object queries and a few Tcl built-in commands: set, list, and expr. For a complete description of the XDC commands, see Appendix B of the Vivado Design Suite User Guide: Using Constraints (UG903). Unlike Tcl scripts, XDC files are managed by the Vivado IDE so that any constraint edited through the graphical interface or the Timing Constraints Editor can be saved back to its original XDC file. For this reason, only XDC commands can be used in a XDC file. If you need to use other Tcl commands to write your constraints, you must use a Tcl script.

The Vivado tools write a journal file called vivado.jou into the directory from which Vivado was launched. The journal is a record of the Tcl commands run during the session that can be used as a starting point to create new Tcl scripts.

A log file, vivado.log is also created by the tool and includes the output of the commands that are executed. Both the journal and log file are useful to verify which commands were run and what result they produced.

Additional Tcl commands are provided by the Tcl interpreter that is built into the Vivado Design Suite. For Tcl built-in commands, Tcl reference material is provided by the Tcl Developer Xchange website, which maintains the open source code base and documentation for Tcl, and is located at Tcl Developer Xchange.

See this tutorial for an introductory tutorial to the Tcl programming language. Also see the Tclers' Wiki located here for some example scripts.

In this document you will see some examples of Tcl commands and Tcl scripts, and the results that are returned by theVivado Design Suite when these commands are run. The commands and their return values appear with the following formats:

  • Tcl commands and example scripts:
    puts $outputDir
  • Output to Tcl Console or results of Tcl commands:
    ./Tutorial_Created_Data/cpu_output