Using the -filter and -regexp Options

The Vivado Design Suite offers multiple ways to select a subset of objects with the get_* commands, using the -filter and/or -regexp options in conjunction with the -hierarchical option.

The table below summarizes the effect of the -hierarchical/-filter/-regexp options on the pattern that is provided to the command:

get_* [-hierarchical] [-filter] [-regexp] pattern

Table 1. Effects of -hierarchical/-filter/-regexp Options
-hierarchical	-filter	-regexp	Result
			`Pattern` matches the local name of objects that belong to the current hierarchical level (`current_instance`).
Yes			`Pattern` matches the local name of objects that belong to the current hierarchical level (`current_instance`) and below.
	Yes		`Pattern` is a filtering expression applied to objects that belong to the current hierarchical level (`current_instance`). The `NAME` property matches against the full hierarchical name of the object.
Yes	Yes		`Pattern` is a filtering expression applied to objects that belong to the current hierarchical level (`current_instance`) and below. The `NAME` property matches against the full hierarchical name of the object.
		Yes	`Pattern` is a regular expression that matches the local name of objects that belong to the current hierarchical level (`current_instance`).
Yes		Yes	`Pattern` is a regular expression that matches the local name of objects that belong to the current hierarchical level (`current_instance`) and below.
	Yes	Yes	`Pattern` is a filtering expression applied to objects that belong to the current hierarchical level (`current_instance`). The Name property matches against the full hierarchical name of the object. The matching expressions are based on the regular expression format.
Yes	Yes	Yes	`Pattern` is a filtering expression applied to objects that belong to the current hierarchical level (`current_instance`) and below. The Name property matches against the full hierarchical name of the object. The matching expressions are based on the regular expression format.

Note: The local name of an object refers to the part of the name that comes from the current hierarchical level (current_instance). It does not include the part of the name inherited from the parent.

Note: When some parts of the design have been flattened, the local name of objects that belonged to the flattened levels includes the hierarchical separator. In such a case, the hierarchy separator in this part of the name is not seen any more as a separator, but just as a literal character.

Note: The -filter option specifies a filtering expression where the pattern matching inside the expression follows the global expression format. A filtering expression involves string matching based on object properties and can be as complex as required. When the NAME property is used inside a filtering expression, the full hierarchical name of the object is used for the string matching and not its local name. However, only objects that belong to the current hierarchical level (current_instance) are being considered. If -hierarchical is used with -filter, then all the objects that belong to the current hierarchical level and below are considered for the filtering. If -regexp is used with -filter, the pattern matching inside the expression follows the regular expression format.

Note: The -regexp option implies that the pattern provided to the command is a regular expression. Be careful as some characters, such as * . [ ] +, have a special meaning inside a regular expression. Those characters need to be escaped when used as literal and not as special characters in the context of the regular expression.

The string matching is case sensitive and always anchored to the start and end of the search string. To match a sub-string of a search string, use the following syntax depending on whether or not a regular expression is used:

The pattern follows the format of a regular expression (-regexp only): .*<substring>.*
The pattern follows the format of a global expression (other options): *<substring>*

Following are some examples based on the cpu_hdl project, which can be found under the Open Example Project link on the Getting Started page of the Vivado IDE, that illustrate the differences between the options.

Change the current instance to fftEngine/fftInst/ingressLoop[7].ingressFifo:

vivado% current_instance fftEngine/fftInst/ingressLoop[7].ingressFifo
fftEngine/fftInst/ingressLoop[7].ingressFifo

Get all the cells under the current instance: there is only one (hierarchical) cell:

vivado% get_cells
fftEngine/fftInst/ingressLoop[7].ingressFifo/buffer_fifo
vivado% get_cells -hier
fftEngine/fftInst/ingressLoop[7].ingressFifo/buffer_fifo 
fftEngine/fftInst/ingressLoop[7].ingressFifo/buffer_fifo/infer_fifo.two_rd_addr_reg
[8]_i_1__29 … (154 other cells)

The local name of the cells under the current instance and below does not include ingressLoop. The string ingressLoop is inherited from the parent cell and is part of the full hierarchical name:
```
vivado% get_cells *ingressLoop*
WARNING: [Vivado 12-180] No cells matched '*ingressLoop*'.
vivado% get_cells *ingressLoop* -hier
WARNING: [Vivado 12-180] No cells matched '*ingressLoop*'.
```

With the -filter option, the NAME property matches the full hierarchical names:

vivado% get_cells -filter {NAME =~ *ingressLoop*}
fftEngine/fftInst/ingressLoop[7].ingressFifo/buffer_fifo
vivado% get_cells -filter {NAME =~ *ingressLoop*} -hier
fftEngine/fftInst/ingressLoop[7].ingressFifo/buffer_fifo 
fftEngine/fftInst/ingressLoop[7].ingressFifo/buffer_fifo/infer_fifo.two_rd_addr_reg
[8]_i_1__29 … (154 other cells)

Search for cells matching the pattern *reg[*]*:

vivado% get_cells *reg[*]*
WARNING: [Vivado 12-180] No cells matched '*reg[*]*'.
vivado% get_cells *reg[*]* -hier
fftEngine/fftInst/ingressLoop[7].ingressFifo/buffer_fifo/infer_fifo.wr_addr_reg[9]_
i_1__15 … (109 other cells)
vivado% get_cells -hier -regexp {.*reg\[.*\].*}
fftEngine/fftInst/ingressLoop[7].ingressFifo/buffer_fifo/infer_fifo.wr_addr_reg[9]_
i_1__15 … (109 other cells)
vivado% get_cells -hier -regexp {.*reg[.*].*}
WARNING: [Vivado 12-180] No cells matched '.*reg[.*].*'.

The last query, get_cells -hier -regexp {.*reg[.*].*} does not match any cell since the square brackets, [] have not been escaped. As a result, they are processed as special characters for the regular expression and not as literal square brackets in the cell name.

When a range of values needs to be specified in the filtering expression, the -regexp option should be used in addition to the -filter option. For example, the code below only gets the cells from *reg[0]* to *reg[16]*. The regular expression is built around matching .*reg\[[0-9]\].* or matching .*reg\[1[0-6]\].* as shown below:

expanse="page">vivado% get_cells -hierarchical -regexp -filter {NAME =~ ".*reg\[([0-9]||1[0-6])\].*"}

In another example, both commands below return all the tiles matching CLB*X*Y*, excluding the tiles from CLB*X1Y* to CLB*X16Y* with X between 1 and 16:

expanse="page">vivado% get_tiles -regexp -filter {NAME !~ "CLB.*X([1][0-6]|[0-9])Y.*" && TYPE=~ "CLB.*"}

expanse="page">vivado% get_tiles -regexp -filter {NAME !~ "CLB.*X1[0-6]Y.*" && NAME !~ "CLB.*X[1-9]Y.*" && 
      TYPE=~ "CLB.*"}

Using the -filter and -regexp Options - 2021.1 English

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