Using the -hierarchical Option - 2022.1 English

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

Document ID
Release Date
2022.1 English

While the default behavior is to search for objects only at the level of the current instance, many of the get_* commands have a -hierarchical option to enable searching the design hierarchy level by level, starting from the level of the current instance.

get_cells -hierarchical * ; # Returns all cells of the design.
get_nets -hier *nt* ; # Returns all hierarchical nets that match *nt*. 

However, one important feature of the -hierarchical option is that the Vivado tools try to match the specified name pattern at each level of the design hierarchy, and not against the full hierarchical name of an object. In general, when -hierarchical is used, the specified search pattern must not include the hierarchical separator otherwise no object will be returned. There is an exception to this rule when the netlist has been partially flattened during synthesis. That is when the hierarchy separator is also used to mark the flattened netlist level. In this case, it is possible to use it in the search pattern as it only represents a level of hierarchy in the name and not in the design loaded in memory.

The following example is based on Getting Objects By Name which shows a purely hierarchical netlist.

get_cells -hierarchical B/* ; # No cell is returned.
get_cells -hierarchical b* ; # B/b1 and B/b2 are returned.

The -hierarchical search is equivalent to manually performing a search at each level of the hierarchy, using the current_instance command to set the search scope to a particular hierarchical instance, and return all the objects that match the specified name pattern at that level. The following Tcl code, based on Getting Objects By Name, illustrates this manual process:

set result {}
foreach hcell [list "" A B A/a1 A/a2 B/b1 B/b2] {
  current_instance $hcell ;# Move scope to $hcell
  set result [concat $result [get_cells <pattern>]]
  current_instance ;# Return scope to design top-level
Important: When -hierarchical is used with -regexp, the specified search string is matched against the full hierarchical name, and B/.* will return all cell names that match this pattern. For example, based on Getting Objects By Name, get_cells -hierarchical -regexp B/.* returns all the cells below the block B. See the Vivado Design Suite Tcl Command Reference Guide (UG835) for more information on -regexp.