Handling Lists of Objects - 2021.1 English

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

Document ID
UG894
Release Date
2021-06-16
Version
2021.1 English

When using the get_* commands, the returned object looks and acts like a standard Tcl list. However, the Vivado Design Suite is returning a container of a single class of objects (for example cells, nets, pins, or ports), which is not a generic Tcl list. However, for most of your purposes, the container of objects looks and acts just like any Tcl list. The container of objects is handled automatically by the Vivado Design Suite, and is totally transparent to the user. For example, the standard Tcl llength command can be used on a container of objects (for example from get_cells) and returns the number of elements in the container, like it would for any standard Tcl list.

The built-in Tcl commands that handle lists in the Vivado Design Suite have been overloaded and enhanced to fully support objects and containers of objects. For example, lsort, lappend, lindex, and llength, have been enhanced to manage the container based on the NAME property of the object. The result of these commands, when passed a container of objects, returns a container of objects. For example, lsort will sort a container of cells from the get_cells command based on the hierarchical names of the objects.

You can add new objects to the container (using lappend, for instance), but you can only add the same type of object that is currently in the container. Adding a different type of object, or string, to the list is not permitted and will result in a Tcl error.

The following example shows a Vivado container being sorted in a descending order, and each object put onto a separate line, by using the puts command and a foreach loop:

foreach X [lsort -decreasing [get_cells]] {puts $X}
wbArbEngine
usb_vbus_pad_1_i_IBUF_inst
usb_vbus_pad_0_i_IBUF_inst
usbEngine1
usbEngine0
...
Note: Although the lappend command is supported by the Tcl Console, it is not supported in a XDC constraint file with the read_xdc command. However, it is possible to convert a list built with the lappend command in a different way that is compatible with the read_xdc command. In the following example:
set myClocks {}
lappend myClocks [get_clocks CLK1]
lappend myClocks [get_clocks CLK2]
lappend myClocks [get_clocks CLK3]

The Tcl variable myClocks can be built differently to be compatible with the read_xdc command:

set myClocks [list [get_clocks CLK1] \
                       [get_clocks CLK2] \
                       [get_clocks CLK3] \
                ]