What a Collection Is

Part II · Module 18 · Chapter 18.1 · What a Collection Is

Every useful thing you do to a design starts by selecting part of it: these ports, those cells, that clock's pins. The command that does the selecting returns something, and what it returns is not what most people assume.

It is not a list of names. It is a collection — a handle to a set of design objects. This module is about what that means, and the first question to answer is why a tool would do it that way.

1. What comes back

set cells [get_cells *]
puts "  the value is       : $cells"
puts "  sizeof_collection  : [sizeof_collection $cells]"
puts "  contents           : [collection_to_list $cells]"

  set cells [get_cells *]
  the value is       : _sel1
  sizeof_collection  : 2
  contents           : u_fifo u_alu

$cells is _sel1. Not u_fifo u_alu — a handle that means nothing on its own and everything to the tool.

The real contents are reachable, but only through the tool's commands: sizeof_collection for the size, and a conversion command when you genuinely want names.

2. Why not just return the names?

The obvious design would be get_cells * returning {u_fifo u_alu} — ordinary Tcl, no new concepts, everything from Part I applies. It is worth understanding why no tool does that.

Three reasons, and each one is a real cost avoided.

3. Reason one: size without building a string

A large block has millions of cells. get_cells -hierarchical * on a real design can select a set that would be hundreds of megabytes as a string of names.

A handle costs nothing to return. The tool already knows how many objects are in the set, so sizeof_collection is an immediate answer rather than a string it has to construct, hand to Tcl, and have Tcl count.

That is why the registry's purpose phrases it as a size the tool can report without building a string. Asking "how many sequential cells are there" should not require materialising every name.

4. Reason two: identity

Two different objects can have the same name. A pin called CLK exists on every flop; a net called reset_n may exist at several levels of hierarchy. A bare string cannot tell them apart.

A collection holds references to the objects, so u_fifo/u_ctrl/CLK and u_alu/u_acc_reg/CLK are distinct things that happen to end in the same four letters. The tool never has to guess which one you meant, because you never handed it a name to re-interpret.

This also means a collection is stable in a way a name is not. If an optimisation step renames a cell, a name you stored last hour now refers to nothing; the object is still the object.

5. Reason three: attributes

This is the one you will use most. An object has properties — a name is just a label.

set c [get_cells -hierarchical *reg*]
set obj [index_collection $c 0]
puts "  object            : $obj"
puts "  full_name         : [get_attribute $obj full_name]"
puts "  object_type       : [get_attribute $obj object_type]"
puts "  ref_name          : [get_attribute $obj ref_name]"
puts "  is_sequential     : [get_attribute $obj is_sequential]"
puts "  a missing one     : [catch {get_attribute $obj no_such_attr} e] / $e"

  object            : u_alu/u_acc_reg
  full_name         : u_alu/u_acc_reg
  object_type       : cell
  ref_name          : DFF
  is_sequential     : true
  a missing one     : 1 / attribute 'no_such_attr' not defined on 'u_alu/u_acc_reg'

is_sequential is the kind of thing you cannot get from a name. You could guess from *_reg* — and you would be wrong about every flop somebody named differently, and wrong about every combinational cell somebody named *_reg*.

Attributes are how you ask what something is rather than what it is called, and Chapter 18.7 turns them into a selection mechanism.

6. The commands that operate on collections

A tool provides a parallel set of commands for collections, because the Tcl list commands do not apply:

The names vary between tools; the categories do not. When you meet a new tool, finding its versions of these six is the first thing to do.

7. When you do want names

Sometimes you genuinely want strings — to write a report, to compare against a file, to pass to something outside the tool. Tools provide a conversion, and it is the right moment to leave collection-land:

set names [collection_to_list [get_cells -hierarchical *reg*]]
puts "  [llength $names] sequential cells"
foreach n [lsort $names] { puts "    $n" }

Once converted, it is an ordinary Tcl list and all of Part I applies — llength, lsort, foreach, join.

That is also the boundary from Chapter 16.4 §6: convert at the edge, then do the logic in standard Tcl where it is testable without a tool.

8. Exercises

Exercise 1. What does a query command return?

Exercise 2. Give the three reasons a tool returns a handle rather than a list of names.

Exercise 3. Why can a name not distinguish two pins both called CLK?

Exercise 4. You want every flop. Why is get_cells *_reg* not a reliable way to get them?

Exercise 5. Name the collection equivalents of llength, foreach and lindex.

Exercise 6. What happens if you ask for an attribute that does not exist, and why is that good?

Exercise 7. When should you convert a collection to a list of names?