Accessing Design Objects - 2024.1 English

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

Document ID
Release Date
2024.1 English

The Vivado Design Suite loads the project, design, and device information into an in-memory database, which is used by synthesis, implementation, timing analysis, and to generate a bitstream. The database is the same for project and Non-Project flows. The database is updated as you step through the FPGA design flow. You can write the database contents out to disk as a checkpoint file (.dcp) at any point of the design flow. Using Tcl commands in the Vivado tools lets you interact with the design database, query Tcl objects, read, or set their properties, and use them in Tcl scripts for various purposes. It is very helpful to understand the content of the database, to understand how efficient scripts can be written around it.

The Vivado Design Suite Tcl interpreter provides access to many first class objects such as project, device, nets, cells, and pins. The Vivado Design Suite updates these design objects dynamically, as the design progresses, and loads them into the in-memory database in both Project and Non-Project modes.

You can interactively query design objects, analyze the state of your project, write a script to access the in-memory design, and run custom reports or execute optional design flow steps. Each object comes with a number of properties that can always be read and sometimes written. Most design objects are related to other design objects, allowing you to traverse the design to find related objects or information.

You can query design objects using the get_* Tcl commands which return list of design objects, that can be directly manipulated, or assigned to a Tcl variable. The complete list of get_* commands can be returned with help get_*. Caching objects in variables can save runtime by reducing the number of queries to the design database. Querying the list of nets or pins can be a time consuming process, so saving the results can speed the design flow when accessing the information repeatedly. See Caching Objects for more on this topic.

Each class of design object (net, pin, port, …) has a unique set of standard properties that can be read and sometimes written to modify their value in the database. In addition, the design attributes specified in the RTL source files, the Verilog parameters and VHDL generics are stored with the associated netlist object as properties. For example, a port object has a property that indicates its direction, while a net object has a property that defines its fanout. The Vivado tools provides a number of commands for adding, changing, and reporting these properties. Using the get_* -filter option lets you get a list of design objects that is filtered, or reduced, to match specific property values, as described in Filtering Results. You can get the list of properties on an object by using the list_property command. When a property type is enum, it is possible to get the list of all the valid values by using the list_property_value command.

There are two properties that are common to all objects: NAME and CLASS. When an object is assigned to a Tcl variable, a pointer to the object is stored in the variable. Objects can be passed by variable to Tcl commands or Tcl procs. When an object is passed as an argument to a Tcl proc or command which expects a string, the object's NAME property value is passed instead of the object itself. The example below shows a cell object assigned to the variable, $inst, and the results of the puts command and the report_property command on the $inst variable. The puts command just prints the object NAME because it only works with strings, while the report_property command returns all of the object properties and their values:

set inst [get_cells cpuEngine]
puts $inst
report_property $inst
Property     Type  Read-only Value
CLASS      string true    cell
FILE_NAME    string true    
IS_BLACKBOX   bool  true    0
IS_PRIMITIVE   bool  true    0
IS_SEQUENTIAL  bool  true    0
LINE_NUMBER   int   true    812044
NAME       string true    cpuEngine
PRIMITIVE_COUNT int   true    11720
REF_NAME     string true    or1200_top

You can also create custom properties for any class of design objects in the Vivado Design Suite. This can be useful when you want to annotate some information from a script onto the in-memory design objects. The following example creates a property, SELECTED, for a cell object. The value of the property is defined as an integer.

create_property SELECTED cell -type int

Once a property has been created on a class of objects, it can be managed on a specific object with set_property and get_property commands, and reported with list_property and report_property commands. The following example sets the SELECTED property to a value of 1 on all the cells that match the specified name pattern, *aurora_64b66b*:

set_property SELECTED 1 [get_cells -hier *aurora_64b66b*]