Handling Lists of Objects - 2022.2 English - UG835

Vivado Design Suite Tcl Command Reference Guide (UG835)
Document ID
UG835
Release Date
2022-10-19
Version
2022.2 English

Commands that return more than one object, such as get_cells or get_sites, return a collection in the Vivado tool that looks and behaves like a native Tcl list. This feature allows performance gains when handling large lists of Tcl objects without the need to use special commands like the foreach_in_collection command. In the Vivado Design Suite collections can be processed like Tcl lists using built-in commands such as lsort, lsearch, and foreach.

Typically, when you run a get_* command, the returned results are echoed to the console and to the log file as a Tcl string, rather than as a list due to a feature of Tcl called "shimmering". Internally, Tcl can store a variable or value both as a string and as a faster native object such as a float or a list object. In Tcl, shimmering occurs when the representation of the object or value changes from the list object to the string object, or from string to list. A list of Vivado objects is returned by the get_* command, but the shimmered string representation is written to the log file and Tcl console.

However, to improve performance and prevent overloading memory buffers, the Vivado Design Suite limits and truncates the shimmered string to a default character length defined by the tcl.collectionResultDisplayLimit parameter, which has a default value of 500. Commands that can return a significant number of objects, such as get_cells or get_sites, will truncate the returned string, ending it with an ellipsis ('...'). You can use the set_param command to change the tcl.collectionResultDisplayLimit parameter value to return more or fewer results.
CAUTION:
The combination of shimmering and the tcl.collectionResultDisplayLimit parameter prevents the use of in and ni list operators in the Vivado Design Suite. Since a string shimmered from the list may be truncated, the in and ni operators cannot effectively determine if a specified object is in, or not-in, a list of objects. You should use list commands such as lsearch and lsort instead of in or ni. 
if {[lsearch -exact [get_cells *] $cellName] != -1} {...}
You can capture the complete list returned by the get_* command by assigning the results to a Tcl variable: 
set allSites [get_sites]
The actual list in the variable assignment includes the complete result set, and is not truncated by the tcl.collectionResultDisplayLimit parameter. An example of this is seen in hierarchically querying all the cells in a design: 
%set allCells [get_cells -hierarchical]
DataIn_pad_0_i_IBUF[0]_inst DataIn_pad_0_i_IBUF[1]_inst \
DataIn_pad_0_i_IBUF[2]_inst DataIn_pad_0_i_IBUF[3]_inst \
DataIn_pad_0_i_IBUF[4]_inst ...
%llength $allCells
42244
%lindex $allCells end
wbArbEngine/s4/next_reg
In the preceding example, the result of the hierarchical get_cells command was assigned to the $allCells variable. In appearance, the results are truncated. However, a check of the length of the list reports more than forty thousand cell objects, and the last index in the list returns an actual object, and not an ellipsis.
Tip: If necessary, you can also use the join command, to join the list of objects returned by the get_* Tcl command, with a newline (\n), tab (\t), or a space (" "), to display the un-truncated list of objects: 
join [get_parts] " "