Filtering Results - 2024.1 English

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

Document ID
Release Date
2024.1 English

More often than not, when you use get_* to search for design objects, you are only interested in a subset of the objects returned. You might not want all of the netlist objects in the design, but for example, only cells of a certain type, or nets of a certain name. In some cases, only a subset of elements are of interest and need to be returned.

Figure 1. Searching Hierachical Designs

You can limit the search results, by narrowly defining your search pattern, using wildcards '*' and ‘?’, or using -regexp to build complex search patterns to evaluate. You can limit the scope of hierarchy being searched, by setting the current_instance or by specifying -hierarchy.

For example, the following expressions return different results:

get_cells * ; # Returns 2 cells: A,B
get_cells -hier * ; # Returns all cells of the design (leaf and hierarchical)
get_cells -hier * -filter {NAME =~ */?1/*} ; # Returns 3 cells: A/a1/data0_i,
                                                      # A/a1/data_reg, B/b1/data_reg

The -filter option lets you filter the results of the get_* commands, based on specific properties of the objects being searched. For example, the following command returns all the cells with a hierarchical name that begins with B/b*, and that have not been placed by the user, so that IS_LOC_FIXED is FALSE, or 0:

set unLoced [ get_cells -hier -filter {NAME =~ B/b* && !IS_LOC_FIXED} ]
Important: The NAME property contains the full hierarchical name of the object. When filtering on the NAME property, the pattern is evaluated against the complete NAME string, regardless of the other options used in the command, including -hierarchical.

The -filter option causes Vivado to filter the results of a query before it is returned. However, in some cases you might have assigned the results of a prior search to a variable, that is now stored in memory. The filter command lets you filter the content of any list of objects, including lists stored in a variable. Using the results of the prior example, stored in $unLoced, you can further filter the list of objects as follows:

set unLocedLeaf [filter $unLoced {IS_PRIMITIVE}]

The preceding example filters the stored results of the prior search, filtering the list to return only the objects that are primitive instances in the design.

Important: The filter command does not modify the original Tcl variable and therefore the result must be saved inside another Tcl variable.
Tip: Note the direct use of the boolean properties IS_LOC_FIXED and IS_PRIMITIVE in the example above. Boolean (bool) type properties can be directly evaluated in filter expressions as true or false.

The specific operators that can be used in filter expressions are "equals" and "not-equals" (== and !=), and "contains" and "not-contains" (=~ and !~). Numeric comparison operators <, >, <=, and >= can also be used. Multiple filter expressions can be joined by AND and OR ( && and ||).