Persistency of Objects - 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 Vivado object persists as long as the element it points to exists in memory. For example, if a Tcl variable points to a cell object and the cell is deleted afterward (either manually or thought some optimization steps), the cell object becomes null. This could lead to unexpected results or crash if you execute a command that relies on it.

In the same way, once a design or a project is closed, all the design objects and potentially all the other Vivado objects are nullified, and any Tcl variable pointing to Vivado objects that no longer exist is stalled.

CAUTION:
If you execute a command that relies on an object that no longer exists in memory, the command could produce unexpected results or cause a system crash.

For example, the code below is flawed:

 foreach port [get_ports] {
    # The 'port' object is used as key
    set dir($port) [get_property DIRECTION $port]
  }
  foreach key [array name dir] {
    puts "$key -> $dir($key)"
  }
  close_project
  # All the objects have been nullified
  foreach key [array name dir] {
    # null
    puts "$key -> $dir($key)"
  }

Once the project is closed, all the objects (i.e., port objects in this example) are nullified and therefore it is no longer possible to print the list of ports.

To be able to print the list of ports after the design is closed, the associative array 'dir' should have been built using the property NAME of the 'port' object:

foreach port [get_ports] {
    set dir([get_property NAME $port]) [get_property DIRECTION $port]}
Another example of objects becoming invalid is after using the command 'read_checkpoint -cell <cell>'. When a checkpoint is read for a cell, the design is rebuilt in the background and previous first-class objects become invalid. The code below could result in a crash as the objects from the get_cell query are invalidated after the first read_checkpoint:
foreach cell_hd [get_cell -hier -filter HD.RECONFIGURABLE==1] { 
  read_checkpoint -cell $cell ... 
}
The safe way to write the code is to convert the objects into their string representation:
foreach cell_hd [get_property NAME [get_cell -hier -filter HD.RECONFIGURABLE==1]] { 
  read_checkpoint -cell $cell ... 
}