NAME

Synopsys::Collection - An interface to the Synopsys shell collection idiom

SYNOPSIS

    use Synopsys;

    $all_cells = $shell->get_cells("-h *");

    $num_cells = $all_cells->size;
    $one_cell  = $all_cells->index(23);

DESCRIPTION

Overview

The Synopsys::Collection module is an auxiliary module to SPP which maps the Tcl based collection idiom into perl. This module is usually not included directly. Its use is automatically enabled when using SPP.

The reader is directed to the Synopsys documentation to learn about what a collection is and how they are used.

The methods provided in the package are based on the functionality provided by collections in pt_shell. Please note that not all the methods are supported in all Synopsys shells. For example, the sort_collection method is unsupported in dc_shell and its derivatives.

The methods in this package come in two basic varieties, methods that create new collections and methods that operate on existing collections.

Emulated Tcl Commands

This sections describes the methods that emulate the common collection manipulation Tcl commands. Each can be called as either a method of a SPP object or a method of an already existing Collection object.

In some cases, there are no differences between the Tcl commands and the Perl methods. In some cases, there are differences in whether the base collection is modified or not. The Perl methods were written in the way that I thought was most appropriate, not necessarily in a way to be most compatible with the like Tcl command.

Many of the methods described below can take one or more collection objects themselves as arguments. As a convenience to the user, will automatically expand any Collection object into Tcl equivalent. For example:

    $collection1 = $shell->get_cells("A*");
    $collection2 = $shell->get_cells("B*");
    $collection3 = $shell->get_cells("C*");

    $collection4 = $shell->add_to_collection($col1, $col2, $col3);

What this means is that anywhere the Tcl documentation specifies that an object argument is appropriate, a perl Collection object can be used in it's place.

Adding to a Collection

Usage:

    $shell->add_to_collection($base_collection,
                              <object_spec>,
                              ['-unique']);

    $base_collection->add(<object_spec>, ['-unique']);

add_to_collection behaves identically to the like named Tcl command. The $base_collection is not modified. The method add is different from both the Tcl command and add_to_collection in that the calling object is modified.

In either case, a Collection object is returned that is the sum of the $base_collection and the collections specified in object_spec or returns undef on error.

Comparing Collections

Usage:

    $shell->compare_collections($collection1,
                                $collection2,
                                [-order_dependent]);

    $collection1->compare($collection2, [-order_dependent]);

Each of these methods behaves identically to the like named Tcl command. Returns 0 when $collection1 equals $collection2 modulo the -order_dependent flag. Retuns non-zero when they are unequal and returns undef on error.

Copying Collections

Usage:

    $shell->copy_collection($collection);

    $collection->copy;

Each of these methods behaves identically to the like named Tcl command. Returns a new Collection object that is copy of $collection on success and returns undef on error. The original collection is unchanged in either case.

Filtering Collections

Usage:

    $shell->filter_collection($collection,
                              <expression>,
                              [-regexp], [-nocase]);

    $collection->filter(<expression>,
                        [-regexp], [-nocase]);

filter_collection behaves identically to the like named Tcl command. The $collection is not modified. The method filter is different from both the Tcl command and filter_collection in that the calling object is modified.

In either case, a Collection object is returned that is the filtered result of the collection or returns undef on error.

Indexing a Collection

Usage:

    $shell->index_collection($collection, $index);

    $collection->index($index);

Each of these methods behaves identically to the like named Tcl command. Returns a new Collection object that is the $index index of $collection on success and returns undef on failure.

Sizeof a Collection

Usage:

    $shell->sizeof_collection($collection);

    $collection->size;

Each of these methods behaves identically to the like named Tcl command. Returns a new Collection object that is the $index index of $collection on success and returns undef on failure.

Removing from a Collection

Usage:

    $shell->remove_from_collection($collection, <object_spec>);

    $collection->remove(<object_spec>);

remove_from_collection behaves identically to the like named Tcl command. The $collection is not modified. The method remove is different from both the Tcl command and remove_from_collection in that the calling object is modified.

In either case, a Collection object is returned that is result of removing <object_spec> from $collection and returns undef on error.

Sorting a Collection

Usage:

    $shell->sort_collection($collection,
                            ['-descending'], <criteria>);

    $collection->remove(['-descending'], <criteria>);

sort_collection behaves identically to the like named Tcl command. The $collection is not modified. The method sort is different from both the Tcl command and sort_collection in that the calling object is modified.

In either case, a Collection object is returned that is result of sorting the $collection based on <criteria> and returns undef on error.

Querying a Collection

Usage:

    $shell->query_objects(<object_spec>,
                          [-verbose],
                          [-class class_name],
                          [-truncate elem_count])

    $collection->query([-verbose],
                       [-class class_name],
                       [-truncate elem_count]);

Each of these methods behaves identically to the like named Tcl command. Returns a string that lists the names (and classes) of all the elements in <object_spec> and returns undef on failure.

If a -truncate argument is not provided, an elem_count of zero is assumed, which returns the entire list. This is different from the default behavior in Tcl where only the first 100 elements are returned if -truncate is not specified.

get_cells( ... )
get_clocks( ... )
get_designs( ... )
get_lib_cells( ... )
get_lib_pins( ... )
get_libs( ... )
get_nets( ... )
get_pins( ... )
get_ports( ... )
current_design( ... )

Usage:

    $shell->get_cells( ... )

    $shell->get_libs( ... )

Each of the above methods return a new Collection object or sucess or undef on error. The functionality of each is identical to that of the like named Tcl command. The reader is directed to the Synopsys documentation for further information.

Other Collection Object Methods

Below is a description of the instance methods that can be called on a collection after it's created.

shell()

Returns the SPP object associated with the collection.

pvar()

Whenever a collection is created, the output of the Tcl command that created the object needs to be saved in a variable or Tcl will implicitly destroy the object. Each collection has a auto-generated Tcl variable associated with it. This method returns that string which will take the form:

    _pvar[1-9]\d+

For example, the code:

    $a = $shell->get_cells("*");

translates into the Tcl command:

    set _pvar34 [get_cells "*"]

_pvar stands for perl variable. The integer for each pvar is auto-generated and starts at 1. _pvar0 is reserved for internal use. This method is generally not needed but is provided that so users can enter commands manually using the _pvar variable if necessary for debugging.

tvar()

Closely related to the pvar() method, tvar() returns the string that pvar() would evaluate to if it were dereferenced in Tcl. For example, given that a collection was created that had a pvar() of _pvar34, the tvar might be:

    _sel1045

which is really equal to:

    $_pvar34

in Tcl notation. The _sel notation is a Synopsys creation and completely arbitrary. This method is generally not needed and only provided for debugging.

class()

Returns the class of the first element in the collection. This is generally used on collections of size one. A call to this method translates into the Tcl code:

    query_objects -verbose _pvar34

where _pvar34 is an example Tcl variable associated with each collection object. If the collection in question were a cell, the output of this command would be:

    {"cell:U1019"}

and the method would return the string cell.

Please note that different Synopsys shells yield different results with this method. dc_shell doesn't have the correct notion of classes yet, so it always returns the string object for every element. Contrast this to pt_shell, which gives correct results.

name()

Returns the full_name attribute for a collection with one element. This method is just a synonym for the full_name attribute which can also be retrieved using the collection attributes functionality.

Internally, name() uses the get_object_name Tcl command.

all_elements()

Returns a list collection objects that are all the elements in the object's collection. This can be used to iterate over a collection. This method can be time-consuming and resource consuming if the collection has many elements (thousands).

Collection Attributes

Any collection that has a size of one can retrieve a named attribute by using the name of the attribute as the method name. For example, if a collection object is created that contains a cell element, the ref_name attribute associated with it could be accessed with this code:

    $cell->ref_name;

This will return a string that is the reference name for that cell.

It is an error to attempt to retrieve an attribute using a collection object that contains more than one object.

It is also an error to retrieve a non-existent attribute.

In all cases, the empty string is returned on failure and the attribute value is returned on success.

It is up to the user to know attributes exist on what types of collection classes (cells, nets, pins, etc). The reader is directed to the Tcl command:

    list_attributes -application -class <class>

to print out a list of available attributes for a given collection class.

Iterating Over A Collection

A common operation is iterating over the elements in a collection. While Synopsys' Tcl provides a foreach_in_collection command, there is no such command in perl. The same effect can be accomplished using either the index or the all_elements. The following two code snippets are functionally the same:

    my $size = $collection->size;
    for(my $i=0; $i<$size; $i++) {
      my $element = $collection->index($i);
      ...
    }

    foreach my $element ($collection->all_elements) {
      ...
    }

Overall, each code snippet takes about the same time to execute and produces the same results. The first snippet uses less memory (for both Perl and Tcl) because the allocation of collection objects (for both Perl and Tcl) is done over the course of the loop. One collection object is allocated and deallocated each time through. Contrast this with the second snippet which first builds a list of collection objects and then iterates over them.

So while the second method may be stylistically cleaner, it is less preferable because it consumes more memory.

Garbage Collection

Everytime a collection is created, a Tcl variable (pvar) is set in the Synopsys shell. Using Perl's automatic garbage collection facility, the Tcl variables will automatically be unset when the perl Collection object is undef'ed or goes out of scope.

This happens automatically and requires no intervention from the user.

TODO

Add support for these Tcl commands:

    get_lib_timing_arcs
    get_path_groups
    get_generated_clocks
    get_qtm_ports
    get_timing_arcs
    get_timing_paths

    all_clocks
    all_inputs
    all_outputs
    all_registers

    all_instances
    all_connected
    all_fanin
    all_fanout

SEE ALSO

Synopsys, synopsys_shell

AUTHOR

Jeff Solomon <jsolomon@vlsi.stanford.edu>

Back