Collection versus String Representation - 2020.2 English

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

Document ID
Release Date
2020.2 English

The get_* commands do not create a regular Tcl list of elements. They create a Vivado collection of objects, but the Vivado collections have been implemented in such way that they behave like any regular Tcl list. The process is transparent to the user and to Tcl. Vivado collections behave like Tcl lists and can be manipulated in the very same way and with the same commands.

Vivado collections have been implemented in Tcl to improve runtime and reduce the memory footprint when dealing with Vivado objects.

Now, when a Vivado collection is converted as a string, it is possible to limit the number of objects to be converted. So, for example, if you print in the Tcl console a list of instances, and that the list (a Vivado collection under the hood) has 100,000 instances, only the first 500 (default limit) instances will be exported. This avoids cluttering the Tcl console with a string that could be extremely long.

The notion of string representation of a Vivado collection of objects is important to understand. The maximum number of objects to include in the string representation of a collection is controlled through the parameter tcl.collectionResultDisplayLimit:

  tcl.collectionResultDisplayLimit 500  integer true  

The maximum number of elements can be displayed by any command that displays a collection. You can make this unlimited by setting the limit to 0. (default: 500). For example:

set_param tcl.collectionResultDisplayLimit 0
set_param tcl.collectionResultDisplayLimit 1000

When a Vivado collection has more elements than the limit defined by the parameter tcl.collectionResultDisplayLimit, only the first nth elements are converted as a string, then '...' is added at the end of the string representation to indicate that more elements in the original collection have not been included.

Note: The string representation does not alter the original collection in any way so there is never any loss of elements in the original collection.
Note: The parameter tcl.collectionResultDisplayLimit only applies to string representation of Vivado collections. It does not apply to string representation of regular Tcl lists.

For example, if a design has 20000 instances:

vivado% set cells [get_cells -hier]
vivado% llength $cells
vivado% set var [join $cells "\n"]
vivado% llength $var
vivado% lindex $var end