Local and Global Variables - 2024.1 English

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

Document ID
Release Date
2024.1 English

A local variable is a variable created inside a procedure. It is created at runtime inside the stack of the function. The variable is only accessible within the procedure and the variable name is not subject to name collision with variable names outside of the procedure. This means that, for example, a local variable foo created inside a procedure is different from a variable foo created outside of the procedure and both variables have independent content. A local variable is created with the set Tcl keyword like any other variable.

The parameters defined as the arguments of a procedure are, by default, local variables. Whenever a procedure is called (for example reportCriticalPaths $myfilename), the content of the calling variables (for example $myfilename) are copied inside the stack of the procedure. If the calling variables are Tcl lists with a large number of elements, this mechanism has a runtime and memory penalty. There are also some scenarios when it is necessary to modify the content of the caller variables. Tcl provides a way to do that by passing a variable name as a reference instead of passing the content of the variable. Once a variable is passed as a reference, any modification of the variable inside the procedure directly modifies the caller's variable inside the caller's space. The keyword upvar is used inside the body of the procedure to define a parameter that is passed as reference. The procedure lshift that has been introduced earlier uses this technique:

proc lshift {listVar} {
   upvar 1 $listVar L
   set r [lindex $L 0]
   set L [lreplace $L [set L 0] 0]
   return $r

In the example proc myproc, lshift is called by passing the variable name args instead of the content $args.

A global variable is a variable created outside of a procedure and that belongs to the global namespace. To refer to a global variable inside a procedure, the keyword global is used followed by the variable name:

proc printEnv {} {
  global env
  foreach var [lsort [array names env]] { puts " $var = $env($var)" }

The above example defines a procedure printEnv that prints the system environment variables. The Tcl array, env is a global variable initialized when the Vivado tools start. The printEnv procedure refers to the global env variable through the global env command. After the global variable is declared, it is accessed like any local variable. The global variable can be read and modified.

Another way to access a global variable is to specify the namespace qualifier with it. The namespace qualifier for the global namespace is "::" (without any quotes) and therefore a procedure can refer to the global variable env with ::env. The syntax is the same for any global variable. For example:

proc printEnv {} {
  foreach var [lsort [array names ::env]] { puts " $var = $::env($var)" }

Since printEnv specifies the full path to the env variable, the procedure does not need to declare global env.

Note: AMD does not recommend that you use global variables as they rely on variable names created outside the scope of the procedure. Global variables are sometimes used to avoid having to pass large Tcl lists to a procedure. The upvar technique should always be considered before using a global variable.
Note: When using the run infrastructure in Project mode, it is not possible to share global variables defined inside the Vivado environment with the hook scripts. Refer to Getting User Inputfor recommended methods to share information between scripts.
Note: The close_project and close_design commands do not change the state of the Tcl interpreter. All the global variables and user created namespaces are persistent after running those commands.