General Tcl Syntax Guidelines

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"

Where:

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.

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: If an identifier already includes a curly brace, then the technique of surrounding the 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 }

as a valid command, since this identifier (the wire name "w") does not required to be escaped. The command must be written as:

add_wave w

VHDL Extended Identifiers - VHDL extended identifiers contain backslashes, "\", which are reserved characters in Tcl. Because Tcl interprets a backslash next to a close curly brace \} as being a close curly brace character, VHDL extended identifiers cannot be written with curly braces. Instead, the curly braces must be absent and each special character to Tcl must be prefixed with a backslash. For example, to add the signal \my sig\ to the Wave window, you must write the command as:

add_wave \\my\ sig\\

Note: Both the backslashes that are part of the extended identifier, and the space inside the identifier are prefixed with a backslash.

General Syntax Structure

The general structure of Vivado Design Suite Tcl commands is:

command [optional_parameters] required_parameters

Command syntax is of the verb-noun and verb-adjective-noun structure separated by the underscore (“_”) character.

Commands are grouped together with common prefixes when they are related.

Commands that query things are generally prefixed with get_.
Commands that set a value or a parameter are prefixed with set_.
Commands that generate reports are prefixed with report_.

The commands are exposed in the global namespace. Commands are “flattened,” meaning there are no “sub-commands” for a command.

Example Syntax

The following example shows the return format on the get_cells -help command:

get_cells

Description: 
Get a list of cells in the current design

Syntax: 
get_cells  [-hsc <arg>] [-hierarchical] [-regexp] [-nocase] [-filter <arg>]
           [-of_objects <args>] [-match_style <arg>] [-quiet] [-verbose]
           [<patterns>]

Returns: 
list of cell objects

Usage: 
  Name             Description
  ----------------------------
  [-hsc]           Hierarchy separator
                   Default: /
  [-hierarchical]  Search level-by-level in current instance
  [-regexp]        Patterns are full regular expressions
  [-nocase]        Perform case-insensitive matching (valid only when -regexp
                   specified)
  [-filter]        Filter list with expression
  [-of_objects]    Get cells of these pins, timing paths, nets, bels, sites 
                   or drc violations
  [-match_style]   Style of pattern matching
                   Default: sdc
                   Values: ucf, sdc
  [-quiet]         Ignore command errors
  [-verbose]       Suspend message limits during command execution
  [<patterns>]     Match cell names against patterns
                   Default: *

Categories: 
SDC, XDC, Object

Unknown Commands

Tcl contains a list of built-in commands that are generally supported by the language, Vivado tool specific commands which are exposed to the Tcl interpreter, and user-defined procedures.

Commands that do not match any of these known commands are sent to the OS for execution in the shell from the exec command. This lets users execute shell commands that might be OS-specific. If there is no shell command, then an error message is issued to indicate that no command was found.

Return Codes

Some Tcl commands are expected to provide a return value, such as a list or collection of objects on which to operate. Other commands perform an action but do not necessarily return a value that can be used directly by the user. Some tools that integrate Tcl interfaces return a 0 or a 1 to indicate success or error conditions when the command is run.

To properly handle errors in Tcl commands or scripts, you should use the Tcl built-in command catch. Generally, the catch command and the presence of numbered info, warning, or error messages should be relied upon to assess issues in Tcl scripted flows.

Vivado tool Tcl commands return either TCL_OK or TCL_ERROR upon completion. In addition, the Vivado Design Suite sets the global variable $ERRORINFO through standard Tcl mechanisms.

To take advantage of the $ERRORINFO variable, use the following line to report the variable after an error occurs in the Tcl console:

puts $ERRORINFO

This reports specific information to the standard display about the error. For example, the following code example shows a Tcl script (procs.tcl) being sourced, and a user-defined procedure (loads) being run. There are a few transcript messages, and then an error is encountered at line 5.

Line 1: Vivado % source procs.tcl 
Line 2: Vivado% loads 
Line 3: Found 180 driving FFs 
Line 4: Processing pin a_reg_reg[1]/Q... 
Line 5: ERROR: [HD-Tcl 53] Cannot specify '-patterns' with '-of_objects'.
Line 6: Vivado% puts $errorInfo 
Line 7: ERROR: [HD-Tcl 53] Cannot specify '-patterns' with '-of_objects'. 
   While executing "get_ports -of objects $pin" (procedure "my_report" line 6) 
   invoked from within procs.tcl

You can add puts $ERRORINFO into catch clauses in your Tcl script files to report the details of an error when it is caught, or use the command interactively in the Tcl console immediately after an error is encountered to get the specific details of the error.

In the example code above, typing the puts $ERRORINFO command in line 6, reports detailed information about the command and its failure in line 7.