Querying ICC2 Objects with Collections and Filters

Hello! Last lesson, you searched files and reports from the Linux shell. Now you’ll search the design database inside ICC2. Instead of finding a line containing an instance name, you’ll ask the tool for that instance, inspect its properties, and follow its connections. These are everyday skills for checking an imported design and investigating a physical-design problem. Allow about 40 minutes.

From text searches to design objects

ICC2 represents a loaded design as objects. A cell is an instance in the design, such as a flip-flop or logic gate. A pin is a connection point on an instance, such as u_launch/Q. A port is an interface of the current design, such as clk. A net connects ports and pins.

The principal query commands mirror those object types:

get_cells u_launch
get_pins u_launch/Q
get_ports clk
get_nets n_data

These are ICC2 shell commands, not Linux terminal commands. Each get_* command returns a collection of design objects, rather than lines of text. That distinction matters: you can pass a collection to another tool command to inspect attributes or connections without parsing printed output.

The following reading explains the query vocabulary. It discusses SDC and related Synopsys-style object access, so use it for the concepts; check help in your installed ICC2 release when an option or attribute is uncertain.

For the examples below, imagine a small loaded design with top-level port clk, cells u_launch and u_capture, and net n_data connecting u_launch/Q to u_capture/D. The names are illustrative, not guaranteed to exist in your design.

Build and narrow a collection

A name pattern can select several objects. For instance, get_cells u_* looks for matching cells in the current search scope. A wildcard does not necessarily descend through every level of hierarchy. In ICC2, use the hierarchical-search option when you need to search below the current level; confirm its spelling and behavior with help get_cells in your release.

A filter asks a different question: which of the returned cells have a particular attribute? The following ICC2-style query seeks sequential cells across the hierarchy:

set regs [get_cells -hierarchical * -filter {is_sequential == true}]
puts "Sequential cells found: [sizeof_collection $regs]"

set saves the collection in regs. sizeof_collection counts its objects; it does not count matching text lines. The braces keep the filter expression together as Tcl passes it to ICC2. If your installed tool does not recognize an option or attribute, inspect its local help rather than silently accepting an empty result.

A filter can also narrow an existing collection:

set named_regs [filter_collection $regs {full_name =~ *capture*}]
puts "Matching sequential cells: [sizeof_collection $named_regs]"

Here == means an exact attribute comparison, while =~ tests a pattern. full_name is useful when the hierarchy matters; ref_name is commonly used when you want to select instances by the library cell they reference. For example, two instances can have different full_name values but the same ref_name.

For a single known object, inspect an attribute directly:

set launch [get_cells u_launch]
puts "Reference cell: [get_attribute $launch ref_name]"
puts "Clock port direction: [get_attribute [get_ports clk] direction]"

Run the first get_attribute command only after confirming that u_launch identifies one cell. A zero-object result may mean a wrong name, the wrong current design, or the wrong hierarchy—not that the cell has an empty reference name. A broad pattern may instead find several cells, making a supposedly single-cell lookup ambiguous.

Follow connections rather than guessing names

Names help you start a search; connectivity tells you what an object actually touches. Read the next part of “SDC - object access,” especially its -of_objects examples. The page includes tool-specific details and advanced cases; you only need the basic cell, pin, port, and net relationships here.

Suppose you want to check the example net n_data. Begin with the net, then ask for its connected leaf pins:

set data_net [get_nets n_data]
set connected_pins [get_pins -leaf -of_objects $data_net]

puts "Connected leaf pins: [sizeof_collection $connected_pins]"
foreach_in_collection pin $connected_pins {
    puts "[get_attribute $pin full_name] : [get_attribute $pin pin_direction]"
}

In the imagined design, you expect to find u_launch/Q as an output pin and u_capture/D as an input pin. -of_objects supplies the net collection as the starting point. -leaf requests pins at leaf instances rather than stopping at intermediate hierarchical boundaries. Direction filters can narrow the result:

set drivers [filter_collection $connected_pins {pin_direction == out}]
set loads   [filter_collection $connected_pins {pin_direction == in}]

Treat those labels carefully: they classify the pins returned by this query. Check ports separately when investigating a connection to the design boundary. Hierarchical nets may also have names at more than one level, so inspect the returned objects rather than assuming every connected pin shares an obvious net name.

You can traverse in the other direction too:

set q_pin [get_pins u_launch/Q]
set q_net [get_nets -of_objects $q_pin]

This asks which net is associated with a known pin. Likewise, get_pins -of_objects [get_cells u_launch] asks for the pins of a cell. These queries are more dependable than inferring connectivity from names such as data or Q.

A safe inspection routine in ICC2

When you have ICC2 access and a design loaded, use this order for a real investigation:

1. Confirm the starting object. Query its type explicitly—get_cells, get_pins, get_ports, or get_nets—and count the result with sizeof_collection.
2. Narrow deliberately. Use a name pattern for naming, or -filter/filter_collection for attributes. If the count is unexpectedly zero or large, revisit the scope and pattern.
3. Inspect before traversing. Print names or relevant attributes with get_attribute; use help and the tool’s attribute listing when you do not know the available property names.
4. Follow -of_objects connections. Move from a cell to its pins, or from a pin to its net, instead of assuming a relationship from similarly named objects.

For example, get_ports clk and get_pins u_launch/Q are different queries even though both objects can participate in connectivity. Keeping their types straight makes subsequent commands easier to predict and explains many otherwise puzzling empty results.

Key takeaways

ICC2 queries return collections of typed design objects, not text matches. Use get_cells, get_pins, get_ports, and get_nets to select the right type; count and inspect what you found; use filters for attributes; and use -of_objects to follow connections. Always verify the scope and result count before trusting a query.

Next, you’ll use Tcl to turn repeatable tool settings and output paths into a parameterized script. The collection variables and Tcl command substitution used here will carry directly into that work.