A Brief Overview of Tcl - 2020.2 English

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

Document ID
UG894
Release Date
2021-03-30
Version
2020.2 English

A Tcl script is a series of Tcl commands, separated by new-lines or semicolons. A Tcl command is a string of words, separated by blanks or tabs. The Tcl interpreter breaks the command line into words and performs command and variable substitutions as needed. The Tcl interpreter reads the line from left to right, and evaluates each word completely before attempting to evaluate the next. Command and variable substitutions are performed from left to right as the line is read.

A word is a string that can be a single word, or multiple words within braces, {}, or multiple words within quotation marks, "". Semicolons, brackets, tabs, spaces, and new-lines, within quotation marks or braces are treated as ordinary characters. However, the backslash, \, is treated as a special character even within braces and quotation marks, as discussed below.

The first word identifies the command, and all subsequent words are passed to the command as arguments.

set outputDir ./Tutorial_Created_Data/cpu_output 

In the preceding example, the first word is the Tcl set command, which is used to assign variables. The second and third words are passed to the set command as the variable name (outputDir), and the variable value (./Tutorial_Created_Data/cpu_output).

When a backslash, '\', is used in a word, then the Tcl interpreter performs backslash substitution. In most cases, this means that the character following the backslash is treated as a standard character in the word. This is used to add quotes, braces, dollar signs, or other special characters to a string. Refer to a Tcl/Tk reference source for more information on how the Tcl interpreter handles the backslash character.

puts $outputDir 
./Tutorial_Created_Data/cpu_output
puts \$outputDir 
$outputDir 

There is a also difference between the use of braces and quotation marks. No substitutions are performed on the characters between the braces. Words, or strings, within braces are taken verbatim, and are not evaluated for variable or command substitution by the Tcl interpreter. The word consists of exactly the characters between the outer braces, not including the braces themselves, as shown in the example below. Strings within quotation marks are evaluated, and variable and command substitutions are performed as needed. Command substitution, variable substitution, and backslash substitution are performed on the characters between quotes.

puts {The version of Vivado Design Suite is [version -short]}
The version of Vivado Design Suite is [version -short]
puts "The version of Vivado Design Suite is [version -short]"
The version of Vivado Design Suite is 2018.1

Notice in the example above, that the [version -short] command is substituted for the returned value when enclosed within quotation marks, but is not substituted when enclosed within braces. Keep substitution in mind when choosing to use either "" or {} to enclose a string of words.

Variable assignment is performed using the set command. You can access a previously assigned variable by specifying the name of the variable with a leading dollar sign, ‘$’. If a word starts with a dollar sign the Tcl interpreter performs variable substitution, replacing the variable with the value currently stored by the variable. The ‘$’ is a reserved character in Tcl.

set outputDir ./Tutorial_Created_Data/cpu_output
puts $outputDir
./Tutorial_Created_Data/cpu_output

Commands can also be nested inside other commands within brackets, [], which are evaluated from left to right in a bottom-up manner. The Tcl interpreter recursively processes the strings within the brackets as a new Tcl script. A nested command can also contain other nested commands. The result of a nested command is passed up into the higher-level command, which is then processed.

set listCells [lsort [get_cells]]

The preceding example assigns the sorted list of cell objects existing at the top-level of the current design to the listCells variable. The get_cells command is executed first, the returned objects are sorted by the lsort command, and the sorted list is assigned to the specified variable.

However, the Vivado Design Suite handles square brackets slightly differently than standard Tcl. Square brackets are treated as standard characters in Verilog and VHDL names (net, instances, etc.), and usually identify one or more elements of vectors, such as buses or arrays of instances. In the Vivado Design Suite tools the square brackets are not evaluated in a bottom-up manner when they are expected to be part of a netlist object name.

The following three commands are equivalent:

1.) set list_of_pins [get_pins transformLoop[0].ct/xOutReg_reg/CARRYOUT[*] ]
2.) set list_of_pins [get_pins {transformLoop[0].ct/xOutReg_reg/CARRYOUT[*] } ]
3.) set list_of_pins [get_pins transformLoop\[0\].ct/xOutReg_reg/CARRYOUT\[*\] ]

In line 1, the outer pair of brackets indicate a nested command, [get_pins], as is standard in Tcl. However, the subsequent square brackets are interpreted by the Vivado tools as part of the specified object name transformLoop[0]. This is handled automatically by the Vivado Design Suite, but is limited to certain characters. These characters must be in one of the following forms, or the brackets will be interpreted as they would be in normal Tcl syntax:

  • star: [*] - The wildcard indicates any of a number of bits or instances.
  • integer: [12] - The integer indicates a specific bit or instance.

In line 2 the use of the braces, {}, will prevent command substitution of the string inside the braces. In this case the square brackets would be evaluated as part of the object name, transformLoop[0].

In line 3, the backslash indicates that the bracket should be interpreted as a standard character rather than a special character, and this will prevent nested command substitution.

While lines 2 and 3 prevent the square brackets from being misinterpreted, those lines require you to manually apply the braces or backslash as needed by standard Tcl. Line 1 shows how the Vivado Design Suite automatically handles this for you.

Finally, to add comments to a Tcl script, simply start a new-line with the number sign, or hash character, ‘#’. Characters that follow a hash character are ignored, up to the next new-line. To add a comment to the end of a line, simply end the command with a semicolon, ‘;’, and then begin the comment with a hash character as shown below:

# This is a comment
puts "This is a command"; # followed by a comment